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.3 $

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. (
    Thanks to Ruslan U. Zakirov <cubic@wr.miee.ru> for this useful feature )

    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 the autosave() entry elsewhere in this
        document)

    *   "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 the decoder() entry
        elsewhere in this document.

    *   "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 the encoder() entry elsewhere in this document.

    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 the hashref() entry elsewhere in this document),
        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 the new() entry elsewhere in this document).
        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 the new() entry elsewhere in this document ).

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

    *   autosave() - sets autosave value (see the new() entry elsewhere in
        this document)

    *   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
    the Config::General manpage