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.