Config::IniHash(3pm)					User Contributed Perl Documentation				      Config::IniHash(3pm)

NAME

       Config::IniHash - Perl extension for reading and writing INI files

VERSION

       Version 3.00.05

SYNOPSIS

	 use Config::IniHash;
	 $Config = ReadINI 'c:somefile.ini';

DESCRIPTION

       This module reads and writes INI files.

   Functions
       ReadINI

	       $hashreference = ReadINI ($filename, %options)
	       $hashreference = ReadINI ($data, %options)
	       $hashreference = ReadINI (@data, %options)
	       $hashreference = ReadINI ($filehandle, %options)

       The returned hash contains a reference to a hash for each section of the INI.

	       [section]
	       name=value
	 leads to
	       $hash->{section}->{name}  = value;

       The available options are:

       heredoc
	   - controls whether the module supports the heredoc syntax :

		   name=<<END
		   the
		   many lines
		   long value
		   END
		   othername=value

		   0 : heredocs are ignored, $data->{section}{name} will be '<<END'
		   1 : heredocs are supported, $data->{section}{name} will be "the
many lines
long value"
			   The Perl-lie extensions of name=<<"END" and <<'END' are not supported!
		   'Perl' : heredocs are supported, $data->{section}{name} will be "the
many lines
long value"
			   The Perl-lie extensions of name=<<"END" and <<'END' are supported.
			   The <<'END' never interpolates %variables%, the "END" always interpolates variables,
			   unlike in other values, the %variables% that are not defined do not stay in the string!

	   Default: 0 = OFF

       systemvars
	   - controls whether the (system) variables enclosed in %% are interpolated and optionaly contains the values in a hash ref.

		   name=%USERNAME%
	     leads to
		   $data->{section}->{name} = "Jenda"

		   systemvars = 1  - yes, take values from %ENV
		   systemvars = \%hash	   - yes, take values from %hash
		   systemvars = 0  - no

       case
	   - controls whether the created hash is case insensitive. The possible values are

	     sensitive	   - the hash will be case sensitive
	     tolower	   - the hash will be case sensitive, all keys are made lowercase
	     toupper	   - the hash will be case sensitive, all keys are made uppercase
	     preserve	   - the hash will be case insensitive, the case is preserved (tied)
	     lower - the hash will be case insensitive, all keys are made lowercase (tied)
	     upper - the hash will be case insensitive, all keys are made uppercase (tied)

       withdefaults
	   - controls whether the created section hashes support defaults. See Hash::WithDefaults.

       class
	   - allows you to specify the class into which to tie the created hashes. This option overwrites the "case" and "withdefaults" options!

	   You may for example use

	     class => 'Tie::IxHash',

	   to store the sections in hashes that remember the insertion order.

       sectionorder
	   - if set to a true value then created hash will contain

		   $config->{'__SECTIONS__'} = [ 'the', 'names', 'of', 'the', 'sections', 'in', 'the',
			   'order', 'they', 'were', 'specified', 'in', 'the', 'INI file'];

	   - if set to an array ref, then the list will be stored in that array, and no $config->{'__SECTIONS__'} is created. The case of the
	   section names stored in this array is controled by the "case" option even in case you specify the "class".

       allowmultiple
	   - if set to a true scalar value then multiple items with the same names in a section do not overwrite each other, but result in an
	   array of the values.

	   - if set to a hash of hashes (or hash of arrays or hash of comma separated item names) specifies what items in what sections will end
	   up as hashes containing the list of values. All the specified items will be arrays, even if there is just a single value. To affect the
	   items in all sections use section name '*'.

	   By default false.

       forValue
	   - allows you to install a callback that will be called for each value as soon as it is read but before it is stored in the hash.  The
	   function is called like this:

	     $value = $forValue->($name, $value, $sectionname, $INIhashref);

	   If the callback returns an undef, the value will not be stored.

       comment
	   - regular expression used to identify comments or a string containing the list of characters starting a comment.  Each line is tested
	   against the regexp is ignored if matches. If you specify a string a regexp like this will be created:

		   qr/^s*[the_list]/

	   The default is

		   qr/^s*[#;]

       layer
	   - the IO layer(s) to use when opening the file. See perldoc "perlopen".

	   If the file is in UTF8 and starts with a BOM it will be automaticaly opened in UTF8 mode and the BOM will be stripped.  If it doesn't
	   start with the BOM you have to specify the utf8 layer!

       You may also set the defaults for the options by modifying the $Config::IniHash::optionname variables. These default settings will be used
       if you do not specify the option in the ReadINI() or ReadSection() call.

       AddDefaults

	 AddDefaults( $config, 'normal section name', 'default section name');
	 AddDefaults( $config, 'normal section name', \%defaults);

       This subroutine adds a some default values into a section. The values are NOT copied into the section, but rather the section knows to look
       up the missing options in the default section or hash.

       Eg.

	 if (exists $config->{':default'}) {
	       foreach my $section (keys %$config) {
		 next if $section =~ /^:/;
		 AddDefaults( $config, $section, ':default');
	       }
	 }

       ReadSection

	 $hashreference = ReadSection ($string)

       This function parses a string as if it was a section of an INI file and creates a hash with the values.	It accepts the same options as
       ReadINI.

       WriteINI

	 WriteINI ($filename, $hashreference)

       Writes the hash of hashes to a file.

       PrintINI

       The same as WriteINI().

AUTHOR

       Jan Krynicky <Jenda@Krynicky.cz> http://Jenda.Krynicky.cz

COPYRIGHT

       Copyright (c) 2002-2005 Jan Krynicky <Jenda@Krynicky.cz>. All rights reserved.

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

perl v5.10.0							    2009-06-08						      Config::IniHash(3pm)