.\" Automatically generated by Pod::Man 4.10 (Pod::Simple 3.35) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "Attribute::Storage 3pm" .TH Attribute::Storage 3pm "2018-11-01" "perl v5.28.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" "Attribute::Storage" \- declare and retrieve named attributes about CODE references .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& package My::Package; \& \& use Attribute::Storage; \& \& sub Title :ATTR(CODE) \& { \& my $package = shift; \& my ( $title ) = @_; \& \& return $title; \& } \& \& package main; \& \& use Attribute::Storage qw( get_subattr ); \& use My::Package; \& \& sub myfunc :Title(\*(AqThe title of my function\*(Aq) \& { \& ... \& } \& \& print "Title of myfunc is: ".get_subattr(\e&myfunc, \*(AqTitle\*(Aq)."\en"; .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" This package provides a base, where a package using it can define handlers for particular code attributes. Other packages, using the package that defines the code attributes, can then use them to annotate subs. .PP This is similar to \f(CW\*(C`Attribute::Handlers\*(C'\fR, with the following key differences: .IP "\(bu" 4 \&\f(CW\*(C`Attribute::Storage\*(C'\fR will store the value returned by the attribute handling code, and provides convenient lookup functions to retrieve it later. \&\f(CW\*(C`Attribute::Handlers\*(C'\fR simply invokes the handling code. .IP "\(bu" 4 \&\f(CW\*(C`Attribute::Storage\*(C'\fR immediately executes the attribute handling code at compile-time. \f(CW\*(C`Attribute::Handlers\*(C'\fR defers invocation so it can look up the symbolic name of the sub the attribute is attached to. \f(CW\*(C`Attribute::Storage\*(C'\fR uses B to provide the name of the sub at invocation time, using the name of the underlying \f(CW\*(C`GV\*(C'\fR. .IP "\(bu" 4 \&\f(CW\*(C`Attribute::Storage\*(C'\fR works just as well on anonymous subs as named ones. .IP "\(bu" 4 \&\f(CW\*(C`Attribute::Storage\*(C'\fR is safe to use on code that will be reloaded, because it executes handlers immediately. \f(CW\*(C`Attribute::Handlers\*(C'\fR will only execute handlers at defined phases such as \f(CW\*(C`BEGIN\*(C'\fR or \f(CW\*(C`INIT\*(C'\fR, and cannot reexecute the handlers in a file once it has been reloaded. .SH "ATTRIBUTES" .IX Header "ATTRIBUTES" Each attribute that the defining package wants to define should be done using a marked subroutine, in a way similar to Attribute::Handlers. When a sub in the using package is marked with such an attribute, the code is executed, passing in the arguments. Whatever it returns is stored, to be returned later when queried by \f(CW\*(C`get_subattr\*(C'\fR or \f(CW\*(C`get_subattrs\*(C'\fR. The return value must be defined, or else the attribute will be marked as a compile error for perl to handle accordingly. .PP Only \f(CW\*(C`CODE\*(C'\fR attributes are supported at present. .PP .Vb 7 \& sub AttributeName :ATTR(CODE) \& { \& my $package = shift; \& my ( $attr, $args, $here ) = @_; \& ... \& return $value; \& } .Ve .PP At attachment time, the optional string that may appear within brackets following the attribute's name is parsed as a Perl expression in list context. If this succeeds, the values are passed as a list to the handling code. If this fails, an error is returned to the perl compiler. If no string is present, then an empty list is passed to the handling code. .PP .Vb 1 \& package Defining; \& \& sub NameMap :ATTR(CODE) \& { \& my $package = shift; \& my @strings = @_; \& \& return { map { m/^(.*)=(.*)$/ and ( $1, $2 ) } @strings }; \& } \& \& package Using; \& \& use Defining; \& \& sub somefunc :NameMap("foo=FOO","bar=BAR","splot=WIBBLE") { ... } \& \& my $map = get_subattr("somefunc", "NameMap"); \& # Will yield: \& # { foo => "FOO", \& # bar => "BAR", \& # splot => "WIBBLE" } .Ve .PP Note that it is impossible to distinguish .PP .Vb 2 \& sub somefunc :NameMap { ... } \& sub somefunc :NameMap() { ... } .Ve .PP It is possible to create attributes that do not parse their argument as a perl list expression, instead they just pass the plain string as a single argument. For this, add the \f(CW\*(C`RAWDATA\*(C'\fR flag to the \f(CW\*(C`ATTR()\*(C'\fR list. .PP .Vb 4 \& sub Title :ATTR(CODE,RAWDATA) \& { \& my $package = shift; \& my ( $text ) = @_; \& \& return $text; \& } \& \& sub thingy :Title(Here is the title for thingy) { ... } .Ve .PP To obtain the name of the function to which the attribute is being applied, use the \f(CW\*(C`NAME\*(C'\fR flag to the \f(CW\*(C`ATTR()\*(C'\fR list. .PP .Vb 4 \& sub Callable :ATTR(CODE,NAME) \& { \& my $package = shift; \& my ( $subname, @args ) = @_; \& \& print "The Callable attribute is being applied to $package :: $subname\en"; \& \& return; \& } .Ve .PP When applied to an anonymous function (\f(CW\*(C`sub { ... }\*(C'\fR), the name will appear as \f(CW\*(C`_\|_ANON_\|_\*(C'\fR. .PP Normally it is an error to attempt to apply the same attribute more than once to the same function. Sometimes however, it would make sense for an attribute to be applied many times. If the \f(CW\*(C`ATTR()\*(C'\fR list is given the \f(CW\*(C`MULTI\*(C'\fR flag, then applying it more than once will be allowed. Each invocation of the handling code will be given the previous value that was returned, or \f(CW\*(C`undef\*(C'\fR for the first time. It is up to the code to perform whatever merging logic is required. .PP .Vb 4 \& sub Description :ATTR(CODE,MULTI,RAWDATA) \& { \& my $package = shift; \& my ( $olddesc, $more ) = @_; \& \& return defined $olddesc ? "$olddesc$more\en" : "$more\en"; \& } \& \& sub Argument :ATTR(CODE,MULTI) \& { \& my $package = shift; \& my ( $args, $argname ) = @_; \& \& push @$args, $argname; \& return $args; \& } \& \& sub Option :ATTR(CODE,MULTI) \& { \& my $package = shift; \& my ( $opts, $optname ) = @_; \& \& $opts and exists $opts\->{$optname} and \& croak "Already have the $optname option"; \& \& $opts\->{$optname}++; \& return $opts; \& } \& \& ... \& \& sub do_copy \& :Description(Copy from SOURCE to DESTINATION) \& :Description(Optionally preserves attributes) \& :Argument("SOURCE") \& :Argument("DESTINATION") \& :Option("attrs") \& :Option("verbose") \& { \& ... \& } .Ve .SH "FUNCTIONS" .IX Header "FUNCTIONS" .ie n .SS "$attrs = get_subattrs( $sub )" .el .SS "\f(CW$attrs\fP = get_subattrs( \f(CW$sub\fP )" .IX Subsection "$attrs = get_subattrs( $sub )" Returns a \s-1HASH\s0 reference containing all the attributes defined on the given sub. The sub should either be passed as a \s-1CODE\s0 reference, or as a name in the caller's package. If no attributes are defined, a reference to an empty \s-1HASH\s0 is returned. .PP The returned \s-1HASH\s0 reference is a new shallow clone, the caller may modify this hash arbitrarily without breaking the stored data, or other users of it. .ie n .SS "$value = get_subattr( $sub, $attrname )" .el .SS "\f(CW$value\fP = get_subattr( \f(CW$sub\fP, \f(CW$attrname\fP )" .IX Subsection "$value = get_subattr( $sub, $attrname )" Returns the value of a single named attribute on the given sub. The sub should either be passed as a \s-1CODE\s0 reference, or as a name in the caller's package. If the attribute is not defined, \f(CW\*(C`undef\*(C'\fR is returned. .ie n .SS "$sub = apply_subattrs( @attrs_kvlist, $sub )" .el .SS "\f(CW$sub\fP = apply_subattrs( \f(CW@attrs_kvlist\fP, \f(CW$sub\fP )" .IX Subsection "$sub = apply_subattrs( @attrs_kvlist, $sub )" A utility function to help apply attributes dynamically to the given \s-1CODE\s0 reference. The \s-1CODE\s0 reference is given last so that calls to the function appear similar in visual style to the same applied at compiletime. .PP .Vb 3 \& apply_subattrs \& Title => "Here is my title", \& sub { return $title }; .Ve .PP Is equivalent to .PP .Vb 1 \& sub :Title(Here is my title) { return $title } .Ve .PP except that because its arguments are evaluated at runtime, they can be calculated by other code in ways that the compiletime version cannot. .PP As the attributes are given in a key-value pair list, it is allowed to apply the same attribute multiple times; and the attributes are applied in the order given. The value of each attribute should be a plain string exactly as it would appear between the parentheses. Specifically, if the attribute does not use the \f(CW\*(C`RAWDATA\*(C'\fR flag, it should be a valid perl expression. As this is still evaluated using an \f(CW\*(C`eval()\*(C'\fR call, take care when handling potentially-unsafe or user-supplied data. .ie n .SS "$sub = apply_subattrs_for_pkg( $pkg, @attrs_kvlist, $sub )" .el .SS "\f(CW$sub\fP = apply_subattrs_for_pkg( \f(CW$pkg\fP, \f(CW@attrs_kvlist\fP, \f(CW$sub\fP )" .IX Subsection "$sub = apply_subattrs_for_pkg( $pkg, @attrs_kvlist, $sub )" As \f(CW\*(C`apply_subattrs\*(C'\fR but allows passing a specific package name, rather than using \f(CW\*(C`caller\*(C'\fR. .ie n .SS "%subs = find_subs_with_attr( $pkg, $attrname, %opts )" .el .SS "\f(CW%subs\fP = find_subs_with_attr( \f(CW$pkg\fP, \f(CW$attrname\fP, \f(CW%opts\fP )" .IX Subsection "%subs = find_subs_with_attr( $pkg, $attrname, %opts )" A utility function to find \s-1CODE\s0 references in the given package that have the name attribute applied. The symbol table is checked for the given package, looking for \s-1CODE\s0 references that have the named attribute applied. These are returned in a key-value list, where the key gives the name of the function and the value is a \s-1CODE\s0 reference to it. .PP \&\f(CW$pkg\fR can also be a reference to an array containing multiple package names, which will be searched in order with earlier ones taking precedence over later ones. This, for example, allows for subclass searching over an entire class heirarchy of packages, via the use of mro: .PP .Vb 1 \& %subs = find_subs_with_attr( [ mro::get_linear_isa $class ], $attrname ); .Ve .PP Takes the following named options: .IP "matching => Regexp | \s-1CODE\s0" 8 .IX Item "matching => Regexp | CODE" If present, gives a filter regexp or \s-1CODE\s0 reference to apply to symbol names. .Sp .Vb 2 \& $name =~ $matching \& $matching\->( local $_ = $name ) .Ve .IP "filter => \s-1CODE\s0" 8 .IX Item "filter => CODE" If present, gives a filter \s-1CODE\s0 reference to apply to the function references before they are accepted as results. Note that this allows the possibility that the first match for a given method name to be rejected, while later ones are accepted. .Sp .Vb 1 \& $filter\->( $cv, $name, $package ) .Ve .SH "AUTHOR" .IX Header "AUTHOR" Paul Evans