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 = 6379

Each 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 6379

A 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 6379

A 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 8000

Whenever 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)]>.

SEE ALSO

Mojar::Config, Mojolicious::Plugin::Config.