/ 
Config-INIPlus-1.0.0
River stage zero No dependents
/ Config::INIPlus

NAME

Config::INIPlus - Read and write INIPlus config files

VERSION

Version 1.0.0

SYNOPSIS

INIPlus is a configurtion file format based on INI which supports multi-line strings and nesting of arrays and hashes. This is useful if you start a project using INI files, but realize you need nested data in your configurations and want to do support new extended configurations without breaking backward compatibility.

The INIPlus Config File

; Comment
Key=Value ; End of line comment
Key2="Multi
Line
Value" ; Post-multi-line comment

[Section]
Foo=This is a foo
Hash {
  Bar=Hey it's a bar
  Baz="Is Baz at the bar?"
}
Array (
  Value One
  "Value Two"
  "Value
Three
Is multi-line!"
)

The hashes and arrays can be nested any number of levels deep:

Hash {
  ArrayOfSubhashes (
    {
      Key1=Val1
      Key2=Val2
    }
    {
      HeyAnotherArray (
        Value1
        Value2
        Value3
      )
    }
  )
}

Creating a config object

use Config::INIPlus;

# Create the config object from a file
$cfg = Config::INIPlus->new( file => 'foo.ini' ); 

# Create the config object from a filehandle
$filehandle = IO::File->new('file.ini');
$cfg = Config::INIPlus->new( fh => $filehandle ); 

# Create the config from a string
$string = <<EOF;
Key1=Val1
Key2=Val2
; ...
EOF

$cfg = Config::INIPlus->new( string => $string );

Extracting the contents of a config object

# Gets a non-sectioned value (like "Key2" in the example INI above)
my $val = $cfg->get( 'KeyName' ); 

# Gets a value from a section (e.g., "Foo" under "Section" in
# the example above)
my $val = $cfg->get( 'KeyName', 'SectionName' ); 
                               
# Gets the entire structure as a hash reference
my $hash = $cfg->as_hashref(); 

# Get one section as a hash reference (e.g., "Section" in the
# exampe INI above)
my $sec = $cfg->section_as_hashref( 'SectionName' );

Modifying a config object

# Set a non-sectioned value
$cfg->set( 'KeyName', 'KeyValue' );

# Set a value for a key within a section
$cfg->set( 'KeyName', 'KeyValue', 'SectionName' ); 

# Remove a non-sectioned key (and respective value)
$cfg->del( 'KeyName' );

# Remove a sectioned key
$cfg->del( 'KeyName', 'SectionName' );

# Add a section
$cfg->add_section( 'SectionName' ); 

# Remove a section
$cfg->del_section( 'SectionName' );

Getting the config object as text / writing to a file

# Get the configuration as a string
$string = $cfg->as_string; 

# Write the configuration back into the file it was originally
# read from
$cfg->write;

# Write the configuration to a specific file
$cfg->write( 'filename.ini' );

METHODS

Config::INIPlus->new( file => 'filename' )

Config::INIPlus->new( fh => $perl_filehandle )

Config::INIPlus->new( string => $string_config )

Creates a new config object. You can use a filename with the 'file' paramter, a IO::Handle style filehandle using the 'fh', or pull from the entire INIPlus configuration loaded into a string using the 'string' paramter.

$cfg->as_hashref

Returns the entire INIPlus structure as a reference to a hash.

$cfg->get( name [ , section ] )

Gets the value of a particular entry. For entries within a section, the section name must be provided.

$cfg->set( name, val [ , section ] )

Sets the value of a particular entry. If an existing entry exists it will be overwritten. For entries within a section, the section name must be provided.

$cfg->del( name [ , section ] );

Removes an entry. For entries within a section, the section name must be provided.

$cfg->add_section( section )

Adds a new section.

$cfg->section_exists( section )

Returns true if a section exists, false if it does not.

$cfg->del_section( section )

Removes a section.

$cfg->section_as_hashref( section )

Retrieves a section as a reference to a hash.

$cfg->write( [ $filename ] )

Writes out the configuration to a file to disk. If a filename is provided, the configuration is written to that file. If the object was read from a source filename and no filename is provided to the write method, then the original file is overwritten. The file written will not include the formatting or comments of the original file read by this object.

$cfg->as_string()

Retrieves the configuration as a string. This will not include the formatting or comments of the original file read by this object.

CAVEATS

  • Right now writing will preserve all data, but comments and formatting will be lost

  • Since double quotes are used to contain multi-line strings, they are not allowed in values. This behaviour is different than most other INI parsers

  • Obviously any of the formatting which allows for nested arrays and hashes will not be compatible with existing INI parsers

  • Keys and section names cannot start with an underscore

TODO

  • Provide a means of escaping quotes in multi-line values

  • Preserve comments / whitespace when writing files

  • Preserve key-value pair order

AUTHOR

Anthony Kilna, <anthony at kilna dot com>

BUGS

Please report any bugs or feature requests to bug-config-iniplus at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Config-INIPlus. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc Config::INIPlus

You can also look for information at:

COPYRIGHT & LICENSE

Copyright 2008 Anthony Kilna, all rights reserved.

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

SEE ALSO

  • Config::INI - The most popular module for reading and writing INI files

  • YAML - A non-INI way of reading and writing nested structures into config files