.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "Config::Model 3pm" .TH Config::Model 3pm "2023-08-19" "perl v5.36.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Config::Model \- a framework to validate, migrate and edit configuration files .SH "VERSION" .IX Header "VERSION" version 2.153 .SH "SYNOPSIS" .IX Header "SYNOPSIS" .SS "Perl program to use an existing model" .IX Subsection "Perl program to use an existing model" .Vb 3 \& use Config::Model qw(cme); \& # load, modify and save popcon configuration file \& cme(\*(Aqpopcon\*(Aq)\->modify("PARTICIPATE=yes"); .Ve .SS "Command line to use an existing model" .IX Subsection "Command line to use an existing model" .Vb 2 \& # with App::Cme \& cme modify popcon \*(AqPARTICIPATE=yes\*(Aq .Ve .SS "Perl program with a custom model" .IX Subsection "Perl program with a custom model" .Vb 1 \& 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 => \*(Aqleaf\*(Aq, value_type => \*(Aquniline\*(Aq }, ], \& rw_config => { backend => \*(AqIniFile\*(Aq, auto_create => 1, \& config_dir => \*(Aq.\*(Aq, file => \*(Aqmini.ini\*(Aq, \& } \& ) ; \& \& # create instance (Config::Model::Instance object) \& my $instance = $model\->instance (root_class_name => \*(AqMiniModel\*(Aq); \& \& # 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 .Ve .SS "Create a new model file and use it" .IX Subsection "Create a new model file and use it" .Vb 11 \& $ mkdir \-p lib/Config/Model/models/ \& $ echo "[ { name => \*(AqMiniModel\*(Aq, \e \& element => [ [qw/foo bar baz/ ] => { type => \*(Aqleaf\*(Aq, value_type => \*(Aquniline\*(Aq }, ], \e \& rw_config => { backend => \*(AqIniFile\*(Aq, auto_create => 1, \e \& config_dir => \*(Aq.\*(Aq, file => \*(Aqmini.ini\*(Aq, \e \& } \e \& } \e \& ] ; " > lib/Config/Model/models/MiniModel.pl \& # require App::Cme \& $ cme modify \-try MiniModel \-dev bar=BARV foo=FOOV baz=BAZV \& $ cat mini.ini .Ve .PP Note that model creation is easier running \f(CW\*(C`cme meta edit\*(C'\fR with App::Cme and Config::Model::Itself. .SH "DESCRIPTION" .IX Header "DESCRIPTION" Config::Model enables a project developer to provide an interactive configuration editor (graphical, curses based or plain terminal) to users. .PP To provide these tools, Config::Model needs: .IP "\(bu" 4 A description of the structure and constraints of the project's configuration (fear not, a \s-1GUI\s0 is available with App::Cme) .IP "\(bu" 4 A module to read and write configuration data (aka a backend class). .PP 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. .PP Smaller models targeted for configuration upgrades can also be created: .IP "\(bu" 4 only upgrade and migration specifications are required .IP "\(bu" 4 unknown parameters can be accepted .PP A command line is provided to perform configuration upgrade with a single command. .SS "How does this work ?" .IX Subsection "How does this work ?" Using this project, a typical configuration editor/validator/upgrader is made of 3 parts : .PP .Vb 7 \& GUI <\-\-\-\-\-\-\-\-> |\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-| \& CursesUI <\-\-\-> | |\-\-\-\-\-\-\-\-\-| | \& | | Model | | \& ShellUI <\-\-\-\-> | |\-\-\-\-\-\-\-\-\-| |<\-\-\-\-\-read\-backend\-\-\-\-\-\-\- |\-\-\-\-\-\-\-\-\-\-\-\-\-| \& | |\-\-\-\-write\-backend\-\-\-\-\-\-\-> | config file | \& FuseUI <\-\-\-\-\-> | Config::Model | |\-\-\-\-\-\-\-\-\-\-\-\-\-| \& |\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-| .Ve .IP "1." 4 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). .IP "2." 4 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. .IP "3." 4 A user interface to modify the content of the configuration tree. A modification is validated immediately by the validation engine. .PP 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). .SH "Question you may ask yourself" .IX Header "Question you may ask yourself" .SS "Don't we already have some configuration validation tools ?" .IX Subsection "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. .PP 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 \f(CW\*(C`xorg.conf\*(C'\fR file). .PP 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. .SS "What's the advantage of this project ?" .IX Subsection "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. .PP 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. .PP The model specifies: .IP "\(bu" 4 The structure of the configuration data (which can be queried by generic user interfaces) .IP "\(bu" 4 The properties of each element (boundaries check, integer or string, enum like type, default value ...) .IP "\(bu" 4 The targeted audience (beginner, advanced, master) .IP "\(bu" 4 The on-line help .PP So, in the end: .IP "\(bu" 4 Maintenance and evolution of the configuration content is easier .IP "\(bu" 4 User sees a *common* interface for *all* programs using this project. .IP "\(bu" 4 Upgrade of configuration data is easier and sanity check is performed during the upgrade. .IP "\(bu" 4 Audit of configuration is possible to check what was modified by the user compared to default values .SS "What about the user interface ?" .IX Subsection "What about the user interface ?" Config::Model interface can be: .IP "\(bu" 4 a shell-like interface (plain or based on Term::ReadLine). .IP "\(bu" 4 Graphical with Config::Model::TkUI (Perl/Tk interface). .IP "\(bu" 4 based on curses with Config::Model::CursesUI. This interface can be handy if your X server is down. .IP "\(bu" 4 Through a virtual file system where every configuration parameter is mapped to a file. (Linux only) .PP All these interfaces are generated from the configuration model. .PP And configuration model can be created or modified with a graphical user interface (with \f(CW\*(C`cme meta edit\*(C'\fR once Config::Model::Itself is installed) .SS "What about configuration data storage ?" .IX Subsection "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. .PP To help with this task, this project provides writer/parsers for common format: \s-1INI\s0 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. .SS "Is there an example of a configuration model ?" .IX Subsection "Is there an example of a configuration model ?" The \*(L"example\*(R" directory contains a configuration model example for \&\f(CW\*(C`/etc/fstab\*(C'\fR file. This example includes a small program that use this model to show some ways to extract configuration information. .SH "Mailing lists" .IX Header "Mailing lists" For more question, please send a mail to: .PP .Vb 1 \& config\-model\-users at lists.sourceforge.net .Ve .SH "Suggested reads to start" .IX Header "Suggested reads to start" .SS "Beginners" .IX Subsection "Beginners" .IP "\(bu" 4 Config::Model::Manual::ModelCreationIntroduction .IP "\(bu" 4 Config::Model::Cookbook::CreateModelFromDoc .SS "Advanced" .IX Subsection "Advanced" .IP "\(bu" 4 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 \s-1GUI\s0 launched by \f(CW\*(C`cme meta edit\*(C'\fR command. .IP "\(bu" 4 Config::Model::Manual::ModelCreationAdvanced .SS "Masters" .IX Subsection "Masters" use the source, Luke .SH "STOP" .IX Header "STOP" The documentation below is quite detailed and is more a reference doc regarding \&\f(CW\*(C`Config::Model\*(C'\fR class. .PP For an introduction to model creation, please check: Config::Model::Manual::ModelCreationIntroduction .SH "Storage backend, configuration reader and writer" .IX Header "Storage backend, configuration reader and writer" See Config::Model::BackendMgr for details .SH "Validation engine" .IX Header "Validation engine" \&\f(CW\*(C`Config::Model\*(C'\fR provides a way to get a validation engine from a set of rules. This set of rules is called the configuration model. .SH "User interface" .IX Header "User interface" The user interface uses some parts of the \s-1API\s0 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. .PP A command line interface is provided in this module. Curses and Tk interfaces are provided by Config::Model::CursesUI and Config::Model::TkUI. .SH "Constructor" .IX Header "Constructor" .Vb 1 \& my $model = Config::Model \-> new ; .Ve .PP creates an object to host your model. .SS "Constructor parameters" .IX Subsection "Constructor parameters" .IP "log_level" 4 .IX Item "log_level" Specify minimal log level. Default is \f(CW\*(C`WARN\*(C'\fR. Can be \f(CW\*(C`INFO\*(C'\fR, \&\f(CW\*(C`DEBUG\*(C'\fR or \f(CW\*(C`TRACE\*(C'\fR to get more logs. Can also be \f(CW\*(C`ERROR\*(C'\fR to get less traces. .Sp This parameter is used to override the log level specified in log configuration file. .SH "Configuration Model" .IX Header "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. .PP 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) .PP Each configuration class may contain a set of: .IP "\(bu" 4 node elements that refer to another configuration class .IP "\(bu" 4 value elements that contain actual configuration data .IP "\(bu" 4 list or hash elements that also contain several node or value elements .PP The structure of your configuration tree is shaped by the a set of configuration classes that are used in node elements, .PP The structure of the configuration data must be based on a tree structure. This structure has several advantages: .IP "\(bu" 4 Unique path to get to a node or a leaf. .IP "\(bu" 4 Simpler exploration and query .IP "\(bu" 4 Simple hierarchy. Deletion of configuration items is simpler to grasp: when you cut a branch, all the leaves attached to that branch go down. .PP But using a tree has also some drawbacks: .IP "\(bu" 4 A complex configuration cannot be mapped on a tree. Some more relation between nodes and leaves must be added. .IP "\(bu" 4 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 \fIreference\fR relations that complete the tree to form a graph. See \*(L"Value Reference\*(R" in Config::Model::Value .PP 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 \s-1DAG\s0 (directed acyclic graph). See also Directed acyclic graph on Wikipedia More on DAGs> .PP Each configuration class declaration specifies: .IP "\(bu" 4 The \f(CW\*(C`name\*(C'\fR of the class (mandatory) .IP "\(bu" 4 A \f(CW\*(C`class_description\*(C'\fR used in user interfaces (optional) .IP "\(bu" 4 Optional include specification to avoid duplicate declaration of elements. .IP "\(bu" 4 The class elements .PP Each element specifies: .IP "\(bu" 4 Most importantly, the type of the element (mostly \f(CW\*(C`leaf\*(C'\fR, or \f(CW\*(C`node\*(C'\fR) .IP "\(bu" 4 The properties of each element (boundaries, check, integer or string, enum like type ...) .IP "\(bu" 4 The default values of parameters (if any) .IP "\(bu" 4 Whether the parameter is mandatory .IP "\(bu" 4 Targeted audience (beginner, advance, master), i.e. the level of expertise required to tinker a parameter (to hide expert parameters from newbie eyes) .IP "\(bu" 4 On-line help (for each parameter or value of parameter) .PP See Config::Model::Node for details on how to declare a configuration class. .PP Example: .PP .Vb 10 \& $ cat lib/Config/Model/models/Xorg.pl \& [ \& { \& name => \*(AqXorg\*(Aq, \& class_description => \*(AqTop level Xorg configuration.\*(Aq, \& include => [ \*(AqXorg::ConfigDir\*(Aq], \& element => [ \& Files => { \& type => \*(Aqnode\*(Aq, \& description => \*(AqFile pathnames\*(Aq, \& config_class_name => \*(AqXorg::Files\*(Aq \& }, \& # snip \& ] \& }, \& { \& name => \*(AqXorg::DRI\*(Aq, \& element => [ \& Mode => { \& type => \*(Aqleaf\*(Aq, \& value_type => \*(Aquniline\*(Aq, \& description => \*(AqDRI mode, usually set to 0666\*(Aq \& } \& ] \& } \& ]; .Ve .SH "Configuration instance methods" .IX Header "Configuration instance methods" A configuration instance is created from a model and is the starting point of a configuration tree. .SS "instance" .IX Subsection "instance" An instance must be created with a model name (using the root class name) or an application name (as shown by "cme \f(CW\*(C`list\*(C'\fR" command). .PP For example: .PP .Vb 2 \& my $model = Config::Model\->new() ; \& $model\->instance( application => \*(Aqapprox\*(Aq); .Ve .PP Or: .PP .Vb 4 \& my $model = Config::Model\->new() ; \& # note that the model class is slightly different compared to \& # application name \& $model\->instance( root_class_name => \*(AqApprox\*(Aq); .Ve .PP A custom configuration class can also be used with \f(CW\*(C`root_class_name\*(C'\fR parameter: .PP .Vb 6 \& my $model = Config::Model\->new() ; \& # create_config_class is described below \& $model \->create_config_class ( \& name => "SomeRootClass", \& element => [ ... ] \& ) ; \& \& # instance name is \*(Aqdefault\*(Aq \& my $inst = $model\->instance (root_class_name => \*(AqSomeRootClass\*(Aq); .Ve .PP You can create several separated instances from a model using \&\f(CW\*(C`name\*(C'\fR option: .PP .Vb 5 \& # instance name is \*(Aqdefault\*(Aq \& my $inst = $model\->instance ( \& root_class_name => \*(AqSomeRootClass\*(Aq, \& name => \*(Aqtest1\*(Aq \& ); .Ve .PP Usually, model files are loaded automatically using a path matching \&\f(CW\*(C`root_class_name\*(C'\fR (e.g. configuration class \f(CW\*(C`Foo::Bar\*(C'\fR is stored in \&\f(CW\*(C`Foo/Bar.pl\*(C'\fR. You can choose to specify the file containing the model with \f(CW\*(C`model_file\*(C'\fR parameter. This is mostly useful for tests. .PP The \f(CW\*(C`instance\*(C'\fR method can also retrieve an instance that has already been created: .PP .Vb 1 \& my $inst = $model\->instance( name => \*(Aqtest1\*(Aq ); .Ve .SS "get_instance" .IX Subsection "get_instance" Retrieve an existing instance using its name. .PP .Vb 1 \& my $inst = $model\->get_instance(\*(Aqtest1\*(Aq ); .Ve .SS "has_instance" .IX Subsection "has_instance" Check if an instance name already exists .PP .Vb 1 \& my $maybe = $model\->has_instance(\*(Aqtest1\*(Aq); .Ve .SS "cme" .IX Subsection "cme" This method is syntactic sugar for short program. It creates a new \&\f(CW\*(C`Config::Model\*(C'\fR object and returns a new instance. .PP \&\f(CW\*(C`cme\*(C'\fR arguments are passed to \*(L"instance\*(R" method, except \&\f(CW\*(C`force\-load\*(C'\fR. .PP Like cme command, \f(CW\*(C`cme\*(C'\fR functions accepts \f(CW\*(C`force\-load\*(C'\fR parameters. When this argument is true, the instance is created with \&\f(CW\*(C`check =\*(C'\fR 'no'>. Hence bad values are stored in \f(CW\*(C`cme\*(C'\fR and must be corrected before saving back the data. .SH "Configuration class" .IX Header "Configuration class" A configuration class is made of series of elements which are detailed in Config::Model::Node. .PP Whatever its type (node, leaf,... ), each element of a node has several other properties: .IP "level" 4 .IX Item "level" Level is \f(CW\*(C`important\*(C'\fR, \f(CW\*(C`normal\*(C'\fR or \f(CW\*(C`hidden\*(C'\fR. .Sp The level is used to set how configuration data is presented to the user in browsing mode. \f(CW\*(C`Important\*(C'\fR elements are shown to the user no matter what. \f(CW\*(C`hidden\*(C'\fR elements are well, hidden. Their purpose is explained with the \fIwarp\fR notion. .IP "status" 4 .IX Item "status" Status is \f(CW\*(C`obsolete\*(C'\fR, \f(CW\*(C`deprecated\*(C'\fR or \f(CW\*(C`standard\*(C'\fR (default). .Sp Using a deprecated element raises a warning. Using an obsolete element raises an exception. .IP "description" 4 .IX Item "description" Description of the element. This description is used while generating user interfaces. .IP "summary" 4 .IX Item "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. .IP "class_description" 4 .IX Item "class_description" Description of the configuration class. This description is used while generating user interfaces. .IP "generated_by" 4 .IX Item "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. .IP "include" 4 .IX Item "include" Include element description from another class. .Sp .Vb 1 \& include => \*(AqAnotherClass\*(Aq , .Ve .Sp or .Sp .Vb 1 \& include => [qw/ClassOne ClassTwo/] .Ve .Sp In a configuration class, the order of the element is important. For instance if \f(CW\*(C`foo\*(C'\fR is warped by \f(CW\*(C`bar\*(C'\fR, you must declare \f(CW\*(C`bar\*(C'\fR element before \f(CW\*(C`foo\*(C'\fR. .Sp When including another class, you may wish to insert the included elements after a specific element of your including class: .Sp .Vb 4 \& # say AnotherClass contains element xyz \& include => \*(AqAnotherClass\*(Aq , \& include_after => "foo" , \& element => [ bar => ... , foo => ... , baz => ... ] .Ve .Sp Now the element of your class are: .Sp .Vb 1 \& ( bar , foo , xyz , baz ) .Ve .Sp Note that include may not clobber an existing element. .IP "include_backend" 4 .IX Item "include_backend" Include read/write specification from another class. .Sp .Vb 1 \& include_backend => \*(AqAnotherClass\*(Aq , .Ve .Sp or .Sp .Vb 1 \& include_backend => [qw/ClassOne ClassTwo/] .Ve .PP Note that include may not clobber an existing read/write specification. .SS "create_config_class" .IX Subsection "create_config_class" This method creates configuration classes. The parameters are described above and are forwarded to Config::Model::Node constructor. See \&\*(L"Configuration class declaration\*(R" in Config::Model::Node for more details on configuration class parameters. .PP Example: .PP .Vb 1 \& my $model = Config::Model \-> new ; \& \& $model\->create_config_class \& ( \& config_class_name => \*(AqSomeRootClass\*(Aq, \& description => [ X => \*(AqX\-ray\*(Aq ], \& level => [ \*(Aqtree_macro\*(Aq => \*(Aqimportant\*(Aq ] , \& class_description => "SomeRootClass description", \& element => [ ... ] \& ) ; .Ve .PP For convenience, \f(CW\*(C`level\*(C'\fR and \f(CW\*(C`description\*(C'\fR parameters can also be declared within the element declaration: .PP .Vb 10 \& $model\->create_config_class \& ( \& config_class_name => \*(AqSomeRootClass\*(Aq, \& class_description => "SomeRootClass description", \& \*(Aqelement\*(Aq \& => [ \& tree_macro => { level => \*(Aqimportant\*(Aq}, \& X => { description => \*(AqX\-ray\*(Aq, } , \& ] \& ) ; .Ve .SH "Load predeclared model" .IX Header "Load predeclared model" You can also load predeclared model. .SS "load( )" .IX Subsection "load( )" This method opens the model directory and execute a \f(CW\*(C`.pl\*(C'\fR file containing the model declaration, .PP This perl file must return an array ref to declare models. E.g.: .PP .Vb 10 \& [ \& [ \& name => \*(AqClass_1\*(Aq, \& element => [ ... ] \& ], \& [ \& name => \*(AqClass_2\*(Aq, \& element => [ ... ] \& ] \& ]; .Ve .PP do not put \f(CW\*(C`1;\*(C'\fR at the end or \f(CW\*(C`load\*(C'\fR will not work .PP When a model name contain a \f(CW\*(C`::\*(C'\fR (e.g \f(CW\*(C`Foo::Bar\*(C'\fR), \f(CW\*(C`load\*(C'\fR looks for a file named \f(CW\*(C`Foo/Bar.pl\*(C'\fR. .PP This method also searches in \f(CW\*(C`Foo/Bar.d\*(C'\fR directory for additional model information. Model snippet found there are loaded with augment_config_class. .PP Returns a list containing the names of the loaded classes. For instance, if \&\f(CW\*(C`Foo/Bar.pl\*(C'\fR contains a model for \f(CW\*(C`Foo::Bar\*(C'\fR and \f(CW\*(C`Foo::Bar2\*(C'\fR, \f(CW\*(C`load\*(C'\fR returns \f(CW\*(C`( \*(AqFoo::Bar\*(Aq , \*(AqFoo::Bar2\*(Aq )\*(C'\fR. .SS "augment_config_class (name => '...', class_data )" .IX Subsection "augment_config_class (name => '...', class_data )" Enhance the feature of a configuration class. This method uses the same parameters as create_config_class. See \&\*(L"Model Plugin\*(R" in Config::Model::Manual::ModelCreationAdvanced for more details on creating model plugins. .SH "Model query" .IX Header "Model query" .SS "model" .IX Subsection "model" Returns a hash containing the model declaration of the passed model name. Do not modify the content of the returned data structure. .PP .Vb 1 \& my $cloned = $model\->model(\*(AqFoo\*(Aq); .Ve .SS "get_model_clone" .IX Subsection "get_model_clone" Like \f(CW\*(C`model\*(C'\fR, returns a hash containing the model declaration of the passed model name, this time in a deep clone of the data structure. .PP .Vb 1 \& my $cloned = $model\->get_model_clone(\*(AqFoo\*(Aq); .Ve .SS "generate_doc ( top_class_name , directory , [ \e%done ] )" .IX Subsection "generate_doc ( top_class_name , directory , [ %done ] )" Generate \s-1POD\s0 document for configuration class top_class_name and all classes used by top_class_name, and write them in specified directory. .PP \&\f(CW\*(C`\e%done\*(C'\fR is an optional reference to a hash used to avoid writing twice the same documentation when this method is called several times. .SS "get_element_model( config_class_name , element)" .IX Subsection "get_element_model( config_class_name , element)" Return a hash containing the model declaration for the specified class and element. .SS "get_element_name( class => Foo )" .IX Subsection "get_element_name( class => Foo )" Get all names of the elements of class \f(CW\*(C`Foo\*(C'\fR. .SS "get_element_property" .IX Subsection "get_element_property" Returns the property of an element from the model. .PP Parameters are: .IP "class" 4 .IX Item "class" .PD 0 .IP "element" 4 .IX Item "element" .IP "property" 4 .IX Item "property" .PD .SS "list_class_element" .IX Subsection "list_class_element" Returns a string listing all the class and elements. Useful for debugging your configuration model. .SH "Error handling" .IX Header "Error handling" Errors are handled with an exception mechanism. .PP When a strongly typed Value object gets an authorized value, it raises an exception. If this exception is not caught, the programs exits. .PP See Config::Model::Exception for details on the various exception classes provided with \f(CW\*(C`Config::Model\*(C'\fR. .SH "Logging" .IX Header "Logging" See \*(L"Logging\*(R" in cme .SS "initialize_log4perl" .IX Subsection "initialize_log4perl" This method can be called to load Log::Log4perl configuration from \&\f(CW\*(C`~/.log4config\-model\*(C'\fR, or from \f(CW\*(C`/etc/log4config\-model.conf\*(C'\fR files or from default configuration . .PP Accepts \f(CW\*(C`verbose\*(C'\fR parameter with a list of log classes that are added to the log4perl configuration read above. .PP For instance, with \f(CW\*(C`verbose => \*(AqLoader\*(Aq\*(C'\fR, log4perl is initialised with .PP .Vb 1 \& log4perl.logger.Verbose.Loader = INFO, PlainMsgOnScreen .Ve .PP Likewise, with \f(CW\*(C`verbose => [ \*(AqLoader\*(Aq, \*(AqFoo\*(Aq ]\*(C'\fR, log4perl is initialised with: .PP .Vb 2 \& log4perl.logger.Verbose.Loader = INFO, PlainMsgOnScreen \& log4perl.logger.Verbose.Foo = INFO, PlainMsgOnScreen .Ve .PP Currently, this module supports only \f(CW\*(C`Loader\*(C'\fR as verbose parameters. .SH "BUGS" .IX Header "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. .SH "FEEDBACK" .IX Header "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. .SH "PROJECT FOUNDER" .IX Header "PROJECT FOUNDER" Dominique Dumont, \*(L"ddumont@cpan.org\*(R" .SH "CREDITS" .IX Header "CREDITS" Contributors to this project are listed in alphabetical order: .PP .Vb 1 \& Harley Pig \& \& Ilya Arosov \& \& Jose Luis Perez Diez \& \& Krzysztof Tyszecki \& \& Mathieu Arnold \& \& Mohammad S Anwar \& \& Topi Miettinen .Ve .PP Many thanks for your help .SH "SEE ALSO" .IX Header "SEE ALSO" Config::Model::Instance, .PP .PP .SS "Model elements" .IX Subsection "Model elements" The arrow shows inheritance between classes .IP "\(bu" 4 Config::Model::Node <\- Config::Model::AnyThing .IP "\(bu" 4 Config::Model::HashId <\- Config::Model::AnyId <\- Config::Model::AnyThing .IP "\(bu" 4 Config::Model::ListId <\- Config::Model::AnyId <\- Config::Model::AnyThing .IP "\(bu" 4 Config::Model::Value <\- Config::Model::AnyThing .IP "\(bu" 4 Config::Model::CheckList <\- Config::Model::AnyThing .IP "\(bu" 4 Config::Model::WarpedNode <\- Config::Model::AnyThing .SS "command line" .IX Subsection "command line" cme. .SS "Read and write backends" .IX Subsection "Read and write backends" .IP "\(bu" 4 Config::Model::Backend::Fstab <\- Config::Model::Backend::Any .IP "\(bu" 4 Config::Model::Backend::IniFile <\- Config::Model::Backend::Any .IP "\(bu" 4 Config::Model::Backend::PlainFile <\- Config::Model::Backend::Any .IP "\(bu" 4 Config::Model::Backend::ShellVar <\- Config::Model::Backend::Any .SS "Model utilities" .IX Subsection "Model utilities" .IP "\(bu" 4 Config::Model::Annotation .IP "\(bu" 4 Config::Model::BackendMgr: Used by \f(CW\*(C`Config::Model::Node\*(C'\fR object .IP "\(bu" 4 Config::Model::Describe .IP "\(bu" 4 Config::Model::Dumper .IP "\(bu" 4 Config::Model::DumpAsData .IP "\(bu" 4 Config::Model::IdElementReference .IP "\(bu" 4 Config::Model::Iterator .IP "\(bu" 4 Config::Model::Loader .IP "\(bu" 4 Config::Model::ObjTreeScanner .IP "\(bu" 4 Config::Model::Report .IP "\(bu" 4 Config::Model::Searcher: Search element in configuration model. .IP "\(bu" 4 Config::Model::SimpleUI .IP "\(bu" 4 Config::Model::TreeSearcher: Search string or regexp in configuration tree. .IP "\(bu" 4 Config::Model::TermUI .IP "\(bu" 4 Config::Model::Iterator .IP "\(bu" 4 Config::Model::ValueComputer .IP "\(bu" 4 Config::Model::Warper .SS "Test framework" .IX Subsection "Test framework" .IP "\(bu" 4 Config::Model::Tester .SH "AUTHOR" .IX Header "AUTHOR" Dominique Dumont .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" This software is Copyright (c) 2005\-2022 by Dominique Dumont. .PP This is free software, licensed under: .PP .Vb 1 \& The GNU Lesser General Public License, Version 2.1, February 1999 .Ve .SH "SUPPORT" .IX Header "SUPPORT" .SS "Websites" .IX Subsection "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. .IP "\(bu" 4 \&\s-1CPANTS\s0 .Sp The \s-1CPANTS\s0 is a website that analyzes the Kwalitee ( code metrics ) of a distribution. .Sp .IP "\(bu" 4 \&\s-1CPAN\s0 Testers .Sp The \s-1CPAN\s0 Testers is a network of smoke testers who run automated tests on uploaded \s-1CPAN\s0 distributions. .Sp .IP "\(bu" 4 \&\s-1CPAN\s0 Testers Matrix .Sp The \s-1CPAN\s0 Testers Matrix is a website that provides a visual overview of the test results for a distribution on various Perls/platforms. .Sp .IP "\(bu" 4 \&\s-1CPAN\s0 Testers Dependencies .Sp The \s-1CPAN\s0 Testers Dependencies is a website that shows a chart of the test results of all dependencies for a distribution. .Sp .SS "Bugs / Feature Requests" .IX Subsection "Bugs / Feature Requests" Please report any bugs or feature requests by email to \f(CW\*(C`ddumont at cpan.org\*(C'\fR, or through the web interface at . You will be automatically notified of any progress on the request by the system. .SS "Source Code" .IX Subsection "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 :) .PP .PP .Vb 1 \& git clone git://github.com/dod38fr/config\-model.git .Ve