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

       Ricardo Signes <cpan@semiotic.systems>

       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.

perl v5.36.0                                       2023-01-21                           Config::INI::Reader(3pm)

       Config::INI::Reader is yetanother config module implementing yetanother 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.

       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.

       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.

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

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

       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.

       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"',
           },
         }

       version 0.029