1Config::IniHash(3)    User Contributed Perl Documentation   Config::IniHash(3)
2
3
4

NAME

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

VERSION

9       Version 3.00.05
10

SYNOPSIS

12         use Config::IniHash;
13         $Config = ReadINI 'c:\some\file.ini';
14

DESCRIPTION

16       This module reads and writes INI files.
17
18   Functions
19       ReadINI
20
21               $hashreference = ReadINI ($filename, %options)
22               $hashreference = ReadINI (\$data, %options)
23               $hashreference = ReadINI (\@data, %options)
24               $hashreference = ReadINI ($filehandle, %options)
25
26       The returned hash contains a reference to a hash for each section of
27       the INI.
28
29               [section]
30               name=value
31         leads to
32               $hash->{section}->{name}  = value;
33
34       The available options are:
35
36       heredoc
37           - controls whether the module supports the heredoc syntax :
38
39                   name=<<END
40                   the
41                   many lines
42                   long value
43                   END
44                   othername=value
45
46                   0 : heredocs are ignored, $data->{section}{name} will be '<<END'
47                   1 : heredocs are supported, $data->{section}{name} will be "the\nmany lines\nlong value"
48                           The Perl-lie extensions of name=<<"END" and <<'END' are not supported!
49                   'Perl' : heredocs are supported, $data->{section}{name} will be "the\nmany lines\nlong value"
50                           The Perl-lie extensions of name=<<"END" and <<'END' are supported.
51                           The <<'END' never interpolates %variables%, the "END" always interpolates variables,
52                           unlike in other values, the %variables% that are not defined do not stay in the string!
53
54           Default: 0 = OFF
55
56       systemvars
57           - controls whether the (system) variables enclosed in %% are
58           interpolated and optionaly contains the values in a hash ref.
59
60                   name=%USERNAME%
61             leads to
62                   $data->{section}->{name} = "Jenda"
63
64                   systemvars = 1  - yes, take values from %ENV
65                   systemvars = \%hash     - yes, take values from %hash
66                   systemvars = 0  - no
67
68       case
69           - controls whether the created hash is case insensitive. The
70           possible values are
71
72             sensitive     - the hash will be case sensitive
73             tolower       - the hash will be case sensitive, all keys are made lowercase
74             toupper       - the hash will be case sensitive, all keys are made uppercase
75             preserve      - the hash will be case insensitive, the case is preserved (tied)
76             lower - the hash will be case insensitive, all keys are made lowercase (tied)
77             upper - the hash will be case insensitive, all keys are made uppercase (tied)
78
79       withdefaults
80           - controls whether the created section hashes support defaults. See
81           Hash::WithDefaults.
82
83       class
84           - allows you to specify the class into which to tie the created
85           hashes. This option overwrites the "case" and "withdefaults"
86           options!
87
88           You may for example use
89
90             class => 'Tie::IxHash',
91
92           to store the sections in hashes that remember the insertion order.
93
94       sectionorder
95           - if set to a true value then created hash will contain
96
97                   $config->{'__SECTIONS__'} = [ 'the', 'names', 'of', 'the', 'sections', 'in', 'the',
98                           'order', 'they', 'were', 'specified', 'in', 'the', 'INI file'];
99
100           - if set to an array ref, then the list will be stored in that
101           array, and no $config->{'__SECTIONS__'} is created. The case of the
102           section names stored in this array is controled by the "case"
103           option even in case you specify the "class".
104
105       allowmultiple
106           - if set to a true scalar value then multiple items with the same
107           names in a section do not overwrite each other, but result in an
108           array of the values.
109
110           - if set to a hash of hashes (or hash of arrays or hash of comma
111           separated item names) specifies what items in what sections will
112           end up as hashes containing the list of values. All the specified
113           items will be arrays, even if there is just a single value. To
114           affect the items in all sections use section name '*'.
115
116           By default false.
117
118       forValue
119           - allows you to install a callback that will be called for each
120           value as soon as it is read but before it is stored in the hash.
121           The function is called like this:
122
123             $value = $forValue->($name, $value, $sectionname, $INIhashref);
124
125           If the callback returns an undef, the value will not be stored.
126
127       comment
128           - regular expression used to identify comments or a string
129           containing the list of characters starting a comment.  Each line is
130           tested against the regexp is ignored if matches. If you specify a
131           string a regexp like this will be created:
132
133                   qr/^\s*[the_list]/
134
135           The default is
136
137                   qr/^\s*[#;]
138
139       layer
140           - the IO layer(s) to use when opening the file. See perldoc
141           "perlopen".
142
143           If the file is in UTF8 and starts with a BOM it will be
144           automaticaly opened in UTF8 mode and the BOM will be stripped.  If
145           it doesn't start with the BOM you have to specify the utf8 layer!
146
147       You may also set the defaults for the options by modifying the
148       $Config::IniHash::optionname variables. These default settings will be
149       used if you do not specify the option in the ReadINI() or ReadSection()
150       call.
151
152       AddDefaults
153
154         AddDefaults( $config, 'normal section name', 'default section name');
155         AddDefaults( $config, 'normal section name', \%defaults);
156
157       This subroutine adds a some default values into a section. The values
158       are NOT copied into the section, but rather the section knows to look
159       up the missing options in the default section or hash.
160
161       Eg.
162
163         if (exists $config->{':default'}) {
164               foreach my $section (keys %$config) {
165                 next if $section =~ /^:/;
166                 AddDefaults( $config, $section, ':default');
167               }
168         }
169
170       ReadSection
171
172         $hashreference = ReadSection ($string)
173
174       This function parses a string as if it was a section of an INI file and
175       creates a hash with the values.  It accepts the same options as
176       ReadINI.
177
178       WriteINI
179
180         WriteINI ($filename, $hashreference)
181
182       Writes the hash of hashes to a file.
183
184       PrintINI
185
186       The same as WriteINI().
187

AUTHOR

189       Jan Krynicky <Jenda@Krynicky.cz> http://Jenda.Krynicky.cz
190
192       Copyright (c) 2002-2005 Jan Krynicky <Jenda@Krynicky.cz>. All rights
193       reserved.
194
195       This program is free software; you can redistribute it and/or modify it
196       under the same terms as Perl itself.
197
198
199
200perl v5.30.1                      2020-01-29                Config::IniHash(3)
Impressum