NAME

Config::Simple - Simple Configuration File class

SYNOPSIS

    # In your configuratin file (some.cfg)
    [mysql]
    user=sherzodr
    password=secret
    host=localhost
    database=test


    # In your program

    use Config::Simple;

    my $cfg = new Config::Simple("some.cfg");

    # reading
    my $user = $cfg->param('mysql.user');
    my $password = $cfg->param('mysql.password');

    # updating
    $cfg->param('mysql.user', foo);

    # saving the changes back into the file
    $cfg->write();

    # tricks are endless

DESCRIPTION

Config::Simple is a Perl class to manipulate simple, windows-ini-styled configuration files. Reading and writing external configurable data is the integral part of any software design, and Config::Simple is designed to help you with it.

REVISION

This manual refers to $Revision: 3.7 $

CONFIGURATION FILE SYNTAX

Syntax of the configuration file is similar to windows .ini files, where configuration variables and their values are seperated with '=' sign, each set belongind to a specific namespace (block):

        [block]
        var1=value1
        var2=value2

If the block is missing, or any of the key=value pairs are encountered without prior block declaration, they will be assigned to a virtual block. Name of the virtual block is controlled with $Config::Simple::DEFAULTNS variable:

    use Config::Simple;
    $Config::Simple::DEFAULTNS = "root";
    $cfg = new Config::Simple("some.cfg");

If you do not explicitly assign a namespace, "default" is implied.

By default, Config::Simple treats everything after the '=' to the end of the line as configuration value (spaces trimmed). Unfortunately, other configuration file parsing utilities do not quite aggree with the idea, and assert if the value contains non-alphanumerics, they should be enclosed in double quotes ("). Config::Simple supports this syntax as well. If you intend to use this syntax, you should enable "-strict" switch like so:

    use Config::Simple qw/-strict/;

Now Config::Simple expects to see any values that contain non-alphanumeric characters in double quotes. Double quotes to be used inside the value should be escaped with \ (backslash):

    [default]
    nick = sherzodR
    name = "Sherzod Ruzmetov"
    url  = "http://author.ultracgis.com"
    email= "sherzodr@cpan.org"
    quoted = "My favorite quote is \"Learn as if you were to live forever\""
    age  = 22

Enabling "-strict" switch is also useful to keep trailing and leading spaces in configuration values:

    [default]
    signature = "            Foo Bar                   "

Lines starting with '#' or ';' to the end of the line are considered comments, thus ignored while parsing. Line, containing a single dot is the logical end of the configuration file (doesn't necessaryily have to be the physical end though ). So everything after that line is also ignored.

Note, when you ask Config::Simple to save the changes back, all the comments will be discarded, but everything after that final dot is stored back as it was.

I admit, keeping the comments would be quite useful too. May be in subsequent releases.

CONSTRUCTOR

new() - constructor, initializes and returns Config::Simple object. Following options are available:

• filename - filename to read into memory. If this option is defined, Config::Simple also calls read() for you. If there's only one argument passed to the constructor, it will be treated as the filename as well.

• autosave - boolean value indicating if in-memory modifications be saved back to configuration file before object is destroyed. Default is 0, which means "no". (See autosave())

• decoder - reference to a function (coderef), is used by read() to decode the values. If this option is missing, default decoder will be used, which simply decodes new line characters (\n) back to newlines (opposite of default encoder). See decoder().

• encoder - reference to a function (coderef). Is used by write() to encode special characters/sequences before saving them in the configuration file. If this option is missing, default encoder will be used, which encodes newlines to avoid corrupted configuration files. See encoder().

All the arguments to the constructor can also be set with their respective accessor methods. However, there's an important point to keep in mind. If you define filename as an argument while calling the constructor and at the same time want to use your custom decoder, you should specify the decoder together with the filename. Otherwise, when constructor calls read(), it will use default decoder(). Another option is not to mention filename to constructor, but do so to read().

METHODS

Following methods are available for a Config::Simple object

• read() - reads and parses the configuration file into Config::Simple object. Accepts one argument, which is treated as a filename to read. If "filename" option to the constructor was defined, there's no point calling read(), since new() will call it for you. Example:

      $cfg = new Config::Simple();
      $cfg->read("some.cfg");

• hashref() - returns the configuration file as a reference to a hash. Keys consist of configuration section and section key separated by a dot (.), and value holding the value for that key. Example:

      # some.cfg
      [section]
      key1=value1
      key2=value2

  Hashref will return the following hash:

      $ref = {
          'section.key1' => value1,
          'section.key2' => value2,
      }

• param_hash() - for backward compatibility. Returns similar data as hashref() does (see hashref()), but returns de referenced hash.

• param() - used for accessing and modifying configuration values. Act differently depending on the arguments passed.

  param()

  If used with no arguments, returns all the keys available in the configuration file. Once again, keys are sections and section variables delimited with a dot.

  param($key)

  If used with a single argument, returns the respective value for that key. Argument is expected to be in the form of "sectionName.variableName".

  param(-name=>$key)

  The same as the previous syntax.

  param($key, $value)

  Used to modify $key with $value. $key is expected to be in "sectionName.variableName" format.

  param(-name=>$key, -value=>$value);

  The same as the previous syntax.

  param(-block=>$blockname)

  Returns a single block/section from the configuration file in form of hashref (reference to a hash). For example, assume we had the following block in our "some.cfg"

      [mysql]
      user=sherzodr
      password=secret
      host=localhost
      database=test

  We can access the above block like so:

      my $mysql = $cfg->param(-block=>'mysql');
      my $user = $mysql->{user};
      my $host = $mysql->{host};

  param(-block=>$blockname, -values=>{key1 => value1,...})

  Used to create a new block or redefine the existing one.

• write() - saves the modifications to the configuration file. Config::Simple will call write() for you automatically if 'autosave' was set to true (see new()). Otherwise, write() is there for you if need. Argument, if exists, will be treated a name of a file current data should be written in. It's useful to copy modified configuration file to a different location, or to save the backup copy of a current configuration file before making any changes to it:

      $cfg = new Config::Simple(filename=>'some.cfg', autosave=>1);
  
      $cfg->write('some.cfg.bak');        # creating backup copy
                                          # before updating the contents

• write_string() - creates and returns the content of the configuration file as a string, instead of writing it into a file. The string returned by write_string() is guaranteed to be the same as what is written into a file.

• encoder() - sets a new encoder to be used in the form of coderef. This encoder will be used by write() before writing the values back to a file. Alternatively, you can define the encoder as an argument to constructor ( see new() ).

• decoder() - sets a new decoder to be used in the form of coderef. This decoder is used by read() ( see read() ), so should be set (if at all) before calling read(). Alternatively, you can define the decoder as an argument to constructor ( see new() ).

• autosave() - sets autosave value (see new())

• dump() - dumps the object data structure either to STDOUT or into a filename which can be defined as the first argument. Used for debugging only

CREDITS

Following people contributed with patches and/or suggestions to the Config::Simple. In chronological order:

Michael Caldwell (mjc@mjcnet.com)

Added witespace support in the configuration files, which enables custom identation

Scott Weinstein (Scott.Weinstein@lazard.com)

Fixed the bugs in the TIEHASH method.

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

Default namespace suggestion and patch.

Adam Kennedy <cpan@ali.as>

Added a write_string() method, for getting the file as a string. Fix for the case when the value is ''

Gavin Brown <gavin.brown@centralnic.com>

Proposed quoted values feature. This made configuration files created by Config::Simple compatible with those expected by PHP's parse_ini_file() function.

AUTHOR

Config::Simple is written and maintained by Sherzod Ruzmetov <sherzodr@cpan.org>

COPYRIGHT

    This library is a free software, and can be modified and redistributed
    under the same terms as Perl itself.

SEE ALSO

Config::General

cpanm Config::Simple

perl -MCPAN -e shell
install Config::Simple