Config::Options(3p)

NAME
Config::Options - module to provide a configuration hash with option to read from file.

SYNOPSIS
        use Config::Options;

        my $options = Config::Options->new({ verbose => 1, optionb => 2, mood => "sardonic" });

        # Access option as a hash...
        print "My mode is ", $options->{mood}, "\n";

        # Merge a hash of options...
        $options->options({ optionc => 5, style => "poor"});

        # Merge options from file

        $options->options("optionfile", $ENV{HOME} . "/.myoptions.conf");
        $options->fromfile_perl();

AUTHOR
Edward Allen, ealleniii _at_ cpan _dot_ org

DESCRIPTION
The motivation for this module was to provide an option hash with a little bit of brains. It's pretty simple and used mainly by other modules I have written.

METHODS

new()
    Create new options hash. Pass it a hash ref to start with. Please note that this reference is copied, not blessed.

            my $options = Config::Options->new({hash_of_startup_options});

clone()
    Creates a clone of options object.

            my $newoptions = $options->clone();

options()
    This is a utility function for accessing options. If passed a hashref, merges it. If passed a scalar, returns the value. If passed two scalars, sets the option.

            my $optionsb = $options->options;     # Duplicates option file.  Not very usefull.
            $options->options($hashref);          # Same as $options->merge($hashref);
            my $value = $options->options("key")  # Return option value.
            $options->options("key", "value")         # Set an option.

merge()
    Takes a hashref as argument and merges with current options.

            $options->merge($hashref);

deepmerge()
    Same as merge, except when a value is a hash or array reference. For example:

            my $options = Config::Options->new({ moods => [ qw(happy sad angry) ] });
            $options->deepmerge({ moods => [ qw(sardonic twisted) ] });

            print join(" ", @{$options->{moods}}), "\n";

    The above outputs:

            happy sad angry sardonic twisted

tofile_perl()
    This is used to store options to a file. The file is actually a perl program that returns a hash. By default uses option 'optionfile' as filename, or value passed as argument.

    If 'optionfile' is an array, then uses LAST option in array as default.

            $options->tofile_perl("/path/to/optionfile");

fromfile_perl()
    This is used to retreive options from a file. The optionfile is actually a perl program that returns a hash. By default uses option 'optionfile' as filename if none is passed.

    If 'optionfile' is an array, reads all option files in order.

    Non-existant files are ignored.

    Please note that values for this are cached.

            $options->fromfile_perl("/path/to/optionfile");

deserialize($data, $source)
    Takes a scalar as argument and evals it, then merges option. If second option is given uses this in error message if the eval fails.

            my $options = $options->deserialize($scalar, $source);

serialize()
    Output optons hash as a scalar using Data::Dumper.

            my $scalar = $options->serialize();

del($key)
    Removes $key from options.

BUGS

Deepmerge does a poor job at recogniaing recursive loops.
    For example, $options->deepmerge($options) will really screw things up. As protection, will only loop 20 deep.

fromfile_perl provides tainted data.
    Since it comes from an external file, the data is considered tainted.

SEE ALSO
Config::General

LICENSE
This program is free software; you can redistribute it and/or modify it under the terms of the Artistic License, distributed with Perl.

COPYRIGHT
Copyright (c) 2007 Edward Allen III. Some rights reserved.