poet::manual::subclassing(3pm) [debian man page]

Poet::Manual::Subclassing(3pm)				User Contributed Perl Documentation			    Poet::Manual::Subclassing(3pm)

NAME

       Poet::Manual::Subclassing - Customizing Poet with subclasses

DESCRIPTION

       You can subclass the following Poet classes for your application:

	   Poet::Cache
	   Poet::Conf
	   Poet::Log
	   Poet::Mason
	   Poet::Import

       and arrange things so that Poet always uses your subclass instead of its default class.

       Place Poet subclasses under "lib/MyApp/Class.pm" in your environment, where "MyApp" is your app name and "Class" is the class you are
       subclassing minus the "Poet" prefix. A few of these subclasses are generated for you by "poet new".

       For example, to subclass "Poet::Cache":

	   package MyApp::Cache;
	   use Poet::Moose;
	   extends 'Poet::Cache';

	   # put your modifications here

	   1;

       (Note: Poet::Moose is Moose plus a few Poet standards. You could also use plain "Moose" here.)

       Poet will automatically detect, load and use any such subclasses. Internally it uses the app_class environment method whenever it needs a
       classname, e.g.

	   # Do something with MyApp::Cache or Poet::Cache
	   $poet->app_class('Cache')->...

   Subclassing Mason
       As long as you have even a bare-bones "Poet::Mason" subclass, e.g.

	   package MyApp::Mason;
	   use Poet::Moose;
	   extends 'Poet::Mason';

	   1;

       then your Mason subclasses will be autodetected as well, e.g.

	   package MyApp::Mason::Interp;
	   use Moose;
	   extends 'Mason::Interp';
	   # put your modifications here
	   1;

       "poet new" will create the bare-bones subclass for you; it is otherwise harmless.

       See Mason::Manual::Subclasses for more information.

EXAMPLES

   Use INI instead of YAML for config files
	   package MyApp::Conf;
	   use Config::INI;
	   use Moose;
	   extends 'Poet::Conf';

	   override 'read_conf_file' => sub {
	       my ($self, $file) = @_;
	       return Config::INI::Reader->read_file($file);
	   };

   Perform tasks before and after each Mason request
	   package MyApp::Mason::Request;
	   use Moose;
	   extends 'Mason::Request';

	   override 'run' => sub {
	       my $self = shift;

	       # Perform tasks before request
	       my $result = super();
	       # Perform tasks after request

	       return $result;
	   };

   Add Perl code to the top of every compiled component
	   package MyApp::Mason::Compilation;
	   use Moose;
	   extends 'Mason::Compilation';

	   override 'output_class_header' => sub {
		return join("
", super(), 'use Foo;', 'use Bar qw(baz);');
	   };

   Use Log::Dispatch instead of Log4perl for logging
	   package MyApp::Log;
	   use Log::Any::Adapter;
	   use Log::Dispatch;
	   use Moose;
	   extends 'Poet::Log';

	   override 'initialize_logging' => sub {
	       my $log = Log::Dispatch->new( ... );
	       Log::Any::Adapter->set('Dispatch', dispatcher => $log);
	   };

   Add your own $dbh quick var
	   package MyApp::Import
	   use DBI;
	   use Poet::Moose;
	   extends 'Poet::Import';

	   method provide_dbh ($caller, $poet) {
	       $dbh = DBI->connect(...);
	   }

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::Manual::Subclassing(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)