- NAME
- SYNOPSIS
- DESCRIPTION
- METHODS

- load
- save
- cache_hit
- inheritance
- create_ok
- tmpfile
- cache
- debug_level
- header
- sort_order

- SEE ALSO
- MAINTAINER
- COPYRIGHT
- VERSION

# 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.47 2007/02/24 00:59:17 sbeck Exp $