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.000002
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

VERSION

24       version 3.000002
25

FILE FORMAT

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

USAGE -- Object Interface

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

METHODS

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

USAGE -- Tied Hash

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

IMPORT / DELTA FEATURES

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

DIAGNOSTICS

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

BUGS

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

Data Structure

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

AUTHOR and ACKNOWLEDGEMENTS

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

LICENSE

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

AUTHOR

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

BUGS

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

SUPPORT

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