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