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