602 lines
17 KiB
HTML
602 lines
17 KiB
HTML
<!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>GT::Config - Dumped-hash configuration handler</title>
|
|
<link rev="made" href="mailto:root@penguin.office.gossamer-threads.com" />
|
|
|
|
<style type="text/css">
|
|
/* $MVD$:fontset("Untitled Font Set 1","ARIEL","HELVETICA","HELV","SANSERIF") */
|
|
/* $MVD$:fontset("Arial","Arial") */
|
|
/* $MVD$:fontset("Arial Black","Arial Black") */
|
|
/* $MVD$:fontset("Algerian","Algerian") */
|
|
|
|
|
|
body {
|
|
background-color: white;
|
|
font-family: Verdana, Arial, sans-serif;
|
|
font-size: small;
|
|
color: black;
|
|
}
|
|
|
|
|
|
p {
|
|
background-color : white;
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-size : small;
|
|
color : black;
|
|
}
|
|
|
|
|
|
h1 {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-weight : bold;
|
|
font-size : medium;
|
|
background-color : white;
|
|
color : maroon;
|
|
}
|
|
|
|
|
|
h2 {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-size : medium;
|
|
font-weight : bold;
|
|
color : blue;
|
|
background-color : white;
|
|
}
|
|
|
|
|
|
h3 {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-weight : bold;
|
|
font-size : medium;
|
|
color : black;
|
|
background-color : white;
|
|
}
|
|
|
|
|
|
h4 {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-weight : bold;
|
|
font-size : small;
|
|
color : maroon;
|
|
background-color : white;
|
|
}
|
|
|
|
|
|
h5 {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-weight : bold;
|
|
font-size : small;
|
|
color : blue;
|
|
background-color : white;
|
|
}
|
|
|
|
|
|
h6 {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-weight : bold;
|
|
font-size : small;
|
|
color : black;
|
|
background-color : white;
|
|
}
|
|
|
|
|
|
ul {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-size : small;
|
|
color : black;
|
|
}
|
|
|
|
|
|
ol {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-size : small;
|
|
color : black;
|
|
}
|
|
|
|
|
|
dl {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-size : small;
|
|
color : black;
|
|
}
|
|
|
|
|
|
li {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-size : small;
|
|
color : black;
|
|
}
|
|
|
|
|
|
th {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-size : small;
|
|
color : black;
|
|
}
|
|
|
|
|
|
td {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-size : small;
|
|
color : black;
|
|
}
|
|
|
|
|
|
dl {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-size : small;
|
|
color : black;
|
|
}
|
|
|
|
|
|
dd {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-size : small;
|
|
color : black;
|
|
}
|
|
|
|
|
|
dt {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-size : small;
|
|
color : black;
|
|
}
|
|
|
|
|
|
code {
|
|
font-family : Courier;
|
|
font-size : small;
|
|
color : black;
|
|
}
|
|
|
|
|
|
pre {
|
|
font-family : Courier;
|
|
font-size : small;
|
|
color : black;
|
|
}
|
|
|
|
.mvd-H1 {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-weight : bold;
|
|
font-size : 14.0pt;
|
|
background-color : transparent;
|
|
background-image : none;
|
|
color : maroon;
|
|
}
|
|
|
|
|
|
.mvd-H2 {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-size : 12.0pt;
|
|
color : blue;
|
|
}
|
|
|
|
|
|
p.indent {
|
|
font-family : "Verdana, Arial, sans-serif";
|
|
list-style-type : circle;
|
|
list-style-position : inside;
|
|
color : black;
|
|
margin-left : 16.0pt;
|
|
}
|
|
|
|
|
|
.mvd-P-indent {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
list-style-type : circle;
|
|
list-style-position : inside;
|
|
color : black;
|
|
margin-left : 16.0pt;
|
|
}
|
|
|
|
|
|
pre.programlisting {
|
|
font-size : 9.0pt;
|
|
list-style-type : disc;
|
|
margin-left : 16.0pt;
|
|
margin-top : -14.0pt;
|
|
}
|
|
|
|
|
|
.mvd-PRE-programlisting {
|
|
font-size : 9.0pt;
|
|
list-style-type : disc;
|
|
margin-left : 16.0pt;
|
|
margin-top : -14.0pt;
|
|
}
|
|
|
|
|
|
.mvd-PRE {
|
|
font-size : 9.0pt;
|
|
}
|
|
|
|
|
|
p.note {
|
|
margin-left : 28.0pt;
|
|
}
|
|
|
|
|
|
.mvd-P-note {
|
|
margin-left : 28.0pt;
|
|
}
|
|
|
|
|
|
.mvd-H4 {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-weight : normal;
|
|
font-size : 9.0pt;
|
|
color : black;
|
|
margin-left : 6.0pt;
|
|
margin-top : -14.0pt;
|
|
}
|
|
|
|
|
|
.mvd-P {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-size : 10.0pt;
|
|
color : black;
|
|
}
|
|
|
|
.mvd-BODY {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
background-color : white;
|
|
}
|
|
|
|
|
|
p.indentnobullet {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
list-style-type : none;
|
|
}
|
|
|
|
|
|
.mvd-P-indentnobullet {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
list-style-type : none;
|
|
}
|
|
</style>
|
|
|
|
|
|
</head>
|
|
|
|
<body style="background-color: white">
|
|
|
|
<p><a name="__index__"></a></p>
|
|
<!-- INDEX BEGIN -->
|
|
|
|
<ul>
|
|
|
|
<li><a href="#name">NAME</a></li>
|
|
<li><a href="#synopsis">SYNOPSIS</a></li>
|
|
<li><a href="#description">DESCRIPTION</a></li>
|
|
<li><a href="#methods">METHODS</a></li>
|
|
<ul>
|
|
|
|
<li><a href="#load">load</a></li>
|
|
<li><a href="#save">save</a></li>
|
|
<li><a href="#cache_hit">cache_hit</a></li>
|
|
<li><a href="#inheritance">inheritance</a></li>
|
|
<li><a href="#create_ok">create_ok</a></li>
|
|
<li><a href="#tmpfile">tmpfile</a></li>
|
|
<li><a href="#cache">cache</a></li>
|
|
<li><a href="#debug_level">debug_level</a></li>
|
|
<li><a href="#header">header</a></li>
|
|
<li><a href="#sort_order">sort_order</a></li>
|
|
</ul>
|
|
|
|
<li><a href="#see_also">SEE ALSO</a></li>
|
|
<li><a href="#maintainer">MAINTAINER</a></li>
|
|
<li><a href="#copyright">COPYRIGHT</a></li>
|
|
<li><a href="#version">VERSION</a></li>
|
|
</ul>
|
|
<!-- INDEX END -->
|
|
|
|
<hr />
|
|
<p>
|
|
</p>
|
|
<h1><a name="name">NAME</a></h1>
|
|
<p>GT::Config - Dumped-hash configuration handler</p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="synopsis">SYNOPSIS</a></h1>
|
|
<pre>
|
|
use GT::Config;
|
|
my $Config = GT::Config->load($config_file);
|
|
...
|
|
print $Config->{variable};
|
|
...
|
|
$Config->{othervar} = "something";
|
|
...
|
|
$Config->save;</pre>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="description">DESCRIPTION</a></h1>
|
|
<p>GT::Config provides a simple way to handle loading config files. It can load
|
|
and save any config file consisting of a dumped hash. You can then use the
|
|
object as if it were the actual hash reference from the config file. It
|
|
supports template set inheritance (see <a href="glist.cgi?do=admin_gtdoc&topic=/GT/Template.html">the GT::Template manpage</a>) and mtime-based
|
|
caching.</p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="methods">METHODS</a></h1>
|
|
<p>
|
|
</p>
|
|
<h2><a name="load">load</a></h2>
|
|
<p>There is no <code>new()</code> method. To get a new config object you do:</p>
|
|
<pre>
|
|
$Config = GT::Config->load("/path/to/config/file", { options });</pre>
|
|
<p>The first argument is the full path to the file to open to read the
|
|
configuration. The file does not necessarily have to exist - see the options
|
|
below.</p>
|
|
<p>The second argument is a hash reference of options, and is optional. The
|
|
possible options are:</p>
|
|
<dl>
|
|
<dt><strong><a name="item_inheritance">inheritance</a></strong><br />
|
|
</dt>
|
|
<dd>
|
|
If provided as something true, GT::Config will scan for .tplinfo files looking
|
|
for inherited template sets. This is typically used for loading globals.txt or
|
|
language.txt files from Gossamer Threads products' template sets.
|
|
</dd>
|
|
<dd>
|
|
<p>Defaults to off.</p>
|
|
</dd>
|
|
<p></p>
|
|
<dt><strong><a name="item_local">local</a></strong><br />
|
|
</dt>
|
|
<dd>
|
|
If provided as something true, GT::Config will look for a ``local'' directory
|
|
containing the file. When using inheritance, a ``local'' directory will also be
|
|
looked for in each inherited configuration file. However, regardless of the
|
|
<a href="#item_inheritance"><code>inheritance</code></a> option, ``local'' configuration files always inherit from their
|
|
non-local counterpart.
|
|
</dd>
|
|
<dd>
|
|
<p>Additionally, this option causes GT::Config to save the file into a ``local''
|
|
directory. Also note that the ``local'' file will _only_ contain keys that were
|
|
already in the local file, or were assigned to the config object after loading
|
|
the file.</p>
|
|
</dd>
|
|
<dd>
|
|
<p>Defaults to off.</p>
|
|
</dd>
|
|
<p></p>
|
|
<dt><strong><a name="item_cache">cache</a></strong><br />
|
|
</dt>
|
|
<dd>
|
|
If provided, will look in the internal cache for a cached copy of the file. If
|
|
none is found, a new GT::Config object will be constructed as usual, then saved
|
|
in the cache.
|
|
</dd>
|
|
<dd>
|
|
<p>Defaults to on. You must pass <code>cache => 0</code> to disable cached loading.
|
|
Note that new objects are always stored in the cache, allowing you to specify
|
|
<code>cache => 0</code> to force a reload of a cached file.</p>
|
|
</dd>
|
|
<p></p>
|
|
<dt><strong><a name="item_create_ok">create_ok</a></strong><br />
|
|
</dt>
|
|
<dd>
|
|
If set, you'll still get back a GT::Config hash even if the file doesn't exist.
|
|
You can then <code>save()</code> the object to create a new config file. If this option is
|
|
not set, a fatal error will occur when attempting to load a file that does not
|
|
exist.
|
|
</dd>
|
|
<dd>
|
|
<p>Defaults to off. Pass in <code>create_ok => 1</code> if the config file doesn't
|
|
necessarily have to exist (i.e. when creating a new config file).</p>
|
|
</dd>
|
|
<p></p>
|
|
<dt><strong><a name="item_empty">empty</a></strong><br />
|
|
</dt>
|
|
<dd>
|
|
The <a href="#item_empty"><code>empty</code></a> option is used to create a new, blank config file - it can be
|
|
thought of as a forced version of the <a href="#item_create_ok"><code>create_ok</code></a> option. It won't read
|
|
<strong>any</strong> files during loading (and as such completely ignores the <a href="#item_inheritance"><code>inheritance</code></a>
|
|
and <a href="#item_cache"><code>cache</code></a> options). This is mainly intended to be used when a complete
|
|
replacement of a file is desired, regardless of what is currently on disk.
|
|
</dd>
|
|
<p></p>
|
|
<dt><strong><a name="item_chmod">chmod</a></strong><br />
|
|
</dt>
|
|
<dd>
|
|
The <a href="#item_chmod"><code>chmod</code></a> option is used to specify the mode of the saved file. It must be
|
|
passed in octal form, such as 0644 (but <strong>not</strong> in string form, such as
|
|
<code>"0644"</code>). The default is 0666, to allow writing by any users. Though not
|
|
terribly secure, this is the sort of environment most CGI scripts require.
|
|
Setting a chmod value of undef instructs GT::Config to not perform a chmod.
|
|
</dd>
|
|
<p></p>
|
|
<dt><strong><a name="item_strict">strict</a></strong><br />
|
|
</dt>
|
|
<dd>
|
|
If set, a fatal error will occur when attempting to access a key of the config
|
|
file that does not exist. Note, however, that this only covers the first level
|
|
data structions - <code>$CFG->{foo}->{bar}</code> will not fatal if <code>foo</code> is a
|
|
hash ref, but <code>bar</code> is not set in that hash reference. <code>$CFG->{foo}</code>
|
|
(and <code>$CFG->{foo}->{bar}</code>) will fatal if the key <code>foo</code> does not exist
|
|
in the config data.
|
|
</dd>
|
|
<p></p>
|
|
<dt><strong><a name="item_debug">debug</a></strong><br />
|
|
</dt>
|
|
<dd>
|
|
If provided, debugging information will be printed. This will also cause a
|
|
warning to occur if <a href="#fatal">fatal</a> is disabled and load fails.
|
|
</dd>
|
|
<dd>
|
|
<p>Defaults to disabled. Should not be used in production code, except when
|
|
debugging.</p>
|
|
</dd>
|
|
<p></p>
|
|
<dt><strong><a name="item_tmpfile">tmpfile</a></strong><br />
|
|
</dt>
|
|
<dd>
|
|
Instructs GT::Config to attempt to use a temporary file when saving. If used,
|
|
the contents will be written to a temporary file, then, if successfully
|
|
written, the temporary file will be moved to overwrite the real file. This
|
|
solves a couple of problems. Firstly, a full disk will never result in a
|
|
partial file as if the entire file is not written to the temporary file, it
|
|
will not overwrite the file already stored on disk. Secondly, it avoids a
|
|
potential problem with multiple processes attempting to write to the file at
|
|
the same time.
|
|
</dd>
|
|
<dd>
|
|
<p>The following values are accepted:</p>
|
|
</dd>
|
|
<dd>
|
|
<pre>
|
|
0 - Do not use a temporary file
|
|
undef - Use a temporary file if the base directory is writable
|
|
1 - Always use a temporary file</pre>
|
|
</dd>
|
|
<dd>
|
|
<p>The default is <code>undef</code>, which will attempt to use a temporary file is
|
|
possible, but won't fail if the script has permission to modify existing files,
|
|
but not to create new ones.</p>
|
|
</dd>
|
|
<p></p>
|
|
<dt><strong><a name="item_header">header</a></strong><br />
|
|
</dt>
|
|
<dd>
|
|
If provided, when saving a file this header will be written above the data.
|
|
Keep in mind that the file must be Perl-compilable, so be careful if you are
|
|
doing anything more than comments.
|
|
</dd>
|
|
<dd>
|
|
<p>Note that the header may contain the string <code>[localtime]</code>, which will be
|
|
replaced with the return value of <code>scalar localtime()</code> when saving, which is
|
|
generally a value such as: <code>Sun Jan 25 15:12:26 2004</code>.</p>
|
|
</dd>
|
|
<p></p>
|
|
<dt><strong><a name="item_tab">tab</a></strong><br />
|
|
</dt>
|
|
<dd>
|
|
If provided, this will set what to use for tabs when calling save(). Defaults
|
|
to an actual tab, since that cuts down the file size over using multiple
|
|
spaces, while leaving the file readable.
|
|
</dd>
|
|
<p></p>
|
|
<dt><strong><a name="item_compile_subs">compile_subs</a></strong><br />
|
|
</dt>
|
|
<dd>
|
|
If provided, any data starting with <code>sub {</code> will be compiled into a
|
|
subroutine. This compilation does not happen until the variable is accessed,
|
|
at which point a fatal error will occur if the code could not be compiled. The
|
|
code referenced will be cached (if using caching), but will be saved as the
|
|
original string (starting with <code>sub {</code>) when <a href="#save">saving</a>.
|
|
</dd>
|
|
<dd>
|
|
<p><strong>NOTE:</strong> The argument to compile_subs must be a valid perl package; the code
|
|
reference will be compiled in that package. For example,
|
|
<code>compile_subs => 'GForum::Post'</code> will compile the code ref in the
|
|
GForum::Post package. You need to do this to provide access to globals
|
|
variables such as $DB, $IN, etc.</p>
|
|
</dd>
|
|
<p></p>
|
|
<dt><strong><a name="item_sort_order">sort_order</a></strong><br />
|
|
</dt>
|
|
<dd>
|
|
If provided, the option will be passed through as the 'order' option of
|
|
GT::Dumper for hash key ordering. See <a href="glist.cgi?do=admin_gtdoc&topic=/GT/Dumper.html">the GT::Dumper manpage</a>. GT::Config always sorts
|
|
hash keys - this can be used when the default alphanumeric sort is not
|
|
sufficient.
|
|
</dd>
|
|
<p></p></dl>
|
|
<p>
|
|
</p>
|
|
<h2><a name="save">save</a></h2>
|
|
<p>To save a config file, simply call <code>$object->save()</code>. If the object uses
|
|
inheritance, only those keys that were not inherited (or were modified from the
|
|
inherited ones) will be saved.</p>
|
|
<pre>
|
|
$Config->save();</pre>
|
|
<p><strong>NOTE</strong>: <strong>ALWAYS SAVE AFTER MAKING ANY CHANGES!!!</strong>. If you do not save after
|
|
making changes, the data retrieved from the cache may not be the same as the
|
|
data stored in the configuration file on disk. After making ANY changes make
|
|
absolutely sure that you either undo the change or save the configuration file.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="cache_hit">cache_hit</a></h2>
|
|
<p>Returns whether or not the current object was loaded from cache (1) or loaded
|
|
from disk (undef).</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="inheritance">inheritance</a></h2>
|
|
<p>Returns the inheritance status (1 or 0) of the object.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="create_ok">create_ok</a></h2>
|
|
<p>Returns the status (1 or 0) of the ``create_ok'' flag.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="tmpfile">tmpfile</a></h2>
|
|
<p>With no arguments, returns whether or not the object will attempt to use a
|
|
temporary file when saving. Possible values are:</p>
|
|
<pre>
|
|
0 - Do not use a temporary file
|
|
undef - Use a temporary file if the base directory is writable
|
|
1 - Always use a temporary file</pre>
|
|
<p>You can pass in a single argument of one of the above values to set whether or
|
|
not the object will use a temporary file when saving.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="cache">cache</a></h2>
|
|
<p>This method returns whether or not the object is cached. This cannot be
|
|
enabled/disabled after loading a config file; you must specify it as an
|
|
argument to <code>load()</code> instead.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="debug_level">debug_level</a></h2>
|
|
<p>This method returns the current debug level.</p>
|
|
<p>You may provide one argument which sets a new debug level.</p>
|
|
<p>0 means no debugging, 1 means basic debugging, 2 means heavy debugging.</p>
|
|
<p>If setting a new debug level, the old debug level is returned.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="header">header</a></h2>
|
|
<p>This method returns or sets the header that will be printed when saving.</p>
|
|
<p>With no arguments, returns the header.</p>
|
|
<p>You may provide one argument which sets a new header. Keep in mind that the
|
|
file must be Perl-compilable, so take care if doing anything other than
|
|
comments.</p>
|
|
<p>If providing a new header, the old header is returned.</p>
|
|
<p>Note that the header may contain the value <code>[localtime]</code>, which will be
|
|
replaced with the return value of <code>scalar localtime()</code> when saving.</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="sort_order">sort_order</a></h2>
|
|
<p>This method returns or sets a code reference to be passed through as the
|
|
'order' option of GT::Dumper for hash key ordering. See <a href="glist.cgi?do=admin_gtdoc&topic=/GT/Dumper.html">the GT::Dumper manpage</a>.
|
|
GT::Config always sorts hash keys - this can be used when the default
|
|
alphanumeric sort is not sufficient.</p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="see_also">SEE ALSO</a></h1>
|
|
<p><a href="glist.cgi?do=admin_gtdoc&topic=/GT/Template/Inheritance.html">the GT::Template::Inheritance manpage</a></p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="maintainer">MAINTAINER</a></h1>
|
|
<p>Jason Rhinelander</p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="copyright">COPYRIGHT</a></h1>
|
|
<p>Copyright (c) 2004 Gossamer Threads Inc. All Rights Reserved.
|
|
<a href="http://www.gossamer-threads.com/">http://www.gossamer-threads.com/</a></p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="version">VERSION</a></h1>
|
|
<p>$Id: Config.pm,v 1.45 2005/03/21 05:49:39 jagerman Exp $</p>
|
|
|
|
</body>
|
|
|
|
</html>
|