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)