Config::INIPlus - Read and write INI-style config files with structure extensions
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 support extended configurations without breaking backward compatibility with existing config files.
; 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 ) } ) }
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 );
# 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' );
# 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' );
# 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' );
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.
Returns the entire INIPlus structure as a reference to a hash.
Gets the value of a particular entry. For entries within a section, the section name must be provided.
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.
Removes an entry. For entries within a section, the section name must be provided.
Adds a new section.
Returns true if a section exists, false if it does not.
Returns a list of all of the sections in the file
Removes a section.
Retrieves a section as a reference to a hash.
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.
Retrieves the configuration as a string. This will not include the formatting or comments of the original file read by this object.
There are times when you have existing INI files you need to maintain backward compatibility with, but you need the ability to add richer syntax. If that's the problem you're trying to solve, this module's for you. If you're not, then you'll likely be better served by YAML.
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
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
Anthony Kilna, <anthony at kilna dot com> - http://anthony.kilna.com
<anthony at kilna dot com>
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.
bug-config-iniplus at rt.cpan.org
You can find documentation for this module with the perldoc command.
perldoc Config::INIPlus
You can also look for information at:
RT: CPAN's request tracker
http://rt.cpan.org/NoAuth/Bugs.html?Dist=Config-INIPlus
AnnoCPAN: Annotated CPAN documentation
http://annocpan.org/dist/Config-INIPlus
CPAN Ratings
http://cpanratings.perl.org/d/Config-INIPlus
Search CPAN
http://search.cpan.org/dist/Config-INIPlus
Copyright 2012 Kilna Companies.
This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.
See http://dev.perl.org/licenses/ for more information.
To install Config::INIPlus, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Config::INIPlus
CPAN shell
perl -MCPAN -e shell install Config::INIPlus
For more information on module installation, please visit the detailed CPAN module installation guide.