NAME

Parrot::Configure::Data - Configuration data container

SYNOPSIS

    use Parrot::Configure::Data;

    my $data = Parrot::Configure::Data->new;
    my @values = $data->get(@keys);
    $data->set($key1 => $value1, $key2 => $value2);
    $data->add($delimiter, $key1 => $value1, $key2 => $value2);
    my @keys = $data->keys;
    my $serialized = $data->dump(q{c}, q{*PConfig});
    $data->clean;
    $data->settrigger($key, $trigger, $cb);
    $data->gettriggers($key);
    $data->gettrigger($key, $trigger);
    $data->deltrigger($key, $trigger);

DESCRIPTION

This module provides methods by which other Parrot::Configure::* modules can access configuration data.

The module supplies a constructor for Parrot::Configure::Data objects and three kinds of accessors:

1 Main configuration data
2 Triggers
3 Data read from Perl 5's %Config or Perl 5 special variables.

USAGE

Constructor

new()

Purpose

Basic object constructor.

Arguments

None.

Return Value

Parrot::Configure::Data object.

Methods for Main Configuration Data

get($key, ...)

Purpose

Provides access to the values assigned to elements in the Parrot::Configure object's main data structure.

Arguments

List of elements found in the Parrot::Configure object's main data structure.

Return Value

List of values associated with corresponding arguments.

set($key => $val, ...)

Purpose

Modifies or creates new values in the main part of the Parrot::Configure object's data structure..

Arguments

List of key => value pairs.

Return Value

Parrot::Configure::Data object.

add($delim, $key => $val, ...)

Purpose

Either creates a new key or appends to an existing key, with the previous/new values joined together by $delim.

Arguments

Delimiter value followed by a list of key => value pairs.

Return Value

Parrot::Configure::Data object.

keys()

Purpose

Provides a list of names of elements in the Parrot::Configure object's main data structure.

Arguments

None.

Return Value

List of elements in the Parrot::Configure object's main data structure.

get_PConfig()

Purpose

Slurps in Parrot::Config data from previous run of Configure.pl.

Arguments

None.

Return Value

Reference to hash holding main Parrot::Configure data structure.

get_PConfig_Temp()

Purpose

Slurps in Parrot::Config temporary data from previous run of Configure.pl. Only to be used when running gen::makefiles plugin.

Arguments

None.

Return Value

Reference to hash holding that part of the main Parrot::Configure data structure holding temporary data.

dump()

Purpose

Provides a Data::Dumper serialized string of the objects key/value pairs suitable for being evaled.

Arguments

Two scalar arguments:

Key in Parrot::Configure object's data structure which is being dumped.
Name of the dumped structure.

Example:

    $conf->data->dump(q{c}, q{*PConfig});
    $conf->data->dump(q{c_temp}, q{*PConfig_Temp});

Return Value

String.

clean()

Purpose

Deletes keys matching /^TEMP_/ from the internal configuration store, and copies them to a special store for temporary keys. Keys using this naming convention are intended to be used only temporarily, e.g. as file lists for Makefile generation. Temporary keys are used only to regenerate makefiles after configuration.

Arguments

None.

Return Value

Parrot::Configure::Data object.

Triggers

settrigger($key, $trigger, $cb)

Purpose

Set a callback on $key named $trigger. Multiple triggers can be set on a given key. When the key is set via set or add then all callbacks that are defined will be called. Triggers are passed the key and value that was set after it has been changed.

Arguments

Accepts a key name, a trigger name, & a CODE ref.

Return Value

Parrot::Configure::Data object.

gettriggers($key)

Purpose

Get the names of all triggers set for $key.

Arguments

String holding single key name.

Return Value

List of triggers set for that key.

gettrigger($key, $trigger)

Purpose

Get the callback set for $key under the name $trigger

Arguments

Accepts a key name & a trigger name.

Return Value

CODE ref.

deltrigger($key, $trigger)

Purpose

Removes the trigger on $key named by $trigger

Arguments

Accepts a key name & a trigger name.

Return Value

Parrot::Configure::Data object.

Methods for Perl 5 Data

get_p5($key, ...)

Purpose

Retrieve data originally derived from the Perl 5 environment during configuration step init::defaults and stored in a special part of the Parrot::Configure::Data object.

Arguments

List of elements found in the Perl 5-related part of the Parrot::Configure object's data structure.

Return Value

List of values associated with corresponding arguments.

Note

Once data from Perl 5's %Config or special variables has been stored in configuration step init::defaults, %Config and the special variables should not be further accessed. Use this method instead.

set_p5($key => $val, ...)

Purpose

Looks up values from either (a) the %Config, located in Config.pm and imported via use Config;, associated with the instance of Perl ($^X) used to run Configure.pl and assigns those values to a special part of the Parrot::Configure::Data object.

Arguments

List of key => value pairs. If the key being set is from %Config, the corresponding value should have the same name. If, however, the key being set is a Perl 5 special variable (e.g., %^O), the corresponding value should be the 'English' name of that special variable as documented in perlvar (less the initial $, of course).

Return Value

Parrot::Configure::Data object.

Examples
Note

This method should only be used in configuration step init::defaults. It is not the method used to assign values to the main Parrot::Configure data structure; use set() (above) instead.

keys_p5()

Purpose

Provides a list of names of elements in the Parrot::Configure object's main data structure.

Arguments

None.

Return Value

List of elements in the part of the Parrot::Configure object's data structure storing Perl 5 configuration data.

CREDITS

Based largely on code written by Brent Royal-Gordon brent@brentdax.com.

AUTHOR

Joshua Hoblitt jhoblitt@cpan.org