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.

LICENSE

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