ePages 6.10 - DE_EPAGES/Core/API/IniConfig.pm

Package DE_EPAGES::Core::API::IniConfig

Module for working with Windows-style .ini files.

Example
my $IniConfig = DE_EPAGES::Core::API::IniConfig->new(
    FileName => 'c:/test/test.ini'
);
my $Value = $IniConfig->get( 'Section 1', 'Key 1' );
$IniConfig->set( 'Section1', 'key2', 'value2' );
$IniConfig->rewrite();

An ini file has the following structure:
[Section 1]
Key 1=value1
key2=value2

private attributes ( for use inside this module only ):
{FileName}  - name of the config file
{CaseSensitive}    - flag set if keys and sections are case insensitive
{Values}    - hash of sections
$self->{Values}->{$Section} is a hash of key-value pairs
$self->{Values}->{$Section}->{$key} is a single value

Functions

addSection
content
create
delete
deleteSection
existsSection
fileName
get
new
print
read
rewrite
section
sectionNames
set
write

addSection

Adds a section to the ini file if the section not exists.

Syntax
$IniConfig->addSection($Section);
Return
$Section (string)
section name

content

Returns the current content of the ini file.

Syntax
$IniConfig->content;

create

Creates a new config file object. The only difference between this function and "new" is that "create" does not require that the configuration file already exists. If a file with the same name exists, it will be overwritten.

Syntax
$IniConfig = DE_EPAGES::Core::API::IniConfig->create(
    FileName => $FileName,
    CaseSensitive => $CaseSensitive,
    flock => $flock,
);
Example
$IniConfig = DE_EPAGES::Core::API::IniConfig->create(
    FileName => 'win.ini'
);
Input
$FileName (string)
config file name
$CaseSensitive (boolean)
if true, then key and section names are case sensitive
Return
$IniConfig (object)
an IniConfig object

delete

Removes the value form the section in the config file. Call $IniConfig->rewrite to make the changes persistent.

Syntax
$IniConfig->delete( $Section, $Key );
Example
$IniConfig->delete( 'Database', 'User' );
Input
$Section (string)
section name
$Key (string)
key name

deleteSection

Removes the section from the config file. Call $IniConfig->rewrite to make the changes persistent.

Syntax
$IniConfig->deleteSection( $Section );
Example
$IniConfig->deleteSection( 'Database' );
Input
$Section (string)
section name

existsSection

Returns true if the section exists in the ini file.

Syntax
$Exists = $IniConfig->existsSection($Section);
Return
$Section (string)
section name

fileName

Sets or returns the config file name.

Syntax
$IniConfig->fileName( $FileName );
$FileName = $IniConfig->fileName;
Input
$FileName (string)
config file name
Return
$FileName (string)
config file name

get

Returns a value from the config file or $Default if the given key was not found.

Syntax
$IniConfig->get( $Section, $Key );
$IniConfig->get( $Section, $Key, $Default );
Example
$IniConfig->get( 'Database', 'User', 'sa' );
Input
$Section (string)
section name
$Key (string)
key name
$Default (string)
(optional) default value, used if the key does not exist
Return
$Value (string)
configuration value

new

Constructs a new config file object. By default, key and section names are case insensitive.

Syntax
$IniConfig = DE_EPAGES::Core::API::IniConfig->new(
    FileName => $FileName,
    CaseSensitive => $CaseSensitive,
    Create => $Create,
    flock => $flock,
);
Example
$IniConfig = DE_EPAGES::Core::API::IniConfig->new(
    FileName => 'win.ini'
);
Input
$FileName (string)
config file name
$CaseSensitive (boolean)
if true, then key and section names are case sensitive
$Create (boolean)
(optional, default=0) if true, no error is thrown when the
file does not exist
$flock (boolean)
(optional, default=1) if true, the file is locked for reading
and writing using
DE_EPAGES::Core::API::File::LockFile
to prevent file corruption
$CaseSensitive (boolean)
if true, then key and section names are case sensitive
Return
$IniConfig (object)
an IniConfig object

print

Prints the content of the config file object in the windows ini file format to STDOUT.

Syntax
$IniConfig->print;

read

Reads the configuration file in the windows ini file format.

Syntax
$IniConfig->read( $FileName );
Example
$IniConfig->read( 'database.ini' );
Input
$FileName (string)
config file name

rewrite

Writes the configuration file back to disk using the file name that was passed to new or create.

Syntax
$IniConfig->rewrite

section

Returns the specified section with key-value pairs as a hash reference or creates a section with the new hash. Returns an empty hash reference if the section does not exist. If 'CaseSensitive' was set to 1, all keys are returned in lowercase letters!

Syntax
$hSection = $IniConfig->section( $Section );
$hSection = $IniConfig->section( $Section, $hSection );
Example
$hDatabase = $IniConfig->section( 'Database' );
Input
$Section (string)
section name
$hSection (hash ref)
key-value pairs (optional)
Return
$hSection (hash ref)
key-value pairs

sectionNames

Returns all section names found in the config file.

Syntax
$aSections = $IniConfig->sectionNames
Return
$aSections (array ref)
section names

set

Sets a value in the config file. Call $INI->rewrite to make the changes persistent.

Syntax
$IniConfig->set( $Section, $Key, $Value );
Example
$IniConfig->set( 'Database', 'User', 'sa' );
Input
$Section (string)
section name
$Key (string)
key name
$Value (string)
configuration value

write

Writes the content of the config file object to the specified file in the windows ini file format.

Syntax
$IniConfig->write( $FileName );
Example
$IniConfig->write( 'database.ini' );
Input
$FileName (string)
config file name