NAME
   Config::Fast - extremely fast configuration file parser

SYNOPSIS
       # default config format is a space-separated file
       company    "Supercool, Inc."
       support    [email protected]

       # and then in Perl
       use Config::Fast;

       %cf = fastconfig;

       print "Thanks for visiting $cf{company}!\n";
       print "Please contact $cf{support} for support.\n";

DESCRIPTION
   This module is designed to provide an extremely lightweight way to parse
   moderately complex configuration files. As such, it exports a single
   function - "fastconfig()" - and does not provide any OO access methods.
   Still, it is fairly full-featured.

   Here's how it works:

       %cf = fastconfig($file, $delim);

   Basically, the "fastconfig()" function returns a hash of keys and values
   based on the directives in your configuration file. By default,
   directives and values are separated by whitespace in the config file,
   but this can be easily changed with the delimiter argument (see below).

   When the configuration file is read, its modification time is first
   checked and the results cached. On each call to "fastconfig()", if the
   config file has been changed, then the file is reread. Otherwise, the
   cached results are returned automatically. This makes this module great
   for "mod_perl" modules and scripts, one of the primary reasons I wrote
   it. Simply include this at the top of your script or inside of your
   constructor function:

       my %cf = fastconfig('/path/to/config/file.conf');

   If the file argument is omitted, then "fastconfig()" looks for a file
   named "$0.conf" in the "../etc" directory relative to the executable.
   For example, if you ran:

       /usr/local/bin/myapp

   Then "fastconfig()" will automatically look for:

       /usr/local/etc/myapp.conf

   This is great if you're really lazy and always in a hurry, like I am.

   If this doesn't work for you, simply supply a filename manually. Note
   that filename generation does not work in "mod_perl", so you'll need to
   supply a filename manually.

FILE FORMAT
   By default, your configuration file is split up on the first white space
   it finds. Subsequent whitespace is preserved intact - quotes are not
   needed (but you can include them if you wish). For example, this:

       company     Hardwood Flooring Supplies, Inc.

   Would result in:

       $cf{company} = 'Hardwood Flooring Supplies, Inc.';

   Of course, you can use the delimiter argument to change the delimiter to
   anything you want. To read Bourne shell style files, you would use:

       %cf = fastconfig($file, '=');

   This would let you read a file of the format:

       system=Windows
       kernel=sortof

   In all formats, any space around the value is stripped. This is one
   situation where you must include quotes:

       greeting="     Some leading and trailing space    "

   Each configuration directive is read sequentially and placed in the
   hash. If the same directive is present multiple times, the last one will
   override any earlier ones.

   In addition, you can reuse previously-defined variables by preceding
   them with a "$" sign. Hopefully this seems logical to you.

       owner       Bill Johnson
       company     $owner and Company, Ltd.
       website     http://www.billjohnsonltd.com
       products    $website/newproducts.html

   Of course, you can include literal characters by escaping them:

       price       \$5.00
       streetname  "Guido \"The Enforcer\" Scorcese"
       verbatim    'Single "quotes" are $$ money @ night'
       fileregex   '(\.exe|\.bat)$'

   Basically, this modules attempts to mimic, as closely as possible,
   Perl's own single and double quoting conventions.

   Variable names are case-insensitive by default (see "KEEPCASE"). In this
   example, the last setting of "ORACLE_HOME" will win:

       oracle_home /oracle
       Oracle_Home /oracle/orahome1
       ORACLE_HOME /oracle/OraHome2

   In addition, variables are converted to lowercase before being returned
   from "fastconfig()", meaning you would access the above as:

       print $cf{oracle_home};     # /oracle/OraHome2

   Speaking of which, an extra nicety is that this module will setup
   environment variables for any ALLCAPS variables you define. So, the
   above "ORACLE_HOME" variable will automatically be stuck into %ENV. But
   you would still access it in your program as "oracle_home". This may
   seem confusing at first, but once you use it, I think you'll find it
   makes sense.

   Finally, if called in a scalar context, then variables will be imported
   directly into the "main::" namespace, just like if you had defined them
   yourself:

       use Config::Fast;

       fastconfig('web.conf');

       print "The web address is: $website\n";     # website from conf

   Generally, this is regarded as dangerous and bad form, so I would
   strongly advise using this form only in throwaway scripts, or not at
   all.

VARIABLES
   There are several global variables that can be set which affect how
   "fastconfig()" works. These can be set in the following way:

       use Config::Fast;
       $Config::Fast::Variable = 'value';
       %cf = fastconfig;

   The recognized variables are:

   $Delim
       The config file delimiter to use. This can also be specified as the
       second argument to "fastconfig()". This defaults to "\s+".

   $KeepCase
       If set to 1, then "MixedCaseVariables" are maintained intact. By
       default, all variables are converted to lowercase.

   $EnvCaps
       If set to 1 (the default), then any "ALLCAPS" variables are set as
       environment variables. They are still returned in lowercase from
       "fastconfig()".

   $Arrays
       If set to 1, then settings that look like shell arrays are converted
       into a Perl array. For example, this config block:

           MATRIX[0]="a b c"
           MATRIX[1]="d e f"
           MATRIX[2]="g h i"

       Would be returned as:

           $conf{matrix} = [ 'a b c', 'd e f', 'g h i' ];

       Instead of the default:

           $conf{matrix[0]} = 'a b c';
           $conf{matrix[1]} = 'd e f';
           $conf{matrix[2]} = 'g h i';

   @Define
       This allows you to pre-define var=val pairs that are set before the
       parsing of the config file. I introduced this feature to solve a
       specific problem: Executable relocation. In my config files, I put
       definitions such as:

           # Parsed by Config::Fast and sourced by shell scripts
           BIN="$ROOT/bin"
           SBIN="$ROOT/sbin"
           LIB="$ROOT/lib"
           ETC="$ROOT/etc"

       With the goal that this file would be equally usable by both Perl
       and shell scripts.

       When parsed by "Config::Fast", I pre-define "ROOT" to "pwd" before
       calling "fastconfig()":

           use Cwd;
           my $pwd = cwd;
           @Config::Fast::Define = ([ROOT => $pwd]);
           my %conf = fastconfig("$pwd/conf/core.conf");

       Each element of

   %Convert
       This is a hash of regex patterns specifying values that should be
       converted before being returned. By default, values that look like
       "true|on|yes" will be converted to 1, and values that match
       "false|off|no" will be converted to 0. You could set your own
       conversions with:

           $Config::Fast::CONVERT{'fluffy|chewy'} = 'taffy';

       This would convert any settings of "fluffy" or "chewy" to "taffy".

NOTES
   Variables starting with a leading underscore are considered reserved and
   should not be used in your config file, unless you enjoy painfully
   mysterious behavior.

   For a much more full-featured config module, check out
   "Config::ApacheFormat". It can handle Apache style blocks, array values,
   etc, etc. This one is supposed to be fast and easy.

VERSION
   $Id: Fast.pm,v 1.7 2006/03/06 22:18:41 nwiger Exp $

AUTHOR
   Copyright (c) 2002-2005 Nathan Wiger <[email protected]>. All Rights
   Reserved.

   This module is free software; you may copy this under the terms of the
   GNU General Public License, or the Artistic License, copies of which
   should have accompanied your Perl kit.

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.