NAME

PFT::Conf - Configuration parser for PFT

SYNOPSIS

    PFT::Conf->new_default()        # Using default
    PFT::Conf->new_load($root)      # Load from conf file in directory
    PFT::Conf->new_load_locate()    # Load from conf file, find directory
    PFT::Conf->new_load_locate($cwd)

    PFT::Conf::locate()             # Locate root
    PFT::Conf::locate($cwd)

    PFT::Conf::isroot($path)        # Check if location exists under path.

    use Getopt::Long;
    Getopt::Long::Configure 'bundling';
    GetOptions(
        PFT::Conf::wire_getopt(\my %opts),
        'more-opt' => \$more,
    );
    PFT::Conf->new_getopt(\%opts);  # Create with command line options

DESCRIPTION

Automatic loader and handler for the configuration file of a PFT site.

The configuration is a simple YAML file with a conventional name. Some keys are mandatory, while other are optional. This module allows a headache free check for mandatory ones.

Many constructors are available, here described:

new_default

Creates a new configuration based on environment variables and common sense.

The configuration can later be stored on a file with the save_to method.

new_load

Loads a configuration file which must already exist. Accepts as optional argument the name of a directory (not encoded), which defaults on the current directory.

This constructor fails with croak if the directory does not contain a configuration file.

new_load_locate

Works as new_load, but before failing makes an attempt to locate the configuration file in the parent directories up to the root level.

This is handy for launching commands from the command line without worrying on the current directory: it works as long as your cwd is below a PFT root directory.

wire_getopt and new_getopt

This is a two-steps constructor meant for command line initializers.

An example of usage can be found in the SYNOPSIS section. In short, the auxiliary function PFT::Conf::wire_getopt provides a list of ready-to-use options for the GetOpt::Long Perl module. It expects a hash reference as argument, which will be used as storage for selected options. The new_getopt constructor expects as argument the same hash reference.

Shared variables

$PFT::Conf::CONF_NAME is a string. Defines the name of the configuration file.

Utility functions

isroot

The PFT::Conf::isroot function searches for the configuration file in the given directory path (not encoded).

Returns undef if the file was not found, and the encoded file name (according to locale) if it was found.

locate

The PFT::Conf::locate function locates a PFT configuration file.

It accepts as optional parameter a directory path (not encoded), defaulting on the current working directory.

Possible return values:

The input directory itself if the configuration file was found in it;

The first encountered parent directory containing the configuration file;

undef if no configuration file was found, up to the root of all directories.

Methods

save_to

Save the configuration to a file. This will also update the inner root reference, so the intsance will point to the saved file.