Alias(3pm)

💖 NAME 💖

alias — declare symbolic aliases for perl data

attr — auto-declare hash attributes for convenient access

const — define compile-time scalar constants

okay so this is the Alias(3pm) page from the User Contributed Perl Documentation, and bestie, it is genuinely one of the most useful little modules to ever exist. let's get into it 🫶

---

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

yeah. that's the vibe. moving on 💅

---

🦋 DESCRIPTION 🦋

So basically: it provides general mechanisms for aliasing perl data for convenient access. and honestly? iconic.

This module works by putting some values on the symbol table with user-supplied names. Here's the part that gets people though — values that are references will get dereferenced into their base types. So if you've got a value of [1,2,3] with a name of foo, it gets made available as @foo, not $foo. that's the whole thing. 🎀

The one exception to this rule is the default behavior of the attr function, which will not dereference values that are blessed references (a.k.a. objects). Wanna change that default? See $Alias::Deref. ✨

✨ Functions ✨

alias 💖

Give it a list of name => value pairs, and it declares aliases in the caller's namespace. If the value you supplied is a reference, the alias gets created for the underlying value instead of the reference itself — and ngl you don't even need this module to alias references, because they're automatically "aliased" on assignment anyway. That's how you get to alias most of the basic types. 💅

If the value you supply is a scalar compile-time constant, the aliases become read-only. Any attempt to write to them will fail with a run time error. not a warning bestie, a whole error. 😭

Aliases can also be dynamically scoped by pre-declaring the target variable as local. But using attr for this purpose is more convenient, and it's what we recommend. 🫶

attr ✨

Hand it a hash reference, and it 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're available as their dereferenced types. So the action is similar to saying:

alias %{$_[0]}

...but, in addition, it also localizes the aliases, and it does not dereference objects. You can force dereferencing of objects by setting the Deref option — see $Alias::Deref. 👑

This is the move for convenient access to hash values and hash-based object attributes.

okay and here's the part that's lowkey genius: this makes available the semantics of local subroutines and methods. Which makes for some nifty possibilities. We could make truly private methods by putting anonymous subs within an object — those subs would be available within methods where we use attr, and will not be visible to the outside world as normal methods. We could also forbid recursion in methods by always putting an empty sub in the object hash with the same key as the method name. That's useful where a method has to run code from other modules, but can't 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. You can control this by setting a few options — see "Configuration Variables" for details. 💜

const 🎀

This is simply a function alias for alias, described above. It's provided on demand at use time, since it reads better for constant declarations. One heads-up though: hashes and arrays cannot be so constrained. nope, not those. 🙈

🎛️ Configuration Variables 🎛️

The following configuration variables can be used to control the behavior of the attr function. They're typically set after the use Alias; statement. Another typical usage is to localize 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. It 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. It 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's 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 "".

You can also use this option as a filter if it's 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. fr fr, actually run them. 🫶

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's worth repeating: 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 localized, the aliases created will be local to that block. And attr localizes the aliases for us, so you don't gotta. 💅

Remember that references will be available as their dereferenced types. 🌀

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

Lexicals can be aliased though. And note that this provides a means of reversing the action of anonymous type generators \, [] and {}. Which means we can anonymously construct data or code and give it a symbol-table presence when we choose. iconic behavior honestly. 👑

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's possible to alias packages, but that might be construed as abuse. 🙈

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

---

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

---

and that's the whole page bestie!! 🎀💖 this one shipped as perl v5.42.3, dated 2026-08-19, and it's the Alias(3pm) page — go forth and alias responsibly, you absolute main character 🦋✨🫶