Config::INIPlus - Read and write INIPlus config files
Version 1.0.0
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.
; 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.
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.
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
Provide a means of escaping quotes in multi-line values
Preserve comments / whitespace when writing files
Preserve key-value pair order
Anthony Kilna, <anthony at kilna dot 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 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.
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
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.