/ 
OpenInteract-1.99_01
River stage zero No dependents
/ OpenInteract2::Config::Ini

NAME

OpenInteract2::Config::Ini - Read/write INI-style (++) configuration files

SYNOPSIS

my $config = OpenInteract2::Config::Ini->new({ filename => 'myconf.ini' });
print "Main database driver is:", $config->{db_info}{main}{driver}, "\n";
$config->{db_info}{main}{username} = 'mariolemieux';
$config->write_file;

DESCRIPTION

This is a very simple implementation of a configuration file reader/writer that preserves comments and section order, enables multivalue fields and one or two-level sections.

Yes, there are other configuration file modules out there to manipulate INI-style files. But this one takes several features from them while providing a very simple and uncluttered interface.

  • From Config::IniFiles we take comment preservation and the idea that we can have multi-level sections like:

    [Section subsection]

  • From Config::Ini and AppConfig we borrow the usage of multivalue keys:

    item = first
item = second

Example

Given the following configuration in INI-style:

[datasource]
default_connection_db = main
db                    = main
db                    = other

[db_info main]
db_owner      =
username      = captain
password      = whitman
dsn           = dbname=usa
db_name       =
driver_name   = Pg
sql_install   =
long_read_len = 65536
long_trunc_ok = 0

[db_info other]
db_owner      =
username      = tyger
password      = blake
dsn           = dbname=britain
db_name       =
driver_name   = Pg
sql_install   =
long_read_len = 65536
long_trunc_ok = 0

You would get the following Perl data structure:

$config = {
  datasource => {
     default_connection_db => 'main',
     db                    => [ 'main', 'other' ],
  },
  db_info => {
     main => {
          db_owner      => undef,
          username      => 'captain',
          password      => 'whitman',
          dsn           => 'dbname=usa',
          db_name       => undef,
          driver_name   => 'Pg',
          sql_install   => undef,
          long_read_len => '65536',
          long_trunc_ok => '0',
     },
     other => {
          db_owner      => undef,
          username      => 'tyger',
          password      => 'blake',
          dsn           => 'dbname=britain',
          db_name       => undef,
          driver_name   => 'Pg',
          sql_install   => undef,
          long_read_len => '65536',
          long_trunc_ok => '0',
     },
  },
};

'Global' Key

Anything under the 'Global' key in the configuration will be available under the configuration object root. For instance:

[Global]
DEBUG = 1

will be available as:

$CONFIG->{DEBUG}

METHODS

Class Methods

new( \%params )

Create a new configuration object. If you pass in 'filename' as a parameter we will try to read it in using read_file(). If you pass in 'content' as a parameter we try to translate it using translate_ini()

Returns: a new OpenInteract2::Config::Ini object

Object Methods

sections()

Returns a list of available sections.

get( $section, [ $sub_section ], $parameter )

Returns the value from $section (and $sub_section, if given) for $parameter.

Returns: value set in config. If called in array context and there are multiple values for $parameter, returns an array. Otherwise returns a simple scalar if there is one value, or an arrayref if multiple values.

set( $section, [ $sub_section ], $parameter, $value )

Set the key/value $parameter/$value pair in the configuration.

Returns: the value set

delete( $section, [ $sub_section ])

Remove the $section (and $sub_section, if given) entirely.

Returns: the value deleted

Input Methods

read_file( $filename )

Reads content from $filename, translates it and puts it into the object.

Returns: the object filled with the content.

translate_ini( \@lines|$content )

Translate the arrayref \@lines or the scalar content from INI format into a Perl data structure.

Returns: the object filled with the content.

read_section_head( $full_section, \@comments )

Splits the section into a section and sub-section, returning a two-item list. Also puts the full section in the object internal order and puts the comments so they can be linked to the section.

Returns: a two-item list with the section and sub-section as elements. If the section is only one-level deep, it is the first and only member.

read_item( $section, $subsection, $parameter, $value )

Reads the value from [$section $subsection] into the object. If the $section is 'Global' we set the $parameter and $value at the root level.

Returns: the value set

set_value( \%values, $parameter, $value )

Sets $parameter to $value in \%values. We do not care where \%values is in the tree.

If a value already exists for $parameter, we make the value of $parameter an arrayref and push $value onto it.

Output Methods

write_file( $filename )

Serializes the INI file (with comments, as applicable) to $filename.

Items from the config object root go into 'Global'.

Returns: the filename to which the INI structure was serialized.

output_section( $section, $sub_section )

Serializes the section $section and $sub_section.

Returns: a scalar suitable for output.

show_item( $parameter, $value )

Serialize the key/value pair.

Returns: "$parameter = $value"

Debugging Note

Because this and other debugging classs can produce so much information, it uses a separate debug switch than the rest of OI. If you want to see debugging from this class, call:

OpenInteract2::Config->SET_DEBUG(1);

SEE ALSO

AppConfig

Config::Ini

Config::IniFiles

COPYRIGHT

Copyright (c) 2001-2003 Chris Winters. All rights reserved.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

AUTHORS

Chris Winters <chris@cwinters.com>