Config::Hierarchical cookbook

Simple usage

Creating a Config::Hierarchical configuration container

This will create a container with default values. You can modify the container behavior by passing options to the constructor. See the Config::Hierarchical manual for all initialization options.

Setting and getting configuration variables

Would display:

Set the same variable multiple time with different values

Would display:

Config::Hierarchical does not generate any warning when you override a variable's value. If you would like to get an error, lock the variable.

Locking variables

$config->Set(NAME => 'CC', VALUE => 'gcc') ;
$config->Lock(NAME => 'CC') ;
$config->Set(NAME => 'CC', VALUE => 'cl') ;

This would generate the following error followed by a stack trace.

Setting Locked variables

Would display:

Getting the lock state

print "'CC' is locked.\n" if $config->IsLocked(NAME => 'CC') ;
print "'LD' is locked.\n" if $config->IsLocked(NAME => 'LD') ;

Would display:

Setting variable in the constructor

Getting a non existing variable value

Would display:

Getting multiple variable values

Would display:

history and comments

Config::Hierarchical will keep an history for each variable in you config.

The reference manual describes a Data::TreeDumper filter that you can use to generate a history in the following format:

You can also add a comment to the history when you manipulate variables.

Would give this history:

See GetHistory in the manual if you want to handle the history data directly.

Validators

You can assign validators to variables. If a validator return false, Config::Hierarchical will generate and error.

Validators can be defined in the Config::Hierarchical constructor or can be local in a Set call.

$config->Set
	(
	NAME => 'CC',
	VALUE => -1, 
	VALIDATORS => {positive_value => \&PositiveValueValidator,},
	) ;	

Will generate the following error:

GetKeys

You can get a list of all the variable names.

Would display:

Key and value tuples

You can also get a list containing a tuple for each of the config variable. The Tuple is a hash reference. This lets you write code like :

map
	{
	my $name =  $_->{NAME} ;
	my $value = $_->{VALUE} ;
	
	# your code here
	
	} $config->GetKeyValueTuples() ;

Categories

my $config = new Config::Hierarchical
			(
			NAME => 'config with categories',
			
			CATEGORY_NAMES   => ['A', 'B'],
			DEFAULT_CATEGORY => 'B',
			
			INITIAL_VALUES  =>
				[
				{CATEGORY => 'A', NAME => 'CC', VALUE => 'A_CC'},
				{CATEGORY => 'B', NAME => 'CC', VALUE => 'B_CC'},
				{CATEGORY => 'A', NAME => 'LD', VALUE => 'A_LD'},
				{CATEGORY => 'B', NAME => 'LD', VALUE => 'B_LD'},
				{CATEGORY => 'A', NAME => 'AS', VALUE => 'A_AS'},
				] ,
			) ;

Would generate the following warnings:

And the config would be:

Config::Hierarchical will display a warning anytime you set a variable and that a higher level configuration takes precedence.

Lower categories warning

By default, no warning are displayed when a lower category value will be ignored. You can make Config::Hierarchical check lower categories this way:

Would generate the following warnings:

The config is now:

Overriding a higher level category

Is done this way:

And would generate the following warnings:

The config is now:

History from multiple categories

Tie::Readonly

You can tie your configuration to a read only hash. this lets you manipulate your config like a normal hash. Interpolation in strings is also much easier.

Would display:

Remember that the hash is read only. Trying to modify a variable is not allowed:

$hash{CC} = 2 ;

Would generate this error:

Copying data from another config

Use the code below to initialized a category from data copied from another category:

And the config would be:

Aliasing other configurations

Would generate this warning:

And the config would be:

History from aliased configuration

Config::Hierarchical will, display aliased categories history.

cpanm Config::Hierarchical

perl -MCPAN -e shell
install Config::Hierarchical