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"');
    
$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.

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 or a code-ref.

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.

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 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;

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)