NAME

Attribute::Exporter

SYNOPSIS

In module YourModule.pm

        package YourModule;
        use base qw(Attribute::Exporter);

        sub your_exported_sub :export_def {
                # will be exported into caller's symbol table
        }

        sub your_export_ok_sub :export_ok {
                # may be imported into caller's symbol table with:
                #        use YourModule qw/your_export_ok_sub/;
        }

        sub your_export_tag_sub :export_tag(tag) {
                # may be imported into caller's symbol table with:
                #        use YourModule qw/:tag/;
        }

        our $your_exported_scalar :export_ok = 1;

DESCRIPTION

The Attribute::Exporter module adds attributes which control how your package exports symbols into calling package symbol tables.

How to export

Subroutines, arrays, hashes, scalars and typeglobs may be exported by setting their attributes. The following attributes are currently supported:

export_def

This attribute will export the corresponding reference by default.

export_ok

This attribute will allow callers to specify they wish to import the symbol.

export_tag(tag)

This attribute will add the reference to a list of items to be exported to the callers namespace when they request to import of ":tag", specifying export_tag(tag1,tag2) will add the symbol to both sets tag1 and tag2.

How to import

Files which want to import your package's symbols into their namespace can do so via the following mechanisms:

use YourModule;

This will import any of YourModule's symbols created with the :export_def attribute.

use YourModule qw/your_export_ok_sub/;

This will import the list of symbols specified on the 'use YourModule' line. It will not import the :export_def symbols unless they have been requested. If you want the full :export_def set as well as specific additional symbols you can ask for qw/:DEFAULT your_export_ok_sub/

use YourModule ();

This will not import any symbols.

Exporting constants

Currently perl's syntax does not support specifying attributes on a use constant line. Instead you can explicitly:

use constant SOME_CONSTANT => 'some constant'; __PACKAGE__->export_constant('SOME_CONSTANT');

Or:

use constant SOME_CONSTANT => 'some constant'; __PACKAGE__->export_constant(\&SOME_CONSTANT);

Special modes

Attribute::Exporter currently supports 2 additional modes of operation, Verbose mode and Indirect mode.

Verbose mode

Verbose mode will print to STDERR some information about what symbols are being exported and where. It is enabled thus:

        BEGIN {
                $Attribute::Exporter::Verbose = 1;
        }

Indirect mode

Indirect mode creates symbols in the importing package's namespace but does not link them directly but instead creates an indirection layer. This means that if the exporting package is reloaded the importing package will be able to access the reloaded symbols rather than the symbols found on first invocation.

Indirect mode is enabled by setting:

        BEGIN {
                $Attribute::Exporter::use_indirection = 1; 
        }

n.b. Indirect mode is currently only supported for CODE and SCALAR data types although support for ARRAY and HASH is straighforward to add.

AUTHOR

Andrew Wansink <ajwans@opera.com>

COPYRIGHT AND LICENSE

This library is made available under the same terms as Perl itself.