Config::IniFiles provides a way to have readable configuration files outside
your Perl script. Configurations can be imported (inherited, stacked,...),
sections can be grouped, and settings can be accessed from a tied hash.

INI files consist of a number of sections, each preceded with the
section name in square brackets. The first non-blank character of
the line indicating a section must be a left bracket and the last
nonblank character of a line indicating a section must be a right
bracket. The characters making up the section name can be any
symbols at all. However section names must be unique.

Parameters are specified in each section as Name=Value. Any spaces
around the equals sign will be ignored, and the value extends to the
end of the line. Parameter names are localized to the namespace of
the section, but must be unique within a section.

[section]
Parameter=Value

Both the hash mark (#) and the semicolon (;) are comment characters.
Lines that begin with either of these characters will be ignored. Any
amount of whitespace may preceed the comment character.

Multiline or multi-valued parameters may also be defined ala UNIX
``here document'' syntax:

Parameter=<<EOT
value/line 1
value/line 2
EOT

You may use any string you want in place of ``EOT''. Note that what
follows the ``<<'' and what appears at the end of the text MUST match
exactly, including any trailing whitespace.

Specifies a section to be used for default values. For example, if you
look up the ``permissions'' parameter in the ``users'' section, but there
is none, Config::IniFiles will look to your default section for a ``permissions''
value before returning undef.

Set -nocase => 1 to handle the config file in a case-insensitive
manner (case in values is preserved, however). By default, config
files are case-sensitive (i.e., a section named 'Test' is not the same
as a section named 'test'). Note that there is an added overhead for
turning off case sensitivity.

This allows you to import or inherit existing setting from another
Config::IniFiles object. When importing settings from another object,
sections with the same name will be merged and parameters that are
defined in both the imported object and the -file will take the
value of given in the -file.

If a -default section is also given on this call, and it does not
coincide with the default of the imported object, the new default
section will be used instead. If no -default section is given,
then the default of the imported object will be used.

Forces the configuration file to be re-read. Returns undef if the
file can not be opened, no filename was defined (with the -file
option) when the object was constructed, or an error occurred while
reading.

If an error occurs while parsinf the INI file the @Config::IniFiles::errors
array will contain messages that might help you figure out where the
problem is in the file.

This is useful for building up lists. Note that parameters within a
``member'' section are referenced normally (i.e., the section name is
still ``Groupname Membername'', including the space) - the concept of
Groups is to aid people building more complex configuration files.

Accessor method for the EOT text (in fact, style) of the specified parameter. If any text is used as an EOT mark, this will be returned. If the parameter was not recorded using HERE style multiple lines, GetParameterEOT returns undef.

Using tie, you can tie a hash to a Config::IniFiles object. This creates a new
object which you can access through your hash, so you use this instead of the
new method. This actually creates a hash of hashes to access the values in
the INI file. The options you provide through tie are the same as given for
the new method, above.

print "We have $ini{Section}{Parameter}." if $ini{Section}{Parameter};

Accessing and using the hash works just like accessing a regular hash and
many of the object methods are made available through the hash interface.

For those methods that do not coincide with the hash paradigm, you can use
the Perl tied function to get at the underlying object tied to the hash
and call methods on that object. For example, to write the hash out to a new
ini file, you would do something like this:

Because of limitations in Perl's tie implementation,
multiline values accessed through a hash will always be returned
as a single value with each line joined by the default line
separator ($\). To break them apart you can simple do this:

To set a multiline or multiv-alue parameter just assign an
array reference to the hash entry, like this:

$ini{$section}{$parameter} = [$value1, $value2, ...];

If the parameter did not exist in the original file, it will
be created. However, Perl does not seem to extend autovivification
to tied hashes. That means that if you try to say

$ini{new_section}{new_paramters} = $val;

and the section 'new_section' does not exist, then Perl won't
properly create it. In order to work around this you will need
to create a hash reference in that section and then assign the
parameter value. Something like this should do nicely:

Using the tie interface, you can copy whole sections of the
ini file into another hash. Note that this makes a copy of
the entire section. The new hash in no longer tied to the
ini file, In particular, this means -default and -nocase
settings will not apply to %hash.

Through the hash interface, you have the ability to replace
the entire section with a new set of parameters. This call
will fail, however, if the argument passed in NOT a hash
reference. You must use both lines, as shown above so that
Perl recognizes the section as a hash reference context
before COPYing over the values from your %parameters hash.

When tied to a hash, you use the Perl keys and each
functions to iteratively list the parameters (keys) or
parameters and their values (each) in a given section.

You can also use the Perl exists function to see if a
parameter is defined in a given section.

Note that none of these will return parameter names that
are part if the default section (if set), although accessing
an unknown parameter in the specified section will return a
value from the default section if there is one.

Contains a list of errors encountered while parsing the configuration
file. If the new method returns undef, check the value of this
to find out what's wrong. This value is reset each time a config file
is read.

The output from [Re]WriteConfig/OutputConfig might not be as pretty as
it can be. Comments are tied to whatever was immediately below them.
And case is not preserved for Section and Parameter names if the -nocase
option was used.

No locking is done by [Re]WriteConfig. When writing servers, take
care that only the parent ever calls this, and consider making your
own backup.

Revision 2.18 2001/03/30 04:41:08 rbowen
Small documentation change in IniFiles.pm - pod2* was choking on misplaces
=item tags. And I regenerated the README
The main reason for this release is that the MANIFEST in the 2.17 version was
missing one of the new test suite files, and that is included in this
re-release.

Revision 1.13 2000/11/28 12:41:42 grail
Added test for being able to add sections with wierd names like section|version2

Revision 1.11 2000/11/24 21:20:11 rbowen
Resolved SourceForge bug #122445 - a parameter should be split from its value on the first = sign encountered, not on the last one. Added test suite to test this, and put test case in test.ini

Revision 1.10 2000/11/24 20:40:58 rbowen
Updated MANIFEST to have file list of new files in t/
Updated IniFiles.pm to have mention of sourceforge addresses, rather than rcbowen.com addresses
Regenerated README from IniFiles.pm

Revision 1.9 2000/11/23 05:08:08 grail
Fixed documentation for bug 122443 - Check that INI files can be created from scratch.

Revision 1.7 2000/09/21 11:19:17 rbowen
Mostly documentation changes. I moved the change log into the POD rather
than having it in a separate Changes file. This allows people to see the
changes in the Readme before they download the module. Now I just
need to make sure I remember to regenerate the Readme every time I do
a commit.

1.6 September 19, 2000 by JW, AS
* Applied several patches submitted to me by Jeremy and Alex.
* Changed version number to the CVS version number, so that I won't
have to think about changing it ever again. Big version change
should not be taken as a huge leap forward.

0.12 September 13, 2000 by JW/WADG
* Added documentation to clarify autovivification issues when
creating new sections
* Fixed version number (Oops!)

0.11 September 13, 2000 by JW/WADG
* Applied patch to Group and GroupMembers functions to return empty
list when no groups are present (submitted by John Bass, Sep 13)

0.10 September 13, 2000 by JW/WADG
* Fixed reference in POD to ReWriteFile. changes to RewriteConfig
* Applied patch for failed open bug submitted by Mordechai T. Abzug Aug 18
* Doc'd behavior of failed open
* Removed planned SIG testing from test.pl as SIGs have been removed
* Applied patch from Thibault Deflers to fix bug in parameter list
when a parameter value is undef

0.09
Hey! Where's the change log for 0.09?

0.08
2000-07-30 Adrian Phillips <adrianp@powertech.no>

* test.pl: Fixed some tests which use $\, and made those that try
to check a non existant val check against ! defined.

* IniFiles.pm: hopefully fixed use of $\ when this is unset
(problems found when running tests with -w). Similar problem with
$/ which can be undefined and trying to return a val which does
not exist. Modified val docs section to indicate a undef return
when this occurs.

0.03 Thu Jun 15, 2000 by RBOW
* Modifications to permit 'use strict', and to get 'make test' working
again.

0.02 Tue Jun 13, 2000 by RBOW
* Fixed bug reported by Bernie Cosell - Sections, Parameters,
and GroupMembers return undef if there are no sections,
parameters, or group members. These functions now return
() if the particular value is undefined.
* Added some contributed documentation, from Alex Satrapa, explaining
how the internal data structure works.
* Set up a project on SourceForge. (Not a change, but worth
noting).
* Added Groups method to return a list of section groups.

0.01 Mon Jun 12, 2000 by RBOW
Some general code cleanup, in preparation for changes to
come. Put up Majordomo mailing list and sent invitation to
various people to join it.