NAME
Config::Simple - Simple Configuration Class
SYNPOSIS
in the app.cfg configuration file:
[mysql]
host=ultracgis.com
login=sherzodr
password=secret
[profile]
first name=Sherzod
last name=Ruzmetov
email=sherzodr@cpan.orgin your Perl application:
use Config::Simple;
my $cfg = new Config::Simple(filename=>"app.cfg");
print "MySQL host: ", $config->param("mysql.host"), "\n";
print "MySQL login: ", $config->param("mysql.login"), "\n";NOTE
This documentation refers to version 2.0 of Config::Simple. If you have a version older than this, please update it to the latest release ASAP (before you get burned).
DESCRIPTION
This Perl5 library makes it very easy to parse INI-styled configuration files and create once on the fly. It optionally requires Digest::MD5 module
CONFIGURATION FILE
Configuration file that Config::Simple uses is similar to Window's *.ini file syntax. Example.,
; sample.cfg
[block1]
key1=value1
key2=value2
...
[block2]
key1=value1
key2=value2
...It can have infinite number of blocks and infinite number of key/value pairs in each block. Block and key names are case sensitive. i.e., [block1] and [Block1] are two completely different blocks. But this might change in the subsequent releases of the library. So please use with caution!
Lines that start with either ';' (semi colon) or '#' (pound) are assumed to be comments till the end of the line. If a line consists of a sole '.' (dot), then all the lines till eof are ignored (it's like __END__ Perl token)
When you create Config::Simple object with $cfg = new Config::Simple(filename=>"sample.cfg") syntax, it reads the above sample.cfg config file, parses the contents, and creates required data structure, which you can access through its public methods.
In this documenation when I mention "name", I'll be refering to block name and key delimited with a dot (.). Forexample, from the above sample.cfg file, following names could be retrieved: block1.key1, block1.key2, block2.key1 and block2.key2 etc.
Here is the configuration file that I use in most of my CGI applications, and I'll be using it in most of the examples throughout this manual:
;app.cfg
[mysql]
host=ultracgis
login=sherzodr
password=secret
db_name=test
RaiseError=1
PrintError=1fcntl.h Constants
by default Config::Simple exports O_RDONLY, O_RDWR, O_CREAT, O_EXCL fcnl.h (file control) constants. When you create Config::Simple object by passing it a filename, it will try to read the file. If it fails it creats the file. This is a default behaviour. If you want to control this behavior, you'll need to pass mode with your desired fcntl O_* constants to the constructor:
$config = new Config::Simple(filename=>"app.cfg", mode=>O_RDONLY);
$config = new Config::Simple(filename=>"app.cfg", mode=>O_RDONLY|O_CREAT); # default
$config = new Config::Simple(filename=>"app.cfg", mode=>O_EXCL);fcntl constants:
+===========+============================================================+
| constant | description |
+===========+============================================================+
| O_RDONLY | opens a file for reading only, failes if doesn't exist |
+-----------+------------------------------------------------------------+
| O_RDWR | opens a file for reading and writing |
+-----------+------------------------------------------------------------+
| O_CREAT | creates a file |
+-----------+------------------------------------------------------------+
| O_EXCL | creates a file if it doesn't already exist |
+-----------+------------------------------------------------------------+METHODS
- new( filename=>$ [, mode=>O_*] [, lockfile=>$] )
-
Constructor method. Requires filename to be present and picks up defaults for the rest if omitted. mode is used while opening the file, lockfile while updating the file.
It returns Config::Simple object if successfull. If it fails, sets the error message to $Config::Simple::errstr variable, and returns undef.
mode can accept any of the above described fcntl constants. Default is
O_RDONLY | O_CREAT. Default lockfile is the name of the configuration file with ".lock" extension - param([args])
-
If called without any arguments, returns the list of all the available blocks in the config. file.
If called with arguments, this method suports several different syntaxes, and we'll discuss them all seperately.
- param($name))
-
returns the value of $name. $name is block and key seperated with a dot. For example, to retrieve the mysql login name from the app.cfg, we could use the following syntax:
$login = $cfg->param("mysql.login"); - param(-name=>$name)
-
the same as "param($name)"
- param($name, $value)
-
updates the value of $name to $value. For example, to set the value of "RaiseError" to 0, and create an new "AutoCommit" key with a true value:
$cfg->param("mysql.RaiseError", 0); $cfg->param("mysql.AutoCommit", 1);As I implied above, if either the block or the key does not exist, it will be created for you. So
$cfg->param("author.f_name", "Sherzod");would create an [author] block with "f_name=Sherzod" key/value pair.
- param(-name=>$name, -value=>$value)
-
the same as "param($name, $value)"
- param(-block=>$block)
-
returns the whole block as a hash reference. For example, to get the whole [mysql] block:
$mysql = $cfg->param(-block=>'mysql'); $login = $mysql->{login}; $psswd = $mysql->{password}; - param(-block=>$block, -values=>{key1=>value1, key2=>value2})
-
creates a new block with the specified values, or overrides existing block. For example, to add the [site] block to the above app.cfg with "title=UltraCgis.com" and "description=The coolest site" key/values we could use the following syntax:
$cfg->param(-block=>"site", -values=>{ title=> "UltraCgis.com", description=>"The coolest site", author=>"Sherzod B. Ruzmetov", });note that if the [site] block already exists, its contents will be cleared and then re-created with the new values.
- set_param($name, $value)
-
This method is provided for backward compatability with 1.x version of Config::Simple. It is identical to param($name, $value) syntax.
- param_hash()
-
handy method to save the contents of the config. file into a hash variable.
%Config = $cfg->param_hash();Structure of %Config looks like the following:
%Config = ( 'mysql.PrintError' => 1, 'mysql.db_name' => 'test', 'mysql.login' => 'sherzodr', 'mysql.password' => 'secret', 'mysql.host' => 'ultracgis.com', 'mysql.RaiseError' => 1, ); - write([$new_filename])
-
Notice, that all the above manipulations take place in the object's memory, ie, changes you make with param() and set_param() methods do not reflect in the actual config. file. To update the config file in the end, you'll need to call "write()" method with no arguments.
If you want to save newly updated/created configuration into a new file, pass the new filename as the first argument to the write() method, and the original config. file will not be touched.
If it detects that configuration file was updated by a third party while Config::Simple was working on the file, it throws a harmless warning to STDERR, and will copy the original file to a new location with the .bk extension, and updates the configuration file with its own contents.
"write()" returns true if successfull, undef, otherwise. Error message can be accessed either vi $Config::Simple::errstr variable, or by calling "error()" method.
- error()
-
Returns the value of $Config::Simple::errstr
BUGS
Hopefully none.
Please send them to my email if you detect any with a sample code that triggers that bug. Even if you don't have any, just let me konw that you are using it. It just makes me feel great ;-)
COPYRIGHT
Copyright (C) 2002 Sherzod Ruzmetov <sherzodr@cpan.org>
This program is free software; you can redistribute it and/or
modify it under the same terms as Perl itselfAUTHOR
Sherzod B. Ruzmetov <sherzodr@cpan.org>
http://www.ultracgis.com