|
Config::Ini - Perl interface to MS-Windows registry files, Windows .ini and Unreal style .ini files. |
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''.
$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"
$ini->put(['sys', 'Number', 100], -add => 1);
print $ini->get(['sys', 'Number']);
This will result in ``100'' being printed.
The registry file contains:
[sys]
"Number"=dword:00000064
$ini->put(['sys', 'ListOfNumbers', ( 1...9) ], -add => 1);
@nums = $ini->get(['sys', 'ListOfNumbers']);
This will result in an array containing 10 elements.
The registry file contains:
[sys]
"ListOfNumbers"=hex:00,01,02,03,04,05,06,07,08,09
$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''.
The registry file contains:
[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 ``\''.
True will be returned if the save is successful, false otherwise.
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.
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 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.
Avatar <avatar@deva.net>, based on a prototype by Mishka Gorodnitzky <misaka@pobox.com>. Registry file support by Fulko Hew <fulko@wecan.com>.
|
Config::Ini - Perl interface to MS-Windows registry files, Windows .ini and Unreal style .ini files. |