summaryrefslogtreecommitdiff
path: root/Master/tlpkg/TeXLive/TLConfFile.pm
diff options
context:
space:
mode:
authorNorbert Preining <preining@logic.at>2010-05-28 17:40:41 +0000
committerNorbert Preining <preining@logic.at>2010-05-28 17:40:41 +0000
commit4bc1cf423b49c531b338ad185e9c2c8bfda0dd32 (patch)
treebac7052e6acb30b209529cba82cf1e95eb2391c7 /Master/tlpkg/TeXLive/TLConfFile.pm
parent4c549328c10ed052b6aa5f29434c661e2534b82f (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/TLConfFile.pm')
-rw-r--r--Master/tlpkg/TeXLive/TLConfFile.pm110
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