Provided by: libconfig-general-perl_2.65-2_all bug

NAME

       Config::General - Generic Config Module

SYNOPSIS

        #
        # the OOP way
        use Config::General;
        $conf = Config::General->new("rcfile");
        my %config = $conf->getall;

        #
        # the procedural way
        use Config::General qw(ParseConfig SaveConfig SaveConfigString);
        my %config = ParseConfig("rcfile");

DESCRIPTION

       This module opens a config file and parses its contents for you. The new method requires
       one parameter which needs to be a filename. The method getall returns a hash which
       contains all options and its associated values of your config file.

       The format of config files supported by Config::General is inspired by the well known
       Apache config format, in fact, this module is 100% compatible to Apache configs, but you
       can also just use simple
        name/value pairs in your config files.

       In addition to the capabilities of an Apache config file it supports some enhancements
       such as here-documents, C-style comments or multiline options.

SUBROUTINES/METHODS

       new()
           Possible ways to call new():

            $conf = Config::General->new("rcfile");

            $conf = Config::General->new(\%somehash);

            $conf = Config::General->new( %options ); # see below for description of possible options

           This method returns a Config::General object (a hash blessed into "Config::General"
           namespace.  All further methods must be used from that returned object. see below.

           You can use the new style with hash parameters or the old style which is of course
           still supported. Possible parameters to new() are:

           * a filename of a configfile, which will be opened and parsed by the parser

           or

           * a hash reference, which will be used as the config.

           An alternative way to call new() is supplying an option- hash with one or more of the
           following keys set:

           -ConfigFile
               A filename or a filehandle, i.e.:

                -ConfigFile => "rcfile" or -ConfigFile => \$FileHandle

           -ConfigHash
               A hash reference, which will be used as the config, i.e.:

                -ConfigHash => \%somehash

           -String
               A string which contains a whole config, or an arrayref containing the whole config
               line by line.  The parser will parse the contents of the string instead of a file.
               i.e:

                -String => $complete_config

               it is also possible to feed an array reference to -String:

                -String => \@config_lines

           -AllowMultiOptions
               If the value is "no", then multiple identical options are disallowed.  The default
               is "yes".  i.e.:

                -AllowMultiOptions => "yes"

               see IDENTICAL OPTIONS for details.

           -LowerCaseNames
               If set to a true value, then all options found in the config will be converted to
               lowercase. This allows you to provide case-in-sensitive configs. The values of the
               options will not lowercased.

           -UseApacheInclude
               If set to a true value, the parser will consider "include ..." as valid include
               statement (just like the well known Apache include statement).

               It also supports apache's "IncludeOptional" statement with the same behavior, that
               is, if the include file doesn't exist no error will be thrown.

           -IncludeRelative
               If set to a true value, included files with a relative path (i.e. "cfg/blah.conf")
               will be opened from within the location of the configfile instead from within the
               location of the script($0). This works only if the configfile has a absolute
               pathname (i.e. "/etc/main.conf").

               If the variable -ConfigPath has been set and if the file to be included could not
               be found in the location relative to the current config file, the module will
               search within -ConfigPath for the file. See the description of -ConfigPath for
               more details.

           -IncludeDirectories
               If set to a true value, you may specify include a directory, in which case all
               files inside the directory will be loaded in ASCII order.  Directory includes will
               not recurse into subdirectories.  This is comparable to including a directory in
               Apache-style config files.

           -IncludeGlob
               If set to a true value, you may specify a glob pattern for an include to include
               all matching files (e.g. <<include conf.d/*.conf>>).  Also note that as with
               standard file patterns, * will not match dot-files, so <<include dir/*>> is often
               more desirable than including a directory with -IncludeDirectories.

               An include option will not cause a parser error if the glob didn't return
               anything.

           -IncludeAgain
               If set to a true value, you will be able to include a sub-configfile multiple
               times.  With the default, false, you will get a warning about duplicate includes
               and only the first include will succeed.

               Reincluding a configfile can be useful if it contains data that you want to be
               present in multiple places in the data tree.  See the example under "INCLUDES".

               Note, however, that there is currently no check for include recursion.

           -ConfigPath
               As mentioned above, you can use this variable to specify a search path for
               relative config files which have to be included. Config::General will search
               within this path for the file if it cannot find the file at the location relative
               to the current config file.

               To provide multiple search paths you can specify an array reference for the path.
               For example:

                @path = qw(/usr/lib/perl /nfs/apps/lib /home/lib);
                ..
                -ConfigPath => \@path

           -MergeDuplicateBlocks
               If set to a true value, then duplicate blocks, that means blocks and named blocks,
               will be merged into a single one (see below for more details on this).  The
               default behavior of Config::General is to create an array if some junk in a config
               appears more than once.

           -MergeDuplicateOptions
               If set to a true value, then duplicate options will be merged. That means, if the
               same option occurs more than once, the last one will be used in the resulting
               config hash.

               Setting this option implies -AllowMultiOptions == false unless you set
               -AllowMultiOptions explicit to 'true'. In this case duplicate blocks are allowed
               and put into an array but duplicate options will be merged.

           -AutoLaunder
               If set to a true value, then all values in your config file will be laundered to
               allow them to be used under a -T taint flag.  This could be regarded as
               circumventing the purpose of the -T flag, however, if the bad guys can mess with
               your config file, you have problems that -T will not be able to stop.  AutoLaunder
               will only handle a config file being read from -ConfigFile.

           -AutoTrue
               If set to a true value, then options in your config file, whose values are set to
               true or false values, will be normalised to 1 or 0 respectively.

               The following values will be considered as true:

                yes, on, 1, true

               The following values will be considered as false:

                no, off, 0, false

               This effect is case-insensitive, i.e. both "Yes" or "No" will result in 1.

           -FlagBits
               This option takes one required parameter, which must be a hash reference.

               The supplied hash reference needs to define variables for which you want to preset
               values. Each variable you have defined in this hash-ref and which occurs in your
               config file, will cause this variable being set to the preset values to which the
               value in the config file refers to.

               Multiple flags can be used, separated by the pipe character |.

               Well, an example will clarify things:

                my $conf = Config::General->new(
                        -ConfigFile => "rcfile",
                        -FlagBits => {
                             Mode => {
                                CLEAR    => 1,
                                STRONG   => 1,
                                UNSECURE => "32bit" }
                        }
                );

               In this example we are defining a variable named "Mode" which may contain one or
               more of "CLEAR", "STRONG" and "UNSECURE" as value.

               The appropriate config entry may look like this:

                # rcfile
                Mode = CLEAR | UNSECURE

               The parser will create a hash which will be the value of the key "Mode". This hash
               will contain all flags which you have pre-defined, but only those which were set
               in the config will contain the pre-defined value, the other ones will be
               undefined.

               The resulting config structure would look like this after parsing:

                %config = (
                            Mode => {
                                      CLEAR    => 1,
                                      UNSECURE => "32bit",
                                      STRONG   => undef,
                                    }
                          );

               This method allows the user (or, the "maintainer" of the configfile for your
               application) to set multiple pre-defined values for one option.

               Please beware, that all occurrences of those variables will be handled this way,
               there is no way to distinguish between variables in different scopes.  That means,
               if "Mode" would also occur inside a named block, it would also parsed this way.

               Values which are not defined in the hash-ref supplied to the parameter -FlagBits
               and used in the corresponding variable in the config will be ignored.

               Example:

                # rcfile
                Mode = BLAH | CLEAR

               would result in this hash structure:

                 %config = (
                            Mode => {
                                      CLEAR    => 1,
                                      UNSECURE => undef,
                                      STRONG   => undef,
                                    }
                          );

               "BLAH" will be ignored silently.

           -DefaultConfig
               This can be a hash reference or a simple scalar (string) of a config. This causes
               the module to preset the resulting config hash with the given values, which allows
               you to set default values for particular config options directly.

               Note that you probably want to use this with -MergeDuplicateOptions, otherwise a
               default value already in the configuration file will produce an array of two
               values.

           -Tie
               -Tie takes the name of a Tie class as argument that each new hash should be based
               off of.

               This hash will be used as the 'backing hash' instead of a standard Perl hash,
               which allows you to affect the way, variable storing will be done. You could, for
               example supply a tied hash, say Tie::DxHash, which preserves ordering of the keys
               in the config (which a standard Perl hash won't do). Or, you could supply a hash
               tied to a DBM file to save the parsed variables to disk.

               There are many more things to do in tie-land, see tie to get some interesting
               ideas.

               If you want to use the -Tie feature together with -DefaultConfig make sure that
               the hash supplied to -DefaultConfig must be tied to the same Tie class.

               Make sure that the hash which receives the generated hash structure (e.g. which
               you are using in the assignment: %hash = $config->getall()) must be tied to the
               same Tie class.

               Example:

                use Config::General qw(ParseConfig);
                use Tie::IxHash;
                tie my %hash, "Tie::IxHash";
                %hash = ParseConfig(
                          -ConfigFile => shift(),
                          -Tie => "Tie::IxHash"
                        );

           -InterPolateVars
               If set to a true value, variable interpolation will be done on your config input.
               See Config::General::Interpolated for more information.

           -InterPolateEnv
               If set to a true value, environment variables can be used in configs.

               This implies -InterPolateVars.

           -AllowSingleQuoteInterpolation
               By default variables inside single quotes will not be interpolated. If you turn on
               this option, they will be interpolated as well.

           -ExtendedAccess
               If set to a true value, you can use object oriented (extended) methods to access
               the parsed config. See Config::General::Extended for more information.

           -StrictObjects
               By default this is turned on, which causes Config::General to croak with an error
               if you try to access a non-existent key using the OOP-way (-ExtendedAcess
               enabled). If you turn -StrictObjects off (by setting to 0 or "no") it will just
               return an empty object/hash/scalar. This is valid for OOP-access 8via AUTOLOAD and
               for the methods obj(), hash() and value().

           -StrictVars
               By default this is turned on, which causes Config::General to croak with an error
               if an undefined variable with InterPolateVars turned on occurs in a config. Set to
               false (i.e. 0) to avoid such error messages.

           -SplitPolicy
               You can influence the way how Config::General decides which part of a line in a
               config file is the key and which one is the value. By default it tries its best to
               guess. That means you can mix equalsign assignments and whitespace assignments.

               However, sometime you may wish to make it more strictly for some reason. In this
               case you can set -SplitPolicy. The possible values are: 'guess' which is the
               default, 'whitespace' which causes the module to split by whitespace, 'equalsign'
               which causes it to split strictly by equal sign, or 'custom'. In the latter case
               you must also set -SplitDelimiter to some regular expression of your choice. For
               example:

                -SplitDelimiter => '\s*:\s*'

               will cause the module to split by colon while whitespace which surrounds the
               delimiter will be removed.

               Please note that the delimiter used when saving a config (save_file() or
               save_string()) will be chosen according to the current -SplitPolicy. If
               -SplitPolicy is set to 'guess' or 'whitespace', 3 spaces will be used to delimit
               saved options. If 'custom' is set, then you need to set -StoreDelimiter.

           -SplitDelimiter
               Set this to any arbitrary regular expression which will be used for option/value
               splitting. -SplitPolicy must be set to 'custom' to make this work.

           -StoreDelimiter
               You can use this parameter to specify a custom delimiter to use when saving
               configs to a file or string. You only need to set it if you want to store the
               config back to disk and if you have -SplitPolicy set to 'custom'.

               However, this parameter takes precedence over whatever is set for -SplitPolicy.

               Be very careful with this parameter.

           -CComments
               Config::General is able to notice c-style comments (see section COMMENTS).  But
               for some reason you might no need this. In this case you can turn this feature off
               by setting -CComments to a false value('no', 0, 'off').

               By default -CComments is turned on.

           -BackslashEscape
               Deprecated Option.

           -SlashIsDirectory
               If you turn on this parameter, a single slash as the last character of a named
               block will be considered as a directory name.

               By default this flag is turned off, which makes the module somewhat incompatible
               to Apache configs, since such a setup will be normally considered as an explicit
               empty block, just as XML defines it.

               For example, if you have the following config:

                <Directory />
                  Index index.awk
                </Directory>

               you will get such an error message from the parser:

                EndBlock "</Directory>" has no StartBlock statement (level: 1, chunk 10)!

               This is caused by the fact that the config chunk below will be internally
               converted to:

                <Directory></Directory>
                  Index index.awk
                </Directory>

               Now there is one '</Directory>' too much. The proper solution is to use quotation
               to circumvent this error:

                <Directory "/">
                  Index index.awk
                </Directory>

               However, a raw apache config comes without such quotes. In this case you may
               consider to turn on -SlashIsDirectory.

               Please note that this is a new option (incorporated in version 2.30), it may lead
               to various unexpected side effects or other failures.  You've been warned.

           -UseApacheIfDefine
               Enables support for Apache <IfDefine> ... </IfDefine>. See -Define.

           -Define
               Defines the symbols to be used for conditional configuration files.  Allowed
               arguments: scalar, scalar ref, array ref or hash ref.

               Examples:

                -Define => 'TEST'
                -Define => \$testOrProduction
                -Define => [qw(TEST VERBOSE)]
                -Define => {TEST => 1, VERBOSE => 1}

               Sample configuration:

                 <Logging>
                   <IfDefine TEST>
                      Level Debug
                      include test/*.cfg
                   </IfDef>
                   <IfDefine !TEST>
                     Level Notice
                      include production/*.cfg
                   </IfDefine>
                 </Logging>

           -ApacheCompatible
               Over the past years a lot of options has been incorporated into Config::General to
               be able to parse real Apache configs.

               The new -ApacheCompatible option now makes it possible to tweak all options in a
               way that Apache configs can be parsed.

               This is called "apache compatibility mode" - if you will ever have problems with
               parsing Apache configs without this option being set, you'll get no help by me.
               Thanks :)

               The following options will be set:

                UseApacheInclude   = 1
                IncludeRelative    = 1
                IncludeDirectories = 1
                IncludeGlob        = 1
                SlashIsDirectory   = 1
                SplitPolicy        = 'whitespace'
                CComments          = 0
                UseApacheIfDefine  = 1

               Take a look into the particular documentation sections what those options are
               doing.

               Beside setting some options it also turns off support for explicit empty blocks.

           -UTF8
               If turned on, all files will be opened in utf8 mode. This may not work properly
               with older versions of Perl.

           -SaveSorted
               If you want to save configs in a sorted manner, turn this parameter on. It is not
               enabled by default.

           -NoEscape
               If you want to use the data ( scalar or final leaf ) without escaping special
               character, turn this parameter on. It is not enabled by default.

           -NormalizeBlock
               Takes a subroutine reference as parameter and gets the current block or blockname
               passed as parameter and is expected to return it in some altered way as a scalar
               string. The sub will be called before anything else will be done by the module
               itself (e.g. interpolation).

               Example:

                -NormalizeBlock => sub { my $x = shift; $x =~ s/\s*$//; $x; }

               This removes trailing whitespaces of block names.

           -NormalizeOption
               Same as -NormalizeBlock but applied on options only.

           -NormalizeValue
               Same as -NormalizeBlock but applied on values only.

       getall()
           Returns a hash structure which represents the whole config.

       files()
           Returns a list of all files read in.

       save_file()
           Writes the config hash back to the hard disk. This method takes one or two parameters.
           The first parameter must be the filename where the config should be written to. The
           second parameter is optional, it must be a reference to a hash structure, if you set
           it. If you do not supply this second parameter then the internal config hash, which
           has already been parsed, will be used.

           Please note that any occurrence of comments will be ignored by getall() and thus be
           lost after you call this method.

           You need also to know that named blocks will be converted to nested blocks (which is
           the same from the perl point of view). An example:

            <user hans>
              id 13
            </user>

           will become the following after saving:

            <user>
              <hans>
                 id 13
              </hans>
            </user>

           Example:

            $conf_obj->save_file("newrcfile", \%config);

           or, if the config has already been parsed, or if it didn't change:

            $conf_obj->save_file("newrcfile");

       save_string()
           This method is equivalent to the previous save_file(), but it does not store the
           generated config to a file. Instead it returns it as a string, which you can save
           yourself afterwards.

           It takes one optional parameter, which must be a reference to a hash structure.  If
           you omit this parameter, the internal config hash, which has already been parsed, will
           be used.

           Example:

            my $content = $conf_obj->save_string(\%config);

           or:

            my $content = $conf_obj->save_string();

CONFIG FILE FORMAT

       Lines beginning with # and empty lines will be ignored. (see section COMMENTS!)  Spaces at
       the beginning and the end of a line will also be ignored as well as tabulators.  If you
       need spaces at the end or the beginning of a value you can surround it with double quotes.
       An option line starts with its name followed by a value. An equal sign is optional.  Some
       possible examples:

        user    max
        user  = max
        user            max

       If there are more than one statements with the same name, it will create an array instead
       of a scalar. See the example below.

       The method getall returns a hash of all values.

BLOCKS

       You can define a block of options. A block looks much like a block in the wellknown Apache
       config format. It starts with <blockname> and ends with </blockname>.

       A block start and end cannot be on the same line.

       An example:

        <database>
         host   = muli
         user   = moare
         dbname = modb
         dbpass = D4r_9Iu
        </database>

       Blocks can also be nested. Here is a more complicated example:

        user   = hans
        server = mc200
        db     = maxis
        passwd = D3rf$
        <jonas>
         user    = tom
         db      = unknown
         host    = mila
         <tablestructure>
          index   int(100000)
          name    char(100)
          prename char(100)
          city    char(100)
          status  int(10)
          allowed moses
          allowed ingram
          allowed joice
         </tablestructure>
        </jonas>

       The hash which the method getall returns look like that:

         print Data::Dumper(\%hash);
         $VAR1 = {
                  'passwd' => 'D3rf$',
                  'jonas'  => {
                               'tablestructure' => {
                                                    'prename' => 'char(100)',
                                                    'index'   => 'int(100000)',
                                                    'city'    => 'char(100)',
                                                    'name'    => 'char(100)',
                                                    'status'  => 'int(10)',
                                                    'allowed' => [
                                                                  'moses',
                                                                  'ingram',
                                                                  'joice',
                                                                 ]
                                                   },
                               'host'           => 'mila',
                               'db'             => 'unknown',
                               'user'           => 'tom'
                              },
                  'db'     => 'maxis',
                  'server' => 'mc200',
                  'user'   => 'hans'
                 };

       If you have turned on -LowerCaseNames (see new()) then blocks as in the following example:

        <Dir>
         <AttriBUTES>
          Owner  root
         </attributes>
        </dir>

       would produce the following hash structure:

         $VAR1 = {
                  'dir' => {
                            'attributes' => {
                                             'owner'  => "root",
                                            }
                           }
                 };

       As you can see, the keys inside the config hash are normalized.

       Please note, that the above config block would result in a valid hash structure, even if
       -LowerCaseNames is not set!  This is because Config::General does not use the block names
       to check if a block ends, instead it uses an internal state counter, which indicates a
       block end.

       If the module cannot find an end-block statement, then this block will be ignored.

NAMED BLOCKS

       If you need multiple blocks of the same name, then you have to name every block.  This
       works much like Apache config. If the module finds a named block, it will create a hashref
       with the left part of the named block as the key containing one or more hashrefs with the
       right part of the block as key containing everything inside the block(which may again be
       nested!). As examples says more than words:

       # given the following sample
        <Directory /usr/frisco>
         Limit Deny
         Options ExecCgi Index
        </Directory>
        <Directory /usr/frik>
         Limit DenyAll
         Options None
        </Directory>

       # you will get:

         $VAR1 = {
                  'Directory' => {
                                  '/usr/frik' => {
                                                  'Options' => 'None',
                                                  'Limit' => 'DenyAll'
                                                 },
                                  '/usr/frisco' => {
                                                    'Options' => 'ExecCgi Index',
                                                    'Limit' => 'Deny'
                                                   }
                                 }
                 };

       You cannot have more than one named block with the same name because it will be stored in
       a hashref and therefore be overwritten if a block occurs once more.

WHITESPACE IN BLOCKS

       The normal behavior of Config::General is to look for whitespace in block names to decide
       if it's a named block or just a simple block.

       Sometimes you may need blocknames which have whitespace in their names.

       With named blocks this is no problem, as the module only looks for the first whitespace:

        <person hugo gera>
        </person>

       would be parsed to:

         $VAR1 = {
                  'person' => {
                               'hugo gera' => {
                                              },
                              }
                 };

       The problem occurs, if you want to have a simple block containing whitespace:

        <hugo gera>
        </hugo gera>

       This would be parsed as a named block, which is not what you wanted. In this very case you
       may use quotation marks to indicate that it is not a named block:

        <"hugo gera">
        </"hugo gera">

       The save() method of the module inserts automatically quotation marks in such cases.

EXPLICIT EMPTY BLOCKS

       Beside the notation of blocks mentioned above it is possible to use explicit empty blocks.

       Normally you would write this in your config to define an empty block:

        <driver Apache>
        </driver>

       To save writing you can also write:

        <driver Apache/>

       which is the very same as above. This works for normal blocks and for named blocks.

IDENTICAL OPTIONS (ARRAYS)

       You may have more than one line of the same option with different values.  Example:

        log  log1
        log  log2
        log  log2

       You will get a scalar if the option occurred only once or an array if it occurred more
       than once. If you expect multiple identical options, then you may need to check if an
       option occurred more than once:

         $allowed = $hash{jonas}->{tablestructure}->{allowed};
         if (ref($allowed) eq "ARRAY") {
           @ALLOWED = @{$allowed};
           else {
             @ALLOWED = ($allowed);
           }
         }

       The same applies to blocks and named blocks too (they are described in more detail below).
       For example, if you have the following config:

        <dir blah>
         user max
        </dir>
        <dir blah>
         user hannes
        </dir>

       then you would end up with a data structure like this:

         $VAR1 = {
                  'dir' => {
                            'blah' => [
                                       {
                                        'user' => 'max'
                                       },
                                       {
                                        'user' => 'hannes'
                                       }
                                      ]
                           }
                 };

       As you can see, the two identical blocks are stored in a hash which contains an
       array(-reference) of hashes.

       Under some rare conditions you might not want this behavior with blocks (and named blocks
       too). If you want to get one single hash with the contents of both identical blocks, then
       you need to turn the new() parameter -MergeDuplicateBlocks on (see above). The parsed
       structure of the example above would then look like this:

         $VAR1 = {
                  'dir' => {
                            'blah' => {
                                       'user' => [
                                                  'max',
                                                  'hannes'
                                                 ]
                                      }
                           }
                 };

       As you can see, there is only one hash "dir->{blah}" containing multiple "user" entries.
       As you can also see, turning on  -MergeDuplicateBlocks does not affect scalar options
       (i.e. "option = value"). In fact you can tune merging of duplicate blocks and options
       independent from each other.

       If you don't want to allow more than one identical options, you may turn it off by setting
       the flag AllowMultiOptions in the new() method to "no".  If turned off, Config::General
       will complain about multiple occurring options with identical names!

   FORCE SINGLE VALUE ARRAYS
       You may also force a single config line to get parsed into an array by turning on the
       option -ForceArray and by surrounding the value of the config entry by []. Example:

        hostlist = [ foo.bar ]

       Will be a singlevalue array entry if the option is turned on. If you want it to remain to
       be an array you have to turn on -ForceArray during save too.

LONG LINES

       If you have a config value, which is too long and would take more than one line, you can
       break it into multiple lines by using the backslash character at the end of the line. The
       Config::General module will concatenate those lines to one single-value.

       Example:

        command = cat /var/log/secure/tripwire | \
        mail C<-s> "report from tripwire" \
        honey@myotherhost.nl

       command will become: "cat /var/log/secure/tripwire | mail "-s" 'report from twire'
       honey@myotherhost.nl"

HERE DOCUMENTS

       You can also define a config value as a so called "here-document". You must tell the
       module an identifier which indicates the end of a here document. An identifier must follow
       a "<<".

       Example:

        message <<EOF
         we want to
         remove the
         homedir of
         root.
        EOF

       Everything between the two "EOF" strings will be in the option message.

       There is a special feature which allows you to use indentation with here documents.  You
       can have any amount of whitespace or tabulators in front of the end identifier. If the
       module finds spaces or tabs then it will remove exactly those amount of spaces from every
       line inside the here-document.

       Example:

        message <<EOF
           we want to
           remove the
           homedir of
           root.
           EOF

       After parsing, message will become:

        we want to
        remove the
        homedir of
        root.

       because there were the string "     " in front of EOF, which were cut from every line
       inside the here-document.

INCLUDES

       You can include an external file at any position in your config file using the following
       statement in your config file:

        <<include externalconfig.rc>>

       If you turned on -UseApacheInclude (see new()), then you can also use the following
       statement to include an external file:

        include externalconfig.rc

       This file will be inserted at the position where it was found as if the contents of this
       file were directly at this position.

       You can also recursively include files, so an included file may include another one and so
       on.  Beware that you do not recursively load the same file, you will end with an error
       message like "too many open files in system!".

       By default included files with a relative pathname will be opened from within the current
       working directory. Under some circumstances it maybe possible to open included files from
       the directory, where the configfile resides. You need to turn on the option
       -IncludeRelative (see new()) if you want that. An example:

        my $conf = Config::General(
         -ConfigFile => "/etc/crypt.d/server.cfg"
         -IncludeRelative => 1
        );

       /etc/crypt.d/server.cfg:

        <<include acl.cfg>>

       In this example Config::General will try to include acl.cfg from /etc/crypt.d:

        /etc/crypt.d/acl.cfg

       The default behavior (if -IncludeRelative is not set!) will be to open just acl.cfg,
       wherever it is, i.e. if you did a chdir("/usr/local/etc"), then Config::General will
       include:

        /usr/local/etc/acl.cfg

       Include statements can be case insensitive (added in version 1.25).

       Include statements will be ignored within C-Comments and here-documents.

       By default, a config file will only be included the first time it is referenced.  If you
       wish to include a file in multiple places, set /-IncludeAgain to true. But be warned: this
       may lead to infinite loops, so make sure, you're not including the same file from within
       itself!

       Example:

        # main.cfg
        <object billy>
         class=Some::Class
        <printers>
         include printers.cfg
        </printers>
        # ...
        </object>
         <object bob>
          class=Another::Class
         <printers>
         include printers.cfg
         </printers>
         # ...
        </object>

       Now "printers.cfg" will be include in both the "billy" and "bob" objects.

       You will have to be careful to not recursively include a file.  Behaviour in this case is
       undefined.

COMMENTS

       A comment starts with the number sign #, there can be any number of spaces and/or tab
       stops in front of the #.

       A comment can also occur after a config statement. Example:

        username = max  # this is the comment

       If you want to comment out a large block you can use C-style comments. A /* signals the
       begin of a comment block and the */ signals the end of the comment block.  Example:

        user  = max # valid option
        db    = tothemax
        /*
        user  = andors
        db    = toand
        */

       In this example the second options of user and db will be ignored. Please beware of the
       fact, if the Module finds a /* string which is the start of a comment block, but no
       matching end block, it will ignore the whole rest of the config file!

       NOTE: If you require the # character (number sign) to remain in the option value, then you
       can use a backslash in front of it, to escape it. Example:

        bgcolor = \#ffffcc

       In this example the value of $config{bgcolor} will be "#ffffcc", Config::General will not
       treat the number sign as the begin of a comment because of the leading backslash.

       Inside here-documents escaping of number signs is NOT required!

PARSER PLUGINS

       You can alter the behavior of the parser by supplying closures which will be called on
       certain hooks during config file processing and parsing.

       The general aproach works like this:

         sub ck {
           my($file, $base) = @_;
           print "_open() tries $file ... ";
           if ($file =~ /blah/) {
             print "ignored\n";
             return (0);
           } else {
             print "allowed\n";
             return (1, @_);
           }
         }

         my %c = ParseConfig(
                             -IncludeGlob      => 1,
                             -UseApacheInclude => 1,
                             -ConfigFile       => shift,
                             -Plug             => { pre_open => *ck }
                            );

       Output:

        _open() tries cfg ... allowed
        _open() tries x/*.conf ... allowed
        _open() tries x/1.conf ... allowed
        _open() tries x/2.conf ... allowed
        _open() tries x/blah.conf ... ignored

       As you can see, we wrote a little sub which takes a filename and a base directory as
       parameters. We tell Config::General via the Plug parameter of new() to call this sub
       everytime before it attempts to open a file.

       General processing continues as usual if the first value of the returned array is true.
       The second value of that array depends on the kind of hook being called.

       The following hooks are available so far:

       pre_open
           Takes two parameters: filename and basedirectory.

           Has to return an array consisting of 3 values:

            - 1 or 0 (continue processing or not)
            - filename
            - base directory

       pre_read
           Takes two parameters: the filehandle of the file to be read and an array containing
           the raw contents of said file.

           This hook will be applied in _read(). File contents are already available at this
           stage, comments will be removed, here-docs normalized and the like. This hook gets the
           unaltered, original contents.

           Has to return an array of 3 values:

            - 1 or 0 (continue processing or not)
            - the filehandle
            - an array of strings

           You can use this hook to apply your own normalizations or whatever.

           Be careful when returning the abort value (1st value of returned array 0), since in
           this case nothing else would be done on the contents. If it still contains comments or
           something, they will be parsed as legal config options.

       post_read
           Takes one parameter: a reference to an array containing the prepared config lines
           (after being processed by _read()).

           This hook will be applied in _read() when everything else has been done.

           Has to return an array of 2 values:

            - 1 or 0 (continue processing or not) [Ignored for post hooks]
            - a reference to an array containing the config lines

       pre_parse_value
           Takes 2 parameters: an option name and its value.

           This hook will be applied in _parse_value() before any processing.

           Has to return an array of 3 values:

            - 1 or 0 (continue processing or not)
            - option name
            - value of the option

       post_parse_value
           Almost identical to pre_parse_value, but will be applied after _parse_value() is
           finished and all usual processing and normalization is done.

       Not implemented yet: hooks for variable interpolation and block parsing.

OBJECT ORIENTED INTERFACE

       There is a way to access a parsed config the OO-way.  Use the module
       Config::General::Extended, which is supplied with the Config::General distribution.

VARIABLE INTERPOLATION

       You can use variables inside your config files if you like. To do that you have to use the
       module Config::General::Interpolated, which is supplied with the Config::General
       distribution.

EXPORTED FUNCTIONS

       Config::General exports some functions too, which makes it somewhat easier to use it, if
       you like this.

       How to import the functions:

        use Config::General qw(ParseConfig SaveConfig SaveConfigString);

       ParseConfig()
           This function takes exactly all those parameters, which are allowed to the new()
           method of the standard interface.

           Example:

            use Config::General qw(ParseConfig);
            my %config = ParseConfig(-ConfigFile => "rcfile", -AutoTrue => 1);

       SaveConfig()
           This function requires two arguments, a filename and a reference to a hash structure.

           Example:

            use Config::General qw(SaveConfig);
            ..
            SaveConfig("rcfile", \%some_hash);

       SaveConfigString()
           This function requires a reference to a config hash as parameter.  It generates a
           configuration based on this hash as the object-interface method save_string() does.

           Example:

            use Config::General qw(ParseConfig SaveConfigString);
            my %config = ParseConfig(-ConfigFile => "rcfile");
            .. # change %config something
            my $content = SaveConfigString(\%config);

CONFIGURATION AND ENVIRONMENT

       No environment variables will be used.

SEE ALSO

       I recommend you to read the following documents, which are supplied with Perl:

        perlreftut                     Perl references short introduction
        perlref                        Perl references, the rest of the story
        perldsc                        Perl data structures intro
        perllol                        Perl data structures: arrays of arrays

        Config::General::Extended      Object oriented interface to parsed configs
        Config::General::Interpolated  Allows one to use variables inside config files

LICENSE AND COPYRIGHT

       Copyright (c) 2000-2022 Thomas Linden

       This library is free software; you can redistribute it and/or modify it under the same
       terms of the Artistic License 2.0.

BUGS AND LIMITATIONS

       See rt.cpan.org for current bugs, if any.

INCOMPATIBILITIES

       None known.

DIAGNOSTICS

       To debug Config::General use the Perl debugger, see perldebug.

DEPENDENCIES

       Config::General depends on the modules FileHandle, File::Spec::Functions, File::Glob,
       which all are shipped with Perl.

AUTHOR

       Thomas Linden <tlinden |AT| cpan.org>

VERSION

       2.65