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.