Jonathan Swartz > Poet-0.15 > Poet::Import

Download:
Poet-0.15.tar.gz

Dependencies

Annotate this POD

CPAN RT

New  3
Open  2
View/Report Bugs
Module Version: 0.15   Source  

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.

syntax highlighting: