/ 
Config-FreeForm-0.01
River stage zero No dependents
/ Config::FreeForm

NAME

Config::FreeForm - Provide in-memory configuration data

SYNOPSIS

use Config::FreeForm %options;

DESCRIPTION

Config::FreeForm provides in-memory configuration data in a free-form manner. Many existing configuration modules attempt to provide some structure to your configuration data; in doing so, they force you to use their own configuration paradigm (association of keywords with values, etc.). Often this isn't what you need in a complex application--you need complete control over your configuration data, and you need the ability to structure it however you like. This is what Config::FreeForm gives you.

In Config::FreeForm configuration data is stored as a Perl data structure. The logic behind this is that you know Perl--you shouldn't need to learn another little language to set up your configuration data, however simple that language may be. Of course, this works best if programmers or tools do the updating of your configuration files; it does make it more difficult for other possible users to edit the files. If this is a problem for you, try some of the other configuration modules listed in MISCELLANEOUS.

Still here? Good. You might then ask what Config::FreeForm gives you that rolling your own light module using Data::Dumper and do would not. It's a good question, considering in particular that Config::FreeForm uses Data::Dumper and do to write and read your data, respectively. Config::FreeForm adds some very nice features, though:

  • Configuration File Management

    So as not to clutter one file with configuration for all purposes, you can separate your configuration data into multiple files, and specify which files to load when you load in the module:

    use Config::FreeForm sets => [ ... ];

    Config::FreeForm manages the various configuration files that you've told it to load, and lets you update your data in memory, then write it back to its original location on disk, using the rewrite function (below, in UPDATING CONFIGURATION).

  • Automated Reloading

    In a mod_perl context, your configuration data will be loaded once, at webserver startup; subsequent access to the configuration data will come from memory. If you update your configuration on disk, then, you'll want those changes to be reflected in the in-memory versions of the configuration. Config::FreeForm will handle this automatically for you if you install it as a PerlInitHandler on your mod_perl-enabled server. For more details, see AUTOMATED RELOADING, below.

HOW TO USE IT

To create a configuration file, add its configuration to a file like Foo.conf:

$conf = {
    Foo => { Bar => 1 }
}

Once you've written your Foo.conf configuration file, load that file explicitly (without the .conf):

use Config::FreeForm sets => [ 'Foo' ];

When the module is loaded, it will attempt to find a configuration file for the set Foo; it will load the data in this file using do; then it will loop over the top-level variables in the tree structure and alias variables into the Config::FreeForm namespace to the values in the structure.

For example, if you have the above Foo.conf, the variable $Config::FreeForm::Foo will be equal to the following structure:

{   Bar => 1   }

So you could access the value of the Bar attribute by treating the aliased variable as a hash reference:

my $value = $Config::FreeForm::Foo->{Bar};

In addition to specifying which configuration files to load, you can use the %options in the import list to set the directory holding the configuration files. By default Config::FreeForm looks in the directory FreeForm within the directory from which it was loaded for the files. For example, if the module were loaded from /foo/bar/Config/FreeForm.pm, the Foo.conf configuration file would be default be looked up in /foo/bar/Config/FreeForm/Foo.conf.

By using the dir import list parameter, though, you can override this default behavior:

use Config::FreeForm dir => '/foo', sets => [ 'Foo' ];

This would look up Foo.conf in the directory /foo.

UPDATING CONFIGURATION

If you wish to update the configuration files programatically (as opposed to editing them by hand), you can use the rewrite function.

This is a two-step process. First, you'll need to update the in-memory configuration--just make a change to one of the variables. For example:

$Config::FreeForm::Foo->{Bar} = 2;

This updates the configuration in memory; now you need to write the configuration to the disk. You can do that using rewrite, which takes the name of a configuration "set" (which corresponds to the name of the configuration file). In this case, that set would be Foo:

Config::FreeForm::rewrite('Foo');

And you're done. The configuration is now updated on disk.

If you'd like to write the configuration data to a file different than that from which it was read, you can pass a filepath as a second argument. For example:

Config::FreeForm::rewrite('Foo', './myfoo.conf');

This will write out the Foo configuration data to ./myfoo.conf.

Keep in mind that, if you're rewriting your configuration in a webserver context, you'll want your on-disk changes to propagate to the other webserver children (the children in which you didn't already change the in-memory configuration). Read on--this can be made to happen automatically.

AUTOMATED RELOADING

When used in a webserver context, the configuration files are parsed once at webserver startup, then stored in memory. If changes occur in the configuration files, under normal circumstances the configuration stored in memory would not be reloaded. However, Config::FreeForm has a built-in capability to automatically reload configuration files that have changed on disk. This allows you to make a change to a config file, then let the webserver automatically pick up the new changes.

This is particularly important when using the rewrite function; if you alter the in-memory configuration, then write the file to disk, you want the other webserver children to pick up the changes, in addition to the child where you actually made the in-memory changes. Using the automated reloading, these changes will be automatically picked up by all of the webserver children.

To use this capability, just install Config::FreeForm as a PerlInitHandler in the webserver. Add this to the configuration:

PerlInitHandler Config::FreeForm

You can either stick this into a Location block or make it global for your entire server. The latter may be easier in terms of maintenance, but the former may give you more flexibility.

By default, Config::FreeForm will go about its business quietly. If you'd like it to write a message to the error log each time it reloads a configuration file, you can add a configuration directive to do so:

PerlSetVar ConfigDebug on

Now, each time Config::FreeForm reloads a configuration file, it will write a message to the log file telling you the process ID, the configuration set, and the modified-time comparison that caused the reload.

MISCELLANEOUS

If the so-called freeform nature of Config::FreeForm doesn't appeal to you, and you'd like a more structured approach to your configuration files, check out App-Config, Boulder, or XML::Simple.

AUTHOR

Benjamin Trott, ben@rhumba.pair.com