Anthony Kilna > Config-INIPlus-1.0.0 > Config::INIPlus

Download:
Config-INIPlus-1.0.0.tar.gz

Dependencies

Annotate this POD

View/Report Bugs
Module Version: 1.0.0   Source   Latest Release: Config-INIPlus-v1.0.3

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 ^

TODO ^

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 ^

syntax highlighting: