NAME

Config::Hierarchical - Hierarchical configuration container

SYNOPSIS

  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',
				
			GET_CATEGORIES         => 
				{
				Inheritable => ['CLI', 'PBS', 'PARENT', 'CURRENT'],
				},
				
			INTERACTION            =>
				{
				INFO  => \&sub,
				WARN  => \&sub,
				DIE   => \&sub,
				DEBUG => \&sub,
				},
				
			INITIAL_VALUES         =>
				[
				[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,],
				} ,
			) ;
	
  $config->Set(NAME => 'CC', VALUE => 'gcc') ;
  $config->Set(NAME => 'CC', VALUE => 'gcc', CATEGORY => 'CLI') ;
  $config->Set(NAME => 'CC', VALUE => 'gcc', IGNORE_LOCK => 1) ;
  $config->Set(NAME => 'CC', VALUE => 'gcc', LOCK => 1) ;
  $config->Set(NAME => 'CC', VALUE => 'gcc', SILENT_OVERRIDE => 1) ;
  
  $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->GetInheritedConfigs() ;
  
  $config->SetDisableSilentOptions(1) ;
	
  $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 constant.

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.

SUBROUTINES/METHODS

new

Create a Config::Hierarchical .

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

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

Options

The options are named, 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, e.g. <PBS>. Protected categories will not be overridden by lesser priority categories even if the OVERRIDE option is used.

If no category names are given, a default name 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.
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 a warning will be displayed.

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
			(
			GET_CATEGORIES =>
				{
				CATEGORY_NAMES   => ['CLI', '<PBS>', 'PARENT', 'LOCAL', 'CURRENT'],	
				}
			Inheritable => ['CLI', '<PBS>', 'PARENT', 'CURRENT'],
			...
			) ;
			
  my $value = $config->GetInheritable(NAME => 'CC') ;
  my $hash_ref = $config->GetInheritableHashRef() ;

In the example above, the LOCAL variables will not be returned by GetInherited.

VERBOSE

This module will display information about its actions when this option is set. See INTERACTION.
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 => 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
			(
			...
			INITIAL_VALUES =>
				[
				[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,],
				} ,
			) ;

Setup

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

CreateCustomGetFunctions

Creates custom Get* functions. This shall not be used directly.

CheckOptionNames

Verifies the options passed to the members of this class. Calls {INTERACTION}{DIE} in case of error. This shall not be used directly.

Set

  my $config = new Config::Hierarchical() ;
  
  $config->Set(NAME => 'CC', VALUE => 'gcc') ;
  
  $config->Set
		(
		NAME => 'CC', VALUE => 'gcc',
		
		# options
		CATEGORY        => 'CLI',
		IGNORE_LOCK     => 1,
		LOCK            => 1,
		OVERRIDE        => 1,
		SILENT_OVERRIDE => 1,
		FILE            => 'some_file',
		LINE            => 1
		) ;

NAME and VALUE must be passed as arguments.

Options

CATEGORY

The name of the category where the variable resides. If no CATEGORY is given, the default category is used.
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.
SILENT_OVERRIDE

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

See FILE and LINE in new.

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.

CheckHigherPriorityCategories

Check if a config variable setting overrides a higher priority category. This shall not be used directly.

CheckAndSetVariable

Set the variable in its category, verify lock, etc.. This shall not be used directly.

Get

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

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.

This function verifies its calling context and will generate a warning if it is called in void or array context. Use GetMultiple in an array context.

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

Options

SILENT_NOT_EXISTS

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

SetMultiple

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

If the first argument is a hash reference, the elements of the hash will be used for each element to set.

see Set.

GetMultiple

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

If the first argument is a hash reference, the elements of the hash will be used for each element to set.

see Get.

GetHashRef

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

Returns a hash reference containing all the elements in the container. The elements value are extracted with the rules used in Get.

This function will generate an error if:

any argument is passed to it
it is called in void context
it is called in array context

SetDisableSilentOptions

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

When set, warning messages will be displayed regardless of local warning disabling options, i.e. SILENT_OVERRIDE and SILENT_NOT_EXIST.

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

Lock

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

Locks a variable in the default category or an explicit category. A locked variable can not be set. An attempt to set a locked variable will generate an error. To set a locked variable, FORCE_LOCK can be used. FORCE_LOCK usually pinpoints a problem in your configuration.

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

See Set.

Unlock

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

See Lock.

IsLocked

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

Query the lock state of a variable. Querying the lock state of a variable that doesn't exist does not generate an error.

Exists

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

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

GetHistory

$history = $config->GetHistory(NAME => 'CC') ;
$history = $config->GetHistory(NAME => 'CC', CATEGORY => 'CLI') ;

Returns a reference to the variable's history if any. Returns an error string if no history is found.

GetDump

$dump = $config->GetDump() ;
$dump = $config->GetDump(DATA_TREEDUMPER_OPTIONS) ;

Returns a dump generated by Data::TreeDumper::DumpTree. The arguments are forwarded to the dumper.

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

Options

Setup

CreateCustomGetFunctions

CheckOptionNames

Set

Options

History

CheckHigherPriorityCategories

CheckAndSetVariable

Get

Options

SetMultiple

GetMultiple

GetHashRef

SetDisableSilentOptions

Lock

Unlock

IsLocked

Exists

GetHistory

GetDump

BUGS AND LIMITATIONS

AUTHOR

LICENSE AND COPYRIGHT

SUPPORT

SEE ALSO

Module Install Instructions