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

cpanm Attribute::Universal

perl -MCPAN -e shell
install Attribute::Universal