.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16)
.\"
.\" 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" ''
'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 turned on, 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.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Prima::IniFile 3"
.TH Prima::IniFile 3 "2009-02-24" "perl v5.14.2" "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"
Prima::IniFile \- support of Windows\-like initialization files
.SH "DESCRIPTION"
.IX Header "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.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&        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) { ... }
.Ve
.SH "METHODS"
.IX Header "METHODS"
.ie n .IP "add_values \s-1SECTION\s0, \s-1ITEM\s0, @LIST" 4
.el .IP "add_values \s-1SECTION\s0, \s-1ITEM\s0, \f(CW@LIST\fR" 4
.IX Item "add_values SECTION, ITEM, @LIST"
Adds \s-1LIST\s0 of string values to the \s-1ITEM\s0 in \s-1SECTION\s0.
.IP "clean" 4
.IX Item "clean"
Cleans all internal data in the object, including the name of the file.
.IP "create \s-1PROFILE\s0" 4
.IX Item "create PROFILE"
Creates an instance of the class. The \s-1PROFILE\s0 is treated partly as
an array, partly as a hash. If \s-1PROFILE\s0 consists of a single item, 
the item is treated as a filename. Otherwise, \s-1PROFILE\s0 is treated as a hash,
where the following keys are allowed:
.RS 4
.IP "file \s-1FILENAME\s0" 4
.IX Item "file FILENAME"
Selects name of file.
.ie n .IP "default %VALUES" 4
.el .IP "default \f(CW%VALUES\fR" 4
.IX Item "default %VALUES"
Selects the initial values for the file, where \s-1VALUES\s0 is a two-level
hash of sections and items. It is passed to read, where it is merged
with the file data.
.RE
.RS 4
.RE
.IP "get_values \s-1SECTION\s0, \s-1ITEM\s0" 4
.IX Item "get_values SECTION, ITEM"
Returns array of values for \s-1ITEM\s0 in \s-1SECTION\s0. If called in scalar context,
and there is more than one value, the first value in list is returned.
.IP "items \s-1SECTION\s0 [ \s-1HINTS\s0 ]" 4
.IX Item "items SECTION [ HINTS ]"
Returns items in \s-1SECTION\s0. \s-1HINTS\s0 parameters is used to tell if a multiple-valued
item must be returned as several items of the same name; 
\&\s-1HINTS\s0 can be supplied in the following forms:
.Sp
items( \f(CW$section\fR, 1 )
items( \f(CW$section\fR, all => 1);
.IP "new \s-1PROFILE\s0" 4
.IX Item "new PROFILE"
Same as create.
.IP "nvalues \s-1SECTION\s0, \s-1ITEM\s0" 4
.IX Item "nvalues SECTION, ITEM"
Returns number of values in \s-1ITEM\s0 in \s-1SECTION\s0.
.ie n .IP "read \s-1FILENAME\s0, %PROFILE" 4
.el .IP "read \s-1FILENAME\s0, \f(CW%PROFILE\fR" 4
.IX Item "read FILENAME, %PROFILE"
Flushes the old content and opens new file. \s-1FILENAME\s0 is a text string,
\&\s-1PROFILE\s0 is a two-level hash of default values for the new file. \s-1PROFILE\s0 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.
.ie n .IP "replace_values \s-1SECTION\s0, \s-1ITEM\s0, @VALUES" 4
.el .IP "replace_values \s-1SECTION\s0, \s-1ITEM\s0, \f(CW@VALUES\fR" 4
.IX Item "replace_values SECTION, ITEM, @VALUES"
Removes all values form \s-1ITEM\s0 in \s-1SECTION\s0 and assigns it to the new
list of \s-1VALUES\s0.
.IP "section \s-1SECTION\s0" 4
.IX Item "section SECTION"
Returns a tied hash for \s-1SECTION\s0. All its read and write operations are reflected
in the caller object, which allows the following syntax:
.Sp
.Vb 2
\&        my $section = $inifile\-> section( \*(AqSample section\*(Aq);
\&        $section\-> {Item1} = \*(AqValue1\*(Aq;
.Ve
.Sp
which is identical to
.Sp
.Vb 1
\&        $inifile\-> set_items( \*(AqSample section\*(Aq, \*(AqItem1\*(Aq, \*(AqValue1\*(Aq);
.Ve
.IP "sections" 4
.IX Item "sections"
Returns array of section names.
.ie n .IP "set_values \s-1SECTION\s0, \s-1ITEM\s0, @VALUES" 4
.el .IP "set_values \s-1SECTION\s0, \s-1ITEM\s0, \f(CW@VALUES\fR" 4
.IX Item "set_values SECTION, ITEM, @VALUES"
Assigns \s-1VALUES\s0 to \s-1ITEM\s0 in \s-1SECTION\s0. 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.
.IP "write" 4
.IX Item "write"
Rewrites the file with the object content. The object keeps an internal modification flag
under name \f(CW\*(C`{changed}\*(C'\fR; in case it is \f(CW\*(C`undef\*(C'\fR, no actual write is performed.
.SH "AUTHORS"
.IX Header "AUTHORS"
Anton Berezin, <tobez@plab.ku.dk>
.PP
Dmitry Karasik <dmitry@karasik.eu.org>