templates status

for now, these templates are available:

 Name  Description 
 shell  handles the shell type files, that's a lot of config files 
 values_section  handles shell type files, plus sections 
 apache  handles the apache configuratino files 
 passwd  handles the /ect/passwd types files, like /etc/group ... 
 xinetd  handlaes the xinetd config files 
 samba  handle the samba config files 
 sshd  handles the ssh config files 
 XF86Config  handles the XFree config files 

CAVEAT : the templates names will be changed, and the template inheritance will be coded, so that it's easier to write new one, and to keep consistancy, without redundance. So this list will change.

TODO

global overview

A template is a set of rules that libconf will use to read and write a given type of conf file. So templates users doesn't have to care about parsing specifications (this is what libconf is designed for...). Technically, a template is a perl structure, containing a list of perl code strings that represents the rules used to parse, write, and edit the config file, plus some other informations :

 Name  Type  description 
 rules  a (ref. on a) list of perl code strings  used to parse the config file. 
 output  a (ref. on a) perl code string  used to write the config file 
 edit_atom  a (ref. on a) perl code string  used to edit the config file 
 comment_output  a (ref. on a) perl code string  used to write commented lines in the config file 
 comments  a (ref. on a) structure  defines the comments type and caracters. 

CAVEAT : the name of the list is rule, and that's bad, it should be input. This will be changed.

global example

libconf template example

Input rules explanations:

Here is an example of input rule :

    q(if ($in =~ s/^\s*(\S+)\s*(.*)\s*$//) {
        $atom->{type} = 'KEY_VALUE';
        $atom->{key} = $1;
        $atom->{value} = $2;
        $out->{current_sections} and $atom->{sections} = ?@{$out->{current_sections}};
        $matched = 1;
     })

Each rule is evaluated for each line of the config file, in a specific context, where some variables are defined:

 Name  Type  Description 
 $_  scalar (string)  the content of the configuration file line being parsed. 
 $atom  reference on hash  the atom the rule has to fill. The atoms plus some additional infos will be the final libcon structure returned. 
 $out  reference on a hash  can be used to store keys/variables to be shared between rules. It is very convenient to keep trace of sections deepeness, or if an atom has to be set from informations from mutliples lines of the config file (see later). 
 $matched  scalar (boolean)  should be set to 1 if the rule matched the line. 

Output rules explanations:

Here is an example of an output rule:

    q(
      if ($atom->{type} eq 'KEY_VALUE') {
          my ($include_type, $include_name) = ($atom->{include_type}, $atom->{include_name});
          return qq($include_type = $include_name\n);
     })

CAVEAT : you can see that the output rules (in the libconf template example) are in a single string, wheras the input rules are in a list. This is not logical, and will be changed, so that output rules will be in a perl list too. This allow to add rules easily. This feature will be used when implementing the template heritance

Each rule is evaluated for each line of the config file, in a specific context, where some variables are defined:

 Name  Type  Description 
 $atom  reference on hash  the atom the rule has to fill. The atoms plus some additional infos will be the final libcon structure returned. 

Each rule should return some string correspondig to the given atom, that will be written in the config file.

Comment rule:

A special comment_output rule has to be in the template, to define how the comments should be written. Here is an example of the comment rule:

    q(
      my $indent = $INDENT_SPACES x $out->{current_indentation};
      /^(\s*)$/ ? "$indent$_\n" : "$indent#$_\n"
      )

This rule is applied for each comment line of each atom, in a specific context, where some variables are defined:

 Name  Type  Description 
 $_  scalar (string)  the comment to be written to the config file. 
 $out  reference on a hash  can be used to get stored keys/variables, like the current indentation. 
 $INDENT_SPACES  scalar (const)  this const represents the indentation spaces 

The rule should return som string coreesponding to the given comment, that will be writtent to the config file.

atoms types

KEY_VALUE

This is the basic atom, that is made to store the informations of simple key is value lines. like key=value, key value, ... This atom can contains:

 Name  Type  Mandatory  Description/value 
 type  scalar (string)  yes  'KEY_VALUE' 
 key  scalar (string)  yes  atom key (e.g. : login
 value  scalar (string)  yes  atom value (e.g. : admin
 sections  reference on a list  no  if there are sections in the configuration file, you should set sections to the list of sections in which the atom is, in order. 

SECTION

This is the atom corresponding to the beginning of a section. This atom can contain:

 Name  Type  Mandatory  Description/value 
 type  scalar (string)  yes  'SECTION' 
 section_name  scalar (string)  yes  section name (e.g. : Display
 section_type  scalar (string)  no  section type, if the sections have multiple types (e.g. : ?IfDefine

ENDSECTION

This is the atom corresponding to the end of a section. This atom can contain:

 Name  Type  Mandatory  Description/value 
 type  scalar (string)  yes  'ENDSECTION' 
 section_type  scalar (string)  no  section type, if the sections have multiple types (e.g. : ?IfDefine

INCLUDE

This is the atom corresponding of the inclusion of another configuration file

 Name  Type  Mandatory  Description/value 
 type  scalar (string)  yes  'ENDSECTION' 
 include_name  scalar (string)  yes  name of the include (e.g. : additional.conf
 include_type  scalar (string)  no  type of the include if there might be different include types (e.g. : includedir

Last edited on November 2, 2002 5:24 pm.