NAME

IniFile - Perl interface to MS-Windows style and Unreal style .ini files

SYNOPSIS

use IniFile;
$ini = new IniFile('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 IniFile('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;

DESCRIPTION

This package provides easy access to the familiar MS-Windows style .ini files as well as the Unreal style extended .ini files, where multiple values can be associated with a single key.

For an .ini file to be recognized it must be of the following format:

[section]
key=value           ; comments

Sections must be separated from each other by an empty line (i.e. a newline on its own). 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. 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.

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.

METHODS

new([filename])

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(self[, filename])

Open the .ini file and read in all valid entries. New entries will be merged with the existing configuration.

save(self[, filename])

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.

file(self[, filename] )

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.

lastpos(self)

Set or retrieve the the byte offset into the file immediately after the last line that conforms to the .ini format.

exists(self, [ section[, key[, value]] ])

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.

get(self, [ section[, key[, value]] ][, -mapping = ('single'|'multiple'))>

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.

put(self, [ section[, key[, value]] ][, -add = boolean])>

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.

delete(self, [ section[, key[, value]] ][, -keep = boolean])>

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.

adjustfilecase(filename[, dirname])

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.

adjustpathcase(pathname)

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.

AUTHOR

Avatar <avatar@deva.net>, based on a prototype by Mishka Gorodnitzky <misaka@pobox.com>.