PFT::Conf(3)

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.