Config::Model(3pm)

1Config::Model(3)      User Contributed Perl Documentation     Config::Model(3)
2
3
4

NAME

6       Config::Model - Framework to create configuration validation tools and
7       editors
8

VERSION

10       version 1.205
11

SYNOPSIS

13        # create new Model object
14        my $model = Config::Model->new() ;
15
16        # create config model
17        $model ->create_config_class
18         (
19          name => "SomeRootClass",
20          element => [ ...  ]
21         ) ;
22
23        # create instance
24        my $instance = $model->instance (root_class_name => 'SomeRootClass',
25                                         instance_name => 'test1');
26
27        # get configuration tree root
28        my $cfg_root = $instance -> config_root ;
29
30        # You can also use load on demand
31        my $model = Config::Model->new() ;
32
33        # this call will look for a AnotherClass.pl that will contain
34        # the model
35        my $inst2 = $model->instance (root_class_name => 'AnotherClass',
36                                     instance_name => 'test2');
37
38        # then get configuration tree root
39        my $cfg_root = $inst2 -> config_root ;
40

DESCRIPTION

42       Using Config::Model, a typical configuration validation tool will be
43       made of 3 parts :
44
45       1.  A reader and writer that will parse the configuration file and
46           transform in a tree representation within Config::Model. The values
47           contained in this configuration tree can be written back in the
48           configuraiton file(s).
49
50       2.  A validation engine which is in charge of validating the content
51           and structure of configuration stored in the configuration tree.
52           This validation engine will follow the structure and constraint
53           declared in a configuration model. This model is a kind of schema
54           for the configuration tree.
55
56       3.  A user interface to modify the content of the configuration tree. A
57           modification will be validated instantly by the validation engine.
58

Storage backend, configuration reader and writer

60       See Config::Model::AutoRead for details
61

Validation engine

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

User interface

67       The user interface will use some parts of the API to set and get
68       configuration values. More importantly, a generic user interface will
69       need to explore the configuration model to be able to generate at run-
70       time relevant configuration screens.
71
72       Simple text interface if provided in this module. Curses and Tk
73       interfaces are provided by Config::Model::CursesUI and
74       Config::Model::TkUI.
75

Constructor

77       Simply call new without parameters:
78
79        my $model = Config::Model -> new ;
80
81       This will create an empty shell for your model.
82

Configuration Model

84       To validate a configuration tree, we must create a configuration model
85       that will set all the properties of the validation engine you want to
86       create.
87
88       The configuration model is expressed in a declarative form (i.e. a Perl
89       data structure which is always easier to maintain than a lot of code)
90
91       Each configuration class contains a set of:
92
93       ·   node element that will refer to another configuration class
94
95       ·   value element that will contains actual configuration data
96
97       ·   List or hash of node or value elements
98
99       By declaring a set of configuration classes and refering them in node
100       element, you will shape the structure of your configuration tree.
101
102       The structure of the configuration data must be based on a tree
103       structure. This structure has several advantages:
104
105       ·   Unique path to get to a node or a leaf.
106
107       ·   Simpler exploration and query
108
109       ·   Simple hierarchy. Deletion of configuration items is simpler to
110           grasp: when you cut a branch, all the leaves attaches to that
111           branch go down.
112
113       But using a tree has also some drawbacks:
114
115       ·   A complex configuration cannot be mapped on a simple tree.  Some
116           more relation between nodes and leaves must be added.
117
118       ·   Some configuration part are actually graph instead of a tree (for
119           instance, any configuration that will map a service to a resource).
120           The graph relation must be decomposed in a tree with special
121           reference relation. See "Value Reference" in Config::Model::Value
122
123       Note: a configuration tree is a tree of objects. The model is declared
124       with classes. The classes themselves have relations that closely match
125       the relation of the object of the configuration tree. But the class
126       need not to be declared in a tree structure (always better to reuse
127       classes). But they must be declared as a DAG (directed acyclic graph).
128
129       Each configuration class declaration specifies:
130
131       ·       The "name" of the class (mandatory)
132
133       ·       A "class_description" used in user interfaces (optional)
134
135       ·       Optional include specification to avoid duplicate declaration
136               of elements.
137
138       ·       The class elements
139
140       Each element will feature:
141
142       8   Most importantly, the type of the element (mostly "leaf", or
143           "node")
144
145       *   The properties of each element (boundaries, check, integer or
146           string, enum like type ...)
147
148       *   The default values of parameters (if any)
149
150       *   Mandatory parameters
151
152       *   Targeted audience (beginner, advance, master)
153
154       *   On-line help (for each parameter or value of parameter)
155
156       *   The level of expertise of each parameter (to hide expert parameters
157           from newbie eyes)
158
159       See Config::Model::Node for details on how to declare a configuration
160       class.
161
162       Example:
163
164        $ cat lib/Config/Model/models/Xorg.pl
165        [
166          {
167            name => 'Xorg',
168            class_description => 'Top level Xorg configuration.',
169            include => [ 'Xorg::ConfigDir'],
170            element => [
171                        Files => {
172                                  type => 'node',
173                                  description => 'File pathnames',
174                                  config_class_name => 'Xorg::Files'
175                                 },
176                        # snip
177                       ]
178          },
179          {
180            name => 'Xorg::DRI',
181            element => [
182                        Mode => {
183                                 type => 'leaf',
184                                 value_type => 'uniline',
185                                 description => 'DRI mode, usually set to 0666'
186                                }
187                       ]
188          }
189        ];
190

Configuration instance

192       A configuration instance if the staring point of a configuration tree.
193       When creating a model instance, you must specify the root class name,
194       I.e. the configuration class that is used by the root node of the tree.
195
196        my $model = Config::Model->new() ;
197        $model ->create_config_class
198         (
199          name => "SomeRootClass",
200          element => [ ...  ]
201         ) ;
202
203        # instance name is 'default'
204        my $inst = $model->instance (root_class_name => 'SomeRootClass');
205
206       You can create several separated instances from a model using "name"
207       option:
208
209        # instance name is 'default'
210        my $inst = $model->instance (root_class_name => 'SomeRootClass',
211                                     name            => 'test1');
212
213       Usually, model files will be loaded automatically depending on
214       "root_class_name". But you can choose to specify the file containing
215       the model with "model_file" parameter. This is mostly useful for tests.
216

Configuration class

218       A configuration class is made of series of elements which are detailed
219       in Config::Model::Node.
220
221       Whatever its type (node, leaf,... ), each element of a node has several
222       other properties:
223
224       experience
225           By using the "experience" parameter, you can change the experience
226           level of each element. Possible experience levels are "master",
227           "advanced" and "beginner" (default).
228
229       level
230           Level is "important", "normal" or "hidden".
231
232           The level is used to set how configuration data is presented to the
233           user in browsing mode. "Important" elements will be shown to the
234           user no matter what. "hidden" elements will be explained with the
235           warp notion.
236
237       status
238           Status is "obsolete", "deprecated" or "standard" (default).
239
240           Using a deprecated element will issue a warning. Using an obsolete
241           element will raise an exception.
242
243       description
244           Description of the element. This description will be used when
245           generating user interfaces.
246
247       summary
248           Summary of the element. This description will be used when
249           generating user interfaces and may be used in comments when writing
250           the configuration file.
251
252       class_description
253           Description of the configuration class. This description will be
254           used when generating user interfaces.
255
256       generated_by
257           Mention with a descriptive string if this class was generated by a
258           program.  This parameter is currently reserved for
259           Config::Model::Itself model editor.
260
261       include
262           Include element description from another class.
263
264             include => 'AnotherClass' ,
265
266           or
267
268             include => [qw/ClassOne ClassTwo/]
269
270           In a configuration class, the order of the element is important.
271           For instance if "foo" is warped by "bar", you must declare "bar"
272           element before "foo".
273
274           When including another class, you may wish to insert the included
275           elements after a specific element of your including class:
276
277             # say AnotherClass contains element xyz
278             include => 'AnotherClass' ,
279             include_after => "foo" ,
280             element => [ bar => ... , foo => ... , baz => ... ]
281
282           Now the element of your class will be:
283
284             ( bar , foo , xyz , baz )
285
286       Example:
287
288         my $model = Config::Model -> new ;
289
290         $model->create_config_class
291         (
292          config_class_name => 'SomeRootClass',
293          experience        => [ [ qw/tree_macro warp/ ] => 'advanced'] ,
294          description       => [ X => 'X-ray' ],
295          level             => [ 'tree_macro' => 'important' ] ,
296          class_description => "SomeRootClass description",
297          element           => [ ... ]
298         ) ;
299
300       Again, see Config::Model::Node for more details on configuration class
301       declaration.
302
303       For convenience, "experience", "level" and "description" parameters can
304       also be declared within the element declaration:
305
306         $model->create_config_class
307         (
308          config_class_name => 'SomeRootClass',
309          class_description => "SomeRootClass description",
310          'element'
311          => [
312               tree_macro => { level => 'important',
313                               experience => 'advanced',
314                             },
315               warp       => { experience => 'advanced', } ,
316               X          => { description => 'X-ray', } ,
317             ]
318         ) ;
319

Load pre-declared model

321       You can also load pre-declared model.
322
323   load( <model_name> )
324       This method will open the model directory and execute a ".pl" file
325       containing the model declaration,
326
327       This perl file must return an array ref to declare models. E.g.:
328
329        [
330         [
331          name => 'Class_1',
332          element => [ ... ]
333         ],
334         [
335          name => 'Class_2',
336          element => [ ... ]
337         ]
338        ];
339
340       do not put "1;" at the end or "load" will not work
341
342       If a model name contain a "::" (e.g "Foo::Bar"), "load" will look for a
343       file named "Foo/Bar.pl".
344
345       Returns a list containining the names of the loaded classes. For
346       instance, if "Foo/Bar.pl" contains a model for "Foo::Bar" and
347       "Foo::Bar2", "load" will return "( 'Foo::Bar' , 'Foo::Bar2' )".
348

Model query

350   get_model( config_class_name )
351       Return a hash containing the model declaration.
352
353   get_element_name( class => Foo, for => advanced )
354       Get all names of the elements of class "Foo" that are accessible for
355       experience level "advanced".
356
357       Level can be "master" (default), "advanced" or "beginner".
358
359   list_class_element
360       Returns a string listing all the class and elements. Useful for
361       debugging your configuration model.
362

Error handling

364       Errors are handled with an exception mechanism (See Exception::Class).
365
366       When a strongly typed Value object gets an authorized value, it raises
367       an exception. If this exception is not catched, the programs exits.
368
369       See Config::Model::Exception for details on the various exception
370       classes provided with "Config::Model".
371

Log and Traces

373       Currently a rather lame trace mechanism is provided:
374
375       ·   Set $::debug to 1 to get debug messages on STDOUT.
376
377       ·   Set $::verbose to 1 to get verbose messages on STDOUT.
378
379       Depending on available time, a better log/error system may be
380       implemented.
381

AUTHOR

383       Dominique Dumont, (ddumont at cpan dot org)
384

LICENSE

386           Copyright (c) 2005-2010 Dominique Dumont.
387
388           This file is part of Config-Model.
389
390           Config-Model is free software; you can redistribute it and/or
391           modify it under the terms of the GNU Lesser Public License as
392           published by the Free Software Foundation; either version 2.1 of
393           the License, or (at your option) any later version.
394
395           Config-Model is distributed in the hope that it will be useful,
396           but WITHOUT ANY WARRANTY; without even the implied warranty of
397           MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
398           Lesser Public License for more details.
399
400           You should have received a copy of the GNU Lesser Public License
401           along with Config-Model; if not, write to the Free Software
402           Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
403           02110-1301 USA
404