Win32::Registry::File - Perl interface to MS-Windows registry files.
use Win32::Registry::File; $reg = new Win32::Registry::File('system.reg'); print $reg->get(['system', 'path']); $oldpath = $reg->put(['system', 'path', 'C:\\windows']); if ($reg->exists(['system', 'path'])) ... $reg->delete(['system', 'path']); $reg->save;
This package provides easy access to MS-Windows registry files with automatic conversion from native Perl to Windows registry data encoding and vice versa.
For an .reg file to be recognized it must be of the following format:
REGEDIT4 [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.
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.
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.
$reg->put(['sys', 'mystr', '"hi there"'], -add => 1); print $reg->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.
$reg->put(['sys', 'Number', 100], -add => 1); print $reg->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.
$reg->put(['sys', 'ListOfNumbers', ( 1...9) ], -add => 1); @nums = $reg->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).
$reg->put(['sys', 'ListOfStr', ( '"str1"', '"str2"', '"str3"' ) ], -add => 1); @strs = $reg->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 .reg file with its content read as the initial configuration of the object.
Open the .reg file and read in all valid entries. New entries will be merged with the existing configuration.
Save the current configuration into file in the .reg 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 .reg 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 .reg format.
Set or retrieve the registry flag which determines whether the file is to be treated as a registry file or .reg file. If this flag is true all subsequent file operations will work in registry file mode, otherwise the .reg 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.
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 Win32::Registry::File, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Win32::Registry::File
CPAN shell
perl -MCPAN -e shell install Win32::Registry::File
For more information on module installation, please visit the detailed CPAN module installation guide.