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::Mason(3pm)					User Contributed Perl Documentation					  Poet::Mason(3pm)

NAME

       Poet::Mason -- Mason settings and enhancements for Poet

SYNOPSIS

	   # In a conf file...
	   mason:
	     plugins:
	       - Cache
	       - TidyObjectFiles
	       - +My::Mason::Plugin
	     static_source: 1
	     static_source_touch_file: ${root}/data/purge.dat

	   # Get the main Mason instance
	   my $mason = Poet::Mason->instance();

	   # Create a new Mason object
	   my $mason = Poet::Mason->new(...);

DESCRIPTION

       This is a Poet-specific Mason subclass. It sets up sane default settings, maintains a main Mason instance for handling web requests, and
       adds Poet-specific methods to $m (the Mason request object).

CLASS METHODS

       get_options
	   Returns a hash of Mason options by combining default settings and configuration.

       instance
	   Returns the main Mason instance used for web requests, which is created with options from get_options.

       new Returns a new main Mason object, using options from get_options. Unless you specifically need a new object, you probably want to call
	   instance.

DEFAULT SETTINGS

       o   "comp_root" is set to $poet->comps_dir, by default the "comps" subdirectory under the environment root.

       o   "data_dir" is set to $poet->data_dir, by default the "data" subdirectory under the environment root.

       o   "plugins" is set to include Cache, HTMLFilters and RouterSimple.

       o   "cache_root_class" (a parameter of the "Cache" plugin) is set to "MyApp::Cache" if it exists (replacing "MyApp" with your app name),
	   otherwise "Poet::Cache".

CONFIGURATION

       The Poet configuration entry 'mason', if any, will be treated as a hash of options that supplements and/or overrides the defaults above. If
       the hash contains 'extra_plugins', these will be added to the default plugins. e.g.

	   mason:
	     static_source: 1
	     static_source_touch_file: ${root}/data/purge.dat
	     extra_plugins:
		- AnotherFavoritePlugin

QUICK VARS AND UTILITIES

       Poet inserts the following line at the top of of every compiled Mason component:

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

       which means that $conf, $poet, and web utilities are available from every component.

NEW REQUEST METHODS

       Under Poet these additional web-related methods are available in the Mason request object, accessible in components via $m or elsewhere via
       "Mason::Request->current_request".

       req ()
	   A reference to the Plack::Request object. e.g.

	       my $user_agent = $m->req->headers->header('User-Agent');

       res ()
	   A reference to the Plack::Response object. e.g.

	       $m->res->content_type('text/plain');

       abort (status)
       clear_and_abort (status)
	   These methods are overridden to set the response status before aborting, if status is provided. e.g. to send back a FORBIDDEN result:

	       $m->clear_and_abort(403);

	   This is equivalent to

	       $m->res->status(403);
	       $m->clear_and_abort();

	   If a status is not provided, the methods work just as before.

       redirect (url[, status])
	   Sets headers and status for redirect, then clears the Mason buffer and aborts the request. e.g.

	       $m->redirect("http://somesite.com", 302);

	   is equivalent to

	       $m->res->redirect("http://somesite.com", 302);
	       $m->clear_and_abort();

       not_found ()
	   Sets the status to 404, then clears the Mason buffer and aborts the request.  e.g.

	       $m->not_found();

	   is equivalent to

	       $m->clear_and_abort(404);

       session
	   A shortcut for "$m->req->session", the Plack session.  This is simply a persistent hash that you can read from and write to. It is tied
	   to the user's browser session via cookies and stored in a file cache in the data directory (by default).

	       my $value = $m->session->{key};
	       $m->session->{key} = { some_complex => ['value'] };

       send_json ($data)
	   Output the JSON-encoded $data, set the content type to "application/json", and abort. e.g.

	       method handle {
		   my $data;
		   # compute data somehow
		   $m->send_json($data);
	       }

	   "send_json" is a shortcut for

	       $m->clear_buffer;
	       $m->print(JSON::XS::encode_json($data));
	       $m->res->content_type("application/json");
	       $m->abort();

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::Mason(3pm)