Poet::Conf(3pm) | User Contributed Perl Documentation | Poet::Conf(3pm) |
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:
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".
layer: development
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 entries can refer to other entries via the syntax "${key}". For example:
# 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"
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.
cache: defaults: driver: File root_dir: ${root_dir}/data/cache
Conf entries can use dot (".") notation to refer to hash entries. e.g. this
foo.bar.baz: 5
is the same as
foo: bar: 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
cache: defaults: 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
cache: defaults: 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;
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:
$conf->get('foo.bar.baz'); $conf->get_hash('foo')->{bar}->{baz};
my $value = $conf->get_or_die('key');
Get key from configuration. If key is unavailable, throw a fatal error.
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 given.
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 given.
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.
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 production.
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.
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!
$conf->generate_dynamic_config();
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/httpd.conf.mc" contains an Apache configuration file with Mason dynamic elements, this method will generate a static configuration file in "data/conf/dynamic/httpd.conf.mc", 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.
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', ... }; };
( root => '/path/to/root' )
override 'ordered_conf_files' => sub { my @list = super(); return (@list, '/path/to/important.cfg'); };
use Config::INI; override 'read_conf_file' => sub { my ($self, $file) = @_; return Config::INI::Reader->read_file($file); };
The ideas of merging multiple conf files and variable interpolation came from YAML::AppConfig.
Poet
Jonathan Swartz <swartz@pobox.com>
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.
2015-01-08 | perl v5.20.2 |