/ 
Attribute-Universal-0.003
River stage one • 1 direct dependent • 1 total dependent
/ Attribute::Universal

NAME

Attribute::Universal - Install attribute handlers directly into UNIVERSAL namespace

VERSION

version 0.003

SYNOPSIS

package Disco;

use Attribute::Universal Loud => 'CODE';

sub ATTRIBUTE {
    my ($package, $symbol, $referent, $attr, $data) = @_;
    # See Attribute::Handlers
}

# Attribute is installed global

sub Noise : Loud {
    ...
}

DESCRIPTION

According to the example above, this module does just this on import:

use Attribute::Handlers;

sub UNIVERSAL::Load : ATTR(CODE) {
    goto &Disco::ATTRIBUTE;
}

Hint: the redefine warning is still enabled.

More than one attribute may be defined at import, with any allowed option:

use Attribute::Universal RealLoud => 'BEGIN,END', TooLoud => 'ANY,RAWDATA';

See Attributes::Handlers for more information about attribute handlers.

FUNCTIONS

import_into

Instead of installing an attribute in UNIVERSAL namespace (which may pollute it) the attributes can also installed directory into a target namespace.

package Producer;

use Attribute::Universal;

sub import {
    my $caller = scalar caller;
    Attribute::Universal->import_into($caller, 'MyAttribute' => 'RAWDATA');
}

sub ATTRIBUTE {
    ...
}

package Consumer;

use Producer;

sub Function : MyAttribute;

to_hash

sub ATTRIBUTE {
    my $hash = Attribute::Universal::to_hash(@_);
}

Its hard to remember what arguments are given to ATTRIBUTE(). This helper function converts the list into a hashref, with these keywords:

  • package

    The package the attribute was used

  • symbol

    The GlobRef to the named symbol or the string LEXICAL.

  • referent

    The reference to the object itself (CodeRef, HashRef, ArrayRef or ScalarRef)

  • attribute

    The name of the attribute

  • payload

    The payload of all attributes, if used more than once. This is an ArrayRef of strings!

  • phase

    The phase the attribute was covered. (BEGIN, CHECK, INIT, END)

  • file

    The filename, if known

  • line

    The linenumber, if known

And these additional keywords:

  • label

    The name of the symbol. Imagine you have:

    sub MyFunction : Attribute;
our $MyScalar : Attribute;

    so label becomes MyFunction and MyScalar

    A lexical symbol cannot have a label.

  • type

    The reftype of the referent (CODE, HASH, ARRAY, SCALAR)

  • sigil

    The sigil by the reftype ($, @, %, c<&>)

    This keyword is available since v0.003

  • name

    The name as sigil plus label (<$scalar>, @array, %hash, &code)

    This keyword is available since v0.003

  • full_name

    The full name as sigil plus package plus label (<$package::scalar>, @package::array, %package::hash, &package::code)

    This keyword is available since v0.003

  • content

    Like payload, but as a forced ArrayRef.

    This keyword is available since v0.003

collect_by_referent

my $collection;
sub ATTRIBUTE {
    my $hash = Attribute::Universal::collect_by_referent($collection, @_);
    # OR
    my $hash = Attribute::Universal::to_hash(@_);
    Attribute::Universal::collect_by_referent($collection, $hash);
}

This helper collects all attributes by the refaddr of the referent and the attribute name:

{
    refaddr($hash->{referent)} => {
        $hash->{attribute} => $hash
    }
}

The major difference is that, the keyword payload is stripped off, but content is grown if the attribute occured more than once at a referent. So after all, content is an ArrayRef holding all payloads together.

This function is available since v0.003

COMPATIBILITY

This module needs a minimum perl version of 5.16 - due to the magic on module import.

BUGS

Please report any bugs or feature requests on the bugtracker website https://github.com/zurborg/libattribute-universal-perl/issues

When submitting a bug or request, please include a test-file or a patch to an existing test-file that illustrates the bug or desired feature.

AUTHOR

David Zurborg <zurborg@cpan.org>

COPYRIGHT AND LICENSE

This software is Copyright (c) 2015 by David Zurborg.

This is free software, licensed under:

The ISC License