Config::Model::Value man page on Pidora

Man page or keyword search:  
man Server   31170 pages
apropos Keyword Search (all sections)
Output format
Pidora logo
[printable version]

Config::Model::Value(3User Contributed Perl DocumentatiConfig::Model::Value(3)

NAME
       Config::Model::Value - Strongly typed configuration value

VERSION
       version 1.235

SYNOPSIS
	use Config::Model;
	use Log::Log4perl qw(:easy);
	Log::Log4perl->easy_init($WARN);

	# define configuration tree object
	my $model = Config::Model->new;
	$model ->create_config_class (
	   name => "MyClass",

	   element => [

	       [qw/foo bar/] => {
		   type	      => 'leaf',
		   value_type => 'string',
		   description => 'foobar',
	       },
	    country => {
	      type =>	    'leaf',
	      value_type => 'enum',
	      choice =>	     [qw/France US/],
	      description => 'big countries',
	    },
	   ],
	) ;

	my $inst = $model->instance(root_class_name => 'MyClass' );

	my $root = $inst->config_root ;

	# put data
	$root->load( step => 'foo=FOO country=US' );

	print $root->report ;
	#  foo = FOO
	#	  DESCRIPTION: foobar
	#
	#  country = US
	#	  DESCRIPTION: big countries

DESCRIPTION
       This class provides a way to specify configuration value with the
       following properties:

       ·   Strongly typed scalar: the value can either be an enumerated type,
	   a boolean, a number, an integer or a string

       ·   default parameter: a value can have a default value specified
	   during the construction. This default value will be written in the
	   target configuration file. ("default" parameter)

       ·   upstream default parameter: specifies a default value that will be
	   used by the application when no information is provided in the
	   configuration file. This upstream_default value will not written in
	   the configuration files. Only the "fetch_standard" method will
	   return the builtin value. This parameter was previously referred as
	   "built_in" value. This may be used for audit purpose.
	   ("upstream_default" parameter)

       ·   mandatory value: reading a mandatory value will raise an exception
	   if the value is not specified and has no default value.

       ·   dynamic change of property: A slave value can be registered to
	   another master value so that the properties of the slave value can
	   change according to the value of the master value. For instance,
	   paper size value can be 'letter' for country 'US' and 'A4' for
	   country 'France'.

       ·   A reference to the Id of a hash of list element. In other word, the
	   value is an enumerated type where the possible values (choice) is
	   defined by the existing keys of a has element somewhere in the
	   tree. See "Value Reference".

Default values
       There are several kind of default values. They depend on where these
       values are defined (or found).

       From the lowest default level to the "highest":

       ·   "upstream_default": The value is knows in the application, but is
	   not written in the configuration file.

       ·   "default": The value is known by the model, but not by the
	   application. This value must be written in the configuration file.

       ·   "computed": The value is computed from other configuration
	   elements. This value must be written in the configuration file.

       ·   "preset": The value is not known by the model or by the
	   application. But it can be found by an automatic program and stored
	   while the configuration Config::Model::Instance is in
	   Config::Model::Instance/"preset_start ()"

       Then there is the value entered by the user. This will override all
       kind of "default" value.

       The fetch_standard function will return the "highest" level of default
       value, but will not return a custom value, i.e. a value entered by the
       user.

Constructor
       Value object should not be created directly.

Value model declaration
       A leaf element must be declared with the following parameters:

       value_type
	   Either "boolean", "enum", "integer", "number", "uniline", "string".
	   Mandatory. See "Value types".

       default
	   Specify the default value (optional)

       upstream_default
	   Specify a built in default value (optional)

       compute
	   Will compute a value according to a formula and other values. By
	   default a computed value cannot be set. See
	   Config::Model::ValueComputer for computed value declaration.

       migrate_from
	   This is a special parameter to cater for smooth configuration
	   upgrade. This parameter can be used to copy the value of a
	   deprecated parameter to its replacement. See "upgrade"" in " for
	   details.

       convert => [uc | lc ]
	   When stored, the value will be converted to uppercase (uc) or
	   lowercase (lc).

       min Specify the minimum value (optional, only for integer, number)

       max Specify the maximum value (optional, only for integer, number)

       mandatory
	   Set to 1 if the configuration value must be set by the
	   configuration user (default: 0)

       choice
	   Array ref of the possible value of an enum. Example :

	    choice => [ qw/foo bar/]

       match
	   Perl regular expression. The value will be match with the regex to
	   assert its validity. Example "match => '^foo'" means that the
	   parameter value must begin with "foo". Valid only for "string" or
	   "uniline" values.

       warn_if_match
	   Hash ref. Keys are made of Perl regular expression. The value can
	   specify a warning message (leave empty or undefined for default
	   warning message) and instructions to fix the value. A warning will
	   be issued when the value match the passed regular expression. Valid
	   only for "string" or "uniline" values. The fix instructions will be
	   evaluated when apply_fixes is called. $_ will contain the value to
	   fix.	 $_ will be stored as the new value once the instructions are
	   done.

	   In the example below, any value matching 'foo' will be converted in
	   uppercase:

	     warn_if_match => { 'foo' => { fix =>'uc;' }},

       warn_unless_match
	   Hash ref like above. A warning will be issued when the value does
	   not match the passed regular expression. Valid only for "string" or
	   "uniline" values.

       warn
	   String. Issue a warning to user with the specified string any time
	   a value is set or read.

       grammar
	   Setup a Parse::RecDescent grammar to perform validation.

	   If the grammar does not start with a "check" rule (i.e does not
	   start with "check: "), the first line of the grammar will be
	   modified to add "check" rule and set up this rules so the entire
	   value must match the passed grammar.

	   I.e. the grammar:

	     token (oper token)(s?)
	     oper: 'and' | 'or'
	     token: 'Apache' | 'CC-BY' | 'Perl'

	   will be changed to

	     check: token (oper token)(s?) /^\Z/ {$return = 1;}
	     oper: 'and' | 'or'
	     token: 'Apache' | 'CC-BY' | 'Perl'

	   The rule is called with Value object and a string reference. So, in
	   the actions you may need to define, you can call the value object
	   as $arg[0], store error message in "${$arg[1]}}" and store warnings
	   in "${$arg[2]}}".

       replace
	   Hash ref. Used for enum to substitute one value with another. This
	   parameter must be used to enable user to upgrade a configuration
	   with obsolete values. For instance, if the value "foo" is obsolete
	   and replaced by "foo_better", you will need to declare:

	     replace => { foo => 'foo_better' }

	   The hash key can also be a regular expression for wider range
	   replacement.	 The regexp must match the whole value:

	     replace => ( 'foo.*' => 'better_foo' }

	   In this case, a value will be replaced by "better_foo" if the
	   "/^foo.*$/" regexp matches.

       refer_to
	   Specify a path to an id element used as a reference. See Value
	   Reference for details.

       computed_refer_to
	   Specify a path to an id element used as a computed reference. See
	   "Value Reference" for details.

       warp
	   See section below: "Warp: dynamic value configuration".

       help
	   You may provide detailed description on possible values with a hash
	   ref. Example:

	    help => { oui => "French for 'yes'", non => "French for 'no'"}

   Value types
       This modules can check several value types:

       "boolean"
	   Accepts values 1 or 0, "yes" or "no", "true" or "false". The value
	   read back is always 1 or 0.

       "enum"
	   Enum choices must be specified by the "choice" parameter.

       "integer"
	   Enable positive or negative integer

       "number"
	   The value can be a decimal number

       "uniline"
	   A one line string. I.e without "\n" in it.

       "string"
	   Actually, no check is performed with this type.

       "reference"
	   Like an "enum" where the possible values (aka choice) is defined by
	   another location if the configuration tree. See "Value Reference".

Warp: dynamic value configuration
       The Warp functionality enable a "Value" object to change its properties
       (i.e. default value or its type) dynamically according to the value of
       another "Value" object locate elsewhere in the configuration tree. (See
       Config::Model::WarpedThing for an explanation on warp mechanism).

       For instance if you declare 2 "Value" element this way:

	$model ->create_config_class (
	  name => "TV_config_class",
	  element => [
	    country => {
	      type => 'leaf',
	      value_type => 'enum',
	      choice => [qw/US Europe Japan/]
	    },
	    tv_standard => {
	      type => 'leaf',
	      value_type => 'enum',
	      choice => [qw/PAL NTSC SECAM/]
	      warp => {
		follow => { c => '- country' }, # this points to the warp master
		rules => {
		  '$c eq "US"'	   => { default => 'NTSC'  },
		  '$c eq "France"' => { default => 'SECAM' },
		  '$c eq "Japan"'  => { default => 'NTSC'  },
		  '$c eq "Europe"' => { default => 'PAL'   },
		}
	      }
	    },
	  ]
	);

       Setting "country" element to "US" will mean that "tv_standard" has a
       default value set to "NTSC" by the warp mechanism.

       Likewise, the warp mechanism enables you to dynamically change the
       possible values of an enum element:

	state => {
	     type => 'leaf',
	     value_type => 'enum', # example is admittedly silly
	     warp =>{
		follow => { c => '- country' },
		rules => {
		  '$c eq "US"'	   => { choice => ['Kansas', 'Texas'	]},
		  '$c eq "Europe"' => { choice => ['France', 'Spain'	]},
		  '$c eq "Japan"'  => { choice => ['Honshu', 'Hokkaido' ]}
		}
	     }
	  }

   Cascaded warping
       Warping value can be cascaded: "A" can be warped by "B" which can be
       warped by "C". But this feature should be avoided since it can lead to
       a model very hard to debug. Bear in mind that:

       ·   Warp loop are not detected and will end up in "deep recursion
	   subroutine" failures.

       ·   If you declare "diamond" shaped warp dependencies, the results will
	   depend on the order of the warp algorithm and can be unpredictable.

       ·   The keys declared in the warp rules ("US", "Europe" and "Japan" in
	   the example above) cannot be checked at start time against the warp
	   master "Value". So a wrong warp rule key will be silently ignored
	   during start up and will fail at run time.

Value Reference
       To set up an enumerated value where the possible choice depends on the
       key of a Config::Model::AnyId object, you must:

       ·   Set "value_type" to "reference".

       ·   Specify the "refer_to" or "computed_refer_to" parameter.  See
	   refer_to parameter.

       In this case, a "IdElementReference" object is created to handle the
       relation between this value object and the referred Id. See
       Config::Model::IdElementReference for details.

Introspection methods
       The following methods returns the current value of the parameter of the
       value object (as declared in the model unless they were warped):

       min
       max
       mandatory
       choice
       convert
       value_type
       default
       upstream_default
       index_value
       element_name

   name()
       Returns the object name.

   get_type
       Returns "leaf".

   can_store()
       Returns true if the value object can be assigned to. Return 0 for a
       read-only value (i.e. a computed value with no override allowed).

   get_choice()
       Query legal values (only for enum types). Return an array (possibly
       empty).

   get_help ( [ on_value ] )
       Returns the help strings passed to the constructor.

       With "on_value" parameter, returns the help string dedicated to the
       passed value or undef.

       Without parameter returns a hash ref that contains all the help
       strings.

   error_msg
       Returns the error messages of this object (if any)

   warning_msg
       Returns warning concerning this value. Returns a list in list context
       and a string in scalar context.

   check_value ( value )
       Check the consistency of the value. Does not check for undefined
       mandatory values.

       "check_value" also accepts named parameters:

       value
       quiet
	   When non null, check will not try to get extra information from the
	   tree. This is required in some cases to avoid loops in check,
	   get_info, get_warp_info, re-check ...

       In scalar context, return 0 or 1.

       In array context, return an empty array when no error was found. In
       case of errors, returns an array of error strings that should be shown
       to the user.

   has_fixes
       Returns the number of fixes that can be applied to the current value.

   apply_fixes
       Applies the fixes to suppress the current warnings.

   check( value	 )
       Like "check_value". Also ensure that mandatory value are defined

       Will also display warnings on STDOUT unless "silent" parameter is set
       to 1.  In this case,user is expected to retrieve them with warning_msg.

Information management
   store( value )
       Can be called as "value => ...,	check => yes|no|skip )"

       Store value in leaf element. "check" parameter can be used to skip
       validation check.

   load_data( scalar_value )
       Load scalar data. Data is simply forwarded to store.

   fetch_custom
       Returns the stored value if this value is different from a standard
       setting or built in setting. In other words, returns undef if the
       stored value is identical to the default value or the computed value or
       the built in value.

   fetch_standard
       Returns the standard value as defined by the configuration model. The
       standard value can be either a preset value, a computed value, a
       default value or a built-in default value.

   fetch( ... )
       Check and fetch value from leaf element. The method can have one
       parameter (the fetch mode) or several pairs:

       mode
	   Whether to fetch default, custom, etc value. See below for details

       check
	   Whether to check if the value is valid or not before returning it.
	   Default is 'yes'.  Possible value are

	   yes Perform check and raise an exception for bad values

	   skip
	       Perform check and return undef for bad values

	   no  Do not check and return values even if bad

       silent
	   When set to 1, warning are not displayed on STDOUT. User is
	   expected to read warnings with warning_msg method.

       According to the "mode" parameter, this method will return either:

       empty mode parameter (default)
	   Value entered by user or default value if the value is different
	   from upstream_default

       custom
	   The value entered by the user (if different from built in, preset,
	   computed or default value)

       preset
	   The value entered in preset mode

       standard
	   The preset or computed or default or built in value.

       default
	   The default value (defined by the configuration model)

       upstream_default
	   The upstream_default value. (defined by the configuration model)

       non_upstream_default
	   The custom or preset or computed or default value. Will return
	   undef if either of this value is identical to the upstream_default
	   value. This feature is useful to reduce data to write in
	   configuration file.

       allow_undef
	   This mode will accept to return undef for mandatory values.
	   Normally, trying to fetch an undefined mandatory value leads to an
	   exception.

   user_value
       Returns the value entered by the user. Does not use the default or
       computed value. Returns undef unless a value was actually stored.

   fetch_preset
       Returns the value entered in preset mode. Does not use the default or
       computed value. Returns undef unless a value was actually stored in
       preset mode.

   get( path => ..., mode => ... ,  check => ... )
       Get a value from a directory like path.

   set( path , value )
       Set a value from a directory like path.

Examples
   Number with min and max values
	bounded_number => {
	   type	      => 'leaf',
	   value_type => 'number',
	   min	      => 1,
	   max	      => 4,
	 },

   Mandatory value
	 mandatory_string => {
	   type	      => 'leaf',
	   value_type => 'string',
	   mandatory  => 1,
	 },

	 mandatory_boolean => {
	   type	      => 'leaf',
	   value_type => 'boolean',
	 },

   Enum with help associated with each value
       Note that the help specification is optional.

	  enum_with_help => {
	   type	      => 'leaf',
	   value_type => 'enum',
	   choice     => [qw/a b c/],
	   help	      => { a => 'a help' }
	 },

   Migrate old obsolete enum value
       Legacy values "a1", "c1" and "foo/.*" are replaced with "a", "c" and
       "foo/".

	 with_replace => {
	   type	      => 'leaf',
	   value_type => 'enum',
	   choice     => [qw/a b c/],
	   replace    => {
	       a1	=> 'a',
	       c1	=> 'c',
	       'foo/.*' => 'foo',
	   },
	 },

   Enforce value to match a regexp
       An exception will be triggered if the value does not match the "match"
       regular expression.

	 match => {
	   type	      => 'leaf',
	   value_type => 'string',
	   match      => '^foo\d{2}$',
	 },

   Enforce value to match a Parse::RecDescent grammar
	 prd_match => {
	   type	      => 'leaf',
	   value_type => 'string',
	   grammar    => q{
	       token (oper token)(s?)
	       oper: 'and' | 'or'
	       token: 'Apache' | 'CC-BY' | 'Perl'
	   },
	 },

   Issue a warning if a value matches a regexp
       Issue a warning if the string contains upper case letters. Propose a
       fix that translate all capital letters to lower case.

	 warn_if_capital => {
	   type		 => 'leaf',
	   value_type	 => 'string',
	   warn_if_match => { '/A-Z/' => { fix => '$_ = lc;' } },
	 },

       A specific warning can be specified:

	 warn_if_capital => {
	   type		 => 'leaf',
	   value_type	 => 'string',
	   warn_if_match => {
	       '/A-Z/' => {
		   fix => '$_ = lc;' ,
		   mesg =>'NO UPPER CASE PLEASE'
	       }
	   },
	 },

   Issue a warning if a value does NOT match a regexp
	 warn_unless => {
	   type		     => 'leaf',
	   value_type	     => 'string',
	   warn_unless_match => { foo => { msg => '', fix => '$_ = "foo".$_;' } },
	 },

   Always issue a warning
	 always_warn => {
	   type	      => 'leaf',
	   value_type => 'string',
	   warn	      => 'Always warn whenever used',
	 },

   Computed values
       See "Examples" in Config::Model::ValueComputer.

Upgrade
       Upgrade is a special case when the configuration of an application has
       changed. Some parameters can be removed and replaced by another one. To
       avoid trouble on the application user side, Config::Model offers a
       possibility to handle the migration of configuration data through a
       special declaration in the configuration model.

       This declaration must:

       ·   Declare the deprecated parameter with a "status" set to
	   "deprecated"

       ·   Declare the new parameter with the instructions to load the
	   semantic content from the deprecated parameter. These instructions
	   are declared in the "migrate_from" parameters (which is similar to
	   the "compute" parameter)

       Here an example where a URL parameter is changed to a set of 2
       parameters (host and path):

	      'old_url' => { type => 'leaf',
			     value_type => 'uniline',
			     status => 'deprecated',
			   },
	      'host'
	      => { type => 'leaf',
		   value_type => 'uniline',
		   # the formula must end with '$1' so the result of the capture is used
		   # as the host value
		   migrate_from => { formula => '$old =~ m!http://([\w\.]+)!; $1 ;' ,
				     variables => { old => '- old_url' } ,
				     use_eval => 1 ,
				   },
			       },
	      'path' => { type => 'leaf',
			  value_type => 'uniline',
			  migrate_from => { formula => '$old =~ m!http://[\w\.]+(/.*)!; $1 ;',
					    variables => { old => '- old_url' } ,
					    use_eval => 1 ,
					  },
			},

EXCEPTION HANDLING
       When an error is encountered, this module may throw the following
       exceptions:

	Config::Model::Exception::Model
	Config::Model::Exception::Formula
	Config::Model::Exception::WrongValue
	Config::Model::Exception::WarpError

       See Config::Model::Exception for more details.

AUTHOR
       Dominique Dumont, (ddumont at cpan dot org)

SEE ALSO
       Config::Model, Config::Model::Node, Config::Model::AnyId,
       Config::Model::WarpedThing, Exception::Class
       Config::Model::ValueComputer,

perl v5.14.1			  2011-07-22	       Config::Model::Value(3)
[top]

List of man pages available for Pidora

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net