NAME

Config::Mini - Very simple INI-style configuration parser

SAMPLE CONFIGURATION

In your config file:

  # this is a comment
  # these will go in section [general] which is the default
  foo = bar
  baz = buz
  
  [section1]
  key1 = val1
  key2 = val2
  
  [section2]
  key3 = val3
  key4 = arrayvalue
  key4 = arrayvalue2
  key4 = arrayvalue3
  

USAGE

In your perl code:

use Config::Mini; my $config = Config::Mini->new ('sample.conf'); print "These are the sections which are defined in the config file:\n"; print join "\n", $config->sections();

# will print 'arrayvalue' print $config->section ('section2')->{'key4'}; print $config->section ('section2')->{'__key4'}->[2];

%directives

By default, Config::Mini turns sections into hashes. For instance, the following section:

  [test]
  foo = bar
  foo = bar2
  baz = buz
  

Will be turned into:

  {
    foo   => 'bar',
    baz   => 'buz',
    __foo => [ 'bar', 'bar2' ],
    __baz => [ 'buz' ],
  }
  

When you write your own objects, having this convention is fine. However, you may want to instantiate other objects from CPAN than your own. For example, a Cache::MemCached is constructed like this in Perl:

  $memd = Cache::Memcached->new {
    'servers'            => [ "10.0.0.15:11211", "10.0.0.15:11212", "10.0.0.17:11211" ]
    'debug'              => 0,
    'compress_threshold' => 10_000,
  };
  
  

So having the following config won't do:

  [cache]
  %package = Cache::Memcached
  servers  = 10.0.0.15:11211
  servers  = 10.0.0.15:11212
  servers  = 10.0.0.17:11211
  debug    = 0
  compress_threshold = 10_000

Because Cache::Memcached expects 'servers' to be an array, not a scalar.

In this case, you can do the following:

  [cache]
  %package = Cache::Memcached
  @servers = 10.0.0.15:11211
  @servers = 10.0.0.15:11212
  @servers = 10.0.0.17:11211
  debug    = 0
  compress_threshold = 10_000

This will let Config::Mini know that 'servers' is meant to be an array reference.

If you want, you can also let it know that debug and compress_threshold are just scalars so it doesn't create the '__debug' and '__compress_threshold' attributes, using the dollar symbol:

  [cache]
  %package = Cache::Memcached
  @servers = 10.0.0.15:11211
  @servers = 10.0.0.15:11212
  @servers = 10.0.0.17:11211
  $debug   = 0
  $compress_threshold = 10_000

The only problem now is that your configuration file is seriously starting to look like Perl, so I would recommend using these 'tricks' only where it's 100% necessary.

%include, %package, %constructor

You can use the following commands:

%include /path/to/file

Will include /path/to/file. Relative paths are supported (it will act as if you were chdir'ed to the current config file location), but wildcards at not (well, not yet).

%package My::Package::Name

Will attempt to create an object rather than a file name. For example:

  [database]
  %package = Rose::DB
  %constructor = register_db
  domain   = development
  type     = main
  driver   = mysql
  database = dev_db
  host     = localhost
  username = devuser
  password = mysecret

%constructor constructor_name

Most Perl objects use new() for their constructor method, however sometimes the constructor is called something else. If %constructor is specified, then it will be called instead of new()

%hashref = true

Some folks prefer to construct their objects this way:

  my $object = Foo->new ( { %args } );
  

Instead of

  my $object = Foo->new ( %args );

This directive allows you to accomodate them (Cache::Cache comes to mind). So for example, you'd have:

  [cache]
  %package = Cache::FileCache
  %hashref = true
  namespace = MyNamespace
  default_expires_in = 600

%args = key1 key2 key3

Some modules have constructors where you don't pass a hash, but a simple list of arguments. For example:

    File::BLOB->from_file( 'filename.txt' );
    

In this case, you can do:

  [fileblob]
  %package = File::Blob
  %constructor = from_file
  %args filename
  filename = filename.txt

my $config = Config::Mini->new ($config_file);

Creates a new Config::Mini object.

@config_sections = $config->sections();

Returns a list of section names.

my $hash = $config->section ($section_name);

Returns a hashref (or an object) which represents this config section.

FUNCTIONAL STYLE

If you don't want to use the OO-style, you can use the functions below.

Config::Mini::parse_file ($filename)

Parses config file $filename

Config::Mini::parse_data (@data)

Parses @data

Config::Mini::get ($context, $key)

Returns the value for $key in $context.

Returns the value as an array if the requested value is an array.

Return the first value otherwise.

Config::Mini::instantiate ($context)

If $context is used to describe an object, Config::Mini will try to instantiate it.

If $section contains a "package" attribute, Config::Mini will try to load that package and call a new() method to instantiate the object.

Otherwise, it will simply return a hash reference.

Values can be considered as a scalar or an array. Hence, Config::Mini uses <attribute_name> for scalar values and '__<attribute_name>' for array values.

Config::Mini::select ($regex)

Selects all section entries matching $regex, and returns a list of instantiated objects using instantiate() for each of them.

AUTHOR

Copyright 2006 - Jean-Michel Hiver All rights reserved

This module is free software and is distributed under the same license as Perl itself. Use it at your own risk.

cpanm Config::Mini

perl -MCPAN -e shell
install Config::Mini