Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Alias(3)	      User Contributed Perl Documentation	      Alias(3)

NAME
       alias - declare symbolic	aliases	for perl data

       attr  - auto-declare hash attributes for	convenient access

       const - define compile-time scalar constants

SYNOPSIS
	   use Alias qw(alias const attr);
	   alias TEN =>	$ten, Ten => \$ten, Ten	=> \&ten,
		 Ten =>	\@ten, Ten => \%ten, TeN => \*ten;
	   {
	      local @Ten;
	      my $ten =	[1..10];
	      alias Ten	=> $ten;   # local @Ten
	   }

	   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)
	   }

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 "[1,2,3]" with a name of
       "foo" will be made available as @foo, not $foo.

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

   Functions
       alias
	   Given a list	of name	=> value pairs,	declares aliases in the
	   "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 "local".	 Using "attr" for this purpose is more
	   convenient, and recommended.

       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 "Deref" option.	See $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 "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
	   "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 "Configuration Variables" for details.

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

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

       $Alias::KeyFilter
	   Specifies the key prefix used for determining which hash entries
	   will	be interned by "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.

       $Alias::AttrPrefix
	   Specifies a prefix to prepend to the	names of localized attributes
	   created by "attr".  Can be a	CODE reference,	in which case it will
	   be called with the key, and the result will determine the full name
	   of the attribute.  The value	can have embedded package delimiters
	   ("::" or "'"), which	cause the attributes to	be interned in that
	   namespace instead of	the "caller"s own namespace. For example,
	   setting it to "main::" makes	"use strict 'vars';" somewhat more
	   palatable (since we can refer to the	attributes as $::foo, etc.,
	   without actually declaring the attributes).

       $Alias::Deref
	   Controls the	implicit dereferencing behavior	of "attr".  If it is
	   set to "" or	0, "attr" will not dereference blessed references.  If
	   it is a true	value (anything	but "",	0, or a	CODE reference), all
	   references will be made available as	their dereferenced types,
	   including values that may be	objects.  The default is "".

	   This	option can be used as a	filter if it is	set to a CODE
	   reference, in which case it will be called with the key and the
	   value (whenever the value happens to	be a reference), and the
	   boolean return value	will determine if that particular reference
	   must	be dereferenced.

   Exports
       alias
       attr

EXAMPLES
       Run these code snippets and observe the results to become more familiar
       with the	features of this module.

	   use Alias qw(alias const attr);
	   $ten	= 10;
	   alias TEN =>	$ten, Ten => \$ten, Ten	=> \&ten,
		 Ten =>	\@ten, Ten => \%ten;
	   alias TeN =>	\*ten;	# same as *TeN = *ten

	   # aliasing basic types
	   $ten	= 20;
	   print "$TEN|$Ten|$ten\n";   # should	print "20|20|20"
	   sub ten { print "10\n"; }
	   @ten	= (1..10);
	   %ten	= (a..j);
	   &Ten;		       # should	print "10"
	   print @Ten, "|", %Ten, "\n";

	   # this will fail at run time
	   const _TEN_ => 10;
	   eval	{ $_TEN_ = 20 };
	   print $@ if $@;

	   # dynamically scoped	aliases
	   @DYNAMIC = qw(m n o);
	   {
	      my $tmp =	[ qw(a b c d) ];
	      local @DYNAMIC;
	      alias DYNAMIC => $tmp, PERM => $tmp;

	      $DYNAMIC[2] = 'zzz';
	      #	prints "abzzzd|abzzzd|abzzzd"
	      print @$tmp, "|",	@DYNAMIC, "|", @PERM, "\n";

	      @DYNAMIC = qw(p q	r);
	      #	prints "pqr|pqr|pqr"
	      print @$tmp, "|",	@DYNAMIC, "|", @PERM, "\n";
	   }

	   # prints "mno|pqr"
	   print @DYNAMIC, "|",	@PERM, "\n";

	   # named closures
	   my($lex) = 'abcd';
	   $closure = sub { print $lex,	"\n" };
	   alias NAMEDCLOSURE => \&$closure;
	   NAMEDCLOSURE();	      #	prints "abcd"
	   $lex	= 'pqrs';
	   NAMEDCLOSURE();	      #	prints "pqrs"

	   # hash/object attributes
	   package Foo;
	   use Alias;
	   sub new {
	     bless
	       { foo =>	1,
		 bar =>	[2,3],
		 buz =>	{ a => 4},
		 privmeth => sub { "private" },
		 easymeth => sub { die "to recurse or to die, is the question" },
	       }, $_[0];
	   }

	   sub easymeth	{
	     my	$s = attr shift;    # localizes	$foo, @bar, %buz etc with values
	     eval { $s->easymeth }; # should fail
	     print $@ if $@;

	     # prints "1|2|3|a|4|private|"
	     print join	'|', $foo, @bar, %buz, $s->privmeth, "\n";
	   }

	   $foo	= 6;
	   @bar	= (7,8);
	   %buz	= (b =>	9);
	   Foo->new->easymeth;	     # this will not recurse endlessly

	   # prints "6|7|8|b|9|"
	   print join '|', $foo, @bar, %buz, "\n";

	   # this should fail at run-time
	   eval	{ Foo->new->privmeth };
	   print $@ if $@;

NOTES
       It is worth repeating that the aliases created by "alias" and "const"
       will be created in the "caller"s	namespace (we can use the "AttrPrefix"
       option to specify a different namespace for "attr").  If	that namespace
       happens to be "local"ized, the aliases created will be local to that
       block.  "attr" localizes	the aliases for	us.

       Remember	that references	will be	available as their dereferenced	types.

       Aliases cannot be lexical, since, by neccessity,	they live on the
       symbol table.

       Lexicals	can be aliased.	Note that this provides	a means	of reversing
       the action of anonymous type generators "\", "[]" and "{}".  This
       allows us to anonymously	construct data or code and give	it a symbol-
       table presence when we choose.

       Any occurrence of "::" or "'" in	names will be treated as package
       qualifiers, and the value will be interned in that namespace.

       Remember	that aliases are very much like	references, only we don't have
       to dereference them as often.  Which means we won't have	to pound on
       the dollars so much.

       We can dynamically make subroutines and named closures with this
       scheme.

       It is possible to alias packages, but that might	be construed as	abuse.

       Using this module will dramatically reduce noise	characters in object-
       oriented	perl code.

BUGS
       "use strict 'vars';" is not very	usable,	since we depend	so much	on the
       symbol table.  You can declare the attributes with "use vars" to	avoid
       warnings.  Setting $Alias::AttrPrefix to	"main::" is one	way to avoid
       "use vars" and frustration.

       Tied variables cannot be	aliased	properly, yet.

VERSION
       Version 2.32	  30 Apr 1999

AUTHOR
       Gurusamy	Sarathy		       gsar@umich.edu

       Copyright (c) 1995-99 Gurusamy Sarathy. All rights reserved.  This
       program is free software; you can redistribute it and/or	modify it
       under the same terms as Perl itself.

SEE ALSO
       perl(1)

perl v5.24.1			  1999-05-01			      Alias(3)

NAME | SYNOPSIS | DESCRIPTION | EXAMPLES | NOTES | BUGS | VERSION | AUTHOR | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Alias&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help