NAME

Symbol::Values - Provides consistent accessing interface to values of symbol.

SYNOPSIS

  use Symbol::Values 'symbol';
  
  sub my_code { print "in original 'my_code'.\n" }
  
  # Get code object in symbol "my_code".
  my $orig_code = symbol("my_code")->code;
  
  my $wrapper = sub {
      print "before original 'my_code'.\n";
      $orig_code->();
      print "after original 'my_code'.\n";
  };
  
  # Set code object in symbol "my_code".
  symbol("my_code")->code = $wrapper;
  
  my_code(); # => before original 'my_code'.
             #    in original 'my_code'.
             #    after original 'my_code'.

DESCRIPTION

OBJECTIVE

I've been feeling that glob notation of perl is little bit funny.

One problem is that it lacks consistency in the way of fetching/storing values of a symbol.

See examples below.

  $code_ref = *name{CODE};    # Getting code object.
                              # This is obvious.
  
  *name{CODE} = $code_ref;    # Setting code object.
                              # THIS CODE DOES NOT WORK!!
  
  
  *name = $code_ref;          # This code works...
                              # Isn't it funny?

The other problem is readability of the code.

I think that inconsistency of the glob notation is making readability of the code little bit difficult.

Therefore I wrote this module to provide alternative way of accessing to the values of a symbol.

By using this module, above examples can be wrote as below.

  use Symbol::Values;
  my $sym = Symbol::Values->new('name');
  
  $code_ref = $sym->code;    # Getting code object.
  
  $sym->code = $code_ref;    # Setting code object.

I hope this module makes your code more readable.

METHODS

$obj = CLASS->new($symbol_name_or_glob);

Constructor. You can pass name of symbol like "my_var" or glob like *my_var as argument.

If the passed argument(glob or name of symbol) was not qualified by package name, it will be qualified by current package name.

  package main;
  use Symbol::Values;
  
  our $a = 1;
  my $obj;
  
  $obj = Symbol::Values->new('a');       # name of symbol.
  $obj = Symbol::Values->new('main::a'); # same as above.
  $obj = Symbol::Values->new(*a);        # glob.
  $obj = Symbol::Values->new(*main::a);  # same as above.

There is alternative way of using "new" method:

  use Symbol::Values 'symbol';
  
  my $obj = symbol($symbol_name_or_glob);

This function "symbol" is not exported by default, so if you prefer to use this syntactic sugar, you should import it explicitly.

$scalar_ref = $obj->scalar_ref;

Get scalar object in the symbol.

You can also assign new scalar object to a symbol.

  my $new_value = "something new";
  $obj->scalar_ref = \$new_value;

$scalar = $obj->scalar;

Get scalar value in the symbol.

You can also assign new scalar value to a symbol.

  my $new_value = "something new";
  $obj->scalar = $new_value;

$array_ref = $obj->array_ref;

Get array object in the symbol.

You can also assign new array object to a symbol.

  my @new_value = ("something", "new");
  $obj->array_ref = \@new_value;

@array = $obj->array;

Get array value in the symbol as reference.

You can also assign new array value to a symbol.

  my @new_value = ("something", "new");
  ($obj->array) = @new_value;

NOTE: You have to call array method in list context when you assign new value.

$hash_ref = $obj->hash_ref;

Get hash object in the symbol.

You can also assign new hash object to a symbol.

  my %new_value = ("something" => "new");
  $obj->hash_ref = \%new_value;

%hash = $obj->hash;

Get hash value in the symbol.

You can also assign new hash value to a symbol.

  my %new_value = ("something" => "new");
  ($obj->hash) = %new_value;

NOTE: You have to call hash method in list context when you assign new value.

$code = $obj->code;

Get code object in the symbol as reference.

  use Symbol::Values 'symbol';
  
  sub my_func {
     print "my_func called.\n";
  }
  
  my $sub = symbol('my_func')->code;  # my $sub = \&my_func;
  $sub->(); # => my_func called.

You can also assign new code object to a symbol.

  symbol('my_func')->code = sub { print "modified code called.\n" };
  
  my_func(); # => modified code called.
  $sub->();  # => my_func called.

$io = $obj->io;

Get IO object in the symbol.

You can also assign new io object to a symbol.

  use Symbol;
  
  my $obj = Symbol::Values->new('io_sym');
  my $io_obj = geniosym();
  $obj->io = $io_obj;

$glob = $obj->glob;

Get glob object in the symbol.

You can also assign new glob object to a symbol.

  use Symbol::Values 'symbol';
  
  our $var1 = 1;
  our $var2 = 2;
  symbol('var2')->glob = symbol('var1')->glob; # *var2 = *var1
  print "$var2\n"; # => 2

$format = $obj->format;

Get format object in the symbol.

You can also assign new format object to a symbol.

  format my_fmt1 =
   ......
  .
  
  # alternate way of '*my_fmt2 = *my_fmt1{FORMAT}'.
  symbol('my_fmt2')->format = symbol('my_fmt1')->format;

EXPORT

None by default.

BUGS/LIMITATIONS

Speed

The cost of getting consistency of notation and readability is time. So if the response is very important problem of your project, please consider to use funny glob notation.

Taste

If you're loving default glob notation, just ignore this module.

SEE ALSO

perlref

Generic information about symbol table mechanism in perl.

Hook::LexWrap

If you want to override some existing functions/methods, it is very nice idea to consult "Hook::LexWrap".

t/Symbol-Values.t

Test file "t/Symbol-Values.t" in the distribution of this module -- This file provides you some example of usage.

AUTHOR

Keitaro Miyazaki, <kmiyazaki@cpan.org>

COPYRIGHT AND LICENSE

Copyright (C) 2005 by Keitaro Miyazaki

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.