Config::Model - Framework to create configuration validation tools and editors
# create new Model object my $model = Config::Model->new() ; # create config model $model ->create_config_class ( name => "SomeRootClass", element => [ ... ] ) ; # create instance my $instance = $model->instance (root_class_name => 'SomeRootClass', instance_name => 'test1'); # get configuration tree root my $cfg_root = $instance -> config_root ; # You can also use load on demand my $model = Config::Model->new() ; # this call will look for a AnotherClass.pl that will contain # the model my $inst2 = $model->instance (root_class_name => 'AnotherClass', instance_name => 'test2'); # then get configuration tree root my $cfg_root = $inst2 -> config_root ;
Using Config::Model, a typical configuration validation tool will be made of 3 parts :
The user interface
The validation engine which is in charge of validating all the configuration information provided by the user.
The storage facility that store the configuration information
Config::Model provides a validation engine according to a set of rules.
Config::Model
The user interface will use some parts of the API to set and get configuration values. More importantly, a generic user interface will need to explore the configuration model to be able to generate at run-time relevant configuration screens.
A generic Curses interface is under development. More on this later.
One can also consider to use Webmin (http://www.webmin.com) on top of config model.
The storage will often be a way to store configuration in usual configuration files, like /etc/X11/xorg.conf
/etc/X11/xorg.conf
One can also consider storing configuration data in a database, ldap directory or using elektra project http://www.libelektra.org/
Config::Model provides a way to get a validation engine from a set of rules. This set of rules is now called the configuration model.
Before talking about a configuration tree, we must create a configuration model that will set all the properties of the validation engine you want to create.
Simply call new without parameters:
my $model = Config::Model -> new ;
This will create an empty shell for your model.
The configuration model is expressed in a declarative form (i.e. a Perl data structure which is always easier to maintain than a lot of code.)
Each node of the configuration tree is attached to a configuration class whose properties you must declare by calling "create_config_class".
Each configuration class contains mostly 2 types of elements:
A node type element that will refer to another configuration class
A value element that will contains actual configuration data
By declaring a set of configuration classes and refering them in node element, you will shape the structure of your configuration tree.
The structure of the configuration data must be based on a tree structure. This structure has several advantages:
Unique path to get to a node or a leaf.
Simpler exploration and query
Simple hierarchy. Deletion of configuration items is simpler to grasp: when you cut a branch, all the leaves attaches to that branch go down.
But using a tree has also some drawbacks:
A complex configuration cannot be mapped on a simple tree. Some more relation between nodes and leaves must be added.
Some configuration part are actually graph instead of a tree (for instance, any configuration that will map a service to a resource). The graph relation must be decomposed in a tree with special reference relation. See "Value Reference" in Config::Model::Value
Note: a configuration tree is a tree of objects. The model is declared with classes. The classes themselves have relations that closely match the relation of the object of the configuration tree. But the class need not to be declared in a tree structure (always better to reuse classes). But they must be declared as a DAG (directed acyclic graph).
Each configuration class declaration specifies:
Most importantly, the type of the element (mostly leaf, or node)
leaf
node
The properties of each element (boundaries, check, integer or string, enum like type ...)
The default values of parameters (if any)
Mandatory parameters
Targeted audience (beginner, advance, master)
On-line help (for each parameter or value of parameter)
The level of expertise of each parameter (to hide expert parameters from newbie eyes)
See Config::Model::Node for details on how to declare a configuration class.
A configuration instance if the staring point of a configuration tree. When creating a model instance, you must specify the root class name, I.e. the configuration class that is used by the root node of the tree.
my $model = Config::Model->new() ; $model ->create_config_class ( name => "SomeRootClass", element => [ ... ] ) ; my $inst = $model->instance (root_class_name => 'SomeRootClass', instance_name => 'test1');
You can create several separated instances from a model.
When using autoread or autowrite feature
A configuration class is made of series of elements which are detailed in Config::Model::Node.
Whatever its type (node, leaf,... ), each element of a node has several other properties:
By using the experience parameter, you can change the experience level of each element. Possible experience levels are master, advanced and beginner (default).
experience
master
advanced
beginner
Level is important, normal or hidden.
important
normal
hidden
The level is used to set how configuration data is presented to the user in browsing mode. Important elements will be shown to the user no matter what. hidden elements will be explained with the warp notion.
Important
Status is obsolete, deprecated or standard (default).
obsolete
deprecated
standard
Using a deprecated element will issue a warning. Using an obsolete element will raise an exception.
Description of the element. This description will be used when generating user interfaces.
Description of the configuration class. This description will be used when generating user interfaces.
Mention with a descriptive string if this class was generated by a program. This parameter is currently reserved for Config::Model::Itself model editor.
Include element description from another class.
include => 'AnotherClass' ,
or
include => [qw/ClassOne ClassTwo/]
In a configuration class, the order of the element is important. For instance if foo is warped by bar, you must declare bar element before foo.
foo
bar
When including another class, you may wish to insert the included elements after a specific element of your including class:
# say AnotherClass contains element xyz include => 'AnotherClass' , include_after => "foo" , element => [ bar => ... , foo => ... , baz => ... ]
Now the element of your class will be:
( bar , foo , xyz , baz )
Example:
my $model = Config::Model -> new ; $model->create_config_class ( config_class_name => 'SomeRootClass', experience => [ [ qw/tree_macro warp/ ] => 'advanced'] , description => [ X => 'X-ray' ], level => [ 'tree_macro' => 'important' ] , class_description => "SomeRootClass description", element => [ ... ] ) ;
Again, see Config::Model::Node for more details on configuration class declaration.
For convenience, experience, level and description parameters can also be declared within the element declaration:
level
description
$model->create_config_class ( config_class_name => 'SomeRootClass', class_description => "SomeRootClass description", 'element' => [ tree_macro => { level => 'important', experience => 'advanced', }, warp => { experience => 'advanced', } , X => { description => 'X-ray', } , ] ) ;
You can also load pre-declared model.
This method will open the model directory and execute a .pl file containing the model declaration,
.pl
This perl file must return an array ref to declare models. E.g.:
[ [ name => 'Class_1', element => [ ... ] ], [ name => 'Class_2', element => [ ... ] ] ];
do not put 1; at the end or load will not work
1;
load
If a model name contain a :: (e.g Foo::Bar), load will look for a file named Foo/Bar.pl.
::
Foo::Bar
Foo/Bar.pl
Returns a list containining the names of the loaded classes. For instance, if Foo/Bar.pl contains a model for Foo::Bar and Foo::Bar2, load will return ( 'Foo::Bar' , 'Foo::Bar2' ).
Foo::Bar2
( 'Foo::Bar' , 'Foo::Bar2' )
Return a hash containing the model declaration.
Get all names of the elements of class Foo that are accessible for experience level advanced.
Foo
Level can be master (default), advanced or beginner.
Returns a string listing all the class and elements. Useful for debugging your configuration model.
Errors are handled with an exception mechanism (See Exception::Class).
When a strongly typed Value object gets an authorized value, it raises an exception. If this exception is not catched, the programs exits.
See Config::Model::Exception for details on the various exception classes provided with Config::Model.
Currently a rather lame trace mechanism is provided:
Set $::debug to 1 to get debug messages on STDOUT.
$::debug
Set $::verbose to 1 to get verbose messages on STDOUT.
$::verbose
Depending on available time, a better log/error system may be implemented.
Dominique Dumont, (ddumont at cpan dot org)
Copyright (c) 2005-2008 Dominique Dumont. This file is part of Config-Model. Config-Model is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version. Config-Model is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser Public License for more details. You should have received a copy of the GNU Lesser Public License along with Config-Model; if not, write to the Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
Config::Model::Instance,
The arrow shows the inheritance of the classes
Config::Model::Node <- Config::Model::AutoRead <- Config::Model::AnyThing
Config::Model::HashId <- Config::Model::AnyId <- Config::Model::WarpedThing <- Config::Model::AnyThing
Config::Model::ListId <- Config::Model::AnyId <- Config::Model::WarpedThing <- Config::Model::AnyThing
Config::Model::Value <- Config::Model::WarpedThing <- Config::Model::AnyThing
Config::Model::CheckList <- Config::Model::WarpedThing <- Config::Model::AnyThing
Config::Model::WarpedNode <- <- Config::Model::WarpedThing <- Config::Model::AnyThing
Config::Model::Describe, Config::Model::Dumper, Config::Model::Loader, Config::Model::ObjTreeScanner, Config::Model::Report, Config::Model::Searcher, Config::Model::TermUI, Config::Model::WizardHelper, Config::Model::AutoRead, Config::Model::ValueComputer,
To install Config::Model, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Config::Model
CPAN shell
perl -MCPAN -e shell install Config::Model
For more information on module installation, please visit the detailed CPAN module installation guide.