NAME
Mojar::Config::Ini - Ini-style configuration utility for standalone code
SYNOPSIS
use Mojar::Config::Ini;
my $config = Mojar::Config::Ini->load('cfg/defaults.ini');
say $config->{redis}{ip};DESCRIPTION
A simple configuration file reader for a configuration written as an ini file. Although fairly primitive (essentially everything is a line-bounded string) it is a widespread format.
USAGE
# cfg/defaults.ini
debug = 0
# Comment
# Records without section are treated as section "_"
expiration = 36000
confession = very basic format, but widely used
secrets = "where,wild,things,roam"
port = 8000
[redis]
ip = 192.168.1.1
port = 6379Each line is read separately. Whitespace following the (first) "=" is ignored, as is any whitespace at the end of the line. In the case of duplicates, later records overwrite earlier records.
METHODS
load
$hashref = Mojar::Config->load('path/to/file.cnf');
$hashref = Mojar::Config->load('path/to/file.cnf', log => $log);Loads an ini-style configuration from the given file path. In normal usage, this is the only method required. The result is a plain (unblessed) hashref.
parse
$content = 'testing = 4';
$config = Mojar::Config::Ini->parse(\$content, sections => ':ignore');
say $config->{testing};Does the actual parsing of the configuration, being passed a ref to the configuration text.
PARAMETERS
Both the load and parse methods accept a sections parameter.
sections
Specifies how to handle sections within the configuration file. Records with no section are treated as if given the section _. The default is :all which loads each section into its individual hash key.
->load('cfg/defaults.ini', sections => ':all'); # load configuration
# The config hashref has two keys, with constituent keys below those
# ->{_}{debug} is 0
# ->{redis}{port} is 6379A section spec of ':ignore' loads each record into a unified configuration, as if the section headings were omitted. Beware any duplicates, later records overwrite earlier records.
->load('cfg/defaults.ini', sections => ':ignore'); # load configuration
# The config hashref has seven keys in a flat structure
# ->{debug} is 0
# ->{port} is 6379A section spec of an arrayref of section names loads each record into a unified configuration, absorbing the sections in the order specified.
->load('cfg/defaults.ini', sections => [qw(redis _)]); # load configuration
# The config hashref has seven keys in a flat structure
# ->{debug} is 0
# ->{port} is 8000Whenever practical, order your configuration file sections starting with the most general (eg 'client') and ending with the most specific (eg 'mysqldump'). That leads to a more intuitive order when loading sections; you load your selected sections in the same order.
DEBUGGING
Both methods accept a Mojar::Log/Mojo::Log object in their parameters. If passed a debug-level logger, some debugging statements become available.
my $log = Mojar::Log->new(level => 'debug', path => '/tmp/stuff.log');
my $config = Mojar::Config->new->load('/etc/stuff.conf', log => $log);RATIONALE
There are many modules for tackling these files, but although the format is simple, how it should be handled is not. The key motivator for this module is the sections parameter and its application to MySQL configuration/credentials files. If your software is functioning as a mysql-client, it should load from my.cnf using sections = [qw(client mysql)]>, and similarly when it loads from a .cnf credentials file. You can add custom sections to such files, so you could end up using, for example, sections = [qw(client datafeed)]>.