Typed lexicals

        package OtherClass;

        my LoudDecl $loudobj : Loud;
        my LoudDecl @loudobjs : Loud;
        my LoudDecl %loudobjex : Loud;

causes the LoudDecl::Loud handler to be invoked (even if OtherClass also defines a handler for ":Loud" attributes).

Type-specific attribute handlers

        package LoudDecl;

        sub RealLoud :ATTR(SCALAR) { print "Yeeeeow!" }

creates an attribute handler that applies only to scalars:

        package Painful;
        use base LoudDecl;

        my $metal : RealLoud;           # invokes &LoudDecl::RealLoud
        my @metal : RealLoud;           # error: unknown attribute
        my %metal : RealLoud;           # error: unknown attribute
        sub metal : RealLoud {...}      # error: unknown attribute

You can also explicitly indicate that a single handler is meant to be used for all types of referents like so:

        package LoudDecl;
        use Attribute::Handlers::Prospective;

        sub SeriousLoud :ATTR(ANY) { warn "Hearing loss imminent" }

(I.e. "ATTR(ANY)" is a synonym for ":ATTR").

Non-interpretive attribute handlers

This can be specified by giving the "ATTR" attribute of an attribute handler the keyword "RAWDATA". For example:

        sub Raw          : ATTR(RAWDATA) {...}
        sub Nekkid       : ATTR(SCALAR,RAWDATA) {...}
        sub Au::Naturale : ATTR(RAWDATA,ANY) {...}

Then the handler makes absolutely no attempt to interpret the data it receives and simply passes it as an uninterpolated "q(...)" string:

        my $power : Raw(1..100);        # handlers receives "1..100"

Phase-specific attribute handlers

However, it is possible to set up attribute handlers that are called at other points in the program's compilation or execution, by explicitly stating the phase (or phases) in which you wish the attribute handler to be called. For example:

        sub Early    :ATTR(SCALAR,BEGIN) {...}
        sub Earlyish :ATTR(SCALAR,CHECK) {...}
        sub Normal   :ATTR(SCALAR,INIT) {...}
        sub Active   :ATTR(SCALAR,RUN) {...}
        sub Final    :ATTR(SCALAR,END) {...}
        sub Bookends :ATTR(SCALAR,BEGIN,END) {...}

As the last example indicates, a handler may be set up to be (re)called in two or more phases. The phase name is passed as the handler's final argument.

Note that attribute handlers that are scheduled for the "BEGIN" phase are handled as soon as the attribute is detected (i.e. before any subsequently defined "BEGIN" blocks are executed).

Attribute handlers that are scheduled for the "RUN" phase are executed every time the code itself executes.

Default attribute handlers

For example:

        package Real;

        sub RealAttr : ATTR {
                print "You ascribed a RealAttr attribute to $_[2]\n";
        }

        sub AUTOATTR : ATTR {
                warn "You tried to ascribe a :$_[3] attribute to $_[2]\n",
                     "but there's no such attribute defined in class $_[0]\n",
                     "(Did you mean :RealAttr?)\n";
        }

Now, ascribing any other attribute except ":RealAttr" to a referent associated with the Real package provokes a warning.

If the "AUTOATTR" hadn't been defined, ascribing any other attribute would have produced a fatal error.

Note that the arguments an "AUTOATTR" receives are indentical to those that would have been received by the real attribute handler it's replacing.

Pre- and post-attribute handlers

These handlers receive the same six arguments as any other handler, the only difference being that their $data argument ($_[4]) is an array of arrays. Each of those inner arrays is the complete argument list that each attribute in turn will receive.

For example, to report each attribute scribed to any scalar, we could write:

        use Data::Dumper 'Dumper';

        sub UNIVERSAL::PREATTR : ATTR(SCALAR) {
                my $name = *{$_[1]}{NAME};
                $name = "PACKAGE(\$$name)" unless $name =~ /^LEXICAL/;
                print "$name was ascribed:\n";
                foreach $arglist ( @{$_[4]} ) {
                        print "$arglist->[3](", Dumper($arglist), ")\n"
                }
        }

Note that changes to the argument lists within the pre- and postfix handlers do not propagate to the actual attribute handler calls (though they may do so in future releases).

Attributes as "tie" interfaces

        use Attribute::Handlers::Prospective;
        use Tie::Cycle;

        sub UNIVERSAL::Cycle : ATTR(SCALAR, RUN) {
                my ($package, $symbol, $referent, $attr, $data, $phase) = @_;
                $data = [ $data ] unless ref $data eq 'ARRAY';
                tie $$referent, 'Tie::Cycle', $data;
        }

        # and thereafter...

        package main;

        my $next : Cycle('A'..'Z');     # $next is now a tied variable

        while (<>) {
                print $next;
        }

In fact, this pattern is so widely applicable that Attribute::Handlers::Prospective provides a way to automate it: specifying 'autotie' in the "use Attribute::Handlers::Prospective" statement. So, the previous example, could also be written:

        use Attribute::Handlers::Prospective autotie => { Cycle => 'Tie::Cycle' };

        # and thereafter...

        package main;

        my $next : Cycle('A'..'Z');     # $next is now a tied variable

        while (<>) {
                print $next;

The argument after 'autotie' is a reference to a hash in which each key is the name of an attribute to be created, and each value is the class to which variables ascribed that attribute should be tied.

Note that there is no longer any need to import the Tie::Cycle module -- Attribute::Handlers::Prospective takes care of that automagically. You can even pass arguments to the module's "import" subroutine, by appending them to the class name. For example:

        use Attribute::Handlers::Prospective
                autotie => { Dir => 'Tie::Dir qw(DIR_UNLINK)' };

If the attribute name is unqualified, the attribute is installed in the current package. Otherwise it is installed in the qualifier's package:

        package Here;

        use Attribute::Handlers::Prospective autotie => {
                Other::Good => Tie::SecureHash, # tie attr installed in Other::
                        Bad => Tie::Taxes,      # tie attr installed in Here::
            UNIVERSAL::Ugly => Software::Patent # tie attr installed everywhere
        };

Autoties are most commonly used in the module to which they actually tie, and need to export their attributes to any module that calls them. To facilitiate this, Attribute::Handlers::Prospective recognizes a special "pseudo-class" -- "__CALLER__", which may be specified as the qualifier of an attribute:

        package Tie::Me::Kangaroo:Down::Sport;

        use Attribute::Handlers::Prospective autotie => { __CALLER__::Roo => __PACKAGE__ };

This causes Attribute::Handlers::Prospective to define the "Roo" attribute in the package that imports the Tie::Me::Kangaroo:Down::Sport module.

Passing the tied object to "tie"

Occasionally it is important to pass a reference to the object being tied to the TIESCALAR, TIEHASH, etc. that ties it.

The "autotie" mechanism supports this too. The following code:

        use Attribute::Handlers::Prospective autotieref => { Selfish => Tie::Selfish };
        my $var : Selfish(@args);

has the same effect as:

        tie my $var, 'Tie::Selfish', @args;

But when "autotieref" is used instead of "autotie":

        use Attribute::Handlers::Prospective autotieref => { Selfish => Tie::Selfish };
        my $var : Selfish(@args);

the effect is to pass the "tie" call an extra reference to the variable being tied:

        tie my $var, 'Tie::Selfish', \$var, @args;

Universal attributes

        package Descriptions;
        use Attribute::Handlers::Prospective;

        my %name;
        sub name { return $name{$_[2]}||*{$_[1]}{NAME} }

        sub UNIVERSAL::Name :ATTR {
                $name{$_[2]} = $_[4];
        }

        sub UNIVERSAL::Purpose :ATTR {
                print STDERR "Purpose of ", &name, " is $_[4]\n";
        }

        sub UNIVERSAL::Unit :ATTR {
                print STDERR &name, " measured in $_[4]\n";
        }

Let's you write:

        use Descriptions;

        my $capacity : Name(capacity)
                     : Purpose(to store max storage capacity for files)
                     : Unit(Gb);


        package Other;

        sub foo : Purpose(to foo all data before barring it) { }

        # etc.