OpenInteract2 Documentation: 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);

COPYRIGHT

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>

Generated from the OpenInteract 1.99_03 source.