NAME

GT::Config - Dumped-hash configuration handler

SYNOPSIS

    use GT::Config;
    my $Config = GT::Config->load($config_file);
    ...
    print $Config->{variable};
    ...
    $Config->{othervar} = "something";
    ...
    $Config->save;

DESCRIPTION

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 the GT::Template manpage) and mtime-based caching.

METHODS

load

There is no new() method. To get a new config object you do:

    $Config = GT::Config->load("/path/to/config/file", { options });

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.

The second argument is a hash reference of options, and is optional. The possible options are:

inheritance
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.

Defaults to off.

local
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 inheritance option, ``local'' configuration files always inherit from their non-local counterpart.

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.

Defaults to off.

cache
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.

Defaults to on. You must pass cache => 0 to disable cached loading. Note that new objects are always stored in the cache, allowing you to specify cache => 0 to force a reload of a cached file.

create_ok
If set, you'll still get back a GT::Config hash even if the file doesn't exist. You can then save() 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.

Defaults to off. Pass in create_ok => 1 if the config file doesn't necessarily have to exist (i.e. when creating a new config file).

empty
The empty option is used to create a new, blank config file - it can be thought of as a forced version of the create_ok option. It won't read any files during loading (and as such completely ignores the inheritance and cache options). This is mainly intended to be used when a complete replacement of a file is desired, regardless of what is currently on disk.

chmod
The chmod option is used to specify the mode of the saved file. It must be passed in octal form, such as 0644 (but not in string form, such as "0644"). 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.

strict
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 - $CFG->{foo}->{bar} will not fatal if foo is a hash ref, but bar is not set in that hash reference. $CFG->{foo} (and $CFG->{foo}->{bar}) will fatal if the key foo does not exist in the config data.

debug
If provided, debugging information will be printed. This will also cause a warning to occur if fatal is disabled and load fails.

Defaults to disabled. Should not be used in production code, except when debugging.

tmpfile
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.

The following values are accepted:

    0 - Do not use a temporary file
    undef - Use a temporary file if the base directory is writable
    1 - Always use a temporary file

The default is undef, 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.

header
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.

Note that the header may contain the string [localtime], which will be replaced with the return value of scalar localtime() when saving, which is generally a value such as: Sun Jan 25 15:12:26 2004.

tab
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.

compile_subs
If provided, any data starting with sub { 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 sub {) when saving.

NOTE: The argument to compile_subs must be a valid perl package; the code reference will be compiled in that package. For example, compile_subs => 'GForum::Post' 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.

sort_order
If provided, the option will be passed through as the 'order' option of GT::Dumper for hash key ordering. See the GT::Dumper manpage. GT::Config always sorts hash keys - this can be used when the default alphanumeric sort is not sufficient.

save

To save a config file, simply call $object->save(). If the object uses inheritance, only those keys that were not inherited (or were modified from the inherited ones) will be saved.

    $Config->save();

NOTE: ALWAYS SAVE AFTER MAKING ANY CHANGES!!!. 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.

cache_hit

Returns whether or not the current object was loaded from cache (1) or loaded from disk (undef).

inheritance

Returns the inheritance status (1 or 0) of the object.

create_ok

Returns the status (1 or 0) of the ``create_ok'' flag.

tmpfile

With no arguments, returns whether or not the object will attempt to use a temporary file when saving. Possible values are:

    0 - Do not use a temporary file
    undef - Use a temporary file if the base directory is writable
    1 - Always use a temporary file

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.

cache

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 load() instead.

debug_level

This method returns the current debug level.

You may provide one argument which sets a new debug level.

0 means no debugging, 1 means basic debugging, 2 means heavy debugging.

If setting a new debug level, the old debug level is returned.

header

This method returns or sets the header that will be printed when saving.

With no arguments, returns the header.

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.

If providing a new header, the old header is returned.

Note that the header may contain the value [localtime], which will be replaced with the return value of scalar localtime() when saving.

sort_order

This method returns or sets a code reference to be passed through as the 'order' option of GT::Dumper for hash key ordering. See the GT::Dumper manpage. GT::Config always sorts hash keys - this can be used when the default alphanumeric sort is not sufficient.

SEE ALSO

the GT::Template::Inheritance manpage

MAINTAINER

Jason Rhinelander

COPYRIGHT

Copyright (c) 2004 Gossamer Threads Inc. All Rights Reserved. http://www.gossamer-threads.com/

VERSION

$Id: Config.pm,v 1.45 2005/03/21 05:49:39 jagerman Exp $