.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Config::INI::Reader 3pm"
.TH Config::INI::Reader 3pm "2020-12-28" "perl v5.32.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Config::INI::Reader \- a subclassable .ini\-file parser
.SH "VERSION"
.IX Header "VERSION"
version 0.025
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
If \fIfamily.ini\fR contains:
.PP
.Vb 1
\&  admin = rjbs
\&
\&  [rjbs]
\&  awesome = yes
\&  height = 5\*(Aq 10"
\&
\&  [mj]
\&  awesome = totally
\&  height = 23"
.Ve
.PP
Then when your program contains:
.PP
.Vb 1
\&  my $hash = Config::INI::Reader\->read_file(\*(Aqfamily.ini\*(Aq);
.Ve
.PP
\&\f(CW$hash\fR will contain:
.PP
.Vb 11
\&  {
\&    \*(Aq_\*(Aq  => { admin => \*(Aqrjbs\*(Aq },
\&    rjbs => {
\&      awesome => \*(Aqyes\*(Aq,
\&      height  => q{5\*(Aq 10"},
\&    },
\&    mj   => {
\&      awesome => \*(Aqtotally\*(Aq,
\&      height  => \*(Aq23"\*(Aq,
\&    },
\&  }
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Config::INI::Reader is \fIyet another\fR config module implementing \fIyet another\fR
slightly different take on the undeniably easy to read \*(L".ini\*(R" file
format.  Its default behavior is quite similar to that of
Config::Tiny, on which it is based.
.PP
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.
.SH "METHODS FOR READING CONFIG"
.IX Header "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, \f(CW\*(C`read_string\*(C'\fR, \f(CW\*(C`read_file\*(C'\fR, and \f(CW\*(C`read_handle\*(C'\fR.
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 \*(L"\s-1METHODS FOR SUBCLASSING\*(R"\s0 section.
.PP
All of the reader methods return an unblessed reference to a hash.
.PP
All throw an exception when they encounter an error.
.SS "read_file"
.IX Subsection "read_file"
.Vb 1
\&  my $hash_ref = Config::INI::Reader\->read_file($filename);
.Ve
.PP
Given a filename, this method returns a hashref of the contents of that file.
.SS "read_string"
.IX Subsection "read_string"
.Vb 1
\&  my $hash_ref = Config::INI::Reader\->read_string($string);
.Ve
.PP
Given a string, this method returns a hashref of the contents of that string.
.SS "read_handle"
.IX Subsection "read_handle"
.Vb 1
\&  my $hash_ref = Config::INI::Reader\->read_handle($io_handle);
.Ve
.PP
Given an IO::Handle, this method returns a hashref of the contents of that
handle.
.SH "METHODS FOR SUBCLASSING"
.IX Header "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.
.SS "current_section"
.IX Subsection "current_section"
.Vb 1
\&  my $section_name = $reader\->current_section;
.Ve
.PP
This method returns the name of the current section.  If no section has yet
been set, it returns the result of calling the \f(CW\*(C`starting_section\*(C'\fR method.
.SS "parse_section_header"
.IX Subsection "parse_section_header"
.Vb 1
\&  my $name = $reader\->parse_section_header($line, $handle);
.Ve
.PP
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.
.SS "change_section"
.IX Subsection "change_section"
.Vb 1
\&  $reader\->change_section($section_name);
.Ve
.PP
This method is called whenever a section change occurs in the file.
.PP
The default implementation is to change the current section into which data is
being read and to initialize that section to an empty hashref.
.SS "parse_value_assignment"
.IX Subsection "parse_value_assignment"
.Vb 1
\&  my ($name, $value) = $reader\->parse_value_assignment($line, $handle);
.Ve
.PP
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.
.SS "set_value"
.IX Subsection "set_value"
.Vb 1
\&  $reader\->set_value($name, $value);
.Ve
.PP
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.
.SS "starting_section"
.IX Subsection "starting_section"
.Vb 1
\&  my $section = Config::INI::Reader\->starting_section;
.Ve
.PP
This method returns the name of the starting section.  The default is: \f(CW\*(C`_\*(C'\fR
.SS "can_ignore"
.IX Subsection "can_ignore"
.Vb 1
\&  do_nothing if $reader\->can_ignore($line, $handle)
.Ve
.PP
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.
.PP
This is run \fIafter\fR preprocess_line.
.SS "preprocess_line"
.IX Subsection "preprocess_line"
.Vb 1
\&  $reader\->preprocess_line(\e$line);
.Ve
.PP
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.
.SS "handle_unparsed_line"
.IX Subsection "handle_unparsed_line"
.Vb 1
\&  $reader\->handle_unparsed_line( $line, $handle );
.Ve
.PP
This method is called when the reader encounters a line that doesn't look like
anything it recognizes.  By default, it throws an exception.
.SS "finalize"
.IX Subsection "finalize"
.Vb 1
\&  $reader\->finalize;
.Ve
.PP
This method is called when the reader has finished reading in every line of the
file.
.SS "new"
.IX Subsection "new"
.Vb 1
\&  my $reader = Config::INI::Reader\->new;
.Ve
.PP
This method returns a new reader.  This generally does not need to be called by
anything but the various \f(CW\*(C`read_*\*(C'\fR methods, which create a reader object only
ephemerally.
.SH "ORIGIN"
.IX Header "ORIGIN"
Originaly derived from Config::Tiny, by Adam Kennedy.
.SH "AUTHOR"
.IX Header "AUTHOR"
Ricardo Signes <rjbs@cpan.org>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This software is copyright (c) 2007 by Ricardo Signes.
.PP
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.