poet::import(3pm) [debian man page]

Poet::Import(3pm)					User Contributed Perl Documentation					 Poet::Import(3pm)

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

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.

perl v5.14.2							    2012-06-05							 Poet::Import(3pm)

Poet::Environment(3pm)					User Contributed Perl Documentation				    Poet::Environment(3pm)

NAME

       Poet::Environment -- Poet environment

SYNOPSIS

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

	   # In a module...
	   use Poet qw($poet);

	   # $poet is automatically available in Mason components

	   # then...
	   my $root_dir       = $poet->root_dir;
	   my $file	      = $poet->path("some/file.txt");
	   my $path_to_script = $poet->bin_path("foo/bar.pl");
	   my $path_to_lib    = $poet->lib_path("Foo/Bar.pm");

DESCRIPTION

       The Poet::Environment object contains information about the current environment and its directory paths.

PATH METHODS

       root_dir
	   Returns the root directory of the environment, i.e. where .poet_root is located.

       path (subpath)
	   Returns the root directory with a relative subpath added. e.g. if the Poet environment root is "/my/env/root", then

	       $poet->path("somefile.txt");
		  ==> returns /my/env/root/somefile.txt

       bin_dir
       comps_dir
       conf_dir
       data_dir
       db_dir
       lib_dir
       logs_dir
       static_dir
	   Returns the specified subdirectory, which by default will be just below the root dirctory. e.g. if the Poet environment root is
	   "/my/env/root", then

	       $poet->conf_dir
		  ==> returns /my/env/root/conf

	       $poet->lib_dir
		  ==> returns /my/env/root/lib

       bin_path (subpath)
       comps_path (subpath)
       conf_path (subpath)
       data_path (subpath)
       db_path (subpath)
       lib_path (subpath)
       logs_path (subpath)
       static_path (subpath)
	   Returns the specified subdirectory with a relative subpath added. e.g. if the Poet environment root is "/my/env/root", then

	       $poet->conf_path("log4perl.conf");
		  ==> returns /my/env/root/conf/log4perl.conf

	       $poet->lib_path("Data/Type.pm");
		  ==> returns /my/env/root/lib/Data/Type.pm

OTHER METHODS

       app_class
	   Returns the full class name to use for the specified class, depending on whether there is a subclass in the environment. e.g.

	       $poet->app_class('Cache')

	   will return "MyApp::Cache" if that module exists, and otherwise "Poet::Cache".  This is used internally by Poet to implement auto
	   subclassing.

       app_name
	   Returns the app name, e.g. 'MyApp', found in .poet_root.

       conf
	   Returns the Poet::Conf object associated with the environment.  Usually you'd access this by importing $conf.

       current_env
	   A class method that returns the current (singleton) environment for the process. Usually you'd access this by importing $poet.

OBTAINING $poet SINGLETON
       In a script:

	   use Poet::Script qw($poet);

       In a module:

	   use Poet qw($poet);

       $poet is automatically available in components.

       You can also get it via

	   my $poet = Poet::Environment->current_env;

CONFIGURING ENVIRONMENT SUBDIRECTORIES

       Any subdirectories other than conf_dir can be overridden in configuration. e.g.

	   # Override bin_dir
	   env.bin_dir: /some/other/bin/dir

       With this configuration in place,

	   $poet->bin_dir
	      ==> returns /some/other/bin/dir

	   $poet->bin_path("foo/bar.pl")
	      ==> returns /some/other/bin/dir/foo/bar.pl

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.

perl v5.14.2							    2012-06-14						    Poet::Environment(3pm)