NAME

ActiveState::Config::INI - Access and edit INI style config files

SYNOPSIS

 use ActiveState::Config::INI;
 my $conf = ActiveState::Config::INI->new( $filename );
 $conf->property($section, $param => $value);
 $conf->save;

DESCRIPTION

The ActiveState::Config::INI class allow INI style configuration files to be accessed and edited safely without rearranging the file or dropping comments. The diff to the file will only affect the lines of properties and sections that has been touched. The existing line ending sequence is preserved regardless of platform.

The INI file dialect that this module support is identical to the one supported by the Config::Tiny module: Lines that start with '#' as the first non-whitespace character are ignored (or introduce commented out parameters). The ' ; ' sequence can be used for trailing comments on parameter values. Quotes have no special meaning in attribute values.

The following methods are provided:

$conf = ActiveState::Config::INI->new
$conf = ActiveState::Config::INI->new( $filename )

This constructs a new ActiveState::Config::INI object and returns it. If a file name is passed in, initialize the object by reading the file.

$conf->read( $filename )

Will initialize the object from the given file. Croaks if the file can't be opened. Any previous state is lost.

No return value.

$conf->write
$conf->write( $filename )

Write the current state back to the given file. The filename can be ommited if the state was previously read from a file. In this case the file will be overwritten.

Croaks if the file can't be opened or if write fails. The file might have been partly overwritten in this case.

No return value.

$conf->content
$conf->content( $buffer )

Without argument returns the content that would be written to the file by $conf->write.

With argument initialize the object from the given buffer. The result is the same as if $conf->read was invoked on a file with $buffer as its content.

$conf->sections

Returns the list of section names used in the file. The section names are returned in the same order as found in configuration file.

There will not be an "" entry (the global section) in the returned list, even though this section can be regarded as always present.

The return value in scalar context is undefined.

$conf->have_section( $section )

Returns TRUE if the given section is present. Disabled sections are still regarded as present.

$conf->add_section( $section, $comment )

Adds the given section to the end of the configuration file. If a comment is provided it's added just before the section in the file. The comment might be multi-lined.

If the section is already present in the configuration file nothing is done. There is no check that the leading comment for the section match the given comment.

$conf->section_enabled( $section )
$conf->section_enabled( $section => $bool )

Get/set the flag that indicate if a section is enabled or not. If set for a section not already present then the section will be automatically added first.

This uses the perlcritic convension of prepending "-" to the section name for disabled sections.

$conf->delete_section( $section )

Removes all the lines from the given section from the configuration file. The removed lines are returned as a list. In scalar context the number of deleted lines is returned.

$conf->properties( $section )

Returns the list of the names of the properties currently in use for the given section. Disabled properties are also included in the list.

The return value in scalar context is undefined.

$conf->property( $section, $param )
$conf->property( $section, $param => $value)
$conf->property( $section, $param => $value, $enabled)

Get/set the given property value. When a property is set then the previous value it had is returned.

If a property value is set it will also become enabled unless $enabled is passed as FALSE or undef. If FALSE is passed the property will be disabled. If undef is passed then the enabledness of the property stay as it was.

Use the empty string as $section to get/set the global property values.

Setting a property to the undef value has the same effect as disabling it; that is $conf->property_enabled( $section, $param, 0 ).

When setting; if the given section is not present it be added first, and if the given property does not exist a line for it will be inserted as the first property of the section.

$conf->_property( $section, $param )

Works like $conf->property but will even return the current value for disabled properties, while $conf->property returns undef for these.

$conf->have_property( $section, $param )

Returns TRUE if the given property is present in the configuration file. Disabled properties are considered present.

$conf->property_enabled( $section, $param )
$conf->property_enabled( $section, $param => $enabled )

Get/set the flag that indicate if the given property is enabled or not.

In the file format disabled properties are commented out by prefixing their line with "# ".

$conf->append_lines( @lines )

Will append the given lines to the configuration file. The passed in strings do not have to be "\n" terminated and they should not have embedded newlines.

$conf->insert_line( $offset, $line )

Inserts the given line into the configuration file at the given position (0-based line number).

$conf->delete_lines( $offset, $length )

Removes the given lines from the configuration file and returns them.

BUGS

Config::Tiny removes "inline comments" (/\s;\s.*/ ) before it tries to recognize section headers or parameters. This cause an incompatiblity with this module which only recognize inline comments in parameter values.

When a new parameter is inserted it's not aligned with the section header indentation. Should not really be a big deal as section headers should not really be indented.

Config::Tiny uses "_" as the name for the global section. This module use "".

SEE ALSO

Config::Tiny http://en.wikipedia.org/wiki/INI_file