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.