NAME

Importer::Zim::Cookbook - Cooking imports à la Invader Zim

VERSION

version 0.9.0

RECIPES

All these recipes use zim, the abbreviation for Importer::Zim. If you prefer non-pragma-looking names, suit yourself.

Importing one subroutine

    use zim 'Scalar::Util' => 'blessed';

Importing a few subroutines

    use zim 'List::Util' => qw(any all none notall);

Importing a subroutine with a new name

    use zim 'List::Util' => 'pairs' => { -as => 'kv' };

Importing all subroutines under a tag

    use zim 'Mango::BSON' => ':bson';

Imports 18 subs (as of Mango 1.29), like bson_bin, bson_code, etc.

Importing all subroutines exported by default

    use zim 'Carp';

Imports confess, croak and carp.

Importing a few subroutines (again)

Now with an array ref:

    use zim 'List::Util' => [qw(any all none notall)];

Notice that array refs are supposed to contain only subroutine names. If you put a :tag in there, it will likely fail, just like

    use zim 'Mango::BSON' => [':bson'];

fails with

    ":bson" is not exported by "Mango::BSON" at ...

Importing subroutines with prefixed names

    use zim 'Mango::BSON' => ':bson' => { -prefix => 'mango_' };

Imports subs with names like mango_bson_bin, mango_bson_code, etc.

Checking for minimum version

    use zim 'List::Util' => { -version => '1.33' } => qw(any all none notall);

Importing a subroutine not declared as exported

Because you know what you're doing.

    use zim 'charnames' => { -strict => 0 } => 'vianame';

    use zim 'Sub::Inject' => { -strict => 0 } => 'sub_inject';

    use zim 'String::Truncate' => { -strict => 0 } => 'elide';

There may be good reasons to do that, including

• to create a shortcut to a stable subroutine in other package

• to bypass the lack of @EXPORT_OK or @EXPORT due to the use of exporters which don't set them (like Sub::Exporter).

Importing subroutines with crafted names

    use zim 'Mango::BSON' => ':bson' => {
        -map => sub { s/^(bson_)/\U$1/; $_ }
    };

This time, subs will be imported with names like BSON_bin, BSON_code, etc.

Cherry-picking subroutines to import

All different specifications of symbols to import mentioned above (subroutine names, tags, array refs) can be put together.

    use zim 'Fcntl' => qw(:flock :seek S_ISUID);

    use zim 'Mojo::Util' => [qw(b64_decode b64_encode)], 'trim';

Writing a module with functions to be imported

    package YourModule;
    our @EXPORT_OK = qw(munge frobnicate);

And the users of this module can say

    use zim 'YourModule' => qw(frobnicate);
    frobnicate($left, $right);

Writing a module with many functions to be imported

If there are too many symbols to be imported, for example tens of constants, it is a good idea to provide tags to name useful subsets of the imported symbols.

    package YourModule;
    our @EXPORT_OK   = qw(BIT1 BIT2 BIT3 BIT4 MASK1 MASK2 MASK3);
    our %EXPORT_TAGS = (    #
        bit  => [qw(BIT1 BIT2 BIT3 BIT4)],
        mask => [qw(MASK1 MASK2 MASK3)]
    );

The users of such module can write

    use zim 'YourModule' => qw(:bit :mask);
    $mode = BIT1 | BIT3 | MASK1 | MASK3;

Writing a module with default exports

Default exports are defined at @EXPORT package variables. When exporters were used and imported symbols were not automatically cleaned, default exports were not such a good idea. (Read it: namespace pollution for free.)

One of the best uses for default exports is to hold the list of symbols a user of your module is most likely to want available.

This is the case of "encode" and "decode" subroutines in modules like JSON, JSON::XS, etc.

    use zim 'JSON::XS';

imports encode_json and decode_json, which is probably what you want while writing quick-and-dirty scripts.

From CamelCase to snake_case

    use zim 'Mojo::Util' => 'decamelize';
    use zim 'YAML' => [qw(LoadFile DumpFile)] => { -map => \&decamelize };

WHICH BACKEND?

The short answer to "What Importer::Zim backend should one use?" is Importer::Zim::Lexical.

However Importer::Zim::Lexical requires perl 5.18 or newer, and a compiler will be needed to install the Sub::Inject dependency.

If you got an older perl, you might want to try Importer::Zim::EndOfScope or Importer::Zim::Unit.

If you got no compiler to build XS dependencies, Importer::Zim::EndOfScope may work.

AUTHOR

Adriano Ferreira <ferreira@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2017 by Adriano Ferreira.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

cpanm Importer::Zim

perl -MCPAN -e shell
install Importer::Zim