Provided by: libpoet-perl_0.16-1_all bug


       Poet::Conf -- Poet configuration


           # 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


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


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


       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.


       Basic conf file format is YAML <>, e.g.

              driver: Memcached
              servers: ["", ""]

              level: info
              output: poet.log
              layout: "%d{dd/MMM/yyyy:HH:mm:ss.SS} [%p] %c - %m - %F:%L - %P%n"

   Interpolation - referring to other entries
       Conf entries can refer to other entries via the syntax "${key}". For example:

          # conf file

          foo: 5
          bar: "The number ${foo}"
          baz: ${bar}00

          # then

             => 5
             => "The number 5"
             => "The number 500"

       The key must exist or a fatal error will occur.

       There is a single built-in entry, "root_dir", containing the root directory of the
       environment that you can use in other entries, e.g.

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

   Dot notation for hash access
       Conf entries can use dot (".") notation to refer to hash entries. e.g. this


       is the same as

                baz: 5

       The dot notation is especially useful for overriding individual hash elements from higher
       precedence config files. For example, if in "global/cache.cfg" you have

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

       and in local.cfg you have

           cache.defaults.depth: 2

       then only "depth" will be overridden; the "driver" and "root_dir" will remain as they were
       set in "global/cache.cfg". If instead local.cfg had

                depth: 3

       then this would completely replace the entire hash under "cache".


       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 for getting conf values
       get (key[, default])
               my $value = $conf->get('key' => 'default');

           Get key from configuration. If key is unavailable, return the default, or undef if no
           default is given.

           The return value may be a scalar, list reference, or hash reference, though we
           recommend using "get_list" and "get_hash" if you expect a list or hash.

           key can contain dot notation to refer to hash entries. e.g. these are equivalent:



       get_or_die (key)
               my $value = $conf->get_or_die('key');

           Get key from configuration. If key is unavailable, throw a fatal error.

       get_list (key[, default])
               my $listref = $conf->get_list('key', ['default']);

           Get key from configuration. If the value is not a list reference, throw an error.

           If key is unavailable, return the default, or an empty list reference if no default is

       get_hash (key[, default])
               my $hashref = $conf->get_hash('key', {'default' => 5});

           Get key from configuration. If the value is not a hash reference, throw an error.

           If key is unavailable, return the default, or an empty hash reference if no default is

       get_boolean (key)
               my $bool = $conf->get_boolean('key');

           Get key from configuration. Return 1 if the value represents true ("1", "t", "true",
           "y", "yes") and 0 if the value represents false ("0", "f", "false", "n", "no") or is
           not present in configuration. These are case insensitive matches. Throws an error if
           there is a value that is a reference or does not match one of the valid options.

       get_secure (key)
               my $password = $conf->get_secure('secret_password');

           Get key from a separate, non-version-controlled, secure config file; if it cannot be
           found, then fallback to normal config. Useful for passwords, encryption keys, etc.
           that might be ok in normal config on development, but ought to be secure on

           The location of the secure config file is determined by config entry
           conf.secure_conf_file; it defaults to "conf/secure.cfg". The file is in plain YAML
           format, with no interpolation or dot notation.

   Other methods
           Returns the current layer, as determined from "local.cfg".

           Boolean; returns true iff the current layer is 'development'.

           Boolean; the opposte of "is_development".

               my @keys = sort $conf->get_keys;

           Return a list of all keys in configuration.

               my $hash = $conf->as_hash;

           Return a hash reference mapping keys to their value as returned by "$conf->get".

               print $conf->as_string;

           Return a printable representation of the keys and values.

               my $lex = $conf->set_local({key => 'value', ...});

           Temporarily set each key to value. The original value will be restored when $lex goes
           out of scope.

           This is intended for specialized use in unit tests and development tools, NOT for
           production code. Setting and resetting of configuration values will make it much more
           difficult to read and debug code!


           This method can be used to dynamically generate configuration files for external
           software (e.g. Apache, nginx, logrotate). It uses MasonX::ProcessDir to process Mason
           templates in "conf/dynamic" and generate destination files in "data/conf/dynamic".

           For example, if "conf/dynamic/" contains an Apache configuration file
           with Mason dynamic elements, this method will generate a static configuration file in
           "data/conf/dynamic/", which you can then feed directly into Apache.


       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.

           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',

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

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

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

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

           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


       The ideas of merging multiple conf files and variable interpolation came from




       Jonathan Swartz <>


       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.