/ 
Exporter-Declare-0.011
River stage two • 12 direct dependents • 53 total dependents
/ Exporter::Declare

NAME

Exporter::Declare - Declarative exports and simple Devel-Declare interface.

DESCRIPTION

Declarative function exporting. You can export subs as usual with @EXPORT, or export anonymous subs under whatever name you want. You can also extend Exporter::Declare very easily.

Exporter-Declare also provides a friendly interface to Devel::Declare magic. With Devel::Declare::Parser and its parser library, you can write Devel::Declare enhanced functions without directly using Devel-Declare.

BASIC SYNOPSIS

If you want to avoid magic you can still easily declare exports:

package MyPackage;
use strict;
use warnings;
use Exporter::Declare;

# works as expected
our @EXPORT = qw/a/;

sub a { 'a' }

# Declare an anonymous export
export b => sub { 'b' };
export( 'c', sub { 'c' });

export 'd';
sub d { 'd' }

1;

ENHANCED INTERFACE SYNOPSIS

Notice, no need for '=> sub', and trailing semicolon is optional.

package MyPackage;
use strict;
use warnings;
use Exporter::Declare;

# Declare an anonymous export
export b { 'b' }

export c {
    'c'
}

1;

EXPORTING DEVEL-DECLARE INTERFACES SYNOPSIS

To export Devel-Declare magic you specify a parser as a second parameter to export(). Please see the PARSERS section for more information about each parser.

package MyPackage;
use strict;
use warnings;
use Exporter::Declare;

export sl sublike {
    # $name and $sub are automatically shifted for you.
    ...
}

export mth method {
    # $name and $sub are automatically shifted for you.
    ...
}

export cb codeblock {
    # $sub is automatically shifted for you.
    ...
}

export beg begin {
    my @args = @_;
    ...
};

# Inject something into the start of the code block
export injected method ( inject => 'my $arg2 = shift; ' ) { ... }

Then to use those in the importing class:

use strict;
use warnings;
use MyPackage;

sl name { ... }

mth name {
    # $self is automatically shifted for you.
    ...
}

cb { ... }

# Same as BEGIN { beg(@args) };
beg( @args );

MANY FACES OF EXPORT

The export() function is the magical interface. It can be used in many forms:

our @EXPORT = @names;

Technically your not actually using the function here, but it is worth noting that use of a package variable '@EXPORT' works just like Exporter. However there is not currently an @EXPORT_OK.

export($name)

Export the sub specified by the string $name. This sub must be defined in the current package.

export($name, sub { ... })
export name => sub { ... }
export name { ... }

Export the coderef under the specified name. In the second 2 forms an ending semicolon is optional, as well name can be quoted in single or double quotes, or left as a bareword.

export( $name, $parser )

Export the sub specified by the string $name, applying the magic from the specified parser whenever the function is called by a class that imports it.

export( $name, $parser, sub { ... })
export name parser { ... }

Export the coderef under the specified name, applying the magic from the specified parser whenever the function is called by a class that imports it. In the second form name and parser can be quoted in single or double quotes, or left as a bareword.

export name ( ... ) { ... }

same as 'export name { ... }' except that parameters can be passed into the parser. Currently you cannot put any variables in the ( ... ) as it will be evaluated as a string outside of any closures - This may be fixed in the future.

Name can be a quoted string or a bareword.

export name parser ( ... ) { ... }

same as 'export name parser { ... }' except that parameters can be passed into the parser. Currently you cannot put any variables in the ( ... ) as it will be evaluated as a string outside of any closures - This may be fixed in the future.

Name and parser can be a quoted string or a bareword.

$class->export( $name )

Method form of 'export( $name )'. $name must be the name of a subroutine in the package $class. The export will be added as an export of $class.

$class->export( $name, sub { ... })

Method form of 'export( $name, \&code )'. The export will be added as an export of $class.

$class->export( $name, $parser )

Method form of 'export( $name, $parser )'. $name must be the name of a subroutine in the package $class. The export will be added as an export of $class.

$class->export( $name, $parser, sub { ... })

Method form of 'export( $name, $parser, \&code )'. The export will be added as an export of $class.

IMPORTER SYNOPSIS

Normal

package MyThing;
use MyThingThatExports;

Import with a prefix

package MyThing;
use MyThingThatExports ':prefix:myprefix';

Import only some subs

package MyThing;
use MyThingThatExports qw/ sub_a sub_b /;

Extending (Writing your own Exporter-Declare)

Doing this will make it so that importing your package will not only import your exports, but it will also make the importing package capable of exporting subs.

package MyExporterDeclare;
use strict;
use warnings;
use Exporter::Declare ':extend';

export my_export export {
    my ( $name, $sub ) = @_;
    export( $name, $sub );
}

PARSERS

Writing custom parsers

See Devel::Declare::Parser

Provided Parsers

Devel::Declare::Parser::Export

Used for functions that export, accepting a name, a parser, and options.

Devel::Declare::Parser::Sublike

Things that act like 'sub name {}'

Devel::Declare::Parser::Method

Same ad Sublike except codeblocks have $self automatically shifted off.

Devel::Declare::Parser::Codeblock

Things that take a single codeblock as an arg. Like defining sub mysub(&) except that you do not need a semicolon at the end.

Devel::Declare::Parser::Begin

Define a sub that works like 'use' in that it runs at compile time (like wrapping it in BEGIN{})

This requires Devel::BeginLift.

AUTHORS

Chad Granum exodist7@gmail.com

COPYRIGHT

Copyright (C) 2010 Chad Granum

Exporter-Declare is free software; Standard perl licence.

Exporter-Declare is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the license for more details.