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

NAME

6       Config::IniFiles - A module for reading .ini-style configuration files.
7

VERSION

9       version 3.000003
10

SYNOPSIS

12         use Config::IniFiles;
13         my $cfg = Config::IniFiles->new( -file => "/path/configfile.ini" );
14         print "The value is " . $cfg->val( 'Section', 'Parameter' ) . "."
15           if $cfg->val( 'Section', 'Parameter' );
16

DESCRIPTION

18       Config::IniFiles provides a way to have readable configuration files
19       outside your Perl script. Configurations can be imported (inherited,
20       stacked,...), sections can be grouped, and settings can be accessed
21       from a tied hash.
22

FILE FORMAT

24       INI files consist of a number of sections, each preceded with the
25       section name in square brackets, followed by parameter names and their
26       values.
27
28         [a section]
29         Parameter=Value
30
31         [section 2]
32         AnotherParameter=Some value
33         Setting=Something else
34         Parameter=Different scope than the one in the first section
35
36       The first non-blank character of the line indicating a section must be
37       a left bracket and the last non-blank character of a line indicating a
38       section must be a right bracket. The characters making up the section
39       name can be any symbols at all. However section names must be unique.
40
41       Parameters are specified in each section as Name=Value.  Any spaces
42       around the equals sign will be ignored, and the value extends to the
43       end of the line (including any whitespace at the end of the line.
44       Parameter names are localized to the namespace of the section, but must
45       be unique within a section.
46
47       Both the hash mark (#) and the semicolon (;) are comment characters.
48       by default (this can be changed by configuration). Lines that begin
49       with either of these characters will be ignored. Any amount of
50       whitespace may precede the comment character.
51
52       Multi-line or multi-valued parameters may also be defined ala UNIX
53       "here document" syntax:
54
55         Parameter=<<EOT
56         value/line 1
57         value/line 2
58         EOT
59
60       You may use any string you want in place of "EOT". Note that whatever
61       follows the "<<" and what appears at the end of the text MUST match
62       exactly, including any trailing whitespace.
63
64       Alternately, as a configuration option (default is off), continuation
65       lines can be allowed:
66
67         [Section]
68         Parameter=this parameter \
69           spreads across \
70           a few lines
71

USAGE -- Object Interface

73       Get a new Config::IniFiles object with the new method:
74
75         $cfg = Config::IniFiles->new( -file => "/path/config_file.ini" );
76         $cfg = new Config::IniFiles -file => "/path/config_file.ini";
77
78       Optional named parameters may be specified after the configuration file
79       name. See the new in the METHODS section, below.
80
81       Values from the config file are fetched with the val method:
82
83         $value = $cfg->val('Section', 'Parameter');
84
85       If you want a multi-line/value field returned as an array, just specify
86       an array as the receiver:
87
88         @values = $cfg->val('Section', 'Parameter');
89

METHODS

91   new ( [-option=>value ...] )
92       Returns a new configuration object (or "undef" if the configuration
93       file has an error, in which case check the global
94       @Config::IniFiles::errors array for reasons why). One Config::IniFiles
95       object is required per configuration file. The following named
96       parameters are available:
97
98       -file  filename
99                 Specifies a file to load the parameters from. This 'file' may
100                 actually be any of the following things:
101
102                   1) the pathname of a file
103
104                     $cfg = Config::IniFiles->new( -file => "/path/to/config_file.ini" );
105
106                   2) a simple filehandle
107
108                     $cfg = Config::IniFiles->new( -file => STDIN );
109
110                   3) a filehandle glob
111
112                     open( CONFIG, "/path/to/config_file.ini" );
113                     $cfg = Config::IniFiles->new( -file => *CONFIG );
114
115                   4) a reference to a glob
116
117                     open( CONFIG, "/path/to/config_file.ini" );
118                     $cfg = Config::IniFiles->new( -file => \*CONFIG );
119
120                   5) an IO::File object
121
122                     $io = IO::File->new( "/path/to/config_file.ini" );
123                     $cfg = Config::IniFiles->new( -file => $io );
124
125                   or
126
127                     open my $fh, '<', "/path/to/config_file.ini" or die $!;
128                     $cfg = Config::IniFiles->new( -file => $fh );
129
130                   6) A reference to a scalar (requires newer versions of IO::Scalar)
131
132                     $ini_file_contents = <<EOT
133                     [section name]
134                     Parameter=A value
135                     Setting=Another value
136                     EOT
137
138                     $cfg = Config::IniFiles->new( -file => \$ini_file_contents );
139
140                 If this option is not specified, (i.e. you are creating a
141                 config file from scratch) you must specify a target file
142                 using SetFileName in order to save the parameters.
143
144       -default section
145                 Specifies a section to be used for default values. For
146                 example, in the following configuration file, if you look up
147                 the "permissions" parameter in the "joe" section, there is
148                 none.
149
150                    [all]
151                    permissions=Nothing
152
153                    [jane]
154                    name=Jane
155                    permissions=Open files
156
157                    [joe]
158                    name=Joseph
159
160                 If you create your Config::IniFiles object with a default
161                 section of "all" like this:
162
163                    $cfg = Config::IniFiles->new( -file => "file.ini", -default => "all" );
164
165                 Then requesting a value for a "permissions" in the [joe]
166                 section will check for a value from [all] before returning
167                 undef.
168
169                    $permissions = $cfg->val( "joe", "permissions");   // returns "Nothing"
170
171       -fallback section
172                 Specifies a section to be used for parameters outside a
173                 section. Default is none.  Without -fallback specified (which
174                 is the default), reading a configuration file which has a
175                 parameter outside a section will fail. With this set to, say,
176                 "GENERAL", this configuration:
177
178                    wrong=wronger
179
180                    [joe]
181                    name=Joseph
182
183                 will be assumed as:
184
185                    [GENERAL]
186                    wrong=wronger
187
188                    [joe]
189                    name=Joseph
190
191                 Note that Config::IniFiles will also omit the fallback
192                 section header when outputting such configuration.
193
194       -nocase 0|1
195                 Set -nocase => 1 to handle the config file in a case-
196                 insensitive manner (case in values is preserved, however).
197                 By default, config files are case-sensitive (i.e., a section
198                 named 'Test' is not the same as a section named 'test').
199                 Note that there is an added overhead for turning off case
200                 sensitivity.
201
202       -import object
203                 This allows you to import or inherit existing setting from
204                 another Config::IniFiles object. When importing settings from
205                 another object, sections with the same name will be merged
206                 and parameters that are defined in both the imported object
207                 and the -file will take the value of given in the -file.
208
209                 If a -default section is also given on this call, and it does
210                 not coincide with the default of the imported object, the new
211                 default section will be used instead. If no -default section
212                 is given, then the default of the imported object will be
213                 used.
214
215       -allowcontinue 0|1
216                 Set -allowcontinue => 1 to enable continuation lines in the
217                 config file.  i.e. if a line ends with a backslash "\", then
218                 the following line is appended to the parameter value,
219                 dropping the backslash and the newline character(s).
220
221                 Default behavior is to keep a trailing backslash "\" as a
222                 parameter value. Note that continuation cannot be mixed with
223                 the "here" value syntax.
224
225       -allowempty 0|1
226                 If set to 1, then empty files are allowed at ReadConfig time.
227                 If set to 0 (the default), an empty configuration file is
228                 considered an error.
229
230       -negativedeltas 0|1
231                 If set to 1 (the default if importing this object from
232                 another one), parses and honors lines of the following form
233                 in the configuration file:
234
235                   ; [somesection] is deleted
236
237                 or
238
239                   [inthissection]
240                   ; thisparameter is deleted
241
242                 If set to 0 (the default if not importing), these comments
243                 are treated like ordinary ones.
244
245                 The WriteConfig1)> form will output such comments to indicate
246                 deleted sections or parameters. This way, reloading a delta
247                 file using the same imported object produces the same results
248                 in memory again. See " DELTA FEATURES" in IMPORT  for more
249                 details.
250
251       -commentchar 'char'
252                 The default comment character is "#". You may change this by
253                 specifying this option to another character. This can be any
254                 character except alphanumeric characters, square brackets or
255                 the "equal" sign.
256
257       -allowedcommentchars 'chars'
258                 Allowed default comment characters are "#" and ";". By
259                 specifying this option you may change the range of characters
260                 that are used to denote a comment line to include any set of
261                 characters
262
263                 Note: that the character specified by -commentchar (see
264                 above) is always part of the allowed comment characters.
265
266                 Note 2: The given string is evaluated as a regular expression
267                 character class, so '\' must be escaped if you wish to use
268                 it.
269
270       -reloadwarn 0|1
271                 Set -reloadwarn => 1 to enable a warning message (output to
272                 STDERR) whenever the config file is reloaded.  The reload
273                 message is of the form:
274
275                   PID <PID> reloading config file <file> at YYYY.MM.DD HH:MM:SS
276
277                 Default behavior is to not warn (i.e. -reloadwarn => 0).
278
279                 This is generally only useful when using Config::IniFiles in
280                 a server or daemon application. The application is still
281                 responsible for determining when the object is to be
282                 reloaded.
283
284       -nomultiline 0|1
285                 Set -nomultiline => 1 to output multi-valued parameter as:
286
287                  param=value1
288                  param=value2
289
290                 instead of the default:
291
292                  param=<<EOT
293                  value1
294                  value2
295                  EOT
296
297                 As the latter might not be compatible with all applications.
298
299       -handle_trailing_comment 0|1
300                 Set -handle_trailing_comment => 1 to enable support of
301                 parameter trailing comments.
302
303                 For example, if we have a parameter line like this:
304
305                  param1=value1;comment1
306
307                 by default, handle_trailing_comment will be set to 0, and we
308                 will get value1;comment1 as the value of param1. If we have
309                 -handle_trailing_comment set to 1, then we will get value1 as
310                 the value for param1, and comment1 as the trailing comment of
311                 param1.
312
313                 Set and get methods for trailing comments are provided as
314                 "SetParameterTrailingComment" and
315                 "GetParameterTrailingComment".
316
317       -php_compat 0|1
318                 Set -php_compat => 1 to enable support for PHP like
319                 configfiles.
320
321                 The differences between parse_ini_file and Config::IniFiles
322                 are:
323
324                  # parse_ini_file
325                  [group]
326                  val1="value"
327                  val2[]=1
328                  val2[]=2
329
330                  vs
331
332                  # Config::IniFiles
333                  [group]
334                  val1=value
335                  val2=1
336                  val2=2
337
338                 This option only affect parsing, not writing new configfiles.
339
340                 Some features from parse_ini_file are not compatible:
341
342                  [group]
343                  val1="val"'ue'
344                  val1[key]=1
345
346   val ($section, $parameter [, $default] )
347       Returns the value of the specified parameter ($parameter) in section
348       $section, returns undef (or $default if specified) if no section or no
349       parameter for the given section exists.
350
351       If you want a multi-line/value field returned as an array, just specify
352       an array as the receiver:
353
354         @values = $cfg->val('Section', 'Parameter');
355
356       A multi-line/value field that is returned in a scalar context will be
357       joined using $/ (input record separator, default is \n) if defined,
358       otherwise the values will be joined using \n.
359
360   exists($section, $parameter)
361       True if and only if there exists a section $section, with a parameter
362       $parameter inside, not counting default values.
363
364   push ($section, $parameter, $value, [ $value2, ...])
365       Pushes new values at the end of existing value(s) of parameter
366       $parameter in section $section.  See below for methods to write the new
367       configuration back out to a file.
368
369       You may not set a parameter that didn't exist in the original
370       configuration file.  push will return undef if this is attempted. See
371       newval below to do this. Otherwise, it returns 1.
372
373   setval ($section, $parameter, $value, [ $value2, ... ])
374       Sets the value of parameter $parameter in section $section to $value
375       (or to a set of values).  See below for methods to write the new
376       configuration back out to a file.
377
378       You may not set a parameter that didn't exist in the original
379       configuration file.  setval will return undef if this is attempted. See
380       newval below to do this. Otherwise, it returns 1.
381
382   newval($section, $parameter, $value [, $value2, ...])
383       Assigns a new value, $value (or set of values) to the parameter
384       $parameter in section $section in the configuration file.
385
386   delval($section, $parameter)
387       Deletes the specified parameter from the configuration file
388
389   ReadConfig
390       Forces the configuration file to be re-read. Returns undef if the file
391       can not be opened, no filename was defined (with the "-file" option)
392       when the object was constructed, or an error occurred while reading.
393
394       If an error occurs while parsing the INI file the
395       @Config::IniFiles::errors array will contain messages that might help
396       you figure out where the problem is in the file.
397
398   Sections
399       Returns an array containing section names in the configuration file.
400       If the nocase option was turned on when the config object was created,
401       the section names will be returned in lowercase.
402
403   SectionExists ( $sect_name )
404       Returns 1 if the specified section exists in the INI file, 0 otherwise
405       (undefined if section_name is not defined).
406
407   AddSection ( $sect_name )
408       Ensures that the named section exists in the INI file. If the section
409       already exists, nothing is done. In this case, the "new" section will
410       possibly contain data already.
411
412       If you really need to have a new section with no parameters in it,
413       check that the name that you're adding isn't in the list of sections
414       already.
415
416   DeleteSection ( $sect_name )
417       Completely removes the entire section from the configuration.
418
419   RenameSection ( $old_section_name, $new_section_name,
420       $include_groupmembers)
421       Renames a section if it does not already exist, optionally including
422       groupmembers
423
424   CopySection ( $old_section_name, $new_section_name, $include_groupmembers)
425       Copies one section to another optionally including groupmembers
426
427   Parameters ($sect_name)
428       Returns an array containing the parameters contained in the specified
429       section.
430
431   Groups
432       Returns an array containing the names of available groups.
433
434       Groups are specified in the config file as new sections of the form
435
436         [GroupName MemberName]
437
438       This is useful for building up lists.  Note that parameters within a
439       "member" section are referenced normally (i.e., the section name is
440       still "Groupname Membername", including the space) - the concept of
441       Groups is to aid people building more complex configuration files.
442
443   SetGroupMember ( $sect )
444       Makes sure that the specified section is a member of the appropriate
445       group.
446
447       Only intended for use in newval.
448
449   RemoveGroupMember ( $sect )
450       Makes sure that the specified section is no longer a member of the
451       appropriate group. Only intended for use in DeleteSection.
452
453   GroupMembers ($group)
454       Returns an array containing the members of specified $group. Each
455       element of the array is a section name. For example, given the sections
456
457         [Group Element 1]
458         ...
459
460         [Group Element 2]
461         ...
462
463       GroupMembers would return ("Group Element 1", "Group Element 2").
464
465   SetWriteMode ($mode)
466       Sets the mode (permissions) to use when writing the INI file.
467
468       $mode must be a string representation of the octal mode.
469
470   GetWriteMode ($mode)
471       Gets the current mode (permissions) to use when writing the INI file.
472
473       $mode is a string representation of the octal mode.
474
475   WriteConfig ($filename [, %options])
476       Writes out a new copy of the configuration file.  A temporary file is
477       written out and then renamed to the specified filename.  Also see BUGS
478       below.
479
480       If "-delta" is set to a true value in %options, and this object was
481       imported from another (see "new"), only the differences between this
482       object and the imported one will be recorded. Negative deltas will be
483       encoded into comments, so that a subsequent invocation of new() with
484       the same imported object produces the same results (see the
485       -negativedeltas option in "new").
486
487       %options is not required.
488
489       Returns true on success, "undef" on failure.
490
491   RewriteConfig
492       Same as WriteConfig, but specifies that the original configuration file
493       should be rewritten.
494
495   GetFileName
496       Returns the filename associated with this INI file.
497
498       If no filename has been specified, returns undef.
499
500   SetFileName ($filename)
501       If you created the Config::IniFiles object without initialising from a
502       file, or if you just want to change the name of the file to use for
503       ReadConfig/RewriteConfig from now on, use this method.
504
505       Returns $filename if that was a valid name, undef otherwise.
506
507   $ini->OutputConfigToFileHandle($fh, $delta)
508       Writes OutputConfig to the $fh filehandle. $delta should be set to 1 1
509       if writing only delta. This is a newer and safer version of
510       OutputConfig() and one is encouraged to use it instead.
511
512   $ini->OutputConfig($delta)
513       Writes OutputConfig to STDOUT. Use select() to redirect STDOUT to the
514       output target before calling this function. Optional argument should be
515       set to 1 if writing only a delta. Also see OutputConfigToFileHandle
516
517   SetSectionComment($section, @comment)
518       Sets the comment for section $section to the lines contained in
519       @comment.
520
521       Each comment line will be prepended with the comment character (default
522       is "#") if it doesn't already have a comment character (ie: if the line
523       does not start with whitespace followed by an allowed comment
524       character, default is "#" and ";").
525
526       To clear a section comment, use DeleteSectionComment ($section)
527
528   GetSectionComment ($section)
529       Returns a list of lines, being the comment attached to section
530       $section. In scalar context, returns a string containing the lines of
531       the comment separated by newlines.
532
533       The lines are presented as-is, with whatever comment character was
534       originally used on that line.
535
536   DeleteSectionComment ($section)
537       Removes the comment for the specified section.
538
539   SetParameterComment ($section, $parameter, @comment)
540       Sets the comment attached to a particular parameter.
541
542       Any line of @comment that does not have a comment character will be
543       prepended with one. See "SetSectionComment($section, @comment)" above
544
545   GetParameterComment ($section, $parameter)
546       Gets the comment attached to a parameter. In list context returns all
547       comments - in scalar context returns them joined by newlines.
548
549   DeleteParameterComment ($section, $parameter)
550       Deletes the comment attached to a parameter.
551
552   GetParameterEOT ($section, $parameter)
553       Accessor method for the EOT text (in fact, style) of the specified
554       parameter. If any text is used as an EOT mark, this will be returned.
555       If the parameter was not recorded using HERE style multiple lines,
556       GetParameterEOT returns undef.
557
558   $cfg->SetParameterEOT ($section, $parameter, $EOT)
559       Accessor method for the EOT text for the specified parameter. Sets the
560       HERE style marker text to the value $EOT. Once the EOT text is set,
561       that parameter will be saved in HERE style.
562
563       To un-set the EOT text, use DeleteParameterEOT ($section, $parameter).
564
565   DeleteParameterEOT ($section, $parameter)
566       Removes the EOT marker for the given section and parameter.  When
567       writing a configuration file, if no EOT marker is defined then "EOT" is
568       used.
569
570   SetParameterTrailingComment ($section, $parameter, $cmt)
571       Set the end trailing comment for the given section and parameter.  If
572       there is a old comment for the parameter, it will be overwritten by the
573       new one.
574
575       If there is a new parameter trailing comment to be added, the value
576       should be added first.
577
578   GetParameterTrailingComment ($section, $parameter)
579       An accessor method to read the trailing comment after the parameter.
580       The trailing comment will be returned if there is one. A null string
581       will be returned if the parameter exists but there is no comment for
582       it.  otherwise, undef will be returned.
583
584   Delete
585       Deletes the entire configuration file in memory.
586

USAGE -- Tied Hash

588   tie %ini, 'Config::IniFiles', (-file=>$filename, [-option=>value ...] )
589       Using "tie", you can tie a hash to a Config::IniFiles object. This
590       creates a new object which you can access through your hash, so you use
591       this instead of the new method. This actually creates a hash of hashes
592       to access the values in the INI file. The options you provide through
593       "tie" are the same as given for the new method, above.
594
595       Here's an example:
596
597         use Config::IniFiles;
598
599         my %ini;
600         tie %ini, 'Config::IniFiles', ( -file => "/path/configfile.ini" );
601
602         print "We have $ini{Section}{Parameter}." if $ini{Section}{Parameter};
603
604       Accessing and using the hash works just like accessing a regular hash
605       and many of the object methods are made available through the hash
606       interface.
607
608       For those methods that do not coincide with the hash paradigm, you can
609       use the Perl "tied" function to get at the underlying object tied to
610       the hash and call methods on that object. For example, to write the
611       hash out to a new ini file, you would do something like this:
612
613         tied( %ini )->WriteConfig( "/newpath/newconfig.ini" ) ||
614           die "Could not write settings to new file.";
615
616   $val = $ini{$section}{$parameter}
617       Returns the value of $parameter in $section.
618
619       Multiline values accessed through a hash will be returned as a list in
620       list context and a concatenated value in scalar context.
621
622   $ini{$section}{$parameter} = $value;
623       Sets the value of $parameter in $section to $value.
624
625       To set a multiline or multi-value parameter just assign an array
626       reference to the hash entry, like this:
627
628        $ini{$section}{$parameter} = [$value1, $value2, ...];
629
630       If the parameter did not exist in the original file, it will be
631       created. However, Perl does not seem to extend autovivification to tied
632       hashes. That means that if you try to say
633
634         $ini{new_section}{new_paramters} = $val;
635
636       and the section 'new_section' does not exist, then Perl won't properly
637       create it. In order to work around this you will need to create a hash
638       reference in that section and then assign the parameter value.
639       Something like this should do nicely:
640
641         $ini{new_section} = {};
642         $ini{new_section}{new_paramters} = $val;
643
644   %hash = %{$ini{$section}}
645       Using the tie interface, you can copy whole sections of the ini file
646       into another hash. Note that this makes a copy of the entire section.
647       The new hash in no longer tied to the ini file, In particular, this
648       means -default and -nocase settings will not apply to %hash.
649
650   $ini{$section} = {}; %{$ini{$section}} = %parameters;
651       Through the hash interface, you have the ability to replace the entire
652       section with a new set of parameters. This call will fail, however, if
653       the argument passed in NOT a hash reference. You must use both lines,
654       as shown above so that Perl recognizes the section as a hash reference
655       context before COPYing over the values from your %parameters hash.
656
657   delete $ini{$section}{$parameter}
658       When tied to a hash, you can use the Perl "delete" function to
659       completely remove a parameter from a section.
660
661   delete $ini{$section}
662       The tied interface also allows you to delete an entire section from the
663       ini file using the Perl "delete" function.
664
665   %ini = ();
666       If you really want to delete all the items in the ini file, this will
667       do it. Of course, the changes won't be written to the actual file
668       unless you call RewriteConfig on the object tied to the hash.
669
670   Parameter names
671       my @keys = keys %{$ini{$section}}
672       while (($k, $v) = each %{$ini{$section}}) {...}
673       if( exists %{$ini{$section}}, $parameter ) {...}
674
675       When tied to a hash, you use the Perl "keys" and "each" functions to
676       iteratively list the parameters ("keys") or parameters and their values
677       ("each") in a given section.
678
679       You can also use the Perl "exists" function to see if a parameter is
680       defined in a given section.
681
682       Note that none of these will return parameter names that are part of
683       the default section (if set), although accessing an unknown parameter
684       in the specified section will return a value from the default section
685       if there is one.
686
687   Section names
688       foreach( keys %ini ) {...}
689       while (($k, $v) = each %ini) {...}
690       if( exists %ini, $section ) {...}
691
692       When tied to a hash, you use the Perl "keys" and "each" functions to
693       iteratively list the sections in the ini file.
694
695       You can also use the Perl "exists" function to see if a section is
696       defined in the file.
697

IMPORT / DELTA FEATURES

699       The -import option to "new" allows one to stack one Config::IniFiles
700       object on top of another (which might be itself stacked in turn and so
701       on recursively, but this is beyond the point). The effect, as briefly
702       explained in "new", is that the fields appearing in the composite
703       object will be a superposition of those coming from the ``original''
704       one and the lines coming from the file, the latter taking precedence.
705       For example, let's say that $master and "overlay" were created like
706       this:
707
708          my $master  = Config::IniFiles->new(-file => "master.ini");
709          my $overlay = Config::IniFiles->new(-file => "overlay.ini",
710                   -import => $master);
711
712       If the contents of "master.ini" and "overlay.ini" are respectively
713
714          ; master.ini
715          [section1]
716          arg0=unchanged from master.ini
717          arg1=val1
718
719          [section2]
720          arg2=val2
721
722       and
723
724          ; overlay.ini
725          [section1]
726          arg1=overridden
727
728       Then "$overlay->val("section1", "arg1")" is "overridden", while
729       "$overlay->val("section1", "arg0")" is "unchanged from master.ini".
730
731       This feature may be used to ship a ``global defaults'' configuration
732       file for a Perl application, that can be overridden piecewise by a much
733       shorter, per-site configuration file. Assuming UNIX-style path names,
734       this would be done like this:
735
736          my $defaultconfig = Config::IniFiles->new
737              (-file => "/usr/share/myapp/myapp.ini.default");
738          my $config = Config::IniFiles->new
739              (-file => "/etc/myapp.ini", -import => $defaultconfig);
740          # Now use $config and forget about $defaultconfig in the rest of
741          # the program
742
743       Starting with version 2.39, Config::IniFiles also provides features to
744       keep the importing / per-site configuration file small, by only saving
745       those options that were modified by the running program. That is, if
746       one calls
747
748          $overlay->setval("section1", "arg1", "anotherval");
749          $overlay->newval("section3", "arg3", "val3");
750          $overlay->WriteConfig('overlay.ini', -delta=>1);
751
752       "overlay.ini" would now contain
753
754          ; overlay.ini
755          [section1]
756          arg1=anotherval
757
758          [section3]
759          arg3=val3
760
761       This is called a delta file (see "WriteConfig"). The untouched
762       [section2] and arg0 do not appear, and the config file is therefore
763       shorter; while of course, reloading the configuration into $master and
764       $overlay, either through "$overlay->ReadConfig()" or through the same
765       code as above (e.g. when application restarts), would yield exactly the
766       same result had the overlay object been saved in whole to the file
767       system.
768
769       The only problem with this delta technique is one cannot delete the
770       default values in the overlay configuration file, only change them.
771       This is solved by a file format extension, enabled by the
772       -negativedeltas option to "new": if, say, one would delete parameters
773       like this,
774
775          $overlay->DeleteSection("section2");
776          $overlay->delval("section1", "arg0");
777          $overlay->WriteConfig('overlay.ini', -delta=>1);
778
779       The overlay.ini file would now read:
780
781          ; overlay.ini
782          [section1]
783          ; arg0 is deleted
784          arg1=anotherval
785
786          ; [section2] is deleted
787
788          [section3]
789          arg3=val3
790
791       Assuming $overlay was later re-read with "-negativedeltas => 1", the
792       parser would interpret the deletion comments to yield the correct
793       result, that is, [section2] and arg0 would cease to exist in the
794       $overlay object.
795

DIAGNOSTICS

797   @Config::IniFiles::errors
798       Contains a list of errors encountered while parsing the configuration
799       file.  If the new method returns undef, check the value of this to find
800       out what's wrong.  This value is reset each time a config file is read.
801

BUGS

803       •  The output from [Re]WriteConfig/OutputConfig might not be as pretty
804          as it can be.  Comments are tied to whatever was immediately below
805          them.  And case is not preserved for Section and Parameter names if
806          the -nocase option was used.
807
808       •  No locking is done by [Re]WriteConfig.  When writing servers, take
809          care that only the parent ever calls this, and consider making your
810          own backup.
811

Data Structure

813       Note that this is only a reference for the package maintainers - one of
814       the upcoming revisions to this package will include a total clean up of
815       the data structure.
816
817         $iniconf->{cf} = "config_file_name"
818                 ->{startup_settings} = \%orginal_object_parameters
819                 ->{imported} = $object WHERE $object->isa("Config::IniFiles")
820                 ->{nocase} = 0
821                 ->{reloadwarn} = 0
822                 ->{sects} = \@sections
823                 ->{mysects} = \@sections
824                 ->{sCMT}{$sect} = \@comment_lines
825                 ->{group}{$group} = \@group_members
826                 ->{parms}{$sect} = \@section_parms
827                 ->{myparms}{$sect} = \@section_parms
828                 ->{EOT}{$sect}{$parm} = "end of text string"
829                 ->{pCMT}{$sect}{$parm} = \@comment_lines
830                 ->{v}{$sect}{$parm} = $value   OR  \@values
831                 ->{e}{$sect} = 1 OR does not exist
832                 ->{mye}{$sect} = 1 OR does not exists
833

AUTHOR and ACKNOWLEDGEMENTS

835       The original code was written by Scott Hutton.  Then handled for a time
836       by Rich Bowen (thanks!), and was later managed by Jeremy Wadsack
837       (thanks!), and now is managed by Shlomi Fish (
838       <http://www.shlomifish.org/> ) with many contributions from various
839       other people.
840
841       In particular, special thanks go to (in roughly chronological order):
842
843       Bernie Cosell, Alan Young, Alex Satrapa, Mike Blazer, Wilbert van de
844       Pieterman, Steve Campbell, Robert Konigsberg, Scott Dellinger, R.
845       Bernstein, Daniel Winkelmann, Pires Claudio, Adrian Phillips, Marek
846       Rouchal, Luc St Louis, Adam Fischler, Kay Röpke, Matt Wilson, Raviraj
847       Murdeshwar and Slaven Rezic, Florian Pfaff
848
849       Geez, that's a lot of people. And apologies to the folks who were
850       missed.
851
852       If you want someone to bug about this, that would be:
853
854           Shlomi Fish <shlomif@cpan.org>
855
856       If you want more information, or want to participate, go to:
857
858       <http://sourceforge.net/projects/config-inifiles/>
859
860       Please submit bug reports using the Request Tracker interface at
861       <https://rt.cpan.org/Public/Dist/Display.html?Name=Config-IniFiles> .
862
863       Development discussion occurs on the mailing list
864       config-inifiles-dev@lists.sourceforge.net, which you can subscribe to
865       by going to the project web site (link above).
866

LICENSE

868       This software is copyright (c) 2000 by Scott Hutton and the rest of the
869       Config::IniFiles contributors.
870
871       This is free software; you can redistribute it and/or modify it under
872       the same terms as the Perl 5 programming language system itself.
873

AUTHOR

875       Shlomi Fish <shlomif@cpan.org>
876
878       This software is copyright (c) 2000 by RBOW and others.
879
880       This is free software; you can redistribute it and/or modify it under
881       the same terms as the Perl 5 programming language system itself.
882

BUGS

884       Please report any bugs or feature requests on the bugtracker website
885       <https://github.com/shlomif/perl-Config-IniFiles/issues>
886
887       When submitting a bug or request, please include a test-file or a patch
888       to an existing test-file that illustrates the bug or desired feature.
889

SUPPORT

891   Perldoc
892       You can find documentation for this module with the perldoc command.
893
894         perldoc Config::IniFiles
895
896   Websites
897       The following websites have more information about this module, and may
898       be of help to you. As always, in addition to those websites please use
899       your favorite search engine to discover more resources.
900
901       •   MetaCPAN
902
903           A modern, open-source CPAN search engine, useful to view POD in
904           HTML format.
905
906           <https://metacpan.org/release/Config-IniFiles>
907
908       •   RT: CPAN's Bug Tracker
909
910           The RT ( Request Tracker ) website is the default bug/issue
911           tracking system for CPAN.
912
913           <https://rt.cpan.org/Public/Dist/Display.html?Name=Config-IniFiles>
914
915       •   CPANTS
916
917           The CPANTS is a website that analyzes the Kwalitee ( code metrics )
918           of a distribution.
919
920           <http://cpants.cpanauthors.org/dist/Config-IniFiles>
921
922       •   CPAN Testers
923
924           The CPAN Testers is a network of smoke testers who run automated
925           tests on uploaded CPAN distributions.
926
927           <http://www.cpantesters.org/distro/C/Config-IniFiles>
928
929       •   CPAN Testers Matrix
930
931           The CPAN Testers Matrix is a website that provides a visual
932           overview of the test results for a distribution on various
933           Perls/platforms.
934
935           <http://matrix.cpantesters.org/?dist=Config-IniFiles>
936
937       •   CPAN Testers Dependencies
938
939           The CPAN Testers Dependencies is a website that shows a chart of
940           the test results of all dependencies for a distribution.
941
942           <http://deps.cpantesters.org/?module=Config::IniFiles>
943
944   Bugs / Feature Requests
945       Please report any bugs or feature requests by email to
946       "bug-config-inifiles at rt.cpan.org", or through the web interface at
947       <https://rt.cpan.org/Public/Bug/Report.html?Queue=Config-IniFiles>. You
948       will be automatically notified of any progress on the request by the
949       system.
950
951   Source Code
952       The code is open to the world, and available for you to hack on. Please
953       feel free to browse it and play with it, or whatever. If you want to
954       contribute patches, please send me a diff or prod me to pull from your
955       repository :)
956
957       <https://github.com/shlomif/perl-Config-IniFiles>
958
959         git clone git://github.com/shlomif/perl-Config-IniFiles.git
960
961
962
963perl v5.36.0                      2023-01-20               Config::IniFiles(3)
Impressum