/ 
Gnuplot-Builder-0.32
River stage one • 1 direct dependent • 1 total dependent
/ Gnuplot::Builder::JoinDict

NAME

Gnuplot::Builder::JoinDict - immutable ordered hash that joins its values in stringification

SYNOPSIS

use Gnuplot::Builder::JoinDict;

my $dict = Gnuplot::Builder::JoinDict->new(
    separator => ', ',
    content => [x => 640, y => 480]
);
"$dict";  ## => 640, 480

$dict->get("x"); ## => 640
$dict->get("y"); ## => 480

my $dict2 = $dict->set(y => 16);
"$dict";   ## => 640, 480
"$dict2";  ## => 640, 16

my $dict3 = $dict2->set(x => 8, z => 32);
"$dict3";  ## => 8, 16, 32

my $dict4 = $dict3->delete("x", "y");
"$dict4";  ## => 32

DESCRIPTION

Basically Gnuplot::Builder::JoinDict is just an ordered associative array (sometimes called as a "dictionary"), so it's the same as Tie::IxHash.

The difference from Tie::IxHash is:

EXPORTABLE FUNCTIONS

$dict = joind($separator, @content)

Alias for Gnuplot::Builder::JoinDict->new(separator => $separator, content => \@content). Exported only by request.

CLASS METHODS

$dict = Gnuplot::Builder::JoinDict->new(%args)

The constructor.

Fields in %args are:

separator => STR (optional, default: "")

The separator string that is used when joining.

content => ARRAY_REF (optional, default: [])

The content of the $dict. The array-ref must contain key-value pairs. Keys must not be undef.

filter => CODE_REF (optional)

If set, this code-ref is called when the $dict is stringified (i.e. $dict->to_string is called). The code-ref is supposed to modify the values in $dict to produce the final result of stringification.

@modified_values = $filter->($dict)

where $dict is the Gnuplot::Builder::JoinDict object. The filter must return a list @modified_values.

For example,

my $dict = Gnuplot::Builder::JoinDict->new(
    separator => " & ", content => [x => 10, y => 20],
    filter => sub {
        my ($dict) = @_;
        my @keys = $dict->get_all_keys();
        my @values = $dict->get_all_values();
        return map { "$keys[$_]=$values[$_]" } 0 .. $#keys;
    }
);
"$dict"; ## => x=10 & y=20

The filter is inherited by Gnuplot::Builder::JoinDict objects derived from the original one.

validator => CODE_REF (optional)

If set, this code-ref is called when some key-value pairs are set or deleted to a Gnuplot::Builder::JoinDict object. The code-ref is supposed to check the content and throw an exception when something is wrong.

$validator->($dict)

where $dict is the Gnuplot::Builder::JoinDict object.

The validator is called when new(), delete(), set() and set_all() methods are called.

The validator is inherited by Gnuplot::Builder::JoinDict objects derived from the original one.

OBJECT METHODS

$str = $dict->to_string()

Join $dict's values with the separator and return the result.

If some values are undef, those values are ignored.

$value = $dict->get($key)

Return the $value for the $key.

If $dict doesn't have $key, it returns undef.

@keys = $dict->get_all_keys()

Return all keys from $dict.

@values = $dict->get_all_values()

Return all values from $dict.

$new_dict = $dict->set($key => $value, ...)

Add new key-value pairs to $dict and return the result. You can specify more than one key-value pairs.

If $dict already has $key, its value is replaced in $new_dict. Otherwise, a new pair of $key and $value is added.

$new_dict = $dict->set_all($value)

Set all values to $value and return the result.

$new_dict = $dict->delete($key, ...)

Delete the given keys from $dict and return the result. You can specify more than one $keys.

If $dict doesn't have $key, it's just ignored.

$new_dict = $dict->clone()

Create and return a clone of $dict.

$separator = $dict->separator()

Get the separator.

OVERLOAD

When you evaluate a $dict as a string, it executes $dict->to_string(). That is,

"$dict" eq $dict->to_string;

Data::Focus COMPATIBLITY

Gnuplot::Builder::JoinDict implements Lens() method, so you can use Data::Focus to access its attributes.

The Lens() method creates a Data::Focus::Lens object for accessing the content via get() and set() methods.

use Data::Focus qw(focus);

my $scalar = focus($dict)->get("x");
## same as: my $scalar = $dict->get("x");

my $new_dict = focus($dict)->set(x => '($1 * 1000)');
## same as: my $new_dict = $dict->set(x => '($1 * 1000)');

AUTHOR

Toshio Ito, toshioito at cpan.org