1Config::IniHash(3) User Contributed Perl Documentation Config::IniHash(3)
2
6 Config::IniHash - Perl extension for reading and writing INI files
7
9 Version 3.00.05
10
12 use Config::IniHash;
13 $Config = ReadINI 'c:\some\file.ini';
14
16 This module reads and writes INI files.
17 Functions
19 ReadINI
20 $hashreference = ReadINI ($filename, %options)
22 $hashreference = ReadINI (\$data, %options)
23 $hashreference = ReadINI (\@data, %options)
24 $hashreference = ReadINI ($filehandle, %options)
25 The returned hash contains a reference to a hash for each section of
27 the INI.
28 [section]
30 name=value
31 leads to
32 $hash->{section}->{name} = value;
33 The available options are:
35 heredoc
37 - controls whether the module supports the heredoc syntax :
38 name=<<END
40 the
41 many lines
42 long value
43 END
44 othername=value
45 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 Default: 0 = OFF
55 systemvars
57 - controls whether the (system) variables enclosed in %% are
58 interpolated and optionaly contains the values in a hash ref.
59 name=%USERNAME%
61 leads to
62 $data->{section}->{name} = "Jenda"
63 systemvars = 1 - yes, take values from %ENV
65 systemvars = \%hash - yes, take values from %hash
66 systemvars = 0 - no
67 case
69 - controls whether the created hash is case insensitive. The
70 possible values are
71 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 withdefaults
80 - controls whether the created section hashes support defaults. See
81 Hash::WithDefaults.
82 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 You may for example use
89 class => 'Tie::IxHash',
91 to store the sections in hashes that remember the insertion order.
93 sectionorder
95 - if set to a true value then created hash will contain
96 $config->{'__SECTIONS__'} = [ 'the', 'names', 'of', 'the', 'sections', 'in', 'the',
98 'order', 'they', 'were', 'specified', 'in', 'the', 'INI file'];
99 - 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 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 - 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 By default false.
117 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 $value = $forValue->($name, $value, $sectionname, $INIhashref);
124 If the callback returns an undef, the value will not be stored.
126 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 qr/^\s*[the_list]/
134 The default is
136 qr/^\s*[#;]
138 layer
140 - the IO layer(s) to use when opening the file. See perldoc
141 "perlopen".
142 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 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 AddDefaults
153 AddDefaults( $config, 'normal section name', 'default section name');
155 AddDefaults( $config, 'normal section name', \%defaults);
156 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 Eg.
162 if (exists $config->{':default'}) {
164 foreach my $section (keys %$config) {
165 next if $section =~ /^:/;
166 AddDefaults( $config, $section, ':default');
167 }
168 }
169 ReadSection
171 $hashreference = ReadSection ($string)
173 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 WriteINI
179 WriteINI ($filename, $hashreference)
181 Writes the hash of hashes to a file.
183 PrintINI
185 The same as WriteINI().
187
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 This program is free software; you can redistribute it and/or modify it
196 under the same terms as Perl itself.
197perl v5.28.1 2009-06-08 Config::IniHash(3)