/ 
Config-Simple-3.14
River stage two • 27 direct dependents • 40 total dependents
/ Config::Simple

NAME

Config::Simple - simple configuration file class

SYNOPSIS

use Config::Simple;

my $cfg = new Config::Simple('app.cfg') or die Config::Simple->error();

# reading
my $user = $cfg->param("User");

# updating:
$cfg->param(User=>'sherzodr');

# saving
$cfg->write();
# or
$cfg->save()

DESCRIPTION

Reading and writing configuration files is one of the most frequent aspects of any software design. Config::Simple is the library to help you with it.

ONE SIZE FITS ALL

Well, almost all. Cofig::Simple supports variety of configuration file formats. Following are some overview of configuration file formats:

SIMPLE CONFIGURATION

Simple syntax is what you need for most of your projects. These are, as the name asserts, the simplest. File consists of key/value pairs, delimited by nothing but whitespace. Keys (variables) should be strictly alpha-numeric with possible dashes (-). Values can hold any arbitrary text. Here is an example of such a configuration file:

Alias     /exec
TempFile  /usr/tmp

Comments start with a pound ('#') sign and cannot share the same line with other configuration data.

HTTP-LIKE SYNTAX

This format of seperating key/value pairs is used by HTTP messages. Each key/value is seperated by semi-colon (:). Keys are alphanumeric strings with possible '-'. Values can be any artibtrary text:

Example:

Alias: /exec
TempFile: /usr/tmp

It is OK to have spaces around ':'. Comments start with '#' and cannot share the same line with other configuration data

INI-FILE

This configuration files are more native to Win32 systems. Data is organized in blocks. Each key/value pair is delimited with an equal (=) sign. Blocks are declared on their own lines inclosed in '[' and ']':

[BLOCK1]
KEY1=VALUE1
KEY2=VALUE2


[BLOCK2]
KEY1=VALUE1
KEY2=VALUE2

This is the perfect choice if you need to organize your configuration file into categories.

ADVICE: Avoid using none alpha-numeric characters as blockname or key. If value consists of none alpha-numeric characters, its better to inclose them in double quotes. Althogh these constraints are not mandatory while using Config::Simple, they will help to make your configuration files more portable.

[site]
url="http://www.handalak.com"
title="Website of a \"Geek\""
author=sherzodr

SIMPLIFIED INI-FILE

If you do not want to declear several blocks, you can easily leave out block declaration. They will be assigned to a default block automatically:

url = "http://www.handalak.com"

is the same as saying:

[default]
url = "http://www.handalak.com"

Comments can begin with either pound ('#') or semi-colon (';'). Each comment should reside on its own line

PROGRAMMING STYLE

READING THE CONFIGURATION FILE

To read the existing configuration file, simply pass its name to the constructor new() while creating the Config::Simple object:

$cfg = new Config::Simple('app.cfg');

The above line reads and parses the configuration file accordingly. It tries to guess which syntax is used. Alternatively, you can create an empty object, and only then read the configuration file in:

$cfg = new Config::Simple();
$cfg->read('app.cfg');

As in the first example, read() tries to guess the syntax used in the configuration file.

If, for any reason, it fail to guess the syntax correctly (which is less likely), you can try to debug by using its guess_syntax() method. It expects filehandle for a configuration file and returns the name of a style.

$cfg = new Config::Simple();

open(FH, "app.cfg");
printf("This file uses '%s' syntax\n", $cfg->quess_syntax(\*FH));

ACCESSING VALUES

After you read the configuration file into Config::Simple object succesfully, you can use param() method to access the configuration values. For example:

$user = $cfg->param("User");

will return the value of "User" from either simple configuration file, or http-styled configuration as well as simplified ini-files. To acccess the value from a traditional ini-file, consider the following syntax:

$user = $cfg->param("mysql.user");

The above returns the value of "user" from within "[mysql]" block. Notice the use of dot "." to delimit block and key names.

Config::Simple also supports vars() method, which, depending on the context used, returns all the values either as hashref or hash:

my %Config = $cfg->vars();

print "Username: $Config{User}";

# If it was a traditional ini-file:
print "Username: $Config{'mysql.user'}";

If you call vars() in scalar context, you will end up with a refrence to a hash:

my $Config = $cfg->vars();

print "Username: $Config->{User}";

UPDATING THE VALUES

Configuration values, once read into Config::Simple, can be updated from within your programs by using the same param() method used for accessing them. For example:

$cfg->param("User", "sherzodR");

The above line changes the value of "User" to "sherzodR". Similar syntax is applicable for ini-files as well:

$cfg->param("mysql.user", "sherzodR");

SAVING/WRITING CONFIGURATION FILES

The above updates to the configuration values are in-memory operations. They do not reflect in the file itself. To modify the files accordingly, you need to call either "write()" or "save()" methods on the object:

$cfg->write();

The above line writes the modifications to the configuration file. Alternatively, you can pass a name to either write() or save() to indicate the name of the file to create instead of modifying existing configuration file:

$cfg->write("app.cfg.bak");

If you want the changes saved all the time, you can turn autosave mode on by passing true value to $cfg->autosave():

$cfg->autosave(1);

MULTIPLE VALUES

Ever wanted a key in the configuration file to hold array of values? Well, I did. That's why Config::Simple supports this fancy feature as well. Simply seperate your values with a comma:

Files hp.cgi, template.html, styles.css

Now param() method returns an array of values split at comma:

@files = $cfg->param("Files");
unlink $_ for @files;

If you want a comma as part of a value, enclose the value(s) in double quotes:

CVSFiles "hp.cgi,v", "template.html,v", "styles.css,v"

In case you want either of the values to hold literal quote ("), you can escape it with a backlash:

SiteTitle "sherzod \"The Geek\""

CASE SENSITIVITY

By default, configuration file keys and values are case sensitive. Which means, $cfg->param("User") and $cfg->param("user") are refering to two different values. But it is possible to force Config::Simple to ignore cases all together by enabling -lc switch while loading the library:

use Config::Simple ('-lc');

WARNING: If you call write() or save(), while working on -lc mode, all the case information of the original file will be lost. So use it if you know what you're doing.

CREDITS

Michael Caldwell (mjc@mjcnet.com)

whitespace support, -lc switch

Scott Weinstein (Scott.Weinstein@lazard.com)

bug fix in TIEHASH

Ruslan U. Zakirov <cubic@wr.miee.ru>

Default namespace suggestion and patch

COPYRIGHT

Copyright (C) 2002-2003 Sherzod B. Ruzmetov.

This softeware is free library. You can modify and/or distribute it
under the same terms as Perl itself

AUTHOR

Sherzod B. Ruzmetov E<lt>sherzodr@cpan.orgE<gt>
URI: http://author.handalak.com