diff options
author | Norbert Preining <preining@logic.at> | 2010-05-28 17:40:41 +0000 |
---|---|---|
committer | Norbert Preining <preining@logic.at> | 2010-05-28 17:40:41 +0000 |
commit | 4bc1cf423b49c531b338ad185e9c2c8bfda0dd32 (patch) | |
tree | bac7052e6acb30b209529cba82cf1e95eb2391c7 /Master/tlpkg/TeXLive | |
parent | 4c549328c10ed052b6aa5f29434c661e2534b82f (diff) |
documentation of TLConfFile.pm
git-svn-id: svn://tug.org/texlive/trunk@18565 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/tlpkg/TeXLive')
-rw-r--r-- | Master/tlpkg/TeXLive/TLConfFile.pm | 110 |
1 files changed, 106 insertions, 4 deletions
diff --git a/Master/tlpkg/TeXLive/TLConfFile.pm b/Master/tlpkg/TeXLive/TLConfFile.pm index a85913da003..ca6204987dc 100644 --- a/Master/tlpkg/TeXLive/TLConfFile.pm +++ b/Master/tlpkg/TeXLive/TLConfFile.pm @@ -396,16 +396,118 @@ C<TeXLive::TLConfFile> -- TeX Live Config File Access Module use TeXLive::TLConfFile; - my $f = TeXLive::TLConfFile->new($file_name, $comment_char, $separator); + $conffile = TeXLive::TLConfFile->new($file_name, $comment_char, $separator); + $conffile->file; + $conffile->cc; + $conffile->sep; + $conffile->key_present($key); + $conffile->keys; + $conffile->value($key [, $value]); + $conffile->is_changed; + $conffile->save; + $conffile->reparse; =head1 DESCRIPTION -To be written +This module allows parsing, changing, saving of configuration files +of a general style. -=head1 SEE ALSO +The configuration files (henceforth conffiles) can contain comments +initiated by the $comment_char defined at instantiation time. +Everything after a $comment_char, as well as empty lines, will be ignored. -LWP +The rest should consists of key/value pairs separated by the separator, +defined as well at instantiation time. +Whitespace around the separator, and before and after key and value +are allowed. + +Comments can be on the same line as key/value pairs and are also preserved +over changes. + +Continuation lines (i.e., lines with last character being a backslash) +are allowed after key/value pairs, but the key and +the separator has to be on the same line. + +Continuations are not possible in comments, so a terminal backslash in +a comment will be ignored, and in fact not written out on save. + +=head2 Methods + +=over 4 + +=item B<< $conffile = TeXLive::TLConfFile->new($file_name, $comment_char, $separator) >> + +instantiates a new TLConfFile and returns the object. The file specified +by C<$file_name> does not have to exist, it will be created at save time. + +The C<$comment_char> can actually be any regular expression, but +embedding grouping is a bad idea as it will break parsing. + +The C<$separator> can also be any regular expression. + +=item B<< $conffile->file >> + +Returns the location of the configuration file. Not changeable (at the moment). + +=item B<< $conffile->cc >> + +Returns the comment character. + +=item B<< $conffile->sep >> + +Returns the separator. + +=item B<< $conffile->key_present($key) >> + +Returns true (1) if the given key is present in the config file, otherwise +returns false (0). + +=item B<< $conffile->keys >> + +Returns the list of keys currently set in the config file. + +=item B<< $conffile->value($key [, $value]) >> + +With one argument, returns the current setting of C<$key>, or undefined +if the key is not set. + +With two arguments changes (or adds) the key/value pair to the config +file and returns the I<new> value. + +=item B<< $conffile->is_changed >> + +Returns true (1) if some real change has happened in the configuration file, +that is a value has been changed to something different, or a new +setting has been added. + +Note that changing a setting back to the original one will not reset +the changed flag. + +=item B<< $conffile->save >> + +Saves the config file, preserving as much structure and comments of +the original file as possible. + +=item B<< $conffile->reparse >> + +Reparses the configuration file. + + +=back + +=head1 EXAMPLES + +For parsing a C<texmf.cnf> file you can use + + $tmfcnf = TeXLive::TLConfFile->new(".../texmf/web2c", "[#%]", "="); + +since the allowed comment characters for texmf.cnf files are # and %. +After that you can query keys: + + $tmfcnf->value("TEXMFMAIN"); + $tmfcnf->value("trie_size", 900000); + =head1 AUTHORS AND COPYRIGHT This script and its documentation were written for the TeX Live |