{ "content": [ { "type": "text", "text": "# Config::IniFiles (perldoc)\n\n## NAME\n\nConfig::IniFiles - A module for reading .ini-style configuration files.\n\n## SYNOPSIS\n\nuse Config::IniFiles;\nmy $cfg = Config::IniFiles->new( -file => \"/path/configfile.ini\" );\nprint \"The value is \" . $cfg->val( 'Section', 'Parameter' ) . \".\"\nif $cfg->val( 'Section', 'Parameter' );\n\n## DESCRIPTION\n\nConfig::IniFiles provides a way to have readable configuration files outside your Perl script.\nConfigurations can be imported (inherited, stacked,...), sections can be grouped, and settings\ncan be accessed from a tied hash.\n\n## Sections\n\n- **NAME**\n- **VERSION**\n- **SYNOPSIS**\n- **DESCRIPTION**\n- **FILE FORMAT**\n- **METHODS** (9 subsections)\n- **IMPORT / DELTA FEATURES**\n- **DIAGNOSTICS**\n- **BUGS**\n- **Data Structure**\n- **LICENSE**\n- **AUTHOR**\n- **COPYRIGHT AND LICENSE**\n- **SUPPORT** (3 subsections)\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n" } ], "structuredContent": { "command": "Config::IniFiles", "section": "", "mode": "perldoc", "summary": "Config::IniFiles - A module for reading .ini-style configuration files.", "synopsis": "use Config::IniFiles;\nmy $cfg = Config::IniFiles->new( -file => \"/path/configfile.ini\" );\nprint \"The value is \" . $cfg->val( 'Section', 'Parameter' ) . \".\"\nif $cfg->val( 'Section', 'Parameter' );", "tldr_summary": null, "tldr_examples": [], "tldr_source": null, "flags": [], "examples": [], "see_also": [], "section_outline": [ { "name": "NAME", "lines": 2, "subsections": [] }, { "name": "VERSION", "lines": 2, "subsections": [] }, { "name": "SYNOPSIS", "lines": 5, "subsections": [] }, { "name": "DESCRIPTION", "lines": 4, "subsections": [] }, { "name": "FILE FORMAT", "lines": 59, "subsections": [] }, { "name": "METHODS", "lines": 264, "subsections": [ { "name": "ReadConfig", "lines": 7 }, { "name": "Sections", "lines": 26 }, { "name": "Groups", "lines": 54 }, { "name": "RewriteConfig", "lines": 2 }, { "name": "GetFileName", "lines": 76 }, { "name": "Delete", "lines": 78 }, { "name": "Parameter names", "lines": 13 }, { "name": "Section names", "lines": 1 }, { "name": "foreach", "lines": 8 } ] }, { "name": "IMPORT / DELTA FEATURES", "lines": 88, "subsections": [] }, { "name": "DIAGNOSTICS", "lines": 5, "subsections": [] }, { "name": "BUGS", "lines": 6, "subsections": [] }, { "name": "Data Structure", "lines": 48, "subsections": [] }, { "name": "LICENSE", "lines": 6, "subsections": [] }, { "name": "AUTHOR", "lines": 2, "subsections": [] }, { "name": "COPYRIGHT AND LICENSE", "lines": 5, "subsections": [] }, { "name": "SUPPORT", "lines": 1, "subsections": [ { "name": "Perldoc", "lines": 4 }, { "name": "Websites", "lines": 48 }, { "name": "Source Code", "lines": 8 } ] } ], "sections": { "NAME": { "content": "Config::IniFiles - A module for reading .ini-style configuration files.\n", "subsections": [] }, "VERSION": { "content": "version 3.000003\n", "subsections": [] }, "SYNOPSIS": { "content": "use Config::IniFiles;\nmy $cfg = Config::IniFiles->new( -file => \"/path/configfile.ini\" );\nprint \"The value is \" . $cfg->val( 'Section', 'Parameter' ) . \".\"\nif $cfg->val( 'Section', 'Parameter' );\n", "subsections": [] }, "DESCRIPTION": { "content": "Config::IniFiles provides a way to have readable configuration files outside your Perl script.\nConfigurations can be imported (inherited, stacked,...), sections can be grouped, and settings\ncan be accessed from a tied hash.\n", "subsections": [] }, "FILE FORMAT": { "content": "INI files consist of a number of sections, each preceded with the section name in square\nbrackets, followed by parameter names and their values.\n\n[a section]\nParameter=Value\n\n[section 2]\nAnotherParameter=Some value\nSetting=Something else\nParameter=Different scope than the one in the first section\n\nThe first non-blank character of the line indicating a section must be a left bracket and the\nlast non-blank character of a line indicating a section must be a right bracket. The characters\nmaking up the section name can be any symbols at all. However section names must be unique.\n\nParameters are specified in each section as Name=Value. Any spaces around the equals sign will\nbe ignored, and the value extends to the end of the line (including any whitespace at the end of\nthe line. Parameter names are localized to the namespace of the section, but must be unique\nwithin a section.\n\nBoth the hash mark (#) and the semicolon (;) are comment characters. by default (this can be\nchanged by configuration). Lines that begin with either of these characters will be ignored. Any\namount of whitespace may precede the comment character.\n\nMulti-line or multi-valued parameters may also be defined ala UNIX \"here document\" syntax:\n\nParameter=<new( -file => \"/path/configfile.ini\" );\n$cfg = new Config::IniFiles -file => \"/path/configfile.ini\";\n\nOptional named parameters may be specified after the configuration file name. See the *new* in\nthe METHODS section, below.\n\nValues from the config file are fetched with the val method:\n\n$value = $cfg->val('Section', 'Parameter');\n\nIf you want a multi-line/value field returned as an array, just specify an array as the\nreceiver:\n\n@values = $cfg->val('Section', 'Parameter');\n", "subsections": [] }, "METHODS": { "content": "new ( [-option=>value ...] )\nReturns a new configuration object (or \"undef\" if the configuration file has an error, in which\ncase check the global @Config::IniFiles::errors array for reasons why). One Config::IniFiles\nobject is required per configuration file. The following named parameters are available:\n\n*-file* filename\nSpecifies a file to load the parameters from. This 'file' may actually be any of the\nfollowing things:\n\n1) the pathname of a file\n\n$cfg = Config::IniFiles->new( -file => \"/path/to/configfile.ini\" );\n\n2) a simple filehandle\n\n$cfg = Config::IniFiles->new( -file => STDIN );\n\n3) a filehandle glob\n\nopen( CONFIG, \"/path/to/configfile.ini\" );\n$cfg = Config::IniFiles->new( -file => *CONFIG );\n\n4) a reference to a glob\n\nopen( CONFIG, \"/path/to/configfile.ini\" );\n$cfg = Config::IniFiles->new( -file => \\*CONFIG );\n\n5) an IO::File object\n\n$io = IO::File->new( \"/path/to/configfile.ini\" );\n$cfg = Config::IniFiles->new( -file => $io );\n\nor\n\nopen my $fh, '<', \"/path/to/configfile.ini\" or die $!;\n$cfg = Config::IniFiles->new( -file => $fh );\n\n6) A reference to a scalar (requires newer versions of IO::Scalar)\n\n$inifilecontents = <new( -file => \\$inifilecontents );\n\nIf this option is not specified, (i.e. you are creating a config file from scratch)\nyou must specify a target file using SetFileName in order to save the parameters.\n\n*-default* section\nSpecifies a section to be used for default values. For example, in the following\nconfiguration file, if you look up the \"permissions\" parameter in the \"joe\" section,\nthere is none.\n\n[all]\npermissions=Nothing\n\n[jane]\nname=Jane\npermissions=Open files\n\n[joe]\nname=Joseph\n\nIf you create your Config::IniFiles object with a default section of \"all\" like this:\n\n$cfg = Config::IniFiles->new( -file => \"file.ini\", -default => \"all\" );\n\nThen requesting a value for a \"permissions\" in the [joe] section will check for a\nvalue from [all] before returning undef.\n\n$permissions = $cfg->val( \"joe\", \"permissions\"); // returns \"Nothing\"\n\n*-fallback* section\nSpecifies a section to be used for parameters outside a section. Default is none.\nWithout -fallback specified (which is the default), reading a configuration file which\nhas a parameter outside a section will fail. With this set to, say, \"GENERAL\", this\nconfiguration:\n\nwrong=wronger\n\n[joe]\nname=Joseph\n\nwill be assumed as:\n\n[GENERAL]\nwrong=wronger\n\n[joe]\nname=Joseph\n\nNote that Config::IniFiles will also omit the fallback section header when outputting\nsuch configuration.\n\n*-nocase* 0|1\nSet -nocase => 1 to handle the config file in a case-insensitive manner (case in\nvalues is preserved, however). By default, config files are case-sensitive (i.e., a\nsection named 'Test' is not the same as a section named 'test'). Note that there is an\nadded overhead for turning off case sensitivity.\n\n*-import* object\nThis allows you to import or inherit existing setting from another Config::IniFiles\nobject. When importing settings from another object, sections with the same name will\nbe merged and parameters that are defined in both the imported object and the *-file*\nwill take the value of given in the *-file*.\n\nIf a *-default* section is also given on this call, and it does not coincide with the\ndefault of the imported object, the new default section will be used instead. If no\n*-default* section is given, then the default of the imported object will be used.\n\n*-allowcontinue* 0|1\nSet -allowcontinue => 1 to enable continuation lines in the config file. i.e. if a\nline ends with a backslash \"\\\", then the following line is appended to the parameter\nvalue, dropping the backslash and the newline character(s).\n\nDefault behavior is to keep a trailing backslash \"\\\" as a parameter value. Note that\ncontinuation cannot be mixed with the \"here\" value syntax.\n\n*-allowempty* 0|1\nIf set to 1, then empty files are allowed at ReadConfig time. If set to 0 (the\ndefault), an empty configuration file is considered an error.\n\n*-negativedeltas* 0|1\nIf set to 1 (the default if importing this object from another one), parses and honors\nlines of the following form in the configuration file:\n\n; [somesection] is deleted\n\nor\n\n[inthissection]\n; thisparameter is deleted\n\nIf set to 0 (the default if not importing), these comments are treated like ordinary\nones.\n\nThe WriteConfig1)> form will output such comments to indicate deleted sections or\nparameters. This way, reloading a delta file using the same imported object produces\nthe same results in memory again. See \" DELTA FEATURES\" in IMPORT for more details.\n\n*-commentchar* 'char'\nThe default comment character is \"#\". You may change this by specifying this option to\nanother character. This can be any character except alphanumeric characters, square\nbrackets or the \"equal\" sign.\n\n*-allowedcommentchars* 'chars'\nAllowed default comment characters are \"#\" and \";\". By specifying this option you may\nchange the range of characters that are used to denote a comment line to include any\nset of characters\n\nNote: that the character specified by -commentchar (see above) is *always* part of the\nallowed comment characters.\n\nNote 2: The given string is evaluated as a regular expression character class, so '\\'\nmust be escaped if you wish to use it.\n\n*-reloadwarn* 0|1\nSet -reloadwarn => 1 to enable a warning message (output to STDERR) whenever the\nconfig file is reloaded. The reload message is of the form:\n\nPID reloading config file at YYYY.MM.DD HH:MM:SS\n\nDefault behavior is to not warn (i.e. -reloadwarn => 0).\n\nThis is generally only useful when using Config::IniFiles in a server or daemon\napplication. The application is still responsible for determining when the object is\nto be reloaded.\n\n*-nomultiline* 0|1\nSet -nomultiline => 1 to output multi-valued parameter as:\n\nparam=value1\nparam=value2\n\ninstead of the default:\n\nparam=< 1 to enable support of parameter trailing comments.\n\nFor example, if we have a parameter line like this:\n\nparam1=value1;comment1\n\nby default, handletrailingcomment will be set to 0, and we will get\n*value1;comment1* as the value of *param1*. If we have -handletrailingcomment set to\n1, then we will get *value1* as the value for *param1*, and *comment1* as the trailing\ncomment of *param1*.\n\nSet and get methods for trailing comments are provided as\n\"SetParameterTrailingComment\" and \"GetParameterTrailingComment\".\n\n*-phpcompat* 0|1\nSet -phpcompat => 1 to enable support for PHP like configfiles.\n\nThe differences between parseinifile and Config::IniFiles are:\n\n# parseinifile\n[group]\nval1=\"value\"\nval2[]=1\nval2[]=2\n\nvs\n\n# Config::IniFiles\n[group]\nval1=value\nval2=1\nval2=2\n\nThis option only affect parsing, not writing new configfiles.\n\nSome features from parseinifile are not compatible:\n\n[group]\nval1=\"val\"'ue'\nval1[key]=1\n\nval ($section, $parameter [, $default] )\nReturns the value of the specified parameter ($parameter) in section $section, returns undef (or\n$default if specified) if no section or no parameter for the given section exists.\n\nIf you want a multi-line/value field returned as an array, just specify an array as the\nreceiver:\n\n@values = $cfg->val('Section', 'Parameter');\n\nA multi-line/value field that is returned in a scalar context will be joined using $/ (input\nrecord separator, default is \\n) if defined, otherwise the values will be joined using \\n.\n\nexists($section, $parameter)\nTrue if and only if there exists a section $section, with a parameter $parameter inside, not\ncounting default values.\n\npush ($section, $parameter, $value, [ $value2, ...])\nPushes new values at the end of existing value(s) of parameter $parameter in section $section.\nSee below for methods to write the new configuration back out to a file.\n\nYou may not set a parameter that didn't exist in the original configuration file. push will\nreturn *undef* if this is attempted. See newval below to do this. Otherwise, it returns 1.\n\nsetval ($section, $parameter, $value, [ $value2, ... ])\nSets the value of parameter $parameter in section $section to $value (or to a set of values).\nSee below for methods to write the new configuration back out to a file.\n\nYou may not set a parameter that didn't exist in the original configuration file. setval will\nreturn *undef* if this is attempted. See newval below to do this. Otherwise, it returns 1.\n\nnewval($section, $parameter, $value [, $value2, ...])\nAssigns a new value, $value (or set of values) to the parameter $parameter in section $section\nin the configuration file.\n\ndelval($section, $parameter)\nDeletes the specified parameter from the configuration file\n", "subsections": [ { "name": "ReadConfig", "content": "Forces the configuration file to be re-read. Returns undef if the file can not be opened, no\nfilename was defined (with the \"-file\" option) when the object was constructed, or an error\noccurred while reading.\n\nIf an error occurs while parsing the INI file the @Config::IniFiles::errors array will contain\nmessages that might help you figure out where the problem is in the file.\n" }, { "name": "Sections", "content": "Returns an array containing section names in the configuration file. If the *nocase* option was\nturned on when the config object was created, the section names will be returned in lowercase.\n\nSectionExists ( $sectname )\nReturns 1 if the specified section exists in the INI file, 0 otherwise (undefined if\nsectionname is not defined).\n\nAddSection ( $sectname )\nEnsures that the named section exists in the INI file. If the section already exists, nothing is\ndone. In this case, the \"new\" section will possibly contain data already.\n\nIf you really need to have a new section with no parameters in it, check that the name that\nyou're adding isn't in the list of sections already.\n\nDeleteSection ( $sectname )\nCompletely removes the entire section from the configuration.\n\nRenameSection ( $oldsectionname, $newsectionname, $includegroupmembers)\nRenames a section if it does not already exist, optionally including groupmembers\n\nCopySection ( $oldsectionname, $newsectionname, $includegroupmembers)\nCopies one section to another optionally including groupmembers\n\nParameters ($sectname)\nReturns an array containing the parameters contained in the specified section.\n" }, { "name": "Groups", "content": "Returns an array containing the names of available groups.\n\nGroups are specified in the config file as new sections of the form\n\n[GroupName MemberName]\n\nThis is useful for building up lists. Note that parameters within a \"member\" section are\nreferenced normally (i.e., the section name is still \"Groupname Membername\", including the\nspace) - the concept of Groups is to aid people building more complex configuration files.\n\nSetGroupMember ( $sect )\nMakes sure that the specified section is a member of the appropriate group.\n\nOnly intended for use in newval.\n\nRemoveGroupMember ( $sect )\nMakes sure that the specified section is no longer a member of the appropriate group. Only\nintended for use in DeleteSection.\n\nGroupMembers ($group)\nReturns an array containing the members of specified $group. Each element of the array is a\nsection name. For example, given the sections\n\n[Group Element 1]\n...\n\n[Group Element 2]\n...\n\nGroupMembers would return (\"Group Element 1\", \"Group Element 2\").\n\nSetWriteMode ($mode)\nSets the mode (permissions) to use when writing the INI file.\n\n$mode must be a string representation of the octal mode.\n\nGetWriteMode ($mode)\nGets the current mode (permissions) to use when writing the INI file.\n\n$mode is a string representation of the octal mode.\n\nWriteConfig ($filename [, %options])\nWrites out a new copy of the configuration file. A temporary file is written out and then\nrenamed to the specified filename. Also see BUGS below.\n\nIf \"-delta\" is set to a true value in %options, and this object was imported from another (see\n\"new\"), only the differences between this object and the imported one will be recorded. Negative\ndeltas will be encoded into comments, so that a subsequent invocation of *new()* with the same\nimported object produces the same results (see the *-negativedeltas* option in \"new\").\n\n%options is not required.\n\nReturns true on success, \"undef\" on failure.\n" }, { "name": "RewriteConfig", "content": "Same as WriteConfig, but specifies that the original configuration file should be rewritten.\n" }, { "name": "GetFileName", "content": "Returns the filename associated with this INI file.\n\nIf no filename has been specified, returns undef.\n\nSetFileName ($filename)\nIf you created the Config::IniFiles object without initialising from a file, or if you just want\nto change the name of the file to use for ReadConfig/RewriteConfig from now on, use this method.\n\nReturns $filename if that was a valid name, undef otherwise.\n\n$ini->OutputConfigToFileHandle($fh, $delta)\nWrites OutputConfig to the $fh filehandle. $delta should be set to 1 1 if writing only delta.\nThis is a newer and safer version of \"OutputConfig()\" and one is encouraged to use it instead.\n\n$ini->OutputConfig($delta)\nWrites OutputConfig to STDOUT. Use select() to redirect STDOUT to the output target before\ncalling this function. Optional argument should be set to 1 if writing only a delta. Also see\nOutputConfigToFileHandle\n\nSetSectionComment($section, @comment)\nSets the comment for section $section to the lines contained in @comment.\n\nEach comment line will be prepended with the comment character (default is \"#\") if it doesn't\nalready have a comment character (ie: if the line does not start with whitespace followed by an\nallowed comment character, default is \"#\" and \";\").\n\nTo clear a section comment, use DeleteSectionComment ($section)\n\nGetSectionComment ($section)\nReturns a list of lines, being the comment attached to section $section. In scalar context,\nreturns a string containing the lines of the comment separated by newlines.\n\nThe lines are presented as-is, with whatever comment character was originally used on that line.\n\nDeleteSectionComment ($section)\nRemoves the comment for the specified section.\n\nSetParameterComment ($section, $parameter, @comment)\nSets the comment attached to a particular parameter.\n\nAny line of @comment that does not have a comment character will be prepended with one. See\n\"SetSectionComment($section, @comment)\" above\n\nGetParameterComment ($section, $parameter)\nGets the comment attached to a parameter. In list context returns all comments - in scalar\ncontext returns them joined by newlines.\n\nDeleteParameterComment ($section, $parameter)\nDeletes the comment attached to a parameter.\n\nGetParameterEOT ($section, $parameter)\nAccessor method for the EOT text (in fact, style) of the specified parameter. If any text is\nused as an EOT mark, this will be returned. If the parameter was not recorded using HERE style\nmultiple lines, GetParameterEOT returns undef.\n\n$cfg->SetParameterEOT ($section, $parameter, $EOT)\nAccessor method for the EOT text for the specified parameter. Sets the HERE style marker text to\nthe value $EOT. Once the EOT text is set, that parameter will be saved in HERE style.\n\nTo un-set the EOT text, use DeleteParameterEOT ($section, $parameter).\n\nDeleteParameterEOT ($section, $parameter)\nRemoves the EOT marker for the given section and parameter. When writing a configuration file,\nif no EOT marker is defined then \"EOT\" is used.\n\nSetParameterTrailingComment ($section, $parameter, $cmt)\nSet the end trailing comment for the given section and parameter. If there is a old comment for\nthe parameter, it will be overwritten by the new one.\n\nIf there is a new parameter trailing comment to be added, the value should be added first.\n\nGetParameterTrailingComment ($section, $parameter)\nAn accessor method to read the trailing comment after the parameter. The trailing comment will\nbe returned if there is one. A null string will be returned if the parameter exists but there is\nno comment for it. otherwise, undef will be returned.\n" }, { "name": "Delete", "content": "Deletes the entire configuration file in memory.\n\nUSAGE -- Tied Hash\ntie %ini, 'Config::IniFiles', (-file=>$filename, [-option=>value ...] )\nUsing \"tie\", you can tie a hash to a Config::IniFiles object. This creates a new object which\nyou can access through your hash, so you use this instead of the new method. This actually\ncreates a hash of hashes to access the values in the INI file. The options you provide through\n\"tie\" are the same as given for the new method, above.\n\nHere's an example:\n\nuse Config::IniFiles;\n\nmy %ini;\ntie %ini, 'Config::IniFiles', ( -file => \"/path/configfile.ini\" );\n\nprint \"We have $ini{Section}{Parameter}.\" if $ini{Section}{Parameter};\n\nAccessing and using the hash works just like accessing a regular hash and many of the object\nmethods are made available through the hash interface.\n\nFor those methods that do not coincide with the hash paradigm, you can use the Perl \"tied\"\nfunction to get at the underlying object tied to the hash and call methods on that object. For\nexample, to write the hash out to a new ini file, you would do something like this:\n\ntied( %ini )->WriteConfig( \"/newpath/newconfig.ini\" ) ||\ndie \"Could not write settings to new file.\";\n\n$val = $ini{$section}{$parameter}\nReturns the value of $parameter in $section.\n\nMultiline values accessed through a hash will be returned as a list in list context and a\nconcatenated value in scalar context.\n\n$ini{$section}{$parameter} = $value;\nSets the value of $parameter in $section to $value.\n\nTo set a multiline or multi-value parameter just assign an array reference to the hash entry,\nlike this:\n\n$ini{$section}{$parameter} = [$value1, $value2, ...];\n\nIf the parameter did not exist in the original file, it will be created. However, Perl does not\nseem to extend autovivification to tied hashes. That means that if you try to say\n\n$ini{newsection}{newparamters} = $val;\n\nand the section 'newsection' does not exist, then Perl won't properly create it. In order to\nwork around this you will need to create a hash reference in that section and then assign the\nparameter value. Something like this should do nicely:\n\n$ini{newsection} = {};\n$ini{newsection}{newparamters} = $val;\n\n%hash = %{$ini{$section}}\nUsing the tie interface, you can copy whole sections of the ini file into another hash. Note\nthat this makes a copy of the entire section. The new hash in no longer tied to the ini file, In\nparticular, this means -default and -nocase settings will not apply to %hash.\n\n$ini{$section} = {}; %{$ini{$section}} = %parameters;\nThrough the hash interface, you have the ability to replace the entire section with a new set of\nparameters. This call will fail, however, if the argument passed in NOT a hash reference. You\nmust use both lines, as shown above so that Perl recognizes the section as a hash reference\ncontext before COPYing over the values from your %parameters hash.\n\ndelete $ini{$section}{$parameter}\nWhen tied to a hash, you can use the Perl \"delete\" function to completely remove a parameter\nfrom a section.\n\ndelete $ini{$section}\nThe tied interface also allows you to delete an entire section from the ini file using the Perl\n\"delete\" function.\n\n%ini = ();\nIf you really want to delete all the items in the ini file, this will do it. Of course, the\nchanges won't be written to the actual file unless you call RewriteConfig on the object tied to\nthe hash.\n" }, { "name": "Parameter names", "content": "my @keys = keys %{$ini{$section}}\nwhile (($k, $v) = each %{$ini{$section}}) {...}\nif( exists %{$ini{$section}}, $parameter ) {...}\n\nWhen tied to a hash, you use the Perl \"keys\" and \"each\" functions to iteratively list the\nparameters (\"keys\") or parameters and their values (\"each\") in a given section.\n\nYou can also use the Perl \"exists\" function to see if a parameter is defined in a given section.\n\nNote that none of these will return parameter names that are part of the default section (if\nset), although accessing an unknown parameter in the specified section will return a value from\nthe default section if there is one.\n" }, { "name": "Section names", "content": "" }, { "name": "foreach", "content": "while (($k, $v) = each %ini) {...}\nif( exists %ini, $section ) {...}\n\nWhen tied to a hash, you use the Perl \"keys\" and \"each\" functions to iteratively list the\nsections in the ini file.\n\nYou can also use the Perl \"exists\" function to see if a section is defined in the file.\n" } ] }, "IMPORT / DELTA FEATURES": { "content": "The *-import* option to \"new\" allows one to stack one *Config::IniFiles* object on top of\nanother (which might be itself stacked in turn and so on recursively, but this is beyond the\npoint). The effect, as briefly explained in \"new\", is that the fields appearing in the composite\nobject will be a superposition of those coming from the ``original'' one and the lines coming\nfrom the file, the latter taking precedence. For example, let's say that $master and \"overlay\"\nwere created like this:\n\nmy $master = Config::IniFiles->new(-file => \"master.ini\");\nmy $overlay = Config::IniFiles->new(-file => \"overlay.ini\",\n-import => $master);\n\nIf the contents of \"master.ini\" and \"overlay.ini\" are respectively\n\n; master.ini\n[section1]\narg0=unchanged from master.ini\narg1=val1\n\n[section2]\narg2=val2\n\nand\n\n; overlay.ini\n[section1]\narg1=overridden\n\nThen \"$overlay->val(\"section1\", \"arg1\")\" is \"overridden\", while \"$overlay->val(\"section1\",\n\"arg0\")\" is \"unchanged from master.ini\".\n\nThis feature may be used to ship a ``global defaults'' configuration file for a Perl\napplication, that can be overridden piecewise by a much shorter, per-site configuration file.\nAssuming UNIX-style path names, this would be done like this:\n\nmy $defaultconfig = Config::IniFiles->new\n(-file => \"/usr/share/myapp/myapp.ini.default\");\nmy $config = Config::IniFiles->new\n(-file => \"/etc/myapp.ini\", -import => $defaultconfig);\n# Now use $config and forget about $defaultconfig in the rest of\n# the program\n\nStarting with version 2.39, *Config::IniFiles* also provides features to keep the importing /\nper-site configuration file small, by only saving those options that were modified by the\nrunning program. That is, if one calls\n\n$overlay->setval(\"section1\", \"arg1\", \"anotherval\");\n$overlay->newval(\"section3\", \"arg3\", \"val3\");\n$overlay->WriteConfig('overlay.ini', -delta=>1);\n\n\"overlay.ini\" would now contain\n\n; overlay.ini\n[section1]\narg1=anotherval\n\n[section3]\narg3=val3\n\nThis is called a *delta file* (see \"WriteConfig\"). The untouched [section2] and arg0 do not\nappear, and the config file is therefore shorter; while of course, reloading the configuration\ninto $master and $overlay, either through \"$overlay->ReadConfig()\" or through the same code as\nabove (e.g. when application restarts), would yield exactly the same result had the overlay\nobject been saved in whole to the file system.\n\nThe only problem with this delta technique is one cannot delete the default values in the\noverlay configuration file, only change them. This is solved by a file format extension, enabled\nby the *-negativedeltas* option to \"new\": if, say, one would delete parameters like this,\n\n$overlay->DeleteSection(\"section2\");\n$overlay->delval(\"section1\", \"arg0\");\n$overlay->WriteConfig('overlay.ini', -delta=>1);\n\nThe *overlay.ini* file would now read:\n\n; overlay.ini\n[section1]\n; arg0 is deleted\narg1=anotherval\n\n; [section2] is deleted\n\n[section3]\narg3=val3\n\nAssuming $overlay was later re-read with \"-negativedeltas => 1\", the parser would interpret the\ndeletion comments to yield the correct result, that is, [section2] and arg0 would cease to exist\nin the $overlay object.\n", "subsections": [] }, "DIAGNOSTICS": { "content": "@Config::IniFiles::errors\nContains a list of errors encountered while parsing the configuration file. If the *new* method\nreturns undef, check the value of this to find out what's wrong. This value is reset each time a\nconfig file is read.\n", "subsections": [] }, "BUGS": { "content": "Please report any bugs or feature requests on the bugtracker website\n\n\nWhen submitting a bug or request, please include a test-file or a patch to an existing test-file\nthat illustrates the bug or desired feature.\n", "subsections": [] }, "Data Structure": { "content": "Note that this is only a reference for the package maintainers - one of the upcoming revisions\nto this package will include a total clean up of the data structure.\n\n$iniconf->{cf} = \"configfilename\"\n->{startupsettings} = \\%orginalobjectparameters\n->{imported} = $object WHERE $object->isa(\"Config::IniFiles\")\n->{nocase} = 0\n->{reloadwarn} = 0\n->{sects} = \\@sections\n->{mysects} = \\@sections\n->{sCMT}{$sect} = \\@commentlines\n->{group}{$group} = \\@groupmembers\n->{parms}{$sect} = \\@sectionparms\n->{myparms}{$sect} = \\@sectionparms\n->{EOT}{$sect}{$parm} = \"end of text string\"\n->{pCMT}{$sect}{$parm} = \\@commentlines\n->{v}{$sect}{$parm} = $value OR \\@values\n->{e}{$sect} = 1 OR does not exist\n->{mye}{$sect} = 1 OR does not exists\n\nAUTHOR and ACKNOWLEDGEMENTS\nThe original code was written by Scott Hutton. Then handled for a time by Rich Bowen (thanks!),\nand was later managed by Jeremy Wadsack (thanks!), and now is managed by Shlomi Fish (\n ) with many contributions from various other people.\n\nIn particular, special thanks go to (in roughly chronological order):\n\nBernie Cosell, Alan Young, Alex Satrapa, Mike Blazer, Wilbert van de Pieterman, Steve Campbell,\nRobert Konigsberg, Scott Dellinger, R. Bernstein, Daniel Winkelmann, Pires Claudio, Adrian\nPhillips, Marek Rouchal, Luc St Louis, Adam Fischler, Kay Röpke, Matt Wilson, Raviraj Murdeshwar\nand Slaven Rezic, Florian Pfaff\n\nGeez, that's a lot of people. And apologies to the folks who were missed.\n\nIf you want someone to bug about this, that would be:\n\nShlomi Fish \n\nIf you want more information, or want to participate, go to:\n\n\n\nPlease submit bug reports using the Request Tracker interface at\n .\n\nDevelopment discussion occurs on the mailing list config-inifiles-dev@lists.sourceforge.net,\nwhich you can subscribe to by going to the project web site (link above).\n", "subsections": [] }, "LICENSE": { "content": "This software is copyright (c) 2000 by Scott Hutton and the rest of the Config::IniFiles\ncontributors.\n\nThis is free software; you can redistribute it and/or modify it under the same terms as the Perl\n5 programming language system itself.\n", "subsections": [] }, "AUTHOR": { "content": "Shlomi Fish \n", "subsections": [] }, "COPYRIGHT AND LICENSE": { "content": "This software is copyright (c) 2000 by RBOW and others.\n\nThis is free software; you can redistribute it and/or modify it under the same terms as the Perl\n5 programming language system itself.\n", "subsections": [] }, "SUPPORT": { "content": "", "subsections": [ { "name": "Perldoc", "content": "You can find documentation for this module with the perldoc command.\n\nperldoc Config::IniFiles\n" }, { "name": "Websites", "content": "The following websites have more information about this module, and may be of help to you. As\nalways, in addition to those websites please use your favorite search engine to discover more\nresources.\n\n* MetaCPAN\n\nA modern, open-source CPAN search engine, useful to view POD in HTML format.\n\n\n\n* RT: CPAN's Bug Tracker\n\nThe RT ( Request Tracker ) website is the default bug/issue tracking system for CPAN.\n\n\n\n* CPANTS\n\nThe CPANTS is a website that analyzes the Kwalitee ( code metrics ) of a distribution.\n\n\n\n* CPAN Testers\n\nThe CPAN Testers is a network of smoke testers who run automated tests on uploaded CPAN\ndistributions.\n\n\n\n* CPAN Testers Matrix\n\nThe CPAN Testers Matrix is a website that provides a visual overview of the test results for\na distribution on various Perls/platforms.\n\n\n\n* CPAN Testers Dependencies\n\nThe CPAN Testers Dependencies is a website that shows a chart of the test results of all\ndependencies for a distribution.\n\n\n\nBugs / Feature Requests\nPlease report any bugs or feature requests by email to \"bug-config-inifiles at rt.cpan.org\", or\nthrough the web interface at .\nYou will be automatically notified of any progress on the request by the system.\n" }, { "name": "Source Code", "content": "The code is open to the world, and available for you to hack on. Please feel free to browse it\nand play with it, or whatever. If you want to contribute patches, please send me a diff or prod\nme to pull from your repository :)\n\n\n\ngit clone git://github.com/shlomif/perl-Config-IniFiles.git\n" } ] } } } }