NAME¶

Poet::Conf -- Poet configuration

SYNOPSIS¶

    # In a script...
    use Poet::Script qw($conf);
    # In a module...
    use Poet qw($conf);
    # $conf is automatically available in Mason components
    # then...
    my $value = $conf->get('key', 'default');
    my $value = $conf->get_or_die('key');
    my $listref = $conf->get_list('key', ['default']);
    my $hashref = $conf->get_hash('key', {'default' => 5});
    my $bool = $conf->get_boolean('key');
    my @keys = grep { /^foo\./ } $conf->get_keys;
    my $hash = $conf->as_hash;
    print $conf->as_string;
    { 
       my $lex = $conf->set_local({'key' => 'new_value'});
       # key has new_value inside this scope only
    }

DESCRIPTION¶

The Poet::Conf object gives access to the current environment's configuration, read from configuration files in the conf/ subdirectory.

CONFIGURATION FILES¶

Poet configuration files are found in the conf/ subdirectory of the environment root:

  conf/
    global.cfg
    global/
      something.cfg
      something_else.cfg
      ...
    layer/
      development.cfg
      production.cfg
      ...
    local.cfg
  $ENV{POET_EXTRA_CONF_FILE}

The files are read and merged in the following order, with later files taking precedence over earlier files. None of the files have to exist except "local.cfg".

• "global.cfg" contains various settings for the environment, typically checked into version control. Having a single file is fine for a simple site and a single developer, but if this gets too unwieldy, see global/ below.
• The "global/" directory contains multiple .cfg files, all of which are read in alphabetical order. This is an alternative to "global.cfg" when the latter gets too crowded and you have multiple developers making simultaneous changes. It is an error for two global files to set the same key.
• The "layer/" directory contains version-controlled files specific to layers, e.g. "development.cfg" and "production.cfg". Only one of these files will be active at a time, depending on the current layer (as set in "local.cfg").
• "local.cfg" contains settings for this particular instance of the environment. It is not checked into version control. local.cfg must exist and must contain at least the layer, e.g.

      layer: development
      

• If $ENV{POET_EXTRA_CONF_FILE} is defined when configuration initializes, it is read as an extra conf file whose values override all others.

CONFIGURATION FORMAT¶

Basic conf file format is YAML <http://www.yaml.org/>, e.g.

   cache:
     defaults:
       driver: Memcached
       servers: ["10.0.0.15:11211", "10.0.0.15:11212"]
   log:
     defaults:
       level: info
       output: poet.log
       layout: "%d{dd/MMM/yyyy:HH:mm:ss.SS} [%p] %c - %m - %F:%L - %P%n"

   # conf file
   foo: 5
   bar: "The number ${foo}"
   baz: ${bar}00
   # then
   
   $conf->get('foo')
      => 5
   $conf->get('bar')
      => "The number 5"
   $conf->get('baz')
      => "The number 500"

   cache:
      defaults:
         driver: File
         root_dir: ${root_dir}/data/cache

   foo.bar.baz: 5

   foo:
      bar:
         baz: 5

   cache:
      defaults:
         driver: File
         root_dir: $root/data/cache
         depth: 3

    cache.defaults.depth: 2

   cache:
      defaults:
         depth: 3

OBTAINING $conf SINGLETON¶

In a script:

    use Poet::Script qw($conf);

In a module:

    use Poet qw($conf);

$conf is automatically available in components.

You can also get it via

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

METHODS¶

MODIFIABLE METHODS¶

These methods are not intended to be called externally, but may be useful to override or modify with method modifiers in subclasses. Their APIs will be kept as stable as possible.

read_conf_data

This is the main method that finds and parses conf files and returns a hash of conf keys to values. You can modify this to dynamically compute certain conf keys:

    override 'read_conf_data' => sub {
        my $hash = super();
        $hash->{complex_key} = ...;
        return $hash;
    };
    

or to completely override how Poet gets its configuration:

    override 'read_conf_data' => sub {
        return {
           some_conf_key => 'some conf value',
           ...
        };
    };
    

initial_conf_data

Returns a hash with initial configuration data before any conf files have been merged in. By default, just contains

    ( root => '/path/to/root' )
    

_build_layer

Determines the current layer before "read_conf" is called. By default, looks for a "layer" key in "local.cfg".

_build_is_development

Determines the value of "is_development", and subsequently its opposite "is_live". By default, true iff layer == 'development'.

ordered_conf_files

Returns a list of conf files to read in order from lowest to highest precedence. You can modify this to insert an additional file, e.g.

    override 'ordered_conf_files' => sub {
        my @list = super();
        return (@list, '/path/to/important.cfg');
    };
    

read_conf_file ($file)

Read a single conf $file and return its hash representation. You can modify this to use a conf format other than YAML, e.g.

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

merge_conf_data ($current_data, $new_data, $file)

Merge $new_data from $file into $current_data. $new_data and $current_data are both hashrefs, and $current_data will be the empty hash for the first file. By default, this just uses Perl's built-in hash merging with values from $new_data taking precedence.

CREDITS¶

The ideas of merging multiple conf files and variable interpolation came from YAML::AppConfig.

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.