NAME

Poet::Import -- Import Poet quick vars and utilities

SYNOPSIS

    # In a script...
    use Poet::Script qw($conf $poet $log :file);

    # In a module...
    use Poet qw($conf $poet $log :file);

DESCRIPTION

Poet makes it easy to import certain variables (known as "quick vars") and utility sets into any script or module in your environment.

In a script:

    use Poet::Script qw(...);

and in a module:

    use Poet qw(...);

where ... contains one or more quick var names (e.g. $conf, $poet) and/or utility tags (e.g. :file, :web).

(Note that use Poet::Script is also necessary for initializing the environment, even if you don't care to import anything, whereas use Poet has no effect other than importing.)

QUICK VARS

Here is the built-in list of quick vars you can import. Some of the variables are singletons, and some of them are specific to each package they are imported into.

$poet

The global environment object, provided by Poet::Environment. This provides information such as the root directory and paths to subdirectories.

For backward compatibility this is also available as $env.

$conf

The global configuration object, provided by Poet::Conf.

$cache

The cache for the current package, provided by Poet::Cache.

$log

The logger for the current package, provided by Poet::Log.

UTILITIES

Default utilities

The utilities in Poet::Util::Debug are always imported, with no tag necessary.

:file

This tag imports all the utilities in Poet::Util::File.

:web

This tag imports all the utilities in Poet::Util::Web. It is automatically included in all Mason components.

MASON COMPONENTS

Every Mason component automatically gets this on top:

    use Poet qw($conf $poet :web);

$m->cache and $m->log will get you the cache and log objects for a particular Mason component.

CUSTOMIZING

Adding variables

To add your own variable, define a method called provide_var_varname in MyApp::Import. For example to add a variable $dbh:

    package MyApp::Import;
    use Poet::Moose;
    extends 'Poet::Import';

    method provide_var_dbh ($caller) {
        # Generate and return a dbh.
        # $caller is the package importing the variable.
        # $poet is the current Poet environment.
    }

provide_dbh can return a single global value, or a dynamic value depending on $caller.

Now your scripts and libraries can do

    use Poet::Script qw($dbh);
    use Poet qw($dbh);

Adding utility tags

To add your own utility tag, define a class MyApp::Util::Mytagname that exports a set of functions via the ':all' tag. For example:

    package MyApp::Util::Hash;
    use Hash::Util qw(hash_seed all_keys);
    use Hash::MoreUtils qw(slice slice_def slice_exists);
    
    our @EXPORT_OK = qw(hash_seed all_keys slice slice_def slice_exists);
    our %EXPORT_TAGS = ( 'all' => \@EXPORT_OK );

    1;

Now your scripts and libraries can do

    use Poet::Script qw(:hash);
    use Poet qw(:hash);

Other exports

To export other general things to the calling class, you can override export_to_class, which takes the calling class as its argument. e.g.

    package MyApp::Import;
    use Poet::Moose;
    extends 'Poet::Import';

    before 'export_to_class' => sub {
        my ($self, $class) = @_;
        no strict 'refs';
        %{$class . "::some_name"} = ...;
    }

SEE ALSO

Poet

AUTHOR

Jonathan Swartz <swartz@pobox.com>

COPYRIGHT AND LICENSE

This software is copyright (c) 2012 by Jonathan Swartz.

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 Poet

perl -MCPAN -e shell
install Poet