- NAME
- SYNOPSIS
- DESCRIPTION
- BUGS
- SEE ALSO

# 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