NAME

Config::INI::Reader - a subclassable .ini-file parser

VERSION

version 0.004

 $Id: /my/cs/projects/Config-INI-Reader/trunk/lib/Config/INI/Reader.pm 31646 2007-05-13T00:33:50.864885Z rjbs  $

SYNOPSIS

If family.ini contains:

  admin = rjbs

  [rjbs]
  awesome = yes
  height = 5' 10"

  [mj]
  awesome = totally
  height = 23"

Then when your program contains:

  my $hash = Config::INI::Reader->read_file('family.ini');

$hash will contain:

  {
    '_'  => { admin => 'rjbs' },
    rjbs => {
      awesome => 'yes',
      height  => q{5' 10"},
    },
    mj   => {
      awesome => 'totally',
      height  => '23"',
    },
  }

DESCRIPTION

Config::INI::Reader is yet another config module implementing yet another slightly different take on the undeniably easy to read ".ini" file format. Its default behavior is nearly identical to that of the Config::Tiny manpage, on which it is based.

The chief difference is that Config::INI::Reader is designed to be subclassed to allow for side-effects and self-reconfiguration to occur during the course of reading its input.

SUBCLASSING

There are three reader methods, read_string, read_file, and read_handle. The first two are implemented in terms of the third. It iterates over lines in a file, calling methods on the reader when events occur. Those events are either change_section, which occurs when a [section] line is read; or set_value, which occurs when a value assignment is read.

All of the reader methods return an unblessed reference to a hash.

All throw an exception when they encounter an error.

METHODS

read_file

  my $hash_ref = Config::INI::Reader->read($filename);

Given a filename, this method returns a hashref of the contents of that file.

read_string

  my $hash_ref = Config::INI::Reader->read_string($string);

Given a string, this method returns a hashref of the contents of that string.

read_handle

  my $hash_ref = Config::INI::Reader->read_handle($io_handle);

Given an IO::Handle, this method returns a hashref of the contents of that handle.

change_section

  $reader->change_section($section_name);

This method is called whenever a section change occurs in the file.

The default implementation is to change the current section into which data is being read and to initialize that section to an empty hashref.

set_value

  $reader->set_value($name, $value);

This method is called whenever an assignment occurs in the file. The default behavior is to change the value of the named property to the given value.

starting_section

  my $section = Config::INI::Reader->starting_section;

This method returns the name of the starting section. The default is: _

new

  my $reader = Config::INI::Reader->new;

This method returns a new reader. This generally does not need to be called by anything but the various read_* methods, which create a reader object only ephemerally.

TODO

• more tests
• Config::INI::Writer, I guess

AUTHOR

Ricardo SIGNES, <rjbs@cpan.org>

Based on the Config::Tiny manpage, by Adam Kennedy.

BUGS

Bugs should be reported via the CPAN bug tracker at

http://rt.cpan.org/NoAuth/ReportBug.html

For other issues, or commercial enhancement or support, contact the author.

COPYRIGHT

Copyright 2007 Ricardo Signes, all rights reserved.

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