################################# From:
This is perl, v5.6.1 built for MSWin32-x86-multi-thread
(with 1 registered patch, see perl -V for more detail)
Copyright 1987-2001, Larry Wall
Binary build 628 provided by ActiveState Tool Corp. http://www.ActiveS
+tate.com
Built 15:41:05 Jul 4 2001
Perl may be copied only under the terms of either the Artistic License
+ or the
GNU General Public License, which may be found in the Perl 5 source ki
+t.
Complete documentation for Perl, including FAQ lists, should be found
+on
this system using `man perl' or `perldoc perl'. If you have access to
+ the
Internet, point your browser at http://www.perl.com/, the Perl Home Pa
+ge.
################################# the documentation
NAME
attributes - get/set subroutine or variable attributes
SYNOPSIS
sub foo : method ;
my ($x,@y,%z) : Bent ;
my $s = sub : method { ... };
use attributes (); # optional, to get subroutine declarations
my @attrlist = attributes::get(\&foo);
use attributes 'get'; # import the attributes::get subroutine
my @attrlist = get \&foo;
DESCRIPTION
Subroutine declarations and definitions may optionally have attrib
+ute
lists associated with them. (Variable "my" declarations also may,
+but
see the warning below.) Perl handles these declarations by passing
+ some
information about the call site and the thing being declared along
+ with
the attribute list to this module. In particular, the first exampl
+e
above is equivalent to the following:
use attributes __PACKAGE__, \&foo, 'method';
The second example in the synopsis does something equivalent to th
+is:
use attributes __PACKAGE__, \$x, 'Bent';
use attributes __PACKAGE__, \@y, 'Bent';
use attributes __PACKAGE__, \%z, 'Bent';
Yes, that's three invocations.
WARNING: attribute declarations for variables are an *experimental
+*
feature. The semantics of such declarations could change or be rem
+oved
in future versions. They are present for purposes of experimentati
+on
with what the semantics ought to be. Do not rely on the current
implementation of this feature.
There are only a few attributes currently handled by Perl itself (
+or
directly by this module, depending on how you look at it.) However
+,
package-specific attributes are allowed by an extension mechanism.
+ (See
the section on "Package-specific Attribute Handling" below.)
The setting of attributes happens at compile time. An attempt to s
+et an
unrecognized attribute is a fatal error. (The error is trappable,
+but it
still stops the compilation within that "eval".) Setting an attrib
+ute
with a name that's all lowercase letters that's not a built-in att
+ribute
(such as "foo") will result in a warning with -w or "use warnings
'reserved'".
Built-in Attributes
The following are the built-in attributes for subroutines:
locked
Setting this attribute is only meaningful when the subroutine
+or
method is to be called by multiple threads. When set on a meth
+od
subroutine (i.e., one marked with the method attribute below),
+ Perl
ensures that any invocation of it implicitly locks its first
argument before execution. When set on a non-method subroutine
+, Perl
ensures that a lock is taken on the subroutine itself before
execution. The semantics of the lock are exactly those of one
explicitly taken with the "lock" operator immediately after th
+e
subroutine is entered.
method
Indicates that the referenced subroutine is a method. This has
+ a
meaning when taken together with the locked attribute, as desc
+ribed
there. It also means that a subroutine so marked will not trig
+ger
the "Ambiguous call resolved as CORE::%s" warning.
lvalue
Indicates that the referenced subroutine is a valid lvalue and
+ can
be assigned to. The subroutine must return a modifiable value
+such
as a scalar variable, as described in the perlsub manpage.
There are no built-in attributes for anything other than subroutin
+es.
Available Subroutines
The following subroutines are available for general use once this
+module
has been loaded:
get This routine expects a single parameter--a reference to a subr
+outine
or variable. It returns a list of attributes, which may be emp
+ty. If
passed invalid arguments, it uses die() (via Carp::croak) to r
+aise a
fatal exception. If it can find an appropriate package name fo
+r a
class method lookup, it will include the results from a
"FETCH_*type*_ATTRIBUTES" call in its return list, as describe
+d in
the section on "Package-specific Attribute Handling" below.
Otherwise, only built-in attributes will be returned.
reftype
This routine expects a single parameter--a reference to a subr
+outine
or variable. It returns the built-in type of the referenced
variable, ignoring any package into which it might have been
blessed. This can be useful for determining the *type* value w
+hich
forms part of the method names described in the section on
"Package-specific Attribute Handling" below.
Note that these routines are *not* exported by default.
Package-specific Attribute Handling
WARNING: the mechanisms described here are still experimental. Do
+not
rely on the current implementation. In particular, there is no pro
+vision
for applying package attributes to 'cloned' copies of subroutines
+used
as closures. (See the section on "Making References" in the perlre
+f
manpage for information on closures.) Package-specific attribute
handling may change incompatibly in a future release.
When an attribute list is present in a declaration, a check is mad
+e to
see whether an attribute 'modify' handler is present in the approp
+riate
package (or its @ISA inheritance tree). Similarly, when
"attributes::get" is called on a valid reference, a check is made
+for an
appropriate attribute 'fetch' handler. See the section on "EXAMPLE
+S" to
see how the "appropriate package" determination works.
The handler names are based on the underlying type of the variable
+ being
declared or of the reference passed. Because these attributes are
associated with subroutine or variable declarations, this delibera
+tely
ignores any possibility of being blessed into some package. Thus,
+a
subroutine declaration uses "CODE" as its *type*, and even a bless
+ed
hash reference uses "HASH" as its *type*.
The class methods invoked for modifying and fetching are these:
FETCH_*type*_ATTRIBUTES
This method receives a single argument, which is a reference t
+o the
variable or subroutine for which package-defined attributes ar
+e
desired. The expected return value is a list of associated
attributes. This list may be empty.
MODIFY_*type*_ATTRIBUTES
This method is called with two fixed arguments, followed by th
+e list
of attributes from the relevant declaration. The two fixed arg
+uments
are the relevant package name and a reference to the declared
subroutine or variable. The expected return value as a list of
attributes which were not recognized by this handler. Note tha
+t this
allows for a derived class to delegate a call to its base clas
+s, and
then only examine the attributes which the base class didn't a
+lready
handle for it.
The call to this method is currently made *during* the process
+ing of
the declaration. In particular, this means that a subroutine
reference will probably be for an undefined subroutine, even i
+f this
declaration is actually part of the definition.
Calling "attributes::get()" from within the scope of a null packag
+e
declaration "package ;" for an unblessed variable reference will n
+ot
provide any starting package name for the 'fetch' method lookup. T
+hus,
this circumstance will not result in a method call for package-def
+ined
attributes. A named subroutine knows to which symbol table entry i
+t
belongs (or originally belonged), and it will use the correspondin
+g
package. An anonymous subroutine knows the package name into which
+ it
was compiled (unless it was also compiled with a null package
declaration), and so it will use that package name.
Syntax of Attribute Lists
An attribute list is a sequence of attribute specifications, separ
+ated
by whitespace or a colon (with optional whitespace). Each attribut
+e
specification is a simple name, optionally followed by a parenthes
+ised
parameter list. If such a parameter list is present, it is scanned
+ past
as for the rules for the "q()" operator. (See the section on "Quot
+e and
Quote-like Operators" in the perlop manpage.) The parameter list i
+s
passed as it was found, however, and not as per "q()".
Some examples of syntactically valid attribute lists:
switch(10,foo(7,3)) : expensive
Ugly('\(") :Bad
_5x5
locked method
Some examples of syntactically invalid attribute lists (with
annotation):
switch(10,foo() # ()-string not balanced
Ugly('(') # ()-string not balanced
5x5 # "5x5" not a valid identifier
Y2::north # "Y2::north" not a simple identif
+ier
foo + bar # "+" neither a colon nor whitespa
+ce
EXPORTS
Default exports
None.
Available exports
The routines "get" and "reftype" are exportable.
Export tags defined
The ":ALL" tag will get all of the above exports.
EXAMPLES
Here are some samples of syntactically valid declarations, with
annotation as to how they resolve internally into "use attributes"
invocations by perl. These examples are primarily useful to see ho
+w the
"appropriate package" is found for the possible method lookups for
package-defined attributes.
1. Code:
package Canine;
package Dog;
my Canine $spot : Watchful ;
Effect:
use attributes Canine => \$spot, "Watchful";
2. Code:
package Felis;
my $cat : Nervous;
Effect:
use attributes Felis => \$cat, "Nervous";
3. Code:
package X;
sub foo : locked ;
Effect:
use attributes X => \&foo, "locked";
4. Code:
package X;
sub Y::x : locked { 1 }
Effect:
use attributes Y => \&Y::x, "locked";
5. Code:
package X;
sub foo { 1 }
package Y;
BEGIN { *bar = \&X::foo; }
package Z;
sub Y::bar : locked ;
Effect:
use attributes X => \&X::foo, "locked";
This last example is purely for purposes of completeness. You shou
+ld not
be trying to mess with the attributes of something in a package th
+at's
not your own.
SEE ALSO
the section on "Private Variables via my()" in the perlsub manpage
+ and
the section on "Subroutine Attributes" in the perlsub manpage for
details on the basic declarations; the attrs manpage for the obsol
+escent
form of subroutine attribute specification which this module repla
+ces;
the use entry in the perlfunc manpage for details on the normal
invocation mechanism.
___crazyinsomniac_______________________________________
Disclaimer: Don't blame. It came from inside the void
perl -e "$q=$_;map({chr unpack qq;H*;,$_}split(q;;,q*H*));print;$q/$q;" |