=encoding utf-8

=head1 NAME

Symbol::Get - Read Perl’s symbol table programmatically

=head1 SYNOPSIS

   package Foo;

   our $name = 'haha';
   our @list = ( 1, 2, 3 );
   our %hash = ( foo => 1, bar => 2 );

   use constant my_const => 'haha';

   sub doit { ... }

   my $name_sr = Symbol::Get::get('$Foo::name');    # \$name
   my $list_ar = Symbol::Get::get('$Foo::list');    # \@list
   my $hash_hr = Symbol::Get::get('$Foo::hash');    $ \%hash

   #Defaults to __PACKAGE__ if none is given:
   my $doit_cr = Symbol::Get::get('&doit');

   #A constant--note the lack of sigil.
   my $const_sr = Symbol::Get::get('Foo::my_const');

   #The below return the same results since get_names() defaults
   #to the current package if none is given.
   my @names = Symbol::Get::get_names('Foo');      # keys %Foo::
   my @names = Symbol::Get::get_names();

=head1 DESCRIPTION

Occasionally I have need to reference a variable programmatically.
This module facilitates that by providing an easy, syntactic-sugar-y,
read-only interface to the symbol table.

The SYNOPSIS above should pretty well cover usage.

=head1 ABOUT PERL CONSTANTS

This construction:

   use constant foo => 'bar';

… does something rather special with the symbol table: while you access
C<foo> as though it were a function (e.g., C<foo()>, or just bareword C<foo>),
the actual symbol table entry is a SCALAR reference, not a GLOB like other
entries.

C<Symbol::Get::get()> expects you to pass in names of constants WITHOUT
trailing parens (C<()>), as in the example above.

=head1 SEE ALSO

=over 4

=item * L<Symbol::Values>

=back

=head1 LICENSE

This module is licensed under the same license as Perl.