.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" 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
.\"
.\" 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 "Config::IniHash 3pm"
.TH Config::IniHash 3pm "2022-11-19" "perl v5.36.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::IniHash \- Perl extension for reading and writing INI files
.SH "VERSION"
.IX Header "VERSION"
Version 3.00.05
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\&  use Config::IniHash;
\&  $Config = ReadINI \*(Aqc:\esome\efile.ini\*(Aq;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module reads and writes \s-1INI\s0 files.
.SS "Functions"
.IX Subsection "Functions"
\fIReadINI\fR
.IX Subsection "ReadINI"
.PP
.Vb 4
\&        $hashreference = ReadINI ($filename, %options)
\&        $hashreference = ReadINI (\e$data, %options)
\&        $hashreference = ReadINI (\e@data, %options)
\&        $hashreference = ReadINI ($filehandle, %options)
.Ve
.PP
The returned hash contains a reference to a hash for each section of
the \s-1INI.\s0
.PP
.Vb 4
\&        [section]
\&        name=value
\&  leads to
\&        $hash\->{section}\->{name}  = value;
.Ve
.PP
The available options are:
.IP "heredoc" 4
.IX Item "heredoc"
\&\- controls whether the module supports the heredoc syntax :
.Sp
.Vb 6
\&        name=<<END
\&        the
\&        many lines
\&        long value
\&        END
\&        othername=value
\&
\&        0 : heredocs are ignored, $data\->{section}{name} will be \*(Aq<<END\*(Aq
\&        1 : heredocs are supported, $data\->{section}{name} will be "the\enmany lines\enlong value"
\&                The Perl\-lie extensions of name=<<"END" and <<\*(AqEND\*(Aq are not supported!
\&        \*(AqPerl\*(Aq : heredocs are supported, $data\->{section}{name} will be "the\enmany lines\enlong value"
\&                The Perl\-lie extensions of name=<<"END" and <<\*(AqEND\*(Aq are supported.
\&                The <<\*(AqEND\*(Aq never interpolates %variables%, the "END" always interpolates variables,
\&                unlike in other values, the %variables% that are not defined do not stay in the string!
.Ve
.Sp
Default: 0 = \s-1OFF\s0
.IP "systemvars" 4
.IX Item "systemvars"
\&\- controls whether the (system) variables enclosed in %% are
interpolated and optionaly contains the values in a hash ref.
.Sp
.Vb 3
\&        name=%USERNAME%
\&  leads to
\&        $data\->{section}\->{name} = "Jenda"
\&
\&        systemvars = 1  \- yes, take values from %ENV
\&        systemvars = \e%hash     \- yes, take values from %hash
\&        systemvars = 0  \- no
.Ve
.IP "case" 4
.IX Item "case"
\&\- controls whether the created hash is case insensitive. The possible values are
.Sp
.Vb 6
\&  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)
.Ve
.IP "withdefaults" 4
.IX Item "withdefaults"
\&\- controls whether the created section hashes support defaults. See Hash::WithDefaults.
.IP "class" 4
.IX Item "class"
\&\- allows you to specify the class into which to tie the created hashes. This option overwrites
the \*(L"case\*(R" and \*(L"withdefaults\*(R" options!
.Sp
You may for example use
.Sp
.Vb 1
\&  class => \*(AqTie::IxHash\*(Aq,
.Ve
.Sp
to store the sections in hashes that remember the insertion order.
.IP "sectionorder" 4
.IX Item "sectionorder"
\&\- if set to a true value then created hash will contain
.Sp
.Vb 2
\&        $config\->{\*(Aq_\|_SECTIONS_\|_\*(Aq} = [ \*(Aqthe\*(Aq, \*(Aqnames\*(Aq, \*(Aqof\*(Aq, \*(Aqthe\*(Aq, \*(Aqsections\*(Aq, \*(Aqin\*(Aq, \*(Aqthe\*(Aq,
\&                \*(Aqorder\*(Aq, \*(Aqthey\*(Aq, \*(Aqwere\*(Aq, \*(Aqspecified\*(Aq, \*(Aqin\*(Aq, \*(Aqthe\*(Aq, \*(AqINI file\*(Aq];
.Ve
.Sp
\&\- if set to an array ref, then the list will be stored in that array, and no \f(CW$config\fR\->{'_\|_SECTIONS_\|_'}
is created. The case of the section names stored in this array is controled by the \*(L"case\*(R" option even
in case you specify the \*(L"class\*(R".
.IP "allowmultiple" 4
.IX Item "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.
.Sp
\&\- 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 '*'.
.Sp
By default false.
.IP "forValue" 4
.IX Item "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:
.Sp
.Vb 1
\&  $value = $forValue\->($name, $value, $sectionname, $INIhashref);
.Ve
.Sp
If the callback returns an undef, the value will not be stored.
.IP "comment" 4
.IX Item "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:
.Sp
.Vb 1
\&        qr/^\es*[the_list]/
.Ve
.Sp
The default is
.Sp
.Vb 1
\&        qr/^\es*[#;]
.Ve
.IP "layer" 4
.IX Item "layer"
\&\- the \s-1IO\s0 layer(s) to use when opening the file. See perldoc \f(CW\*(C`perlopen\*(C'\fR.
.Sp
If the file is in \s-1UTF8\s0 and starts with a \s-1BOM\s0 it will be automatically opened in \s-1UTF8\s0 mode and the \s-1BOM\s0 will be stripped.
If it doesn't start with the \s-1BOM\s0 you have to specify the utf8 layer!
.PP
You may also set the defaults for the options by modifying the \f(CW$Config::IniHash::optionname\fR
variables. These default settings will be used if you do not specify the option in the \fBReadINI()\fR
or \fBReadSection()\fR call.
.PP
\fIAddDefaults\fR
.IX Subsection "AddDefaults"
.PP
.Vb 2
\&  AddDefaults( $config, \*(Aqnormal section name\*(Aq, \*(Aqdefault section name\*(Aq);
\&  AddDefaults( $config, \*(Aqnormal section name\*(Aq, \e%defaults);
.Ve
.PP
This subroutine adds a some default values into a section. The values are \s-1NOT\s0 copied into the section,
but rather the section knows to look up the missing options in the default section or hash.
.PP
Eg.
.PP
.Vb 6
\&  if (exists $config\->{\*(Aq:default\*(Aq}) {
\&        foreach my $section (keys %$config) {
\&          next if $section =~ /^:/;
\&          AddDefaults( $config, $section, \*(Aq:default\*(Aq);
\&        }
\&  }
.Ve
.PP
\fIReadSection\fR
.IX Subsection "ReadSection"
.PP
.Vb 1
\&  $hashreference = ReadSection ($string)
.Ve
.PP
This function parses a string as if it was a section of an \s-1INI\s0 file and creates a hash with the values.
It accepts the same options as ReadINI.
.PP
\fIWriteINI\fR
.IX Subsection "WriteINI"
.PP
.Vb 1
\&  WriteINI ($filename, $hashreference)
.Ve
.PP
Writes the hash of hashes to a file.
.PP
\fIPrintINI\fR
.IX Subsection "PrintINI"
.PP
The same as \fBWriteINI()\fR.
.SH "AUTHOR"
.IX Header "AUTHOR"
Jan Krynicky <Jenda@Krynicky.cz>
http://Jenda.Krynicky.cz
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (c) 2002\-2005 Jan Krynicky <Jenda@Krynicky.cz>. All rights reserved.
.PP
This program is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.