Home | Wiki | OI 1.x Docs | OI 2.x Docs |
OpenInteract2::Config::Ini - Read/write INI-style (++) configuration files
my $config = OpenInteract2::Config::Ini->new({ filename => 'myconf.ini' }); print "Main database driver is:", $config->{datasource}{main}{driver}, "\n"; $config->{datasource}{main}{username} = 'mariolemieux'; $config->write_file;
This is a very simple implementation of a configuration file reader/writer that preserves comments and section order, enables multivalue fields, enables multi-line values, and has 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
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 comment = this is the database for mr whitman who \ is not feeling very well as of late
[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', comment => 'this is the database for mr whitman who is not feeling very well as of late', }, 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', }, }, };
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}
new( \%params )
Create a new configuration object. If you pass in 'filename' as a parameter we will parse the file and fill the returned object with its values.
If you pass in raw INI text in the parameter 'content' we try to translate it using the same means as reading a file.
And if you pass in a hashref in the parameter 'struct' we attempt to map its keys and values to the internal format which can then be saved as normal. This will throw an exception if your structures are nested too deeply. For instance, this would be ok:
my $foo = { top_key => { myvalue => 1, yourvalue => [ 'one', 'two' ] }, bottom_key => { other => { mine => '1', yours => 2 }, bell => 'weather' }, };
As it would represent:
[top_key] myvalue = 1 yourvalue = one yourvalue = two
[bottom_key] bell = weather
[bottom_key other] mine = 1 yours = 2
But the following has references nested too deeply:
my $foo = { top_key => { myvalue => 1, yourvalue => [ 'one', 'two' ] }, bottom_key => { other => { mine => { <--- this key's value is too deep zaphod => 'towel', }, yours => { <--- this key's value is too deep abe => 'honest', }, } bell => 'weather', }, };
Returns: a new OpenInteract2::Config::Ini object
as_data()
Get the data back from the object as an unblessed hash reference.
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
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.
Configuration input and output can generate a ton of logging
information, so it uses a separate logging category 'LOG_CONFIG' as
imported from
OpenInteract2::Constants. Set this to
DEBUG
with fair warning...
_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_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"
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.
Chris Winters <chris@cwinters.com>
Generated from the OpenInteract 1.99_04 source.