Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Config::Fast(3)	      User Contributed Perl Documentation      Config::Fast(3)

NAME
       Config::Fast - extremely	fast configuration file	parser

SYNOPSIS
	   # default config format is a	space-separated	file
	   company    "Supercool, Inc."
	   support    nobody@nowhere.com

	   # 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 <nate@wiger.org>. 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.

perl v5.32.0			  2006-03-06		       Config::Fast(3)

NAME | SYNOPSIS | DESCRIPTION | FILE FORMAT | VARIABLES | NOTES | VERSION | AUTHOR

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Config::Fast&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help