Config::Ini - Perl interface to MS-Windows registry files, Windows .ini and Unreal style .ini files.
use Config::Ini; $ini = new Config::Ini('system.ini'); # MS-Windows style print $ini->get(['system', 'path']); $oldpath = $ini->put(['system', 'path', 'C:\\windows']); if ($ini->exists(['system', 'path'])) ... $ini->delete(['system', 'path']); # Unreal style (multi-valued keys) $ini = new Config::Ini('UnrealTournament.ini'); print map "$_\n", $ini->get(['Engine.GameEngine', 'ServerPackages']); $ini->put(['Engine.GameEngine', 'ServerPackages', 'New Mod'], -add => 1); if ($ini->exists(['Engine.GameEngine', 'ServerPackages', 'Old Mod'])) ... $ini->delete(['Engine.GameEngine', 'ServerPackages', 'Some Mod']); $ini->save; # Save it in the registry file format $ini->registry(1); $ini->save('system.reg');
This package provides easy access to MS-Windows style .ini files, Unreal style extended .ini files (where multiple values can be associated with a single key), as well as registry files with automatic conversion from native Perl to Windows registry data encoding and vice versa.
For an .ini file to be recognized it must be of the following format:
[section] key=value ; comments
In our implementation the key must be no longer than 1024 characters, and contain no high-ASCII nor control character.
On a line, everything after the semicolon (;) is ignored. Backslash (\) right before the end of line is treated as line continuation marker and the contents of the next line will be appended after stripping off preceeding whitespaces. Comment delimiter takes precedence over line continuation marker. Spaces surrounding the delimiting equation sign are stripped. If there are more than one equation sign on a line the first one is treated as the delimiter, the rest of them are considered part of the value.
The comment delimiter can be specified during calls to new or open via the -commentdelim option as a regular expression. If no comment stripping is desired supply the empty string ('') as the argument.
Specifcations of section, key and value are to be supplied to methods via an array reference containing just a section name, or the section name plus a key name, or the section name plus a key name with its associated value.
If the first line of a file starts with "REGEDIT4" it will be treated as a registry file. See the "Registry Format" section below for more details. Invoking the save method on such a file will have it saved in registry file format. If this is not desirable the output mode can be forced by calling the registry method.
If the module is processing a Windows "registry" style file, or is placed into registry mode, all values are automatically converted to and from native Perl/Windows registry formats. For special situations you can use the decode_reg_value subroutine for manual decoding.
A registry file follows the same format described above, except that keys are expected to be enclosed in double quotes. The first line of a registry file starts with "REGEDIT4".
Strings - A string is stored in the registry as a sequence of alphanumeric symbols that are enclosed in a pair of double quotation marks ("). When retrieving a string from a registry file, only the actual data is returned in the scalar variable. When writting a string, you need to enclose it within the double quotations marks.
$ini->put(['sys', 'mystr', '"hi there"'], -add => 1); print $ini->get(['sys', 'mystr']);
This will result in the un-quoted 8 character long "hi there" string being printed.
The registry file contains:
[sys] "mystr"="hi there"
32 bit numbers - The registry format allows for special handling of 32 bit numbers. When you pass in a scalar that is not enclosed in double quotations, this library will assume you are tring to store a number. When retrieving a number it is returned as a Perl number.
$ini->put(['sys', 'Number', 100], -add => 1); print $ini->get(['sys', 'Number']);
This will result in "100" being printed.
[sys] "Number"=dword:00000064
Arrays of 8 bit numbers - If you need to store value that is an array of numbers, you can pass in an array or list of non-quote enclosed scalars. When retrieving that key's value this module will return an array or list of scalars.
$ini->put(['sys', 'ListOfNumbers', ( 1...9) ], -add => 1); @nums = $ini->get(['sys', 'ListOfNumbers']);
This will result in an array containing 10 elements.
[sys] "ListOfNumbers"=hex:00,01,02,03,04,05,06,07,08,09
Multiple Strings - Registries can also store a list of strings. They are stored as a sequence of null terminated arrays of 8 bit numbers, and there is a final null marking the end of the sequence. When saving multiple strings, you pass in an array or list of scalars that contains double-quote delimited strings. When retrieving one of these values, you will receive an array of strings (without the enclosing quotation marks).
$ini->put(['sys', 'ListOfStr', ( '"str1"', '"str2"', '"str3"' ) ], -add => 1); @strs = $ini->get(['sys', 'ListOfStr']);
This will result in an array containing 3 elements: "str1", "str2" and "str3".
[sys] "ListOfStr"=hex(7):73,74,72,31,00,73,74,72,32,00,73,74,\ 72,33,00,00
Note that this example contains a line continuation marker "\".
Constructor. If a filename is supplied it will be opened as an .ini file with its content read as the initial configuration of the object.
Open the .ini file and read in all valid entries. New entries will be merged with the existing configuration.
Save the current configuration into file in the .ini format. Both the section order and the order of key=value pairs within a section are preserved. If a filename is given the file will be used as the save target, otherwise the configuration will be save to the last used (via new, open or save) file. The original content of the file will be clobbered. Be careful not to inadvertently merge two .ini files into one by opening them in turn and then saving.
True will be returned if the save is successful, false otherwise.
Set or retrieve the filename that was last used. new, open and save will all update the last used filename if a filename was supplied to them.
Set or retrieve the byte offset into the file immediately after the last line that conforms to the .ini format.
Set or retrieve the registry flag which determines whether the file is to be treated as a registry file or .ini file. If this flag is true all subsequent file operations will work in registry file mode, otherwise the .ini mode is used. Normally this flag need not be altered manually because it is automatically set to a value matching the format of the most recently read file.
Set or retrieve the comment delimiter.
Return true if the specified section exists, or if the specified key exists in the specified section. If a value is specified, return true if it is any one of the values of the key.
Depending on how many elements are specified in the array reference, retrieve the entire specified section or the values of the specified key.
If nothing is specified the entire file is returned as a hash reference.
If only a section name is specified the matching section is returned in its entirety as a hash reference.
If both a section name and a key name are specified, the associated values are returned. If the key has multiple values the returned result is an array reference containing all the values, otherwise if the key has only one value that single value is returned as a scalar.
The decision of whether to return a single or multiple values can be forced via the -mapping argument. If the multiple mapping option is applied to a single value result an array of one element that is the single value will be returned. If on the other hand the single mapping option is forced upon a mutli-valued result only the first value will be returned.
In general, don't specify any mapping when dealing with standard MS-Windows style .ini files and use the multiple mapping when dealing with multivalued keys in an Unreal style .ini files.
Set the value for the specified key in the specified section and return the old value. If the optional -add argument is true a new value will be added to the key if that value does not already exist.
Returns a decoded value or list of values from a registry key. See the section above on "Registry Format". This routine accepts the raw value field from a registry entry, and return a Perl specific data structure that natively represents the data.
This routine is called automatically when either get or set methods are called specifying a particular key. If you used get to retrieve a whole section, the values of the registry keys will be in their native file format. You must use this method call to convert them from registry to Perl format.
If section, key and value are all given the corresponding key=value pair will be deleted from the specified section. If a specific value is not given the entire key including all its values will be deleted. If the path only specifies a section the entire section will be deleted.
If the optional -keep argument evaluates to true, when performing section deletion all the keys along with their values are deleted but the now empty section will still exist to mimic the bahavior of the Unreal uninstaller.
Return the properly cased filename by performing a case-insensitive match of the specified file within the specified parent directory. If there is no match the filename passed in is return as-is. If the dirname argument is not given the current directory will be used.
Return the properly cased and slashed pathname, unless running on a brain-damaged OS that is too dumb to handle pathnames in a modern, case-sensitive manner. Each path components are inspected from left to right to see if a file or directory of the same name, in any case combination, already exists. If any match results the first match is used, otherwise the original path component is used verbatim. No backtracking is performed, so if any path component in the middle fails to match an existing directory, all subsequent path components are used as-is. All backslashes are also changed to forward-slashes.
Avatar <avatar@deva.net>, based on a prototype by Mishka Gorodnitzky <misaka@pobox.com>. Registry file support by Fulko Hew <fulko@wecan.com>.
To install Config::Ini, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Config::Ini
CPAN shell
perl -MCPAN -e shell install Config::Ini
For more information on module installation, please visit the detailed CPAN module installation guide.