Prima::IniFile(3)					User Contributed Perl Documentation					 Prima::IniFile(3)

NAME

       Prima::IniFile - support of Windows-like initialization files

DESCRIPTION

       The module contains a class, that provides mapping of text initialization file to a two-level hash structure. The first level is called
       sections, which groups the second level hashes, called items.  Sections must have unique keys. The items hashes values are arrays of text
       strings. The methods, operated on these arrays are get_values, set_values, add_values and replace_values.

SYNOPSIS

	       use Prima::IniFile;

	       my $ini = create Prima::IniFile;
	       my $ini = create Prima::IniFile FILENAME;
	       my $ini = create Prima::IniFile FILENAME,
					       default => HASHREF_OR_ARRAYREF;
	       my $ini = create Prima::IniFile file => FILENAME,
					       default => HASHREF_OR_ARRAYREF;

	       my @sections = $ini->sections;
	       my @items = $ini->items(SECTION);
	       my @items = $ini->items(SECTION, 1);
	       my @items = $ini->items(SECTION, all => 1);

	       my $value = $ini-> get_values(SECTION, ITEM);
	       my @vals = $ini-> get_values(SECTION, ITEM);
	       my $nvals = $ini-> nvalues(SECTION, ITEM);

	       $ini-> set_values(SECTION, ITEM, LIST);
	       $ini-> add_values(SECTION, ITEM, LIST);
	       $ini-> replace_values(SECTION, ITEM, LIST);

	       $ini-> write;
	       $ini-> clean;
	       $ini-> read( FILENAME);
	       $ini-> read( FILENAME, default => HASHREF_OR_ARRAYREF);

	       my $sec = $ini->section(SECTION);
	       $sec->{ITEM} = VALUE;
	       my $val = $sec->{ITEM};
	       delete $sec->{ITEM};
	       my %everything = %$sec;
	       %$sec = ();
	       for ( keys %$sec) { ... }
	       while ( my ($k,$v) = each %$sec) { ... }

METHODS

       add_values SECTION, ITEM, @LIST
	   Adds LIST of string values to the ITEM in SECTION.

       clean
	   Cleans all internal data in the object, including the name of the file.

       create PROFILE
	   Creates an instance of the class. The PROFILE is treated partly as an array, partly as a hash. If PROFILE consists of a single item,
	   the item is treated as a filename. Otherwise, PROFILE is treated as a hash, where the following keys are allowed:

	   file FILENAME
	       Selects name of file.

	   default %VALUES
	       Selects the initial values for the file, where VALUES is a two-level hash of sections and items. It is passed to read, where it is
	       merged with the file data.

       get_values SECTION, ITEM
	   Returns array of values for ITEM in SECTION. If called in scalar context, and there is more than one value, the first value in list is
	   returned.

       items SECTION [ HINTS ]
	   Returns items in SECTION. HINTS parameters is used to tell if a multiple-valued item must be returned as several items of the same
	   name; HINTS can be supplied in the following forms:

	   items( $section, 1 ) items( $section, all => 1);

       new PROFILE
	   Same as create.

       nvalues SECTION, ITEM
	   Returns number of values in ITEM in SECTION.

       read FILENAME, %PROFILE
	   Flushes the old content and opens new file. FILENAME is a text string, PROFILE is a two-level hash of default values for the new file.
	   PROFILE is merged with the data from file, and the latter keep the precedence.  Does not return any success values but, warns if any
	   error is occurred.

       replace_values SECTION, ITEM, @VALUES
	   Removes all values form ITEM in SECTION and assigns it to the new list of VALUES.

       section SECTION
	   Returns a tied hash for SECTION. All its read and write operations are reflected in the caller object, which allows the following
	   syntax:

		   my $section = $inifile-> section( 'Sample section');
		   $section-> {Item1} = 'Value1';

	   which is identical to

		   $inifile-> set_items( 'Sample section', 'Item1', 'Value1');

       sections
	   Returns array of section names.

       set_values SECTION, ITEM, @VALUES
	   Assigns VALUES to ITEM in SECTION. If number of new values are equal or greater than the number of the old, the method is same as
	   replace_values. Otherwise, the values with indices higher than the number of new values are not touched.

       write
	   Rewrites the file with the object content. The object keeps an internal modification flag under name "{changed}"; in case it is
	   "undef", no actual write is performed.

AUTHORS

       Anton Berezin, <tobez@plab.ku.dk>

       Dmitry Karasik <dmitry@karasik.eu.org>

perl v5.14.2							    2009-02-24							 Prima::IniFile(3)