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

FreeBSD Manual Pages


home | help
AppConfig::State(3)   User Contributed Perl Documentation  AppConfig::State(3)

       AppConfig::State	- application configuration state

	   use AppConfig::State;

	   my $state = AppConfig::State->new(\%cfg);

	   $state->define("foo");	     # very simple variable definition
	   $state->define("bar", \%varcfg);  # variable	specific configuration
	   $state->define("foo|bar=i@");     # compact format

	   $state->set("foo", 123);	     # trivial set/get examples

	   $state->foo();		     # shortcut	variable access
	   $state->foo(456);		     # shortcut	variable update

       AppConfig::State	is a Perl5 module to handle global configuration
       variables for perl programs.  It	maintains the state of any number of
       variables, handling default values, aliasing, validation, update
       callbacks and option arguments for use by other AppConfig::* modules.

       AppConfig::State	is distributed as part of the AppConfig	bundle.

   USING THE AppConfig::State MODULE
       To import and use the AppConfig::State module the following line	should
       appear in your Perl script:

	    use	AppConfig::State;

       The AppConfig::State module is loaded automatically by the new()
       constructor of the AppConfig module.

       AppConfig::State	is implemented using object-oriented methods.  A new
       AppConfig::State	object is created and initialised using	the new()
       method.	This returns a reference to a new AppConfig::State object.

	   my $state = AppConfig::State->new();

       This will create	a reference to a new AppConfig::State with all
       configuration options set to their default values.  You can initialise
       the object by passing a reference to a hash array containing
       configuration options:

	   $state = AppConfig::State->new( {
	       CASE	 => 1,
	       ERROR	 => \&my_error,
	   } );

       The new() constructor of	the AppConfig module automatically passes all
       parameters to the AppConfig::State new()	constructor.  Thus, any	global
       configuration values and	variable definitions for AppConfig::State are
       also applicable to AppConfig.

       The following configuration options may be specified.

	   Determines if the variable names are	treated	case sensitively.  Any
	   non-zero value makes	case significant when naming variables.	 By
	   default, CASE is set	to 0 and thus "Variable", "VARIABLE" and
	   "VaRiAbLe" are all treated as "variable".

	   By default, CREATE is turned	off meaning that all variables
	   accessed via	set() (which includes access via shortcut such as
	   "$state->variable($value)" which delegates to set())	must
	   previously have been	defined	via define().  When CREATE is set to
	   1, calling set($variable, $value) on	a variable that	doesn't	exist
	   will	cause it to be created automatically.

	   When	CREATE is set to any other non-zero value, it is assumed to be
	   a regular expression	pattern.  If the variable name matches the
	   regex, the variable is created.  This can be	used to	specify
	   configuration file blocks in	which variables	should be created, for

	       $state =	AppConfig::State->new( {
		   CREATE => '^define_',
	       } );

	   In a	config file:

	       name = fred	     # define_name gets	created	automatically

	       name = john	     # other_name doesn't - warning raised

	   Note	that a regex pattern specified in CREATE is applied to the
	   real	variable name rather than any alias by which the variables may
	   be accessed.

	   The PEDANTIC	option determines what action the configuration	file
	   (AppConfig::File) or	argument parser	(AppConfig::Args) should take
	   on encountering a warning condition (typically caused when trying
	   to set an undeclared	variable).  If PEDANTIC	is set to any true
	   value, the parsing methods will immediately return a	value of 0 on
	   encountering	such a condition.  If PEDANTIC is not set, the method
	   will	continue to parse the remainder	of the current file(s) or
	   arguments, returning	0 when complete.

	   If no warnings or errors are	encountered, the method	returns	1.

	   In the case of a system error (e.g. unable to open a	file), the
	   method returns undef	immediately, regardless	of the PEDANTIC

	   Specifies a user-defined error handling routine.  When the handler
	   is called, a	format string is passed	as the first parameter,
	   followed by any additional values, as per printf(3C).

	   Turns debugging on or off when set to 1 or 0	accordingly.
	   Debugging may also be activated by calling _debug() as an object
	   method ("$state->_debug(1)")	or as a	package	function
	   (AppConfig::State::_debug(1)), passing in a true/false value	to set
	   the debugging state accordingly.  The package variable
	   $AppConfig::State::DEBUG can	also be	set directly.

	   The _debug()	method returns the current debug value.	 If a new
	   value is passed in, the internal value is updated, but the previous
	   value is returned.

	   Note	that any AppConfig::File or App::Config::Args objects that are
	   instantiated	with a reference to an App::State will inherit the
	   DEBUG (and also PEDANTIC) values of the state at that time.
	   Subsequent changes to the AppConfig::State debug value will not
	   affect them.

	   The GLOBAL option allows default values to be set for the DEFAULT,
	   ARGCOUNT, EXPAND, VALIDATE and ACTION options for any subsequently
	   defined variables.

	       $state =	AppConfig::State->new({
		   GLOBAL => {
		       DEFAULT	=> '<undef>',	  # default value for new vars
		       ARGCOUNT	=> 1,		  # vars expect	an argument
		       ACTION	=> \&my_set_var,  # callback when vars get set

	   Any attributes specified explicitly when a variable is defined will
	   override any	GLOBAL values.

	   See "DEFINING VARIABLES" below which	describes these	options	in

       The "define()" function is used to pre-declare a	variable and specify
       its configuration.


       In the simple example above, a new variable called "foo"	is defined.  A
       reference to a hash array may also be passed to specify configuration
       information for the variable:

	   $state->define("foo", {
		   DEFAULT   =>	99,
		   ALIAS     =>	'metavar1',

       Any variable-wide GLOBAL	values passed to the new() constructor in the
       configuration hash will also be applied.	 Values	explicitly specified
       in a variable's define()	configuration will override the	respective
       GLOBAL values.

       The following configuration options may be specified

	   The DEFAULT value is	used to	initialise the variable.

	       $state->define("drink", {
		       DEFAULT => 'coffee',

	       print $state->drink();	     # prints "coffee"

	   The ALIAS option allows a number of alternative names to be
	   specified for this variable.	 A single alias	should be specified as
	   a string.  Multiple aliases can be specified	as a reference to an
	   array of alternatives or as a string	of names separated by vertical
	   bars, '|'.  e.g.:

	       # either
	       $state->define("name", {
		       ALIAS  => 'person',

	       # or
	       $state->define("name", {
		       ALIAS =>	[ 'person', 'user', 'uid' ],

	       # or
	       $state->define("name", {
		       ALIAS =>	'person|user|uid',

	       $state->user('abw');	# equivalent to	$state->name('abw');

	   The ARGCOUNT	option specifies the number of arguments that should
	   be supplied for this	variable.  By default, no additional arguments
	   are expected	for variables (ARGCOUNT_NONE).

	   The ARGCOUNT_* constants can	be imported from the AppConfig module:

	       use AppConfig ':argcount';

	       $state->define('foo', { ARGCOUNT	=> ARGCOUNT_ONE	});

	   or can be accessed directly from the	AppConfig package:

	       use AppConfig;

	       $state->define('foo', { ARGCOUNT	=> AppConfig::ARGCOUNT_ONE });

	   The following values	for ARGCOUNT may be specified.

	       Indicates that no additional arguments are expected.  If	the
	       variable	is identified in a confirguration file or in the
	       command line arguments, it is set to a value of 1 regardless of
	       whatever	arguments follow it.

	       Indicates that the variable expects a single argument to	be
	       provided.  The variable value will be overwritten with a	new
	       value each time it is encountered.

	       Indicates that the variable expects multiple arguments.	The
	       variable	value will be appended to the list of previous values
	       each time it is encountered.

	       Indicates that the variable expects multiple arguments and that
	       each argument is	of the form "key=value".  The argument will be
	       split into a key/value pair and inserted	into the hash of
	       values each time	it is encountered.

	   The ARGS option can also be used to specify advanced	command	line
	   options for use with	AppConfig::Getopt, which itself	delegates to
	   Getopt::Long.  See those two	modules	for more information on	the
	   format and meaning of these options.

	       $state->define("name", {
		       ARGS => "=i@",

	   The EXPAND option specifies how the AppConfig::File processor
	   should expand embedded variables in the configuration file values
	   it reads.  By default, EXPAND is turned off (EXPAND_NONE) and no
	   expansion is	made.

	   The EXPAND_*	constants can be imported from the AppConfig module:

	       use AppConfig ':expand';

	       $state->define('foo', { EXPAND => EXPAND_VAR });

	   or can be accessed directly from the	AppConfig package:

	       use AppConfig;

	       $state->define('foo', { EXPAND => AppConfig::EXPAND_VAR });

	   The following values	for EXPAND may be specified.  Multiple values
	   should be combined with vertical bars , '|',	e.g. "EXPAND_UID |

	       Indicates that no variable expansion should be attempted.

	       Indicates that variables	embedded as $var or $(var) should be
	       expanded	to the values of the relevant AppConfig::State

	       Indicates that '~' or '~uid' patterns in	the string should be
	       expanded	to the current users ($<), or specified	user's home
	       directory.  In the first	case, "~" is expanded to the value of
	       the "HOME" environment variable.	 In the	second case, the
	       "getpwnam()" method is used if it is available on your system
	       (which it isn't on Win32).

	       Inidicates that variables embedded as ${var} should be expanded
	       to the value of the relevant environment	variable.

	       Equivalent to "EXPAND_VARS | EXPAND_UIDS	| EXPAND_ENVS").

	       Indicates that embedded variables that are not defined should
	       raise a warning.	 If PEDANTIC is	set, this will cause the
	       read() method to	return 0 immediately.

	   Each	variable may have a sub-routine	or regular expression defined
	   which is used to validate the intended value	for a variable before
	   it is set.

	   If VALIDATE is defined as a regular expression, it is applied to
	   the value and deemed	valid if the pattern matches.  In this case,
	   the variable	is then	set to the new value.  A warning message is
	   generated if	the pattern match fails.

	   VALIDATE may	also be	defined	as a reference to a sub-routine	which
	   takes as its	arguments the name of the variable and its intended
	   value.  The sub-routine should return 1 or 0	to indicate that the
	   value is valid or invalid, respectively.  An	invalid	value will
	   cause a warning error message to be generated.

	   If the GLOBAL VALIDATE variable is set (see GLOBAL in DESCRIPTION
	   above) then this value will be used as the default VALIDATE for
	   each	variable unless	otherwise specified.

	       $state->define("age", {
		       VALIDATE	=> '\d+',

	       $state->define("pin", {
		       VALIDATE	=> \&check_pin,

	   The ACTION option allows a sub-routine to be	bound to a variable as
	   a callback that is executed whenever	the variable is	set.  The
	   ACTION is passed a reference	to the AppConfig::State	object,	the
	   name	of the variable	and the	value of the variable.

	   The ACTION routine may be used, for example,	to post-process
	   variable data, update the value of some other dependant variable,
	   generate a warning message, etc.


	       $state->define("foo", { ACTION => \&my_notify });

	       sub my_notify {
		   my $state = shift;
		   my $var   = shift;
		   my $val   = shift;

		   print "$variable set	to $value";

	       $state->foo(42);	       # prints	"foo set to 42"

	   Be aware that calling "$state->set()" to update the same variable
	   from	within the ACTION function will	cause a	recursive loop as the
	   ACTION function is repeatedly called.

       Variables may be	defined	in a compact format which allows any ALIAS and
       ARGS values to be specified as part of the variable name.  This is
       designed	to mimic the behaviour of Johan	Vromans' Getopt::Long module.

       Aliases for a variable should be	specified after	the variable name,
       separated by vertical bars, '|'.	 Any ARGS parameter should be appended
       after the variable name(s) and/or aliases.

       The following examples are equivalent:

	   $state->define("foo", {
		   ALIAS => [ 'bar', 'baz' ],
		   ARGS	 => '=i',


       AppConfig::State	defines	two methods to manipulate variable values:

	   set($variable, $value);

       Both functions take the variable	name as	the first parameter and
       "set()" takes an	additional parameter which is the new value for	the
       variable.  "set()" returns 1 or 0 to indicate successful	or
       unsuccessful update of the variable value.  If there is an ACTION
       routine associated with the named variable, the value returned will be
       passed back from	"set()".  The "get()" function returns the current
       value of	the variable.

       Once defined, variables may be accessed directly	as object methods
       where the method	name is	the same as the	variable name.	i.e.

	   $state->set("verbose", 1);

       is equivalent to


       Without parameters, the current value of	the variable is	returned.  If
       a parameter is specified, the variable is set to	that value and the
       result of the set() operation is	returned.

	   $state->age(29);	   # sets 'age'	to 29, returns 1 (ok)

       The varlist() method can	be used	to extract a number of variables into
       a hash array.  The first	parameter should be a regular expression used
       for matching against the	variable names.

	   my %vars = $state->varlist("^file");	  # all	"file*"	variables

       A second	parameter may be specified (any	true value) to indicate	that
       the part	of the variable	name matching the regex	should be removed when
       copied to the target hash.


	   my %vars = $state->varlist("^file_",	1);

	   # %vars:
	   #	name =>	/tmp/file
	   #	path =>	"/foo:/bar:/baz"

       The interal (private) methods of	the AppConfig::State class are listed

       They aren't intended for	regular	use and	potential users	should
       consider	the fact that nothing about the	internal implementation	is
       guaranteed to remain the	same.  Having said that, the AppConfig::State
       class is	intended to co-exist and work with a number of other modules
       and these are considered	"friend" classes.  These methods are provided,
       in part,	as services to them.  With this	acknowledged co-operation in
       mind, it	is safe	to assume some stability in this core interface.

       The _varname() method can be used to determine the real name of a
       variable	from an	alias:


       Note that all methods that take a variable name,	including those	listed
       below, can accept an alias and automatically resolve it to the correct
       variable	name.  There is	no need	to call	_varname() explicitly to do
       alias expansion.	 The _varname()	method will fold all variables names
       to lower	case unless CASE sensititvity is set.

       The _exists() method can	be used	to check if a variable has been


       The _default() method can be used to reset a variable to	its default


       The _expand() method can	be used	to determine the EXPAND	value for a

	   print "$varname EXPAND: ", $state->_expand($varname), "\n";

       The _argcount() method returns the value	of the ARGCOUNT	attribute for
       a variable:

	   print "$varname ARGCOUNT: ",	$state->_argcount($varname), "\n";

       The _validate() method can be used to determine if a new	value for a
       variable	meets any validation criteria specified	for it.	 The variable
       name and	intended value should be passed	in.  The methods returns a
       true/false value	depending on whether or	not the	validation succeeded:

	   print "OK\n"	if $state->_validate($varname, $value);

       The _pedantic() method can be called to determine the current value of
       the PEDANTIC option.

	   print "pedantic mode	is ", $state->_pedantic() ? "on" ; "off", "\n";

       The _debug() method can be used to turn debugging on or off (pass 1 or
       0 as a parameter).  It can also be used to check	the debug state,
       returning the current internal value of $AppConfig::State::DEBUG.  If a
       new debug value is provided, the	debug state is updated and the
       previous	state is returned.

	   $state->_debug(1);		    # debug on,	returns	previous value

       The _dump_var($varname) and _dump() methods may also be called for
       debugging purposes.

	   $state->_dump_var($varname);	   # show variable state
	   $state->_dump();		   # show internal state and all vars

       Andy Wardley, <>

       Copyright (C) 1997-2007 Andy Wardley.  All Rights Reserved.

       Copyright (C) 1997,1998 Canon Research Centre Europe Ltd.

       This module is free software; you can redistribute it and/or modify it
       under the same terms as Perl itself.

       AppConfig, AppConfig::File, AppConfig::Args, AppConfig::Getopt

perl v5.32.0			  2015-03-01		   AppConfig::State(3)


Want to link to this manual page? Use this URL:

home | help