Exporter::Tidy

INSTALLATION

To install this module type the following:

perl Makefile.PL make make test make install

Or use CPANPLUS to automate the process.

Module documentation: NAME Exporter::Tidy - Another way of exporting symbols

SYNOPSIS package MyModule::HTTP; use Exporter::Tidy default => [ qw(get) ], other => [ qw(post head) ];

    use MyModule::HTTP qw(:all);
    use MyModule::HTTP qw(:default post);
    use MyModule::HTTP qw(post);
    use MyModule::HTTP _prefix => 'http_', qw(get post);
    use MyModule::HTTP qw(get post), _prefix => 'http_', qw(head);
    use MyModule::HTTP
        _prefix => 'foo', qw(get post),
        _prefix => 'bar', qw(get head);

    package MyModule::Foo;
    use Exporter::Tidy
        default => [ qw($foo $bar quux) ],
        _map    => {
            '$foo' => \$my_foo,
            '$bar' => \$my_bar,
            quux => sub { print "Hello, world!\n" }
        };

    package MyModule::Constants;
    use Exporter::Tidy
        default => [ qw(:all) ],
        _map => {
            FOO     => sub () { 1 },
            BAR     => sub () { 2 },
            OK      => sub () { 1 },
            FAILURE => sub () { 0 }
        };

DESCRIPTION This module serves as an easy, clean alternative to Exporter. Unlike Exporter, it is not subclassed, but it simply exports a custom import() into your namespace.

With Exporter::Tidy, you don't need to use any package global in your
module. Even the subs you export can be lexically scoped.

use Exporter::Tidy LIST The list supplied to “use Exporter::Tidy” should be a key-value list. Each key serves as a tag, used to group exportable symbols. The values in this key-value list should be array references. There are a few special tags:

all       If you don't provide an "all" tag yourself, Tidy::Exporter
          will generate one for you. It will contain all exportable
          symbols.

default   The "default" tag will be used if the user supplies no list to
          the "use" statement.

_map      With _map you should not use an array reference, but a hash
          reference. Here, you can rewrite symbols to other names or
          even define one on the spot by using a reference. You can "foo
          => 'bar'" to export "bar" if "foo" is requested.

Exportable symbols Every symbol specified in a tag’s array, or used as a key in _map’s hash is exportable.

Symbol types You can export subs, scalars, arrays, hashes and typeglobs. Do not use an ampersand (“&”) for subs. All other types must have the proper sigil.

Importing from a module that uses Exporter::Tidy You can use either a symbol name (without the sigil if it is a sub, or with the appropriate sigil if it is not), or a tag name prefixed with a colon. It is possible to import a symbol twice, but a symbol is never exported twice under the same name, so you can use tags that overlap. If you supply any list to the “use” statement, “:default” is no longer used if not specified explicitly.

To avoid name clashes, it is possible to have symbols prefixed. Supply
"_prefix" followed by the prefix that you want. Multiple can be used.

    use Some::Module qw(foo bar), _prefix => 'some_', qw(quux);

imports Some::Module::foo as foo, Some::Module::bar as bar, and
Some::Module::quux as some_quux. See the SYNOPSIS for more examples.

COMPARISON Exporter::Tidy “versus” Exporter

These numbers are valid for my Linux system with Perl 5.8.0. Your
mileage may vary.

Speed Exporting two symbols using no import list (@EXPORT and :default) is approximately 10% faster with Exporter. But if you use any tag explicitly, Exporter::Tidy is more than twice as fast (!) as Exporter.

Memory usage perl -le’require X; print((split “ “, cat /proc/ $/stat)[22])’

 No module       3022848
 Exporter::Tidy  3067904
 Exporter        3084288
 Exporter::Heavy 3174400

Exporter loads Exporter::Heavy automatically when needed. It is needed
to support exporter tags, amongst other things. Exporter::Tidy has all
functionality built into one module.

Both Exporter(::Heavy) and Exporter::Tidy delay loading Carp until it is
needed.

Usage Exporter is subclassed and gets its information from package global variables like @EXPORT, @EXPORT_OK and %EXPORT_TAGS.

Exporter::Tidy exports an "import" method and gets its information from
the "use" statement.

LICENSE This software may be redistributed under the terms of the GPL, LGPL, modified BSD, or Artistic license, or any of the other OSI approved licenses listed at http://www.opensource.org/licenses/alphabetical. Distribution is allowed under all of these licenses, or any smaller subset of multiple or just one of these licenses.

When using a packaged version, please refer to the package metadata to see
under which license terms it was distributed. Alternatively, a distributor
may choose to replace the LICENSE section of the documentation and/or
include a LICENSE file to reflect the license(s) they chose to redistribute
under.

AUTHOR Juerd Waalboer juerd@cpan.org http://juerd.nl/