ePages 7.38.0 - 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',
    CaseSensitive => 1,
);
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

MergeIniFiles
addSection
content
create
delete
deleteSection
deleteSectionComment
deleteValueComment
existsSection
fileName
get
lock
merge
new
print
read
rewrite
section
sectionNames
set
valueComment
valueComment
write

MergeIniFiles

Adds sections from $Source to $Target if not yet exist in $Target. For all $aEditSections, do not simply add/replace $Target section by $Source section but add/replace only the $Target parameters that exist in $Source. Removes duplicate comments in $Target.

Syntax
MergeIniFiles($Target, $Source, $aEditSections, $hFlags);
Example
MergeIniFiles("$ENV{EPAGES_CONFIG}/Scheduler.conf",
  "$ENV{EPAGES_CARTRIDGES}/DE_EPAGES/Database/Data/Scheduler/Scheduler.conf",
  [ 'LOOPS' ], { 'replace' => 'parameters' } );
Input
$Target (string)
name of file
$Source (string)
name of file
$aEditSections (ref.array)
(optional) list of section names
$hFlags (hash ref)
(optional) flags to modify the behaviour of MergeIniFiles.
  • replace
    if set to 'sections' - overwrites target for all but $aEditSections
    if set to 'parameters' - overwrites target only for $aEditSections
    if otherwise set - overwrites target for all
    if unset - existing sections/parameters in target are not changed
  • delcomments
    if set to ';' - deletes comments starting with ';'
    if set to '#' - deletes comments starting with '#'
    if otherwise set - deletes all comments
    if unset - comments remain
  • delete
    if set delete sections on the fly

addSection

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

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

content

Returns the current content of the ini file.

Syntax
$IniConfig->content;
Return
$Content (string)
content of $self->fileName

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,
);
Example
$IniConfig = DE_EPAGES::Core::API::IniConfig->create(
    FileName => 'win.ini'
);
Input
@Params (array)
same parameters as for new
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

deleteSectionComment

Removes the comment from a section.

Syntax
$IniConfig->deleteSectionComment( $Section );
Input
$Section (string)
section name

deleteValueComment

Removes the comment from the value in the section.

Syntax
$IniConfig->deleteValueComment( $Section, $Key );
Input
$Section (string)
section name
$Key (string)
key name

existsSection

Returns true if the section exists in the ini file.

Syntax
$Exists = $IniConfig->existsSection($Section);
Input
$Section (string)
section name
Return
$SectionExists (boolean)
1 if $Section, else 0

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

lock

Constructs a new config file object, locks the file and executes a function before the lock is released. By default, key and section names are case insensitive.

Syntax
$IniConfig = DE_EPAGES::Core::API::IniConfig->lock(
    FileName => $FileName,
    CaseSensitive => $CaseSensitive,
    Create => $Create,
    Access => $Access,
    Sub => $Sub,
);
Example
DE_EPAGES::Core::API::IniConfig->lock(
    FileName => 'win.ini',
    CaseSensitive => 1,
    Sub => sub {
        my ($IniConfig) = @_;
        print $IniConfig->get('Mail', 'MAPI');
    },
);
Input
%options (hash ref)
parameters for DE_EPAGES::Core::API::IniConfig->new.
The following parameters can be used:
  • FileName - config file name
  • CaseSensitive - if true, key and section are case sensitive
  • Create - if true, returns no error if file doesn't exist
  • Sub - function to execute during the lock. The function
    gets an IniFile object as first parameter - code ref
  • Access - requested access ('r'=read, 'w'=write) - string

merge

Adds sections from $IniSource if not yet exist. For all $aEditSections, do not simply add/replace section by $Source section but add/replace only the parameters that exist in $Source. Removes duplicate comments.

Syntax
$IniConfig->merge($IniSource, $aEditSections, $hFlags);
Example
my $IniSource = DE_EPAGES::Core::API::IniConfig->new(
    FileName => 'c:/test/source.ini'
);
my $IniTarget = DE_EPAGES::Core::API::IniConfig->new(
    FileName => 'c:/test/target.ini'
);
$IniTarget->merge( $IniSource, [ 'GLOBAL' ], { 'replace' => 'parameters' } );
$IniTarget->rewrite;
Input
$IniSource (DE_EPAGES::Core::API::IniConfig)
source of changes
$aEditSections (ref.array)
(optional) list of section names
$hFlags (hash ref)
(optional) flags to modify the behaviour of MergeIniFiles.
  • replace
    if set to 'sections' - overwrites target for all but $aEditSections
    if set to 'parameters' - overwrites target only for $aEditSections
    if otherwise set - overwrites target for all
    if unset - existing sections/parameters in target are not changed
  • delcomments
    if set to ';' - deletes comments starting with ';'
    if set to '#' - deletes comments starting with '#'
    if otherwise set - deletes all comments
    if unset - comments remain
  • delete
    if set delete sections on the fly

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,
);
Example
$IniConfig = DE_EPAGES::Core::API::IniConfig->new(
    FileName => 'win.ini'
    CaseSensitive => 1,
);
Input
%options (hash ref)
parameters for DE_EPAGES::Core::API::IniConfig->new.
The following parameters can be used:
  • FileName - config file name
  • CaseSensitive - if true, key and section are case sensitive
  • Create - if true, returns no error if file doesn't exist

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;
Return
$Content (string)
prints content of $self->fileName to STDOUT

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. Note: when the file was opened as case insensitive, then all section names and keys are converted to lower case.

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

valueComment

Sets or gets the comment of a section.

Syntax
$Comment = $IniConfig->sectionComment( $Section );
$IniConfig->sectionComment( $Section, $Comment );
Input
$Section (string)
section name
$Comment (string)
value comment
Return
$Comment (string)
value comment

valueComment

Sets or gets the comment of a value in the section.

Syntax
$Comment = $IniConfig->valueComment( $Section, $Key );
$IniConfig->valueComment( $Section, $Key, $Comment );
Input
$Section (string)
section name
$Key (string)
key name
$Comment (string)
value comment
Return
$Comment (string)
value comment

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