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

FreeBSD Manual Pages

  
 
  

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

NAME
       AppConfig::State	- application configuration state

SYNOPSIS
	   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->get("foo");

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

OVERVIEW
       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.

DESCRIPTION
   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.

       CASE
	   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".

       CREATE
	   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
	   example:

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

	   In a	config file:

	       [define]
	       name = fred	     # define_name gets	created	automatically

	       [other]
	       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.

       PEDANTIC
	   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
	   option.

       ERROR
	   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).

       DEBUG
	   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.

       GLOBAL
	   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
	   detail.

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

	   $state->define("foo");

       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

       DEFAULT
	   The DEFAULT value is	used to	initialise the variable.

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

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

       ALIAS
	   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');

       ARGCOUNT
	   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.

	   ARGCOUNT_NONE (0)
	       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.

	   ARGCOUNT_ONE	(1)
	       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.

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

	   ARGCOUNT_HASH (3)
	       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.

       ARGS
	   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@",
		   });

       EXPAND
	   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 |
	   EXPAND_VAR").

	   EXPAND_NONE
	       Indicates that no variable expansion should be attempted.

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

	   EXPAND_UID
	       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).

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

	   EXPAND_ALL
	       Equivalent to "EXPAND_VARS | EXPAND_UIDS	| EXPAND_ENVS").

	   EXPAND_WARN
	       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.

       VALIDATE
	   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,
		   });

       ACTION
	   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.

	   Example:

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

   DEFINING VARIABLES USING THE	COMPACT	FORMAT
       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',
	       });

	   $state->define("foo|bar|baz=i");

   READING AND MODIFYING VARIABLE VALUES
       AppConfig::State	defines	two methods to manipulate variable values:

	   set($variable, $value);
	   get($variable);

       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

	   $state->verbose(1);

       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)

   VARLIST
       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.

	   $state->file_name("/tmp/file");
	   $state->file_path("/foo:/bar:/baz");

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

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

   INTERNAL METHODS
       The interal (private) methods of	the AppConfig::State class are listed
       below.

       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:

	   $varname->_varname($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
       defined:

	   $state->_exists($varname);

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

	   $state->_default($varname);

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

	   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

AUTHOR
       Andy Wardley, <abw@wardley.org>

COPYRIGHT
       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.

SEE ALSO
       AppConfig, AppConfig::File, AppConfig::Args, AppConfig::Getopt

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

NAME | SYNOPSIS | OVERVIEW | DESCRIPTION | AUTHOR | COPYRIGHT | SEE ALSO

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

home | help