NAME

Config::Hierarchical - Hierarchical configuration container

SYNOPSIS

  use Config::Hierarchical ;
   
  my $config = new Config::Hierarchical(); 
  
  # or
  
  my $config = new Config::Hierarchical
			(
			NAME                       => 'some_namespace',
			VERBOSE                    => 0,
			DISABLE_SILENT_OPTIONS     => 0,
			CATEGORY_NAMES             => ['<CLI>', '<PBS>', 'PARENT', 'LOCAL', 'CURRENT'],
			DEFAULT_CATEGORY           => 'CURRENT',
			
			WARN_FOR_EXPLICIT_CATEGORY => 0,
			
			GET_CATEGORIES => 
				{
				Inheritable => ['CLI', 'PBS', 'PARENT', 'CURRENT'],
				},
				
			INTERACTION =>
				{
				INFO  => \&sub,
				WARN  => \&sub,
				DIE   => \&sub,
				DEBUG => \&sub,
				},
				
			SET_VALIDATOR => \&my_set_validator,
			
			VALIDATORS =>
				[
				{
				CATEGORY_NAMES => ['CLI', 'CURRENT',] ,
				NAMES          => ['CC', 'LD'],
				VALIDATORS     => 
					{
					alphanumeric => \&alphanumeric,
					other_validator => \&other_validator,
					},
				},
				
				{
				CATEGORY_NAMES => ['CURRENT',] ,
				NAMES          => ['CC',],
				VALIDATORS     => {only_gcc => \&only_gcc,},
				}, 
				],
				
			INITIAL_VALUES =>
				[
				{
				CATEGORY       => 'PBS',
				ALIAS_CATEGORY => $pbs_config,
				HISTORY        => ....,
				COMMENT        => ....,
				},
				
				{CATEGORY => 'CLI', NAME => 'CC', VALUE => 1,},
				{CATEGORY => 'CLI', NAME => 'LD', VALUE => 2, LOCK => 1},
				
				{CATEGORY => 'CURRENT', NAME => 'CC', VALUE => 3, OVERRIDE => 1},
				{CATEGORY => 'CURRENT', NAME => 'AS', VALUE => 4,},
				{CATEGORY => 'CURRENT', NAME => 'VARIABLE_WITH_HISTORY', VALUE => $previous_value, HISTORY => $history },
				] ,
				
			LOCKED_CATEGORIES => ['CLI'],
			) ;
	
  $config->Set(NAME => 'CC', VALUE => 'gcc') ;
  $config->Set(NAME => 'CC', VALUE => 'gcc', CATEGORY => 'CLI') ;
  $config->Set(NAME => 'CC', VALUE => 'gcc', FORCE_LOCK => 1) ;
  $config->Set(NAME => 'CC', VALUE => 'gcc', SILENT_OVERRIDE => 1, COMMENT => 'we prefer gcc') ;
  
  $config->Exists(NAME => 'CC') ;
  
  $config->GetKeyValueTuples() ;
  
  $config->SetMultiple
	(
	{FORCE_LOCK => 1}
	{NAME => 'CC', VALUE => 'gcc', SILENT_OVERRIDE => 1},
	{NAME => 'LD', VALUE => 'ld'},
	) ;
  
  $config->Set(CC => 'gcc') ;
  
  $value = $config->Get(NAME => 'CC') ;
  $value = $config->Get(NAME => 'NON_EXISTANT', SILENT_NOT_EXISTS => 1) ;
  
  @values = $config->GetMultiple(@config_variables_names) ;
  @values = $config->GetMultiple({SILENT_NOT_EXISTS => 1}, @config_variables_names) ;
  
  $hash_ref = $config->GetHashRef() ; # no warnings
  
  $config->GetInheritable() ;
  
  $config->SetDisableSilentOptions(1) ;
	
  $config->LockCategories('PBS') ;
  $config->UnlockCategories('CLI', 'PBS') ;
  $config->IsCategoryLocked('PBS') ;
  
  $config->Lock(NAME => 'CC') ;
  $config->Unlock(NAME => 'CC', CATEGORY => 'CLI') ;
  $config->IsLocked(NAME => 'CC') ;
  
  $history = $config->GetHistory(NAME => 'CC') ;
  $dump = $config->GetDump() ;

DESCRIPTION

This module implements a configuration variable container. The container has multiple categories which are declared in decreasing priority order.

A variable can exist in multiple categories within the container. When queried for a variable, the container will return the variable in the category with the highest priority.

When setting a variable, the container will display a warning message if it is set in a category with lower priority than a category already containing the same variable.

Priority overriding is also possible.

DOCUMENTATION

I'll start by giving a usage example. In a build system, configuration variables can have different source.

the build tool
the command line
the parent build file (in a hierarchical build system)
the current build file

It is likely that a configuration variable set on the command line should be used regardless of a local setting. Also, a configuration variable set by the build tool itself should have the highest priority.

Among the most difficult errors to find are configuration errors in complex build systems. Build tools generally don't help much when variables are overridden. it's also difficult to get a variable's history.

This module provides the necessary functionality to handle most of the cases needed in a modern build system.

Test t/099_cookbook.t is also a cookbook you can generate with POD::Tested. It's a nice complement to this documentation.

SUBROUTINES/METHODS

Subroutines that are not part of the public interface are marked with [p].

new(@named_arguments)

Create a Config::Hierarchical .

my $config = new Config::Hierarchical() ;

Arguments

The arguments are named. All argument are optional. The order is not important.

my $config = new Config::Hierarchical(NAME => 'some_namespace', VERBOSE  => 1) ;

NAME

A string that will be used in all the dumps and interaction with the user.
CATEGORY_NAMES

A list of category names. The first named category has the highest priority. Only categories listed in this list can be manipulated. Using an unregistered category in a Set or Get operation will generate an error.
```
  my $config = new Config::Hierarchical
			(
			CATEGORY_NAMES   => ['CLI', '<PBS>', 'PARENT', 'CURRENT', 'LOCAL'],	
			DEFAULT_CATEGORY => 'CURRENT',
			) ;
```
A category can be protected by enclosing its name in angle bracket, IE: <PBS>. Protected categories will not be overridden by lesser priority categories even if the OVERRIDE option is used.

If no category names are given, 'CURRENT' will be used and DEFAULT_CATEGORY will be set accordingly.
DEFAULT_CATEGORY

The name of the category used when Set is called without a CATEGORY argument.

If the CATEGORY_NAMES list contains more than one entry, DEFAULT_CATEGORY must be set or an error will be generated.
DIE_NOT_EXISTS
```
my $config = new Config::Hierarchical(..., DIE_NOT_EXISTS => 0) ;
```
Calling Get on an unexisting variable will generate an exception when this option is set. The option is not set by default.
DISABLE_SILENT_OPTIONS
```
my $config = new Config::Hierarchical(NAME => 'some_namespace', DISABLE_SILENT_OPTIONS => 1) ;
```
When this option is set, SILENT_OVERRIDE and SILENT_NOT_EXISTS will be ignored and Config::Hierarchical will display a warning.

GET_CATEGORIES

This option allows you to define functions that fetch variables in a specific category list and in a specific order.

  my $config = new Config::Hierarchical
			(
			CATEGORY_NAMES   => ['CLI', '<PBS>', 'PARENT', 'CURRENT', 'LOCAL'],
			
			GET_CATEGORIES =>
				{
				Inheritable => ['CLI', 'PBS', 'PARENT', 'CURRENT'],
				}
			...
			) ;
			
  my $value = $config->GetInheritable(NAME => 'CC') ;
  my $hash_ref = $config->GetInheritableHashRef() ;

In the example above, the LOCAL category will not be used by GetInheritable.

WARN_FOR_EXPLICIT_CATEGORY

if set, Config::Hierarchical will display a warning if any category is specified in Get or Set.
VERBOSE

This module will display information about its actions when this option is set.

See INTERACTION and SetDisplayExplicitCategoryWarningOption.
INTERACTION

Lets you define subs used to interact with the user.
```
  my $config = new Config::Hierarchical
			(
			INTERACTION      =>
				{
				INFO  => \&sub,
				WARN  => \&sub,
				DIE   => \&sub,
				DEBUG => \&sub,
				}
			) ;
```
INFO

This sub will be used when displaying verbose information.

WARN

This sub will be used when a warning is displayed. e.g. a configuration that is refused or an override.

DIE

Used when an error occurs. E.g. a locked variable is set.

DEBUG

If this option is set, Config::Hierarchical will call the sub before and after acting on the configuration. This can act as a breakpoint in a debugger or allows you to pinpoint a configuration problem.

The functions default to:
- INFO => CORE::print
- WARN => Carp::carp
- DIE => Carp::confess
FILE and LINE

These will be used in the information message and the history information if set. If not set, the values returned by caller will be used. These options allow you to write wrapper functions that report the callers location properly.

INITIAL_VALUES

Lets you initialize the Config::Hierarchical object. Each entry will be passed to Set.

  my $config = new Config::Hierarchical
			(
			...
			
			EVALUATOR => \&sub,
			
			INITIAL_VALUES =>
				[
				{ # aliased category
				CATEGORY       => 'PBS',
				ALIAS_CATEGORY => $pbs_config,
				HISTORY        => ....,
				COMMENT        => ....,
				},
				
				{CATEGORY => 'CLI', NAME => 'CC', VALUE => 1},
				{CATEGORY => 'CLI', NAME => 'LD', VALUE => 2, LOCK => 1},
				
				{CATEGORY => 'CURRENT', NAME => 'CC', VALUE => 3, OVERRIDE => 1},
				{CATEGORY => 'CURRENT', NAME => 'AS', VALUE => 4,},
				} ,
			) ;

See Set for options to INITIAL_VALUES and a details explanation about EVALUATOR.

Aliased categories allow you to use a category to refer to an existing Config::Hierarchical object. The referenced object is read only. This is because multiple configurations might alias to the same Config::Hierarchical object.

Variables from aliased category can still be overridden.

LOG_ACCESS

If this set, Config::Hierarchical will log all access made through Get.
LOCKED_CATEGORIES

Lets you lock categories making them read only. Values in INITIAL_VALUES are used before locking the category.
```
my $config = new Config::Hierarchical(..., LOCKED_CATEGORIES => ['CLI', 'PBS']) ;
```
See LockCategories and IsCategoryLocked.
SET_VALIDATOR

This gives you full control over what gets into the config. Pass a sub reference that will be used to check the configuration variable passed to the subroutine Set.

Argument passed to the subroutine reference:

$config

The configuration object. Yous should use the objects interaction subs for message display.

$options

The options passed to Set.

$location

The location where Set was called. Useful when displaying an error message.
```
sub my_set_validator
{
my ($config, $options, $location) = @_ ;

# eg, check the variable name
if($options->{NAME} !~ /^CFG_[A-Z]+/)
	{
	$config->{INTERACTION}{DIE}->("$config->{NAME}: Invalid variable name '$options->{NAME}' at at '$location'!")
	}
	
# all OK, let Config::Hierarchical handle variable setting
}

my $config = new Config::Hierarchical(SET_VALIDATOR => \&my_set_validator) ;
```
VALIDATORS
```
  my $config = new Config::Hierarchical
			(
			...
			VALIDATORS =>
				[
				{
				CATEGORY_NAMES => ['CURRENT', 'OTHER'] ,
				NAMES          => ['CC', 'LD'],
				VALIDATORS     => 
					{
					validator_name => \&PositiveValueValidator,
					other_validator => \&SecondValidator
					},
				},
				],
			) ;
```
Let you add validation subs to Config::Hierarchical for specific variables.

Each variable in NAMES in each category in CATEGORY_NAMES will be assigned the validators defined in Validators.

The example above will add a validator PositiveValueValidator and validator SecondValidator to CURRENT::CC, CURRENT::LD, OTHER::CC and OTHER::LD.

A validator is sub that will be called every time a value is assigned to a variable. The sub is passed a single argument, the value to be assigned to the variable. If false is returned by any of the validators, an Exception will be raised through INTERACTION::DIE.

see AddValidator.

GetInformation()

Arguments - None

Returns

The configuration name
The configuration object's creation location

[p] Setup

Helper sub called by new. This shall not be used directly.

[p] SetInteractionDefault

Sets {INTERACTION} fields that are not set by the user.

[p] SetupCategories

Helper sub called by new.

AddValidator(CATEGORY_NAMES => \@categories, NAMES => \@names, VALIDATORS => \%validators)

$config->AddValidator
		(
		CATEGORY_NAMES => ['CLI'] ,
		NAMES          => ['CC', 'LD'],
		VALIDATORS     => {positive_value => \&PositiveValueValidator},
		) ;

You can add validators after creating a configuration and even after adding variables to your configuration. The existing variables will be checked when the validators are added.

Arguments

CATEGORY_NAMES => \@catagories - A reference to an array containing the names of the categories to add the validators to
NAMES => \@names - A reference to an array containing the names of the variables that will be validated
VALIDATORS => \%validators - A reference to a hash where keys are validator_names and values are validator code references

Returns - Nothing

Config::Hierarchical will warn you if you override a validator.

[p] AddValidators

[p] AddVariableValidator

[p] SetCategoryAlias

Used to handle category aliases.

  my $pbs_config = new Config::Hierarchical(...) ;
  
  my $config = new Config::Hierarchical
			(
			NAME                       => 'some_namespace',
			CATEGORY_NAMES             => ['<CLI>', '<PBS>', 'PARENT', 'LOCAL', 'CURRENT'],
				
			INITIAL_VALUES =>
				[
				{
				CATEGORY       => 'PBS',
				ALIAS_CATEGORY => $pbs_config,
				HISTORY        => ....,
				COMMENT        => ....,
				},
				{NAME => 'CC1', VALUE => 'gcc'},
				...
				] ,
				
			) ;

CATEGORY and ALIAS_CATEGORY must be passed as arguments. See new for details about aliased categories.

Arguments

HISTORY
COMMENT
CHECK_LOWER_LEVEL_CATEGORIES

[p] CreateCustomGetFunctions

Creates custom Get* functions.

[p] CheckOptionNames

Verifies the options passed to the members of this class. Calls {INTERACTION}{DIE} in case of error.

Set(@named_arguments)

  my $config = new Config::Hierarchical() ;
  
  $config->Set(NAME => 'CC', VALUE => 'gcc') ;
  
  $config->Set
		(
		NAME => 'CC', VALUE => 'gcc',
		
		# options
		HISTORY         => $history,
		COMMENT         => 'we like gcc'
		CATEGORY        => 'CLI',
		VALIDATORS      => {positive_value => \&PositiveValueValidator,}
		FORCE_LOCK      => 1,
		LOCK            => 1,
		OVERRIDE        => 1,
		SILENT_OVERRIDE => 1,
		ATTRIBUTE       => 'some attribute',
		FILE            => 'some_file',
		LINE            => 1,
		
		CHECK_LOWER_LEVEL_CATEGORIES => 1,
		) ;

ARGUMENTS

NAME - The variable's name. MANDATORY
EVAL - Can be used instead for NAME. See 'Using EVAL instead for VALUE'
VALUE - A scalar value associated with the 'NAME' variable. MANDATORY
HISTORY

The argument passed is kept in the configuration variable. You can pass any scalar variable; Config::Hierarchical will not manipulate this information.

See GetHistory.
COMMENT

A comment that will be added to the variable history.
CATEGORY

The name of the category where the variable resides. If no CATEGORY is given, the default category is used.
ATTRIBUTE

Set the configuration variable's attribute to the passed argument. See <SetAttribute>.
SET_VALIDATOR

Configuration validators that will only be used during this call to Set. The SET_VALIDATOR set in the constructor will not be called if this option is set. This lets you add configuration variable from different source and check them with specialized validators.
VALIDATORS

Extra validators that will only be used during this call to Set.
FORCE_LOCK

If a variable is locked, trying to set it will generate an error. It is possible to temporarily force the lock with this option. A warning is displayed when a lock is forced.
LOCK

Will lock the variable if set to 1, unlock if set to 0.

OVERRIDE

This allows the variable in a category to override the variable in a category with higher priority. Once a variable is overridden, it's value will always be the override value even if it is set again.

my $config = new Config::Hierarchical
			(
			NAME => 'Test config',
			
                        CATEGORY_NAMES         => ['PARENT', 'CURRENT'],
                        DEFAULT_CATEGORY       => 'CURRENT',
					
			INITIAL_VALUES  =>
				[
				{NAME => 'CC', CATEGORY => 'PARENT', VALUE => 'parent'},
				] ,
			) ;
			
$config->Set(NAME => 'CC', CATEGORY => 'CURRENT', OVERRIDE => 1, VALUE => 'current') ;
$config->Set(NAME => 'CC', CATEGORY => 'PARENT', VALUE => 'parent') ;

$config->Get(NAME => 'CC') ; # will return 'current'

SILENT_OVERRIDE

Disables the warning displayed when overriding a variable.
FILE and LINE

See FILE and LINE in new.
CHECK_LOWER_LEVEL_CATEGORIES

Config::Hierarchical display warnings about all the collisions with higher priority categories. If this option is set, warnings will also be displayed for lower priority categories.

History

Config::Hierarchical will keep a history of all the setting you make. The history can be retrieved with GetHistory. The history is also part of the dump generated by GetDump.

Using EVAL instead for VALUE

Quite often configuration variables values are base on other configuration variable values. A typical example would be a set of paths.

my $config = new Config::Hierarchical() ;

$config->Set(NAME => 'BASE',        VALUE => '/somewhere') ;
$config->Set(NAME => 'MODULE',      VALUE => 'module') ;
$config->Set(NAME => 'CONFIG_FILE', VALUE => 'my_config') ;

If you wanted to set a variable to the full path of your config file you have to write:

$config->Set
	(
	NAME => 'PATH_TO_CONFIG_FILE', 
	VALUE => $config->Get(NAME => 'BASE') . '/'
		 . $config->Get(NAME => 'MODULE') . '/'
		 . $config->Get(NAME => 'CONFIG_FILE'),
	) ;

If you have many variables that are based on other variables, you code get messy quite fast. With a little work, Config::Hierarchical let's you write code like this:

$config->Set(NAME => 'PATH_TO_CONFIG_FILE', EVAL => q~ "$BASE/$MODULE/$CONFIG_FILE" ~) ;

To achieve this, Config::Hierarchical let's you implement an "EVALUATOR", a subroutine responsible for handling EVAL. It is set during the call to new or Set. The subroutine is passed the following arguments:

$config - A reference to the Config::Hierarchical object
$arguments - A hash reference containing the arguments passed to Set

Below is an example using Eval::Context. See t/020_eval.t for a complete example.

  sub eval_engine
  {
  my ($config, $arguments) = @_ ;
  my $hash_ref = $config->GetHashRef() ;
  
  my $context = new Eval::Context
  		(
  		INSTALL_VARIABLES => 
  			[
  			map {["\$$_" => $hash_ref->{$_} ]} keys %$hash_ref
  			],
		INTERACTION  =>
			{
			EVAL_DIE => sub { my($self, $error) = @_ ; croak $error; },
			}
  		) ;
  
  my $value = eval {$context->eval(CODE => $arguments->{EVAL})} ;
  
  if($@)
  	{
  	$config->{INTERACTION}{DIE}->
  		(
  		"Error: Config::Hierarchical evaluating variable '$arguments->{NAME}' "
  		. "at $arguments->{FILE}:$arguments->{LINE}:\n\t". $@
  		) ;
  	}
  
  return $value ;
  }
  
  my $config = new Config::Hierarchical(EVALUATOR => \&eval_engine, ...) ;

EVAL can be used in Set and in INITIAL_VALUES.

[p] CheckSetArguments

Checks input to Set.

[p] CheckHigherPriorityCategories

Check if a config variable setting overrides a higher priority category.

[p] CheckVariableInCategory

[p] OverrideVariable

[p] CheckLowerPriorityCategories

Check if a config variable setting takes precedence over a lower priority category.

[p] CheckAndSetVariable

Set the variable in its category, verify lock, etc..

SetAttribute(NAME => $variable_name, ATTRIBUTE => $attribute, CATEGORY => $category)

This sub allows you to attach an attribute per variable (the attribute you set is per category) other than a value. It will raise an exception if you try to set a variable that does not exists or if you try to set an attribute to a variable in an aliased category.

$config->SetAttribute(NAME => 'CC', ATTRIBUTE => 'attribute') ;

# or directly in the 'Set' call

$config->Set(NAME => 'CC', VALUE => 'CC', ATTRIBUTE => 'attribute') ;

my ($attribute, $attribute_exists) = $config->GetAttribute(NAME => 'CC') ;

Arguments

NAME => $variable_name - The variable name
ATTRIBUTE => $attribute - A scalar attribute
CATEGORY => $category - Category in which you want to set the attribute.

Returns - Nothing

GetAttribute(NAME => $variable_name)

This sub returns the attribute as well as the existence of the attribute. If the attribute didn't exist, the value is set to undef. No warnings are displayed if you query the attribute of a variable that does not have an attribute.

A warning message is displayed if you call this sub in void or scalar context.

my ($attribute, $attribute_exists) = $config->GetAttribute(NAME => 'CC') ;

Arguments

NAME => $variable_name - The name of the variable you want to get the attribute for

Returns - a list

The attribute
A boolean. Set if the attribute existed

Exceptions - This sub will raise an exception if you query a variable that does not exists.

[p] Validate

Get(@named_arguments)

Returns the value associated with the variable passed as argument. If more than one category contains the variable, the variable from the category with the highest priority, which is not overridden, will be used.

If the variable doesn't exist in the container, a warning is displayed and undef is returned.

my $config = new Config::Hierarchical(INITIAL_VALUES => [{NAME => 'CC', VALUE => 'gcc'}]) ;

my $cc = $config->Get(NAME => 'CC') ;
my $ld = $config->Get(NAME => 'LD', SILENT_NOT_EXISTS => 1) ;

Arguments

SILENT_NOT_EXISTS

Setting this option will disable the warning generated when the variable doesn't exist in the container.
CATEGORIES_TO_EXTRACT_FROM

If set, Get will only search in the specified categories. A warning is displayed if the categories are not in the same order as passed to the constructor.
GET_CATEGORY

If this option is set, Get will return the value _and_ the category it it comes from.

Returns

If GET_CATEGORY is not set:

The variable's value

If GET_CATEGORY is set:

The variable's value
The category the value comes from

Warnings

This function verifies its calling context and will generate a warning if it is called in void context.

[p] CheckCategoriesOrder

SetMultiple(\%options, \@variable_to_set, \@variable_to_set, ...)

Set multiple configuration in one call.

  $config->SetMultiple
	(
	{FORCE_LOCK => 1},
	
	[NAME => 'CC', VALUE => 'gcc', SILENT_OVERRIDE => 1],
	[NAME => 'LD', VALUE => 'ld'],
	) ;

Arguments

\%options - An optional hash reference with options applied to each Set call
\@variable_to_set - An array reference containing the parameter for the Set call

Multiple \@variable_to_set can be passed.

Returns - Nothing

see Set.

GetMultiple(\%options, @variables_to_get)

Get multiple configuration in one call.

  my $config = new Config::Hierarchical(INITIAL_VALUES => [{NAME => 'CC', VALUE => 'gcc'}]) ;
  
  my @values = $config->GetMultiple('CC') ;
  
  my @other_values = $config->GetMultiple
			(
			{SILENT_NOT_EXISTS => 1},
			'CC',
			'AR'
			) ;

Arguments

\%options - An optional hash reference with options applied to each Get call
@variable_to_get - A list containing the names of the variables to get.

Option GET_CATEGORY will be ignored in this sub.

Returns - Nothing

see Get.

GetKeys()

my @keys = $config->GetKeys() ;

Returns the names of the element in the config object.

Arguments

Optional, CATEGORIES_TO_EXTRACT_FROM

if set, GetKeys will only search in the specified categories.

Returns

The list of variables contained in the Config::Hierarchical object.

Warnings

A warning will be generated if GetKeys is called in void context.

GetKeyValueTuples()

Returns a list of hash references containing the name and the value of each configuration variable contained in the object. This can be useful when you you create config objects from data in other objects.

my $config_1 = new Config::Hierarchical(.....) ;

my $config_2 = new Config::Hierarchical
				(
				NAME => 'config 2',
				
				CATEGORY_NAMES         => ['PARENT', 'CURRENT'],
				DEFAULT_CATEGORY       => 'CURRENT',
				
				INITIAL_VALUES =>
					[
					# Initializing a category from another config
					map
						({
							{
							NAME     => $_->{NAME},
							VALUE    => $_->{VALUE}, 
							CATEGORY => 'PARENT',
							LOCK     => 1,
							HISTORY  => $config_1->GetHistory(NAME => $_->{NAME}),
							}
						} $config_1->GetKeyValueTuples()),
					
					{NAME => 'CC', VALUE => 1,},
					]
				) ;

Argument

Optional, CATEGORIES_TO_EXTRACT_FROM

If set, GetKeyValueTuples will only search in the specified categories.

Returns

A list of hash references. Each hash has a NAME and VALUE key.

GetHashRef()

my $hash_ref = $config->GetHashRef() ;

Arguments - None

This function will generate an error if any argument is passed to it.

Returns - A hash reference containing a copy of all the elements in the container.

Warnings

GetHashRef will generate a warning if:

it is called in void context
it is called in array context

SetDisplayExplicitCategoryWarningOption($boolean)

$config->SetDisplayExplicitCategoryWarningOption(1) ;
$config->SetDisplayExplicitCategoryWarningOption(0) ;

Arguments

$boolean - controls if messages are displayed if an explicit category is used in Get or Set.

Return - Nothing

SetDisableSilentOptions($boolean)

$config->SetDisableSilentOptions(1) ;
$config->SetDisableSilentOptions(0) ;

Arguments

$boolean - controls if messages are displayed regardless of local warning disabling options

This is useful when debugging your configuration as it forces all the warning to be displayed.

Return - Nothing

LockCategories(@categories)

Locks the categories passed as argument. A variable in a locked category can not be set. An attempt to set a locked variable will generate an error. FORCE_LOCK has no effect on locked categories.

$config->LockCategories('PARENT', 'OTHER') ;

Arguments

@categories - a list of categories to lock

Returns - Nothing

Exceptions - An exception is generated if you try to lock a category that doesn't exist.

See UnlockCategories.

Lock(NAME => $variable_name, CATEGORY => $category)

Locks a variable in the default category or an explicit category. A locked variable can not be set.

To set a locked variable, FORCE_LOCK can be used. FORCE_LOCK usually pinpoints a problem in your configuration.

$config->Lock(NAME => 'CC') ;
$config->Lock(NAME => 'CC', CATEGORY => 'PARENT') ;

Arguments

NAME => $variable_name - Name of the variable to lock
CATEGORY => $category - Name of the category containing the variable

Returns - Nothing

Exceptions - An exception is generated if you try to lock a variable that doesn't exist.

See Set.

UnlockCategories(@categories)

Unlocks the categories passed as argument.

$config->UnlockCategories('PARENT', 'OTHER') ;

Arguments

@categories - a list of categories to unlock

Returns - Nothing

See LockCategories.

Unlock(NAME => $variable_name, CATEGORY => $category)

Unlocks a variable in the default category or an explicit category.

$config->Unlock(NAME => 'CC') ;
$config->Unlock(NAME => 'CC', CATEGORY => 'PARENT') ;

Arguments

NAME => $variable_name - Name of the variable to unlock
CATEGORY => $category - Name of the category containing the variable

Returns - Nothing

Exceptions - An exception is generated if you pass a category that doesn't exist.

See Lock.

IsCategoryLocked($category)

Query the lock state of a category.

$config->IsCategoryLocked('PARENT') ;

Arguments

$category - Name of the category containing to query

Returns - A boolean

Exceptions - Querying the lock state of a category that doesn't exist generates an exception.

IsLocked(NAME => $variable_name, CATEGORY => $category)

Query the lock state of a variable.

$config->IsLocked(NAME => 'CC') ;
$config->IsLocked(NAME => 'CC', CATEGORY => 'PARENT') ;

Arguments

NAME => $variable_name - Name of the variable to query
Optional, CATEGORY => $category - Name of the category containing the variable

Returns - A boolean

Exceptions - Querying the lock state of a variable that doesn't exist does not generate an exception.

Exists(NAME => $variable_name, CATEGORIES_TO_EXTRACT_FROM => \@categories)

$config->Exists(NAME => 'CC') ;

Returns true if the variable exist, false otherwise. All the categories are checked.

Arguments

NAME => $variable_name - Name of the variable to check
CATEGORIES_TO_EXTRACT_FROM => \@categories - list of category names

Returns - A boolean

Exceptions - An exception is generated if you pass a category that doesn't exist.

GetHistory(NAME => $variable_name, CATEGORIES_TO_EXTRACT_FROM => \@categories)

Returns a variable history.

$history = $config->GetHistory(NAME => 'CC') ;
$history = $config->GetHistory(NAME => 'CC', CATEGORIES_TO_EXTRACT_FROM => ['PARENT']) ;

Arguments

NAME => $variable_name - Name of the variable to check
CATEGORIES_TO_EXTRACT_FROM => \@categories - list of category names

Returns - Returns a reference to the variable's history or an empty list if the variable doesn't exist.

my $config = new Config::Hierarchical
				(
				NAME => 'Test config',
				
				CATEGORY_NAMES         => ['PARENT', 'CURRENT'],
				DEFAULT_CATEGORY       => 'CURRENT',
						
				INITIAL_VALUES  =>
					[
					{NAME => 'CC', CATEGORY => 'PARENT', VALUE => 'parent'},
					] ,
				) ;
				
$config->Set(NAME => 'CC', OVERRIDE => 1, VALUE => 'override value') ;

my($value, $category) = $config->Get(NAME => 'CC',  GET_CATEGORY => 1) ;

my $title = "'CC' = '$value' from category '$category':" ;
print DumpTree($config->GetHistory(NAME=> 'CC'), $title, DISPLAY_ADDRESS => 0) ;

Would print as:

'CC' = 'override value' from category 'CURRENT':
|- 0 
|  |- EVENT = . CREATE AND SET. value = 'parent', category = 'PARENT' at 'nadim2.pl:21', status = OK. 
|  `- TIME = 0 
`- 1 
   |- EVENT = value = CREATE AND SET, OVERRIDE. 'override value', category = 'CURRENT' at 'nadim2.pl:34', status =
   |  Overriding 'PARENT::CC' (existed, value was different).OK. 
   `- TIME = 1

while

my($value, $category) = $config->Get(NAME => 'CC', GET_CATEGORY => 1, CATEGORIES_TO_EXTRACT_FROM => ['PARENT']) ;

my $title = "'CC' = '$value' from category '$category':" ;
print DumpTree($config->GetHistory(NAME=> 'CC', CATEGORIES_TO_EXTRACT_FROM => ['PARENT']), $title, DISPLAY_ADDRESS => 0) ;

Would print as:

'CC' = 'parent' from category 'PARENT':
`- 0 
   |- EVENT = value = CREATE AND SET. 'parent', category = 'PARENT' at 'nadim2.pl:21', status = OK. 
   `- TIME = 0

Explicit history and comments

If you passed a HISTORY or a COMMENT when you created or modified a variable, that information will be included in the history structure returned by GetHistory.

my $config3 = new Config::Hierarchical
				(
				NAME => 'config3',
				...
				INITIAL_VALUES  =>
					[
					{
					COMMENT => "history and value from category 2",	
					NAME => 'CC', CATEGORY => 'PARENT', VALUE => $value2,
					HISTORY => $history2,
					},
					] ,
				...
				) ;
				
my($value3, $category3) = $config3->Get(NAME => 'CC',  GET_CATEGORY => 1) ;
my $title3 = "'CC' = '$value3' from category '$category3':" ;
my $history3 = $config3->GetHistory(NAME=> 'CC') ;
print DumpTree($history3, $title3, DISPLAY_ADDRESS => 0) ;

Would print as:

'CC' = '3' from category 'PARENT':
|- 0
|  |- COMMENT = history and value from config 2
|  |- EVENT = CREATE, SET HISTORY AND SET. value = '3', category = 'PARENT' at 'history.pl:56', status = OK.
|  |- HISTORY
|  |  |- 0
...

Aliased category history

if you used an aliased category, The history structure returned by GetHistory will automatically include the history of the aliased config.

my $config0 = (...) ;
my $config1 = (...) ;
my $config2 = new Config::Hierarchical
				(
				...
				INITIAL_VALUES =>
					[
					{
					CATEGORY       => 'PBS',
					ALIAS_CATEGORY => $config1,
					HISTORY        => ....,
					COMMENT        => ....,
					},
				...
				) ;
				
...
print DumpTree $config_3->GetHistory( NAME => 'CC1'), 'CC1', DISPLAY_ADDRESS => 0;

Would print as:

CC1
|- 0
|  |- HISTORY FROM ALIASED CATEGORY 'config 1'
|  |  |- 0
|  |  |  |- HISTORY FROM ALIASED CATEGORY 'config 0'
|  |  |  |  `- 0
|  |  |  |     |- EVENT = CREATE AND SET. value = '1', category = 'CURRENT' at 'nadim.pl:21', status = OK.
|  |  |  |     `- TIME = 0
|  |  |  `- TIME = 2
|  |  |- 1
|  |  |  |- EVENT = CREATE AND SET. value = '1', category = 'A' at 'nadim.pl:33', status = OK.
|  |  |  `- TIME = 3
|  |  `- 2
|  |     |- EVENT = Set. value = '1.1', category = 'A' at 'nadim.pl:50', status = OK.
|  |     `- TIME = 6
|  `- TIME = 3
|- 1
|  |- EVENT = CREATE AND SET, OVERRIDE. value = 'A', category = 'A' at 'nadim.pl:64', status = OK.
|  `- TIME = 4
`- 2
   |- EVENT = SET, OVERRIDE. value = 'A2', category = 'A' at 'nadim.pl:65', status = OK.
   `- TIME = 5

Compact display

Given the following Data::TreeDumper filter

sub Compact
{
my ($s, $level, $path, $keys, $setup, $arg) = @_ ;

if('ARRAY' eq ref $s)
	{
	my ($index, @replacement, @keys) = (0) ;
	
	for my $entry( @$s)
		{
		if(exists $entry->{EVENT})
			{
			push @replacement, $entry->{EVENT} ; #. 'time: ' . $entry->{TIME};
			push@keys, $index++ ;
			}
		else
			{
			my ($aliased_history_name) = grep {$_ ne 'TIME'} keys %$entry ;
			
			push @replacement, $entry->{$aliased_history_name} ;
			push@keys, [$index, "$index = $aliased_history_name"] ;
			$index++ ;
			}
		}
	
	return('ARRAY', \@replacement, @keys) ;
	}
}

print DumpTree $config_2->GetHistory( NAME => 'CC1'), 'CC1', DISPLAY_ADDRESS => 0, FILTER => \&Compact ;

the above output becomes:

CC1
|- 0 = HISTORY FROM ALIASED CATEGORY 'config 1'
|  |- 0 = HISTORY FROM ALIASED CATEGORY 'config 0'
|  |  `- 0 = CREATE AND SET. value = '1', category = 'CURRENT' at 'nadim.pl:21', status = OK.
|  |- 1 = CREATE AND SET. value =  '1', category = 'A' at 'nadim.pl:33', status = OK.
|  `- 2 = SET. value = '1.1', category = 'A' at 'nadim.pl:50', status = OK.
|- 1 = CREATE AND SET, OVERRIDE. value = 'A', category = 'A' at 'nadim.pl:64', status = OK.
`- 2 = SET, OVERRIDE. value = 'A2', category = 'A' at 'nadim.pl:65', status = OK.

Note that comments are also removed.

[p] GetVariableHistory

This shall not be used directly. Use GetHistory.

GetHistoryDump(@named_arguments)

Returns a dump, of the variable history, generated by Data::TreeDumper::DumpTree.

$dump = $config->GetHistoryDump(NAME => 'CC') ;

$dump = $config->GetHistoryDump(CATEGORIES_TO_EXTRACT_FROM => ['A', 'B'], NAME => 'CC', DATA_TREEDUMPER_OPTIONS => []) ;

Arguments

NAME => $variable_name - Name of the variable to check
Optional, CATEGORIES_TO_EXTRACT_FROM => \@categories - list of category names

Returns - Returns a reference to the variable's history or an empty list if the variable doesn't exist.

See Data::TreeDumper.

GetAccessLog()

Returns a list of all the Config::Hierarchical accesses.

my $config = new Config::Hierarchical( LOG_ACCESS => 1, ...) ;

my $value = $config->Get(NAME => 'A') ;
$value    = $config->Get(NAME => 'B') ;
$value    = $config->Get(NAME => 'A', CATEGORIES_TO_EXTRACT_FROM => ['PARENT']) ;

my $access_log = $config->GetAccessLog() ;

would return the following structure :

access log:
|- 0 
|  |- FILE = test.pl 
|  |- LINE = 28 
|  `- NAME = A 
|- 1 
|  |- FILE = test.pl 
|  |- LINE = 29 
|  `- NAME = B 
`- 2 
   |- CATEGORIES_TO_EXTRACT_FROM 
   |  `- 0 = PARENT 
   |- FILE = test.pl 
   |- LINE = 30 
   `- NAME = A

Arguments - None

Returns - An array reference containing all the read accesses.

If LOG_ACCESS was not set, an empty array reference is returned.

GetDump()

$dump = $config->GetDump(@data_treedumper_options) ;
$dump = $config->GetDump(@data_treedumper_options) ;

Arguments

@data_treedumper_options - A list of options forwarded to Data::TreeDumper::DumpTree.

Returns

A dump, of the Config::Hierarchical object, generated by Data::TreeDumper::DumpTree.

See Data::TreeDumper.

BUGS AND LIMITATIONS

None so far.

AUTHOR

Khemir Nadim ibn Hamouda
CPAN ID: NKH
mailto:nadim@khemir.net

LICENSE AND COPYRIGHT

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

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc Config::Hierarchical

You can also look for information at:

AnnoCPAN: Annotated CPAN documentation

http://annocpan.org/dist/Config-Hierarchical
RT: CPAN's request tracker

Please report any bugs or feature requests to L <bug-config-hierarchical@rt.cpan.org>.

We will be notified, and then you'll automatically be notified of progress on your bug as we make changes.
Search CPAN

http://search.cpan.org/dist/Config-Hierarchical

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

SYNOPSIS

DESCRIPTION

DOCUMENTATION

SUBROUTINES/METHODS

new(@named_arguments)

GetInformation()

[p] Setup

[p] SetInteractionDefault

[p] SetupCategories

AddValidator(CATEGORY_NAMES => \@categories, NAMES => \@names, VALIDATORS => \%validators)

[p] AddValidators

[p] AddVariableValidator

[p] SetCategoryAlias

[p] CreateCustomGetFunctions

[p] CheckOptionNames

Set(@named_arguments)

History

Using EVAL instead for VALUE

[p] CheckSetArguments

[p] CheckHigherPriorityCategories

[p] CheckVariableInCategory

[p] OverrideVariable

[p] CheckLowerPriorityCategories

[p] CheckAndSetVariable

SetAttribute(NAME => $variable_name, ATTRIBUTE => $attribute, CATEGORY => $category)

GetAttribute(NAME => $variable_name)

[p] Validate

Get(@named_arguments)

[p] CheckCategoriesOrder

SetMultiple(\%options, \@variable_to_set, \@variable_to_set, ...)

GetMultiple(\%options, @variables_to_get)

GetKeys()

GetKeyValueTuples()

GetHashRef()

SetDisplayExplicitCategoryWarningOption($boolean)

SetDisableSilentOptions($boolean)

LockCategories(@categories)

Lock(NAME => $variable_name, CATEGORY => $category)

UnlockCategories(@categories)

Unlock(NAME => $variable_name, CATEGORY => $category)

IsCategoryLocked($category)

IsLocked(NAME => $variable_name, CATEGORY => $category)

Exists(NAME => $variable_name, CATEGORIES_TO_EXTRACT_FROM => \@categories)

GetHistory(NAME => $variable_name, CATEGORIES_TO_EXTRACT_FROM => \@categories)

Explicit history and comments

Aliased category history

Compact display

[p] GetVariableHistory

GetHistoryDump(@named_arguments)

GetAccessLog()

GetDump()

BUGS AND LIMITATIONS

AUTHOR

LICENSE AND COPYRIGHT

SUPPORT

SEE ALSO

Module Install Instructions