NAME

Gnuplot::Builder::Dataset - object-oriented builder for gnuplot dataset

SYNOPSIS

use Gnuplot::Builder::Script;
use Gnuplot::Builder::Dataset;
    
my $builder = Gnuplot::Builder::Script->new;

my $func_data = Gnuplot::Builder::Dataset->new('sin(x)');
$func_data->set(title => '"function"', with => "lines");
    
my $unit_scale = 0.001;
my $file_data = Gnuplot::Builder::Dataset->new_file("sampled_data1.dat");
$file_data->set(
    using => sub { "1:(\$2 * $unit_scale)" },
    title => '"sample 1"',
    with  => 'linespoints lw 2'
);
    
my $another_file_data = $file_data->new_child;
$another_file_data->set_file("sampled_data2.dat");  ## override parent's setting
$another_file_data->setq(title => "sample 2");      ## override parent's setting

my $inline_data = Gnuplot::Builder::Dataset->new_data(<<INLINE_DATA);
1.0  3.2
1.4  3.0
1.9  4.3
2.2  3.9
INLINE_DATA
$inline_data->set(using => "1:2", title => '"sample 3"');
    
print $builder->plot($func_data, $file_data, $another_file_data, $inline_data);

DESCRIPTION

Gnuplot::Builder::Dataset is a builder object for gnuplot dataset (the data to be plotted).

Like Gnuplot::Builder::Script, this module stores dataset parameters in a hash-like structure. It supports lazy evaluation and prototype-based inheritance, too.

Data Model

A Gnuplot::Builder::Dataset consists of three attributes; the source, the options and the inline data.

plot "source.dat" using 1:2 title "file" with lp, \
     f(x) title "function" with lines, \
     "-" using 1:2 title "inline" with lp
10 20
15 11
20 43
25 32
end

The source is the first part of the dataset parameters. In the above example, "source.dat", f(x) and "-" are the sources.
The options are the rest of the dataset parameters after the source. In the above example, using 1:2 title "file" with lp is the options of the first dataset. Gnuplot::Builder::Dataset stores the options in a hash-like data structure.
The inline data is the data given after the "plot" command. In the above example, only the third dataset has its inline data.

Complex Dataset Options

Sometimes dataset options can be complex. For example, have you ever been confused by the complicated order of "using" option parameters for "candlesticks" plot style ? I have!

If you have trouble dealing with those complex options, check out Gnuplot::Builder::Template and Gnuplot::Builder::JoinDict. They might help you arrange option values and stuff.

CLASS METHODS

$dataset = Gnuplot::Builder::Dataset->new($source, @set_args)

The general-purpose constructor. All arguments are optional. $source is the source string of this dataset. @set_args are the option settings.

This method is equivalent to new()->set_source($source)->set(@set_args).

$dataset = Gnuplot::Builder::Dataset->new_file($filename, @set_args)

The constructor for datasets whose source is a file. $filename is the name of the source file.

This method is equivalent to new()->set_file($filename)->set(@set_args).

$dataset = Gnuplot::Builder::Dataset->new_data($data_provider, @set_args)

The constructor for datasets that have inline data. $data_provider is the inline data or a code-ref that provides it.

This method is equivalent to new()->set_file('-')->set_data($data_provider)->set(@set_args).

OBJECT METHODS - BASICS

$string = $dataset->to_string()

Build and return the dataset parameter string. It does not contain the inline data.

$string = $dataset->params_string()

Alias of to_string() method. It's for plotting methods of Gnuplot::Builder::Script.

OBJECT METHODS - SOURCE

Methods about the source of the dataset.

$dataset = $dataset->set_source($source)

Set the source of the $dataset to $source.

$source is either a string or code-ref. If $source is a string, that string is used for the source.

If $source is a code-ref, it is evaluated in list context when $dataset builds the parameters.

($source_str) = $source->($dataset)

$dataset is passed to the code-ref. The first element of the result ($source_str) is used for the source.

$dataset = $dataset->setq_source($source)

Same as set_source() method except that the eventual source string is quoted. Useful for setting the file name of the dataset.

my $file_index = 5;
$dataset->setq_source(sub { qq{file_$file_index.dat} });
$dataset->to_string();
## => 'file_5.dat'

$dataset = $dataset->set_file($source_filename)

Alias of setq_source() method.

$source_str = $dataset->get_source()

Return the source string of the $dataset.

If a code-ref is set for the source, it is evaluated and the result is returned.

If the source is not set in the $dataset, it returns its parent's source string. If none of the ancestors doesn't have the source, it returns undef.

$dataset = $dataset->delete_source()

Delete the source setting from the $dataset.

After the source is deleted, get_source() method will search the parent for the source string.

OBJECT METHODS - OPTIONS

Methods about the options of the dataset.

These methods are very similar to the methods of the same names in Gnuplot::Builder::Script.

$dataset = $dataset->set($opt_name => $opt_value, ...)

Set the dataset option named $opt_name to $opt_value. You can specify more than one pairs of $opt_name and $opt_value.

$opt_name is the name of the option (e.g. "using" and "every").

$opt_value is either undef, a string, an array-ref of strings, a code-ref or a blessed object.

If $opt_value is undef, the whole option (including the name) won't appear in the parameters it builds.
If $opt_value is a string, the option is set to that string.
If $opt_value is an array-ref, the elements in the array-ref will be concatenated with spaces when it builds the parameters. If the array-ref is empty, the whole option (including the name) won't appear in the parameters.
```
$dataset->set(
    binary => ['record=356:356:356', 'skip=512:256:256']
);
$dataset->to_string;
## => 'hoge' binary record=356:356:356 skip=512:256:256
```
If $opt_value is a code-ref, that is evaluated in list context when the $dataset builds the parameters.
```
@returned_values = $opt_value->($dataset, $opt_name)
```
$dataset and $opt_name are passed to the code-ref.

Then, the option is generated as if $opt_name => \@returned_values was set. You can return an undef or an empty list to disable the option.
If $opt_value is a blessed object, it's stringification (i.e. "$opt_value") is evaluated when $dataset builds the parameters. You can retrieve the object by get_option() method.

The options are stored in a hash-like structure, so you can change them individually.

Even if you change an option value, its order is unchanged.

my $scale = 0.001;
$dataset->set_file('dataset.csv');
$dataset->set(
    every => undef,
    using => sub { qq{1:(\$2*$scale)} },
    title => '"data"',
    with  => 'lines lw 2'
);
$dataset->to_string();
## => 'dataset.csv' using 1:($2*0.001) title "data" with lines lw 2

$dataset->set(
    title => undef,
    every => '::1',
);
$dataset->to_string();
## => 'dataset.csv' every ::1 using 1:($2*0.001) with lines lw 2

You are free to pass any string to $opt_name in any order, but this module does not guarantee it's syntactically correct.

$bad_dataset->set(
    lw => 4,
    w  => "lp",
    ps => "variable",
    u  => "1:2:3"
);
$bad_dataset->to_string();
## => 'hoge' lw 4 w lp ps variable u 1:2:3

## The above parameters are invalid!!!

$good_dataset->set(
    u  => "1:2:3",
    w  => "lp",
    lw => 4,
    ps => "variable"
);
$good_dataset->to_string();
## => 'hoge' u 1:2:3 w lp lw 4 ps variable

Some dataset options such as "matrix" and "volatile" don't have arguments. You can set such options like this.

$dataset->set(
    matrix   => "",    ## enable
    volatile => undef, ## disable
);

Or, you can even write like this.

$dataset->set(
    "" => "matrix"
);

There is more than one way to do it.

$dataset = $dataset->set($options)

If set() method is called with a single string argument $options, it is parsed to set options.

$dataset->set(<<END_OPTIONS);
using = 1:3
-axes
title = "Weight [kg]"
with  = lines
lw    = 2
END_OPTIONS

The parsing rule is more or less the same as set() method of Gnuplot::Builder::Script. Here is the overview.

Options are set like
```
OPT_NAME = OPT_VALUE
```
If OPT_VALUE is an empty string, you can omit "=".
Options can be explicitly disabled by the leading "-" like
```
-OPT_NAME
```
If the same OPT_NAME is repeated with different OPT_VALUEs, it's equivalent to set($opt_name => [$opt_value1, $opt_value2, ...]).

$dataset = $dataset->set_option(...)

set_option() method is alias of set().

$dataset = $dataset->setq(...)

Same as set() method except that the eventual option value is quoted. This is useful for setting "title" and "index".

$dataset->setq(
    title => "Sample A's result",
);
$dataset->to_string();
## => "hoge" title 'Sample A''s result'

$dataset->setq(
    title => ""  ## same effect as "notitle"
);
$dataset->to_string();
## => "hoge" title ''

$dataset = $dataset->setq_option(...)

setq_option() method is alias of setq().

$dataset = $dataset->unset($opt_name ...)

Short-cut for set($opt_name => undef). It disables the dataset option.

You can specify more than one $opt_names.

@opt_values = $dataset->get_option($opt_name)

Return the option values for the name $opt_name. In list context, it returns all values for $opt_name. In scalar context, it returns only the first value.

If a code-ref is set to the $opt_name, it's evaluated and its results are returned.

If a blessed object is set to the $opt_name, that object is returned.

If the option is not set in $dataset, the value of its parent is returned. If none of the ancestors doesn't have the option, it returns an empty list in list context or undef in scalar context.

$dataset = $dataset->delete_option($opt_name, ...)

Delete the option from the $dataset. You can specify more than one $opt_names.

Note the difference between delete_option($opt_name) and set_option($opt_name => undef). delete_option() removes the option setting from the $dataset, so it's up to its ancestors to determine the value of the option. On the other hand, set_option() always overrides the parent's setting.

OBJECT METHODS - INLINE DATA

Methods about the inline data of the dataset.

$dataset = $dataset->set_data($data_provider)

Set the inline data of the $dataset.

$data_provider is either undef, a string or a code-ref.

If $data_provider is undef, it means that $dataset has no inline data.
If $data_provider is a string, that is the inline data of the $dataset.
```
$dataset->set_data(<<INLINE_DATA);
1 10
2 20
3 30
INLINE_DATA
```
If $data_provider is a code-ref, it is called in void context when $dataset needs the inline data.
```
$data_provider->($dataset, $writer)
```
$dataset is passed as the first argument to the code-ref. The second argument ($writer) is a code-ref that you have to call to write inline data.
```
$dataset->set_data(sub {
    my ($dataset, $writer) = @_;
    foreach my $x (1 .. 3) {
        my $y = $x * 10;
        $writer->("$x $y\n");
    }
});
```
This allows for very large inline data streaming directly into the gnuplot process.

If you don't pass any data to $writer, it means the $dataset doesn't have inline data at all.

$dataset = $dataset->write_data_to($writer)

Write the inline data using the $writer. This method is required by plotting methods of Gnuplot::Builder::Script.

$writer is a code-ref that is called by the $dataset to write inline data. $writer can be called zero or more times.

my $inline_data = "";
$dataset->write_data_to(sub {
    my ($data_part) = @_;
    $inline_data .= $data_part;
});

If $dataset doesn't have inline data setting, it's up to $dataset's ancestors to write the inline data. If none of them have inline data, $writer is not called at all.

$dataset = $dataset->delete_data()

Delete the inline data setting from the $dataset.

OBJECT METHODS - INHERITANCE

Gnuplot::Builder::Dataset supports prototype-based inheritance just like Gnuplot::Builder::Script.

A child dataset inherits the source, the options and the inline data from its parent. The child can override them individually, or use the parent's setting as-is.

$dataset = $dataset->set_parent($parent_dataset)

Set $parent_dataset as the $dataset's parent.

If $parent_dataset is undef, $dataset doesn't have parent anymore.

$parent_dataset = $dataset->get_parent()

Return the $dataset's parent.

If $dataset doesn't have any parent, it returns undef.

$child_dataset = $dataset->new_child()

Create and return a new child of the $dataset.

This is equivalent to Gnuplot::Builder::Dataset->new->set_parent($dataset).

OVERLOAD

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

"$dataset" eq $dataset->to_string;

Data::Focus COMPATIBLITY

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

The Lens() method creates a Data::Focus::Lens object for accessing dataset options via get_option() and set_option().

Note that the lens calls get_option() always in scalar context, just like the lens for Gnuplot::Builder::Script.

AUTHOR

Toshio Ito, <toshioito at cpan.org>

To install Gnuplot::Builder, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Gnuplot::Builder

CPAN shell

perl -MCPAN -e shell
install Gnuplot::Builder

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)