Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Config::Model(3)      User Contributed Perl Documentation     Config::Model(3)

NAME
       Config::Model - Create tools to validate, migrate and edit
       configuration files

VERSION
       version 2.105

SYNOPSIS
   Perl	program	to use an existing model
	use Config::Model qw(cme);
	# load,	modify and save	popcon configuration file
	cme('popcon')->modify("PARTICIPATE=yes");

   Command line	to use an existing model
	# with App::Cme
	cme modify popcon 'PARTICIPATE=yes'

   Perl	program	with a custom model
	use Config::Model;

	# create new Model object
	my $model = Config::Model->new() ; # Config::Model object

	# create config	model. A more complex model should be stored in	a
	# file in lib/Config/Model/models. Then, run cme as explained below
	$model ->create_config_class (
	  name => "MiniModel",
	  element => [ [qw/foo bar baz/	] => { type => 'leaf', value_type => 'uniline' }, ],
	  read_config => { backend => 'IniFile', auto_create =>	1,
			   config_dir => '.', file => 'mini.ini',
			 }
	) ;

	# create instance (Config::Model::Instance object)
	my $instance = $model->instance	(root_class_name => 'MiniModel');

	# get configuration tree root
	my $cfg_root = $instance -> config_root	; # C::M:Node object

	# load some dummy data
	$cfg_root -> load("bar=BARV foo=FOOV baz=BAZV")	;

	# write	new ini	file
	$instance -> write_back;

	# now look for new mini.ini file un current directory

   Create a new	model file and use it
	$ mkdir	-p lib/Config/Model/models/
	$ echo "[ { name => 'MiniModel', \
		    element => [ [qw/foo bar baz/ ] => { type => 'leaf', value_type => 'uniline' }, ], \
		    read_config	=> { backend =>	'IniFile', auto_create => 1, \
				     config_dir	=> '.',	file =>	'mini.ini', \
				   } \
		  } \
		] ; " >	lib/Config/Model/models/MiniModel.pl
	# require App::Cme
	$ cme modify -try MiniModel -dev bar=BARV foo=FOOV baz=BAZV
	$ cat mini.ini

       Note that model creation	is easier running "cme meta edit" with
       App::Cme	and Config::Model::Itself.

DESCRIPTION
       Config::Model enables a project developer to provide an interactive
       configuration editor (graphical,	curses based or	plain terminal)	to
       users.

       To provide these	tools, Config::Model needs:

       o   A description of the	structure and constraints of the project's
	   configuration (fear not, a GUI is available with App::Cme)

       o   A module to read and	write configuration data. This can be one of
	   the read/write backends provided by Config::Model or	a custom
	   backend.

       With the	elements above,	Config::Model generates	interactive
       configuration editors (with integrated help and data validation).
       These editors can be graphical (with Config::Model::TkUI), curses based
       (with Config::Model::CursesUI) or based on ReadLine.

       Smaller models targeted for configuration upgrades can also be created:

       o   only	upgrade	and migration specifications are required

       o   unknown parameters can be accepted

       A command line is provided to perform configuration upgrade with	a
       single command.

   How does this work ?
       Using this project, a typical configuration editor/validator/upgrader
       is made of 3 parts :

	 GUI <-------->	|---------------|
	 CursesUI <--->	| |---------|	|
			| | Model   |	|
	 ShellUI <---->	| |---------|	|<-----read-backend------- |-------------|
			|		|----write-backend-------> | config file |
	 FuseUI	<----->	| Config::Model	|			   |-------------|
			|---------------|

       1.  A reader and	writer that parse the configuration file and transform
	   its data into a tree	representation within Config::Model. The
	   values contained in this configuration tree can be written back in
	   the configuration file(s).

       2.  A validation	engine which is	in charge of validating	the content
	   and structure of configuration stored in the	configuration tree.
	   This	validation engine follows the structure	and constraint
	   declared in a configuration model. This model is a kind of schema
	   for the configuration tree.

       3.  A user interface to modify the content of the configuration tree. A
	   modification	is validated immediately by the	validation engine.

       The important part is the configuration model used by the validation
       engine. This model can be created or modified with a graphical editor
       (Config::Model::Iself).

Question you may ask yourself
   Don't we already have some configuration validation tools ?
       You're probably thinking	of tools like webmin. Yes, these tools exist
       and work	fine, but they have their set of drawbacks.

       Usually,	the validation of configuration	data is	done with a script
       which performs semantic validation and often ends up being quite
       complex (e.g. 2500 lines	for Debian's xserver-xorg.config script	which
       handles "xorg.conf" file).

       In most cases, the configuration	model is expressed in instructions
       (whatever programming language is used) and interspersed	with a lot of
       processing to handle the	actual configuration data.

   What's the advantage	of this	project	?
       Config::Model projects provide a	way to get a validation	engine where
       the configuration model is completely separated from the	actual
       processing instructions.

       A configuration model can be created and	modified with the graphical
       interface provide by Config::Model::Itself. The model is	saved in a
       declarative form	(currently, a Perl data	structure). Such a model is
       easier to maintain than a lot of	code.

       The model specifies:

       o   The structure of the	configuration data (which can be queried by
	   generic user	interfaces)

       o   The properties of each element (boundaries check, integer or
	   string, enum	like type, default value ...)

       o   The targeted	audience (beginner, advanced, master)

       o   The on-line help

       So, in the end:

       o   Maintenance and evolution of	the configuration content is easier

       o   User	sees a *common*	interface for *all* programs using this
	   project.

       o   Upgrade of configuration data is easier and sanity check is
	   performed during the	upgrade.

       o   Audit of configuration is possible to check what was	modified by
	   the user compared to	default	values

   What	about the user interface ?
       Config::Model interface can be:

       o   a shell-like	interface (plain or based on Term::ReadLine).

       o   Graphical with Config::Model::TkUI (Perl/Tk interface).

       o   based on curses with	Config::Model::CursesUI. This interface	can be
	   handy if your X server is down.

       o   Through a virtual file system where every configuration parameter
	   is mapped to	a file.	 (Linux	only)

       All these interfaces are	generated from the configuration model.

       And configuration model can be created or modified with a graphical
       user interface (with "cme meta edit" once Config::Model::Itself is
       installed)

   What	about configuration data storage ?
       Since the syntax	of configuration files vary wildly form	one
       application to another, people who want to use this framework may have
       to provide a dedicated parser/writer.

       To help with this task, this project provides writer/parsers for	common
       format: INI style file and perl file. With the additional
       Config::Model::Backend::Augeas, Augeas library can be used to read and
       write some configuration	files. See http://augeas.net for more details.

   Is there an example of a configuration model	?
       The "example" directory contains	a configuration	model example for
       "/etc/fstab" file. This example includes	a small	program	that use this
       model to	show some ways to extract configuration	information.

Mailing	lists
       For more	question, please send a	mail to:

	config-model-users at lists.sourceforge.net

Suggested reads	to start
   Beginners
       o   Config::Model::Manual::ModelCreationIntroduction

       o   Config::Model::Cookbook::CreateModelFromDoc

   Advanced
       o   Config::Model::models::Itself::Class: This doc and its siblings
	   describes all parameters available to create	a model. These are the
	   parameters available	in the GUI launched by "cme meta edit"
	   command.

       o   Config::Model::Manual::ModelCreationAdvanced

   Masters
       use the source, Luke

STOP
       The documentation below is quite	detailed and is	more a reference doc
       regarding "Config::Model" class.

       For an introduction to model creation, please check:
       Config::Model::Manual::ModelCreationIntroduction

Storage	backend, configuration reader and writer
       See Config::Model::BackendMgr for details

Validation engine
       "Config::Model" provides	a way to get a validation engine from a	set of
       rules. This set of rules	is called the configuration model.

User interface
       The user	interface uses some parts of the API to	set and	get
       configuration values. More importantly, a generic user interface	needs
       to analyze the configuration model to be	able to	generate at run-time
       relevant	configuration screens.

       A command line interface	is provided in this module. Curses and Tk
       interfaces are provided by Config::Model::CursesUI and
       Config::Model::TkUI.

Constructor
	my $model = Config::Model -> new ;

       creates an object to host your model.

   Constructor parameters
       log_level
	   Specify minimal log level. Default is "WARN". Can be	"INFO",
	   "DEBUG" or "TRACE" to get more logs.	Can also be "ERROR" to get
	   less	traces.

	   This	parameter is used to override the log level specified in log
	   configuration file.

Configuration Model
       To validate a configuration tree, we must create	a configuration	model
       that defines all	the properties of the validation engine	you want to
       create.

       The configuration model is expressed in a declarative form (i.e.	a Perl
       data structure which should be easier to	maintain than a	lot of code)

       Each configuration class	may contain a set of:

       o   node	elements that refer to another configuration class

       o   value elements that contain actual configuration data

       o   list	or hash	elements that also contain several node	or value
	   elements

       The structure of	your configuration tree	is shaped by the a set of
       configuration classes that are used in node elements,

       The structure of	the configuration data must be based on	a tree
       structure. This structure has several advantages:

       o   Unique path to get to a node	or a leaf.

       o   Simpler exploration and query

       o   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:

       o   A complex configuration cannot be mapped on a simple	tree.  Some
	   more	relation between nodes and leaves must be added.

       o   A configuration may actually	be structured as a graph instead as a
	   tree	(for instance, any configuration that maps a service to	a
	   resource). The graph	relation must be decomposed in a tree with
	   special reference relations that complete the tree to form a	graph.
	   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).
       See also	Directed acyclic graph on Wikipedia
       <http://en.wikipedia.org/wiki/Directed_acyclic_graph">More on DAGs>

       Each configuration class	declaration specifies:

       o   The "name" of the class (mandatory)

       o   A "class_description" used in user interfaces (optional)

       o   Optional include specification to avoid duplicate declaration of
	   elements.

       o   The class elements

       Each element specifies:

       o   Most	importantly, the type of the element (mostly "leaf", or
	   "node")

       o   The properties of each element (boundaries, check, integer or
	   string, enum	like type ...)

       o   The default values of parameters (if	any)

       o   Whether the parameter is mandatory

       o   Targeted audience (beginner,	advance, master), i.e. the level of
	   expertise required to tinker	a parameter (to	hide expert parameters
	   from	newbie eyes)

       o   On-line help	(for each parameter or value of	parameter)

       See Config::Model::Node for details on how to declare a configuration
       class.

       Example:

	$ cat lib/Config/Model/models/Xorg.pl
	[
	  {
	    name => 'Xorg',
	    class_description => 'Top level Xorg configuration.',
	    include => [ 'Xorg::ConfigDir'],
	    element => [
			Files => {
				  type => 'node',
				  description => 'File pathnames',
				  config_class_name => 'Xorg::Files'
				 },
			# snip
		       ]
	  },
	  {
	    name => 'Xorg::DRI',
	    element => [
			Mode =>	{
				 type => 'leaf',
				 value_type => 'uniline',
				 description =>	'DRI mode, usually set to 0666'
				}
		       ]
	  }
	];

Configuration instance methods
       A configuration instance	is created from	a model	and is the starting
       point of	a configuration	tree.

   instance
       An instance must	be created with	a model	name (using the	root class
       name) or	an application name (as	shown by "cme "list"" command).

       For example:

	my $model = Config::Model->new() ;
	$model->instance( application => 'approx');

       Or:

	my $model = Config::Model->new() ;
	# note that the	model class is slightly	different compared to
	# application name
	$model->instance( root_class_name => 'Approx');

       A custom	configuration class can	also be	used with "root_class_name"
       parameter:

	my $model = Config::Model->new() ;
	# create_config_class is described below
	$model ->create_config_class (
	  name => "SomeRootClass",
	  element => [ ...  ]
	) ;

	# instance name	is 'default'
	my $inst = $model->instance (root_class_name =>	'SomeRootClass');

       You can create several separated	instances from a model using "name"
       option:

	# instance name	is 'default'
	my $inst = $model->instance (
	  root_class_name => 'SomeRootClass',
	  name		  => 'test1'
	);

       Usually,	model files are	loaded automatically using a path matching
       "root_class_name" (e.g. configuration class "Foo::Bar" is stored	in
       "Foo/Bar.pl". You can choose to specify the file	containing the model
       with "model_file" parameter. This is mostly useful for tests.

       The "instance" method can also retrieve an instance that	has already
       been created:

	my $inst = $model->instance( name => 'test1' );

   get_instance
       Retrieve	an existing instance using its name.

	my $inst = $model->get_instance('test1'	);

   has_instance
       Check if	an instance name already exists

	 my $maybe = $model->has_instance('test1');

   cme
       This method is syntactic	sugar for short	program. It creates a new
       "Config::Model" object and returns a new	instance. See "instance" for
       the parameters.

Configuration class
       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:

       level
	   Level is "important", "normal" or "hidden".

	   The level is	used to	set how	configuration data is presented	to the
	   user	in browsing mode. "Important" elements are shown to the	user
	   no matter what. "hidden" elements are well, hidden. Their purpose
	   is explained	with the warp notion.

       status
	   Status is "obsolete", "deprecated" or "standard" (default).

	   Using a deprecated element raises a warning.	Using an obsolete
	   element raises an exception.

       description
	   Description of the element. This description	is used	while
	   generating user interfaces.

       summary
	   Summary of the element. This	description is used while generating a
	   user	interfaces and may be used in comments when writing the
	   configuration file.

       class_description
	   Description of the configuration class. This	description is used
	   while generating user interfaces.

       generated_by
	   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
	   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".

	   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 are:

	     ( bar , foo , xyz , baz )

	   Note	that include may not clobber an	existing element.

       include_backend
	   Include read/write specification from another class.

	     include_backend =>	'AnotherClass' ,

	   or

	     include_backend =>	[qw/ClassOne ClassTwo/]

       Note that include may not clobber an existing read/write	specification.

   create_config_class
       This method creates configuration classes. The parameters are described
       above and are forwarded to Config::Model::Node constructor. See
       "Configuration class declaration" in Config::Model::Node	for more
       details on configuration	class parameters.

       Example:

	 my $model = Config::Model -> new ;

	 $model->create_config_class
	 (
	  config_class_name => 'SomeRootClass',
	  description	    => [ X => 'X-ray' ],
	  level		    => [ 'tree_macro' => 'important' ] ,
	  class_description => "SomeRootClass description",
	  element	    => [ ... ]
	 ) ;

       For convenience,	"level"	and "description" parameters can also be
       declared	within the element declaration:

	 $model->create_config_class
	 (
	  config_class_name => 'SomeRootClass',
	  class_description => "SomeRootClass description",
	  'element'
	  => [
	       tree_macro => { level =>	'important'},
	       X	  => { description => 'X-ray', } ,
	     ]
	 ) ;

Load predeclared model
       You can also load predeclared model.

   load( <model_name> )
       This method opens the model directory and execute a ".pl" file
       containing the model declaration,

       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

       When a model name contain a "::"	(e.g "Foo::Bar"), "load" looks for a
       file named "Foo/Bar.pl".

       This method also	searches in "Foo/Bar.d"	directory for additional model
       information.  Model snippet found there are loaded with
       augment_config_class.

       Returns a list containing the names of the loaded classes. For
       instance, if "Foo/Bar.pl" contains a model for "Foo::Bar" and
       "Foo::Bar2", "load" returns "( 'Foo::Bar' , 'Foo::Bar2' )".

   augment_config_class	(name => '...',	class_data )
       Enhance the feature of a	configuration class. This method uses the same
       parameters as create_config_class. See "Model Plugin" in
       Config::Model::Manual::ModelCreationAdvanced for	more details on
       creating	model plugins.

Model query
   get_model( config_class_name	)
       Return a	hash containing	the model declaration (in a deep clone copy of
       the hash).  You may modify the hash at leisure.

   generate_doc	( top_class_name , directory , [ \%done	] )
       Generate	POD document for configuration class top_class_name and	all
       classes used by top_class_name, and write them in specified directory.

       "\%done"	is an optional reference to a hash used	to avoid writing twice
       the same	documentation when this	method is called several times.

   get_element_model( config_class_name	, element)
       Return a	hash containing	the model declaration for the specified	class
       and element.

   get_element_name( class => Foo )
       Get all names of	the elements of	class "Foo".

   get_element_property
       Returns the property of an element from the model.

       Parameters are:

       class
       element
       property

   list_class_element
       Returns a string	listing	all the	class and elements. Useful for
       debugging your configuration model.

Error handling
       Errors are handled with an exception mechanism.

       When a strongly typed Value object gets an authorized value, it raises
       an exception. If	this exception is not caught, the programs exits.

       See Config::Model::Exception for	details	on the various exception
       classes provided	with "Config::Model".

Logging
       See "Logging" in	cme

BUGS
       Given Murphy's law, the author is fairly	confident that you will	find
       bugs or miss some features. Please report them to
       https://github.com/dod38fr/config-model/issues The author will be
       notified, and then you'll automatically be notified of progress on your
       bug.

FEEDBACK
       Feedback	from users are highly desired. If you find this	module useful,
       please share your use cases, success stories with the author or with
       the config-model- users mailing list.

PROJECT	FOUNDER
       Dominique Dumont, "ddumont@cpan.org"

CREDITS
       In alphabetical order:

	 Harley	Pig

	 Jose Luis Perez Diez

	 Krzysztof Tyszecki

	 Mathieu Arnold

	 Mohammad S Anwar

LICENSE
	   Copyright (c) 2005-2016 Dominique Dumont.

	   Config-Model	is free	software; you can redistribute it and/or
	   modify it under the terms of	the GNU	Lesser General 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 General 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

SEE ALSO
       Config::Model::Instance,

       <https://github.com/dod38fr/config-model/wiki>

       <https://github.com/dod38fr/config-model/wiki/Creating-models>

   Model elements
       The arrow shows inheritance between classes

       o   Config::Model::Node <- Config::Model::AnyThing

       o   Config::Model::HashId <- Config::Model::AnyId <-
	   Config::Model::AnyThing

       o   Config::Model::ListId <- Config::Model::AnyId <-
	   Config::Model::AnyThing

       o   Config::Model::Value	<- Config::Model::AnyThing

       o   Config::Model::CheckList <- Config::Model::AnyThing

       o   Config::Model::WarpedNode <-	Config::Model::AnyThing

   command line
       cme.

   Read	and write backends
       o   Config::Model::Backend::Fstab <- Config::Model::Backend::Any

       o   Config::Model::Backend::IniFile <- Config::Model::Backend::Any

       o   Config::Model::Backend::PlainFile <-	Config::Model::Backend::Any

       o   Config::Model::Backend::ShellVar <- Config::Model::Backend::Any

       o   Config::Model::Backend::Yaml	<- Config::Model::Backend::Any

   Model utilities
       o   Config::Model::Annotation

       o   Config::Model::BackendMgr: Used by "Config::Model::Node" object

       o   Config::Model::Describe

       o   Config::Model::Dumper

       o   Config::Model::DumpAsData

       o   Config::Model::IdElementReference

       o   Config::Model::Iterator

       o   Config::Model::Loader

       o   Config::Model::ObjTreeScanner

       o   Config::Model::Report

       o   Config::Model::Searcher: Search element in configuration model.

       o   Config::Model::SimpleUI

       o   Config::Model::TreeSearcher:	Search string or regexp	in
	   configuration tree.

       o   Config::Model::TermUI

       o   Config::Model::Iterator

       o   Config::Model::ValueComputer

       o   Config::Model::Warper

   Test	framework
       o   Config::Model::Tester

AUTHOR
       Dominique Dumont

COPYRIGHT AND LICENSE
       This software is	Copyright (c) 2005-2017	by Dominique Dumont.

       This is free software, licensed under:

	 The GNU Lesser	General	Public License,	Version	2.1, February 1999

SUPPORT
   Websites
       The following websites have more	information about this module, and may
       be of help to you. As always, in	addition to those websites please use
       your favorite search engine to discover more resources.

       o   Search CPAN

	   The default CPAN search engine, useful to view POD in HTML format.

	   <http://search.cpan.org/dist/Config-Model>

       o   AnnoCPAN

	   The AnnoCPAN	is a website that allows community annotations of Perl
	   module documentation.

	   <http://annocpan.org/dist/Config-Model>

       o   CPAN	Ratings

	   The CPAN Ratings is a website that allows community ratings and
	   reviews of Perl modules.

	   <http://cpanratings.perl.org/d/Config-Model>

       o   CPANTS

	   The CPANTS is a website that	analyzes the Kwalitee (	code metrics )
	   of a	distribution.

	   <http://cpants.cpanauthors.org/dist/Config-Model>

       o   CPAN	Testers

	   The CPAN Testers is a network of smokers who	run automated tests on
	   uploaded CPAN distributions.

	   <http://www.cpantesters.org/distro/C/Config-Model>

       o   CPAN	Testers	Matrix

	   The CPAN Testers Matrix is a	website	that provides a	visual
	   overview of the test	results	for a distribution on various
	   Perls/platforms.

	   <http://matrix.cpantesters.org/?dist=Config-Model>

       o   CPAN	Testers	Dependencies

	   The CPAN Testers Dependencies is a website that shows a chart of
	   the test results of all dependencies	for a distribution.

	   <http://deps.cpantesters.org/?module=Config::Model>

   Bugs	/ Feature Requests
       Please report any bugs or feature requests by email to "ddumont at
       cpan.org", or through the web interface at
       <https://github.com/dod38fr/config-model/issues>. You will be
       automatically notified of any progress on the request by	the system.

   Source Code
       The code	is open	to the world, and available for	you to hack on.	Please
       feel free to browse it and play with it,	or whatever. If	you want to
       contribute patches, please send me a diff or prod me to pull from your
       repository :)

       <http://github.com/dod38fr/config-model>

	 git clone git://github.com/dod38fr/config-model.git

perl v5.24.1			  2017-07-02		      Config::Model(3)

NAME | VERSION | SYNOPSIS | DESCRIPTION | Question you may ask yourself | Mailing lists | Suggested reads to start | STOP | Storage backend, configuration reader and writer | Validation engine | User interface | Constructor | Configuration Model | Configuration instance methods | Configuration class | Load predeclared model | Model query | Error handling | Logging | BUGS | FEEDBACK | PROJECT FOUNDER | CREDITS | LICENSE | SEE ALSO | AUTHOR | COPYRIGHT AND LICENSE | SUPPORT

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Config::Model&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help