<?xml version="1.0" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>Libconf::Templates - Libconf low level templates common module</title>
<meta http-equiv="content-type" content="text/html; charset=utf-8" />
<link rev="made" href="mailto:root@localhost" />
</head>
<body style="background-color: white">
<!-- INDEX BEGIN -->
<div name="index">
<p><a name="__index__"></a></p>
<ul>
<li><a href="#name">NAME</a></li>
<li><a href="#description">DESCRIPTION</a></li>
<li><a href="#global_options">GLOBAL OPTIONS</a></li>
<li><a href="#template_list">TEMPLATE LIST</a></li>
<li><a href="#template_general_methods">TEMPLATE GENERAL METHODS</a></li>
</ul>
<hr name="index" />
</div>
<!-- INDEX END -->
<p>
</p>
<h1><a name="name">NAME</a></h1>
<p>Libconf::Templates - Libconf low level templates common module</p>
<p>
</p>
<hr />
<h1><a name="description">DESCRIPTION</a></h1>
<p>Libconf::Templates is a class that represents a config file at a low level.</p>
<p>
</p>
<hr />
<h1><a name="global_options">GLOBAL OPTIONS</a></h1>
<dl>
<dt><strong><a name="_libconf__templates__warn" class="item"><strong>$Libconf::Templates::Warn</strong></a></strong></dt>
<dd>
<p>Set or unset warnings issued by this module. Can be set with :
use Libconf::Templates qw(nowarn)
or
use Libconf::Templates qw(warn)
Default: true.</p>
</dd>
<dt><strong><a name="_libconf__templates__strict" class="item"><strong>$Libconf::Templates::Strict</strong></a></strong></dt>
<dd>
<p>Set or unset the strict behaviour. Can be set with :
use Libconf::Templates qw(nostrict)
or
use Libconf::Templates qw(strict)</p>
<p>If strict is enabled, informations not understood will be treated as invalid, whereas if strict is disabled, informations not understood will be stored and outputed as it was found. Default: true.</p>
</dd>
<dt><strong><a name="_libconf__templates__indentspaces" class="item"><strong>$Libconf::Templates::Indentspaces</strong></a></strong></dt>
<dd>
<p>This STRING is written for each indentation level. Default: 4 space chars ' '</p>
</dd>
<dt><strong><a name="_libconf__templates__trimspaces" class="item"><strong>$Libconf::Templates::Trimspaces</strong></a></strong></dt>
<dd>
<p>if set to true, unused space characters (+ tabs, ...) are removed when writing
down a config file. Default: true.</p>
</dd>
</dl>
<p>
</p>
<hr />
<h1><a name="template_list">TEMPLATE LIST</a></h1>
<p>See their documentation for specific methods</p>
<dl>
<dt><strong><a name="keyvalue" class="item"><strong>KeyValue</strong></a></strong></dt>
<dd>
<p><a href="./Libconf/Templates/Generic/KeyValue.html">the Libconf::Templates::Generic::KeyValue manpage</a> : Libconf low level template for semantic (KEY VALUE) styles config files.</p>
</dd>
<dt><strong><a name="keyvaluesections" class="item"><strong>KeyValueSections</strong></a></strong></dt>
<dd>
<p><a href="./Libconf/Templates/Generic/KeyValueSections.html">the Libconf::Templates::Generic::KeyValueSections manpage</a> : Libconf low level template for semantic (KEY VALUE) + sections styles config files.</p>
</dd>
<dt><strong><a name="keyvalues" class="item"><strong>KeyValues</strong></a></strong></dt>
<dd>
<p><a href="./Libconf/Templates/Generic/KeyValues.html">the Libconf::Templates::Generic::KeyValues manpage</a> : Libconf low level template for semantic (KEY (list of named VALUES)) styles config files.</p>
</dd>
<dt><strong><a name="list" class="item"><strong>List</strong></a></strong></dt>
<dd>
<p><a href="./Libconf/Templates/Generic/List.html">the Libconf::Templates::Generic::List manpage</a> : Libconf low level template for semantic (LIST) informations styles config files.</p>
</dd>
<dt><strong><a name="sections" class="item"><strong>Sections</strong></a></strong></dt>
<dd>
<p><a href="./Libconf/Templates/Generic/Sections.html">the Libconf::Templates::Generic::Sections manpage</a> : Libconf low level template for semantic (SECTIONS) handling in config files.</p>
</dd>
<dt><strong><a name="value" class="item"><strong>Value</strong></a></strong></dt>
<dd>
<p><a href="./Libconf/Templates/Generic/Value.html">the Libconf::Templates::Generic::Value manpage</a> : Libconf low level template for semantic (VALUE) styles config files.</p>
</dd>
<dt><strong><a name="keylist" class="item"><strong>KeyList</strong></a></strong></dt>
<dd>
<p><a href="./Libconf/Templates/Generic/Value.html">the Libconf::Templates::Generic::Value manpage</a> : Libconf low level template for semantic (KEY LIST) styles config files.</p>
</dd>
<dt><strong><a name="shell" class="item"><strong>Shell</strong></a></strong></dt>
<dd>
<p><a href="./Libconf/Templates/Shell.html">the Libconf::Templates::Shell manpage</a> : Libconf low level template for shell styles config files.</p>
</dd>
<dt><strong><a name="group" class="item"><strong>Group</strong></a></strong></dt>
<dd>
<p><a href="./Libconf/Templates/Group.html">the Libconf::Templates::Group manpage</a> : Libconf low level template for group config files</p>
</dd>
<dt><strong><a name="passwd" class="item"><strong>Passwd</strong></a></strong></dt>
<dd>
<p><a href="./Libconf/Templates/Passwd.html">the Libconf::Templates::Passwd manpage</a> : Libconf low level template for password config files</p>
</dd>
<dt><strong><a name="samba" class="item"><strong>Samba</strong></a></strong></dt>
<dd>
<p><a href="./Libconf/Templates/Samba.html">the Libconf::Templates::Samba manpage</a> : Libconf low level template for samba config files</p>
</dd>
<dt><strong><a name="xf86config" class="item"><strong>XF86Config</strong></a></strong></dt>
<dd>
<p><a href="./Libconf/Templates/XF86Config.html">the Libconf::Templates::XF86Config manpage</a> : Libconf low level template for XF86Config/Xorg config files</p>
</dd>
</dl>
<p>
</p>
<hr />
<h1><a name="template_general_methods">TEMPLATE GENERAL METHODS</a></h1>
<dl>
<dt><strong><a name="read_conf" class="item"><strong>read_conf()</strong></a></strong></dt>
<dt><strong><strong>read_conf($filename)</strong></strong></dt>
<dd>
<pre>
$template->read_conf();
$template->read_conf($alternate_filename);</pre>
<p><strong>arguments</strong></p>
<p>$filename [<strong>type</strong> : STRING, <strong>default</strong> : $self->{filename}] : Specifies the file to read.</p>
<p><strong>description</strong></p>
<p>This method reads the config file by following the rules of the template. The
datas created are attached to the template instance. This function is very
useful.</p>
<p>Note that the file is read using the special encoding $self->{encoding}, if
specified. If not specified, it is up to perl to choose the encoding.</p>
<p>Usually you want to simply do :</p>
<pre>
$template->read_conf(); # reads the config file associated to the template</pre>
<p>If you want, you can read an alternate config file like this :</p>
<pre>
$template->read_conf($alternate_filename); # reads another filename</pre>
<p>But I doubt it is useful, if you want to work on another file, you should do :</p>
<pre>
$template->set_filename($alternate_filename); # change the file we are working on
$template->read_conf(); # reads the config file associated to the template</pre>
<p>It doesn't return anything, but stores the interpreted values in $template->{atoms}.</p>
</dd>
<dt><strong><a name="write_conf" class="item"><strong>write_conf()</strong></a></strong></dt>
<dt><strong><strong>write_conf($filename)</strong></strong></dt>
<dd>
<pre>
$template->write_conf();
$template->write_conf($alternate_filename);</pre>
<p><strong>arguments</strong></p>
<p>$filename [<strong>type</strong> : STRING, <strong>default</strong> : $self->{filename}] : Specifies the file to write into.</p>
<p><strong>description</strong></p>
<p>This method writes the config file by following the rules of the template. This function is very useful.</p>
<p>Note that the file is written using the special encoding $self->{encoding}, if
specified. If not specified, it is up to perl to choose the encoding.</p>
<p>Usually you want to simply do :</p>
<pre>
$template->write_conf(); # writes the config file associated to the template</pre>
<p>If you want, you can write an alternate config file like this :</p>
<pre>
$template->write_conf($alternate_filename); # writes down another filename</pre>
<p>But I doubt it is useful, if you want to work on another file, you should do :</p>
<pre>
$template->set_filename($alternate_filename); # change the file we are working on
$template->write_conf(); # writes the config associated to the template</pre>
</dd>
<dt><strong><a name="edit_atom" class="item"><strong>edit_atom($index, $struct1, $struct2)</strong></a></strong></dt>
<dd>
<pre>
$template->edit_atom(5, { key => 'AUTOLOGIN',
value => 'no' }
);
$template->edit_atom(-1, { key => 'daemon' },
{ values => { passwd => 'x',
GID => 2,
user_list => 'root,bin,daemon,ldap,rpc'
}
});
$template->edit_atom(-1, { values => { foo => 'some value',
}
},
{ values => { foo => 'some value',
bar => 'an other value',
}
});
$template->edit_atom(-1, { list => [ 'some value', 2 ] }, { list => [ 'foo', 2, 3, 'an other value' ] });
...</pre>
<p><strong>arguments</strong></p>
<p>$index [<strong>type</strong> : INTEGER] : Specify the atom to edit (first atom is 0). If $index = -1, the method will
try to find the atom that is the most similar to $struct, then edit it.</p>
<p>$struct1 [<strong>type</strong> : HASH_REF] : If $index is NOT -1, this structure contains
the new properties of the atom at $index. Properties are added or overwritten,
but not removed from the atom.
If $index is equal to -1, then this struct contains the properties to be looked
for in the atom lists of the template.</p>
<p>$struct2 [<strong>type</strong> : HASH_REF] : Used only if $index is equal to -1, this
structure contains the new properties of the atom at $index. Properties are
added or overwritten, but not removed from the atom.</p>
<p><strong>description</strong></p>
<p>This method allows to edit one atom, by setting its properties to the struct
ones. It returns the atom index that has been modified (usefull when -1 is
passed), or -2 if $index was equal to -1 but no atom where found.</p>
</dd>
<dt><strong><a name="append_atom" class="item"><strong>append_atom($atom)</strong></a></strong></dt>
<dd>
<pre>
$template->append_atom({type => 'KEYVALUE', key => 'foo', value => $value });</pre>
<p><strong>arguments</strong></p>
<p>$atom [<strong>type</strong> : HASH_REF ] : reference on an atom structure.</p>
<p><strong>description</strong></p>
<p>appends an atom at the end of the template</p>
</dd>
<dt><strong><a name="insert_atom" class="item"><strong>insert_atom($index, $atom)</strong></a></strong></dt>
<dd>
<pre>
$template->insert_atom($position, { type => 'KEY_VALUE', sections => [ @depth ], key => $key, value => $value} );</pre>
<p><strong>arguments</strong></p>
<p>$index [<strong>type</strong> : INTEGER ] : position where to insert the atom</p>
<p>$atom [<strong>type</strong> : HASH_REF ] : reference on an atom structure.</p>
<p><strong>description</strong></p>
<p>inserts the given atom at the given position. atoms are shift to the right.</p>
</dd>
<dt><strong><a name="get_atom" class="item"><strong>get_atom($atom_pos)</strong></a></strong></dt>
<dd>
<pre>
my $atom = $template->get_atom($atom_pos)</pre>
<p><strong>arguments</strong></p>
<p>$atom_pos [<strong>type</strong> : INTEGER ] : position of the atom.</p>
<p><strong>description</strong></p>
<p>Returns the atom located at the given position.</p>
</dd>
<dt><strong><a name="get_comments" class="item"><strong>get_comments($atom_pos)</strong></a></strong></dt>
<dd>
<pre>
my $comments = $template->get_comments($atom_pos)</pre>
<p><strong>arguments</strong></p>
<p>$atom_pos [<strong>type</strong> : INTEGER ] : position of the atom.</p>
<p><strong>description</strong></p>
<p>Returns a structure representing the comments associated to the atom.
see how it is structured with:
use Data::Dumper;
print <code>Dumper($comments)</code> . "\n";</p>
</dd>
<dt><strong><a name="set_comments" class="item"><strong>set_comments($atom_pos)</strong></a></strong></dt>
<dd>
<pre>
$template->set_comments($atom_pos, $comments)</pre>
<p><strong>arguments</strong></p>
<p>$atom_pos [<strong>type</strong> : INTEGER ] : position of the atom.
$comments [<strong>type</strong> : HASHREF ] : comments of the atom.</p>
<p><strong>description</strong></p>
<p>Set the comments of an atom. the structure comments has the same format as
described in get_comments.</p>
</dd>
<dt><strong><a name="comment_string" class="item"><strong>comment_string($string, $comment_number)</strong></a></strong></dt>
<dd>
<pre>
my $commented_string = $template->comment_string($string, $comment_number)</pre>
<p><strong>arguments</strong></p>
<p>$string [<strong>type</strong> : STRING ] : string to comment.
$comment_number [<strong>type</strong> : INTEGER ] : optional, specify which comment to use. If not set, the first comment will be used.</p>
<p><strong>description</strong></p>
<p>This function takes a normal string and comments it, using the comment of the
template. If there are more than one way to comment things, you can indicate
which comment should be used with the second argument</p>
</dd>
<dt><strong><a name="uncomment_string" class="item"><strong>uncomment_string($string)</strong></a></strong></dt>
<dd>
<pre>
my $uncommented_string = $template->uncomment_string($commented_string)</pre>
<p><strong>arguments</strong></p>
<p>$commented_string [<strong>type</strong> : STRING ] : string to uncomment.</p>
<p><strong>description</strong></p>
<p>This function takes a commented string and uncomments it, using the comments
structure of the template.</p>
</dd>
<dt><strong><a name="get_size" class="item"><strong>get_size()</strong></a></strong></dt>
<dd>
<pre>
my $size = $template->get_size();</pre>
<p><strong>description</strong></p>
<p>returns the number of atoms of the template.</p>
</dd>
<dt><strong><a name="get_section_size" class="item"><strong>get_section_size($section_atom_pos)</strong></a></strong></dt>
<dd>
<pre>
my $section_size = $template->get_section_size($section_atom_pos)</pre>
<p><strong>arguments</strong></p>
<p>$section_atom_pos [<strong>type</strong> : INTEGER ] : position of the section.</p>
<p><strong>description</strong></p>
<p>Given the atom position of the beginning of a section, returns the number of
atoms of the section, including the 'SECTION' and 'ENDSECTION' (if available)
atoms.</p>
</dd>
<dt><strong><a name="get_section_end_atom" class="item"><strong>get_section_end_atom($section_atom_pos)</strong></a></strong></dt>
<dd>
<pre>
my $last_atom = $template->get_section_end_atom($section_atom_pos)</pre>
<p><strong>arguments</strong></p>
<p>$section_atom_pos [<strong>type</strong> : INTEGER ] : position of the section.</p>
<p><strong>description</strong></p>
<p>Given the atom position of the beginning of a section, returns the position of the
last atom of the section, (usually the ENDSECTION atom if the sections have ENDSECTIONS).</p>
</dd>
<dt><strong><a name="clear" class="item"><strong>clear()</strong></a></strong></dt>
<dd>
<pre>
$template->clear();</pre>
<p><strong>description</strong></p>
<p>Clears the atoms of the templates. The templates is then empty of any
configuration informations. But it keeps its settings.</p>
</dd>
<dt><strong><a name="delete_atom" class="item"><strong>delete_atom()</strong></a></strong></dt>
<dd>
<pre>
$template->delete_atom(5);</pre>
<p><strong>description</strong></p>
<p>removes the atom at the given position.</p>
</dd>
<dt><strong><a name="find_atom_pos" class="item"><code>find_atom_pos($struct)</code></a></strong></dt>
<dt><strong>find_atom_pos($struct, $first_atom)</strong></dt>
<dt><strong>find_atom_pos($struct, $first_atom, $last_atom)</strong></dt>
<dd>
<pre>
my @atom_pos = $template->find_atom_pos({key => 'AUTOLOGIN', value => 'yes'});
my $last_atom_pos = $template->find_atom_pos({key => 'AUTOLOGIN', value => 'yes'});
my $last_atom_pos = $template->find_atom_pos({key => 'AUTOLOGIN', value => 'yes'}, 5, 10);</pre>
<p><strong>arguments</strong></p>
<p>$struct [<strong>type</strong> : HASH_REF] : This hash ref contains the properties that the atom looked for should be compliant to.</p>
<p>$first_atom [<strong>type</strong> : INTEGER, <strong>default</strong> : 0 ] : If specified, the search is started from this position.</p>
<p>$last_atom_atom [<strong>type</strong> : INTEGER, <strong>default</strong> : scalar(@{$self->{atoms}}) ] : If specified, the search is stopped at this position.</p>
<p><strong>description</strong></p>
<p>This function allows to find the position of an atom, given a struct that
describes the atom, and an optional interval. In list context, it returns the
list of the positions of the atoms that match the $struct criteria. In scalar
context, returns the last atom position to meet the criteria.</p>
</dd>
<dt><strong><a name="delete_section" class="item"><strong>delete_section($section_pos, $no_end_section)</strong></a></strong></dt>
<dd>
<pre>
# deletes the 5th section. This section has no ENDSECTION atom to indicate its termination.
$template->delete_section(4, 1);</pre>
<pre>
# deletes the 1st section. This is a normal section, with ENDSECTION termination
$template->delete_section(0);</pre>
<pre>
$nb_atom -= $template->delete_section(4);</pre>
<pre>
my @removed_atom = $template->delete_section(4);</pre>
<p><strong>arguments</strong></p>
<p>$section_pos [<strong>type</strong> : INTEGER ] : position of the section to delete.</p>
<p>$no_end_section [<strong>type</strong> : BOOLEAN ] : if 1, tells that the section has no
ENDSECTION atom to indicate its termination. The end of the section is detected
by the start of another section.</p>
<p><strong>description</strong></p>
<p>deletes the given section. The section and the atoms it contains are removed
from the template. Returns the list of atoms removed.</p>
</dd>
<dt><strong><a name="clear_section" class="item"><strong>clear_section($section_pos, $no_end_section)</strong></a></strong></dt>
<dd>
<pre>
# clears the 5th section. This section has no ENDSECTION atom to indicate its termination.
$template->clear_section(4, 1)</pre>
<pre>
# clears the 1st section. This is a normal section, with ENDSECTION termination
$template->clear_section(1)</pre>
<pre>
$nb_atom -= $template->clear_section(4);</pre>
<pre>
my @removed_atom = $template->clear_section(4);</pre>
<p><strong>arguments</strong></p>
<p>$section_pos [<strong>type</strong> : INTEGER ] : position of the section to delete.</p>
<p>$no_end_section [<strong>type</strong> : BOOLEAN ] : if 1, tells that the section has no
ENDSECTION atom to indicate its termination. The end of the section is detected by the start of another section.</p>
<p><strong>description</strong></p>
<p>clears the given section. The atoms it contains are removed, but the section is
still kept, empty. Returns the list of atoms removed.</p>
</dd>
<dt><strong><a name="match_in_comments" class="item"><strong>match_in_comments($expression, $evaluate_expression)</strong></a></strong></dt>
<dd>
<pre>
# will perform the regexp /\Qfoo.*bar\E/ on the templates comments
my $is_in_comment = $template->match_in_struct_comments('foo.*bar')</pre>
<pre>
# will perform the regexp /foo.*bar/ on the templates comments
my $is_in_comment = $template->match_in_struct_comments('foo.*bar', 1)</pre>
<p><strong>arguments</strong></p>
<p>$expression [<strong>type</strong> : STRING ] : expression to look for in the template.</p>
<p>$evaluate_expression [<strong>type</strong> : BOOLEAN ] : if 1, tells that the expression
should not be escaped when passed to the regexp matcher.</p>
<p><strong>description</strong></p>
<p>returns 1 if the given expression matches in any templates comments.
If $evaluate_expression is true, EXPR will be evaluated in the pattern matching.</p>
</dd>
<dt><strong><a name="set_uniq" class="item"><strong>set_uniq()</strong></a></strong></dt>
<dd>
<pre>
my $template = new Libconf::Templates::Samba({filename => 'smb.conf'});
$template->read_conf();</pre>
<pre>
# will ensure there is no duplicated atom. the keys are the element of the
# hash that need to be compared
$libconf->setUniq(qw(type key sections));</pre>
<p><strong>description</strong></p>
<p>This function removes dupliacted atoms from a $template structure. In list
context, it returns the list of the positions of the atoms that has been
removed. In scalar context, returns the first atom that has been removed (this is not really
useful)</p>
</dd>
</dl>
</body>
</html>
