Libconf::Templates - Libconf low level templates common module
Libconf::Templates is a class that represents a config file at a low level.
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.
Set or unset the strict behaviour. Can be set with : use Libconf::Templates qw(nostrict) or use Libconf::Templates qw(strict)
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.
This STRING is written for each indentation level. Default: 4 space chars ' '
if set to true, unused space characters (+ tabs, ...) are removed when writing down a config file. Default: true.
See their documentation for specific methods
Libconf::Templates::Generic::KeyValue : Libconf low level template for semantic (KEY VALUE) styles config files.
Libconf::Templates::Generic::KeyValueSections : Libconf low level template for semantic (KEY VALUE) + sections styles config files.
Libconf::Templates::Generic::KeyValues : Libconf low level template for semantic (KEY (list of named VALUES)) styles config files.
Libconf::Templates::Generic::List : Libconf low level template for semantic (LIST) informations styles config files.
Libconf::Templates::Generic::Sections : Libconf low level template for semantic (SECTIONS) handling in config files.
Libconf::Templates::Generic::Value : Libconf low level template for semantic (VALUE) styles config files.
Libconf::Templates::Generic::Value : Libconf low level template for semantic (KEY LIST) styles config files.
Libconf::Templates::Shell : Libconf low level template for shell styles config files.
Libconf::Templates::Group : Libconf low level template for group config files
Libconf::Templates::Passwd : Libconf low level template for password config files
Libconf::Templates::Samba : Libconf low level template for samba config files
Libconf::Templates::XF86Config : Libconf low level template for XF86Config/Xorg config files
$template->read_conf();
$template->read_conf($alternate_filename);
arguments
$filename [type : STRING, default : $self->{filename}] : Specifies the file to read.
description
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.
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.
Usually you want to simply do :
$template->read_conf(); # reads the config file associated to the template
If you want, you can read an alternate config file like this :
$template->read_conf($alternate_filename); # reads another filename
But I doubt it is useful, if you want to work on another file, you should do :
$template->set_filename($alternate_filename); # change the file we are working on
$template->read_conf(); # reads the config file associated to the template
It doesn't return anything, but stores the interpreted values in $template->{atoms}.
$template->write_conf();
$template->write_conf($alternate_filename);
arguments
$filename [type : STRING, default : $self->{filename}] : Specifies the file to write into.
description
This method writes the config file by following the rules of the template. This function is very useful.
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.
Usually you want to simply do :
$template->write_conf(); # writes the config file associated to the template
If you want, you can write an alternate config file like this :
$template->write_conf($alternate_filename); # writes down another filename
But I doubt it is useful, if you want to work on another file, you should do :
$template->set_filename($alternate_filename); # change the file we are working on
$template->write_conf(); # writes the config associated to the template
$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' ] });
...
arguments
$index [type : 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.
$struct1 [type : 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.
$struct2 [type : 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.
description
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.
$template->append_atom({type => 'KEYVALUE', key => 'foo', value => $value });
arguments
$atom [type : HASH_REF ] : reference on an atom structure.
description
appends an atom at the end of the template
$template->insert_atom($position, { type => 'KEY_VALUE', sections => [ @depth ], key => $key, value => $value} );
arguments
$index [type : INTEGER ] : position where to insert the atom
$atom [type : HASH_REF ] : reference on an atom structure.
description
inserts the given atom at the given position. atoms are shift to the right.
my $atom = $template->get_atom($atom_pos)
arguments
$atom_pos [type : INTEGER ] : position of the atom.
description
Returns the atom located at the given position.
my $comments = $template->get_comments($atom_pos)
arguments
$atom_pos [type : INTEGER ] : position of the atom.
description
Returns a structure representing the comments associated to the atom. see how it is structured with: use Data::Dumper; print Dumper($comments) . "\n";
$template->set_comments($atom_pos, $comments)
arguments
$atom_pos [type : INTEGER ] : position of the atom. $comments [type : HASHREF ] : comments of the atom.
description
Set the comments of an atom. the structure comments has the same format as described in get_comments.
my $commented_string = $template->comment_string($string, $comment_number)
arguments
$string [type : STRING ] : string to comment. $comment_number [type : INTEGER ] : optional, specify which comment to use. If not set, the first comment will be used.
description
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
my $uncommented_string = $template->uncomment_string($commented_string)
arguments
$commented_string [type : STRING ] : string to uncomment.
description
This function takes a commented string and uncomments it, using the comments structure of the template.
my $size = $template->get_size();
description
returns the number of atoms of the template.
my $section_size = $template->get_section_size($section_atom_pos)
arguments
$section_atom_pos [type : INTEGER ] : position of the section.
description
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.
my $last_atom = $template->get_section_end_atom($section_atom_pos)
arguments
$section_atom_pos [type : INTEGER ] : position of the section.
description
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).
$template->clear();
description
Clears the atoms of the templates. The templates is then empty of any configuration informations. But it keeps its settings.
$template->delete_atom(5);
description
removes the atom at the given position.
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);
arguments
$struct [type : HASH_REF] : This hash ref contains the properties that the atom looked for should be compliant to.
$first_atom [type : INTEGER, default : 0 ] : If specified, the search is started from this position.
$last_atom_atom [type : INTEGER, default : scalar(@{$self->{atoms}}) ] : If specified, the search is stopped at this position.
description
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.
# deletes the 5th section. This section has no ENDSECTION atom to indicate its termination.
$template->delete_section(4, 1);
# deletes the 1st section. This is a normal section, with ENDSECTION termination
$template->delete_section(0);
$nb_atom -= $template->delete_section(4);
my @removed_atom = $template->delete_section(4);
arguments
$section_pos [type : INTEGER ] : position of the section to delete.
$no_end_section [type : 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.
description
deletes the given section. The section and the atoms it contains are removed from the template. Returns the list of atoms removed.
# clears the 5th section. This section has no ENDSECTION atom to indicate its termination.
$template->clear_section(4, 1)
# clears the 1st section. This is a normal section, with ENDSECTION termination
$template->clear_section(1)
$nb_atom -= $template->clear_section(4);
my @removed_atom = $template->clear_section(4);
arguments
$section_pos [type : INTEGER ] : position of the section to delete.
$no_end_section [type : 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.
description
clears the given section. The atoms it contains are removed, but the section is still kept, empty. Returns the list of atoms removed.
# will perform the regexp /\Qfoo.*bar\E/ on the templates comments
my $is_in_comment = $template->match_in_struct_comments('foo.*bar')
# will perform the regexp /foo.*bar/ on the templates comments
my $is_in_comment = $template->match_in_struct_comments('foo.*bar', 1)
arguments
$expression [type : STRING ] : expression to look for in the template.
$evaluate_expression [type : BOOLEAN ] : if 1, tells that the expression should not be escaped when passed to the regexp matcher.
description
returns 1 if the given expression matches in any templates comments. If $evaluate_expression is true, EXPR will be evaluated in the pattern matching.
my $template = new Libconf::Templates::Samba({filename => 'smb.conf'});
$template->read_conf();
# 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));
description
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)