NAME

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

VERSION

       version 0.029

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
       quite similar to that of Config::Tiny, 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.

PERL VERSION

       This library should run on perls released even a long time ago.  It should work on any
       version of perl released in the last five years.

       Although it may work on older versions of perl, no guarantee is made that the minimum
       required version will not be increased.  The version may be increased for any reason, and
       there is no promise that patches will be accepted to lower the minimum required perl.

METHODS FOR READING CONFIG

       These methods are all that most users will need: they read configuration from a source of
       input, then they return the data extracted from that input.  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 detailed below in the "METHODS FOR SUBCLASSING" section.

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

       All throw an exception when they encounter an error.

   read_file
         my $hash_ref = Config::INI::Reader->read_file($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.

METHODS FOR SUBCLASSING

       These are the methods you need to understand and possibly change when subclassing
       Config::INI::Reader to handle a different format of input.

   current_section
         my $section_name = $reader->current_section;

       This method returns the name of the current section.  If no section has yet been set, it
       returns the result of calling the "starting_section" method.

   parse_section_header
         my $name = $reader->parse_section_header($line, $handle);

       Given a line of input, this method decides whether the line is a section-change
       declaration.  If it is, it returns the name of the section to which to change.  If the
       line is not a section-change, the method returns false.

   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.

   parse_value_assignment
         my ($name, $value) = $reader->parse_value_assignment($line, $handle);

       Given a line of input, this method decides whether the line is a property value
       assignment.  If it is, it returns the name of the property and the value being assigned to
       it.  If the line is not a property assignment, the method returns false.

   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: "_"

   can_ignore
         do_nothing if $reader->can_ignore($line, $handle)

       This method returns true if the given line of input is safe to ignore.  The default
       implementation ignores lines that contain only whitespace or comments.

       This is run after preprocess_line.

   preprocess_line
         $reader->preprocess_line(\$line);

       This method is called to preprocess each line after it's read but before it's parsed.  The
       default implementation just strips inline comments.  Alterations to the line are made in
       place.

   handle_unparsed_line
         $reader->handle_unparsed_line( $line, $handle );

       This method is called when the reader encounters a line that doesn't look like anything it
       recognizes.  By default, it throws an exception.

   finalize
         $reader->finalize;

       This method is called when the reader has finished reading in every line of the file.

   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.

ORIGIN

       Originaly derived from Config::Tiny, by Adam Kennedy.

AUTHOR

       Ricardo Signes <cpan@semiotic.systems>

COPYRIGHT AND LICENSE

       This software is copyright (c) 2007 by Ricardo Signes.

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