view release on metacpan or  search on metacpan

Alias.pm  view on Meta::CPAN

    }

    const pi => 3.14, ten => 10;

    package Foo;
    use Alias;
    sub new { bless {foo => 1, _bar => [2, 3]}, $_[0] }
    sub a_method {
       my $s = attr shift;
       # $foo, @_bar are now local aliases for
       # $_[0]{foo}, @{$_[0]{_bar}} etc.
    }

    sub b_method {
      local $Alias::KeyFilter = "_";
      local $Alias::AttrPrefix = "main::";
      my $s = attr shift;
      # local @::_bar is now available, ($foo, $::foo are not)
    }

    sub c_method {
      local $Alias::KeyFilter = sub { $_ = shift; return (/^_/ ? 1 : 0) };
      local $Alias::AttrPrefix = sub {
                                       $_ = shift;
				       s/^_(.+)$/main::$1/;
				       return $_
				     };
      my $s = attr shift;
      # local @::bar is now available, ($foo, $::foo are not)
    }


=head1 DESCRIPTION

Provides general mechanisms for aliasing perl data for convenient access.

This module works by putting some values on the symbol table with
user-supplied names.  Values that are references will get dereferenced into
their base types.  This means that a value of C<[1,2,3]> with a name of
"foo" will be made available as C<@foo>, not C<$foo>.

The exception to this rule is the default behavior of the C<attr> function,
which will not dereference values which are blessed references (aka
objects).  See L<$Alias::Deref> for how to change this default behavior.

=head2 Functions

=over 4

=item alias

Given a list of name => value pairs, declares aliases
in the C<caller>s namespace. If the value supplied is a reference, the
alias is created for the underlying value instead of the reference
itself (there is no need to use this module to alias references--they
are automatically "aliased" on assignment).  This allows the user to
alias most of the basic types.

If the value supplied is a scalar compile-time constant, the aliases 
become read-only. Any attempt to write to them will fail with a run time
error. 

Aliases can be dynamically scoped by pre-declaring the target variable as
C<local>.  Using C<attr> for this purpose is more convenient, and
recommended.

=item attr

Given a hash reference, aliases the values of the hash to the names that
correspond to the keys.  It always returns the supplied value.  The aliases
are local to the enclosing block. If any of the values are unblessed
references, they are available as their dereferenced types.  Thus the action
is similar to saying:

    alias %{$_[0]}

but, in addition, also localizes the aliases, and does not dereference
objects.  Dereferencing of objects can be forced by setting the C<Deref>
option.  See L<$Alias::Deref>.

This can be used for convenient access to hash values and hash-based object
attributes.  

Note that this makes available the semantics of C<local> subroutines and
methods.  That makes for some nifty possibilities.  We could make truly
private methods by putting anonymous subs within an object.  These subs
would be available within methods where we use C<attr>, and will not
be visible to the outside world as normal methods.  We could forbid 
recursion in methods by always putting an empty sub in the object hash 
with the same key as the method name. This would be useful where a method 
has to run code from other modules, but cannot be certain whether that 
module will call it back again.

The default behavior is to create aliases for all the entries in the hash,
in the callers namespace.  This can be controlled by setting a few options.
See L<Configuration Variables> for details.

=item const

This is simply a function alias for C<alias>, described above.  Provided on
demand at C<use> time, since it reads better for constant declarations.
Note that hashes and arrays cannot be so C<const>rained.

=back

=head2 Configuration Variables

The following configuration variables can be used to control the behavior of
the C<attr> function.  They are typically set after the C<use Alias;>
statement.  Another typical usage is to C<local>ize them in a block so that
their values are only effective within that block.

=over 4

=item $Alias::KeyFilter

Specifies the key prefix used for determining which hash entries will be
interned by C<attr>.  Can be a CODE reference, in which case it will be
called with the key, and the boolean return value will determine if
that hash entry is a candidate attribute.