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);
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.