NAME

Gnuplot::Builder::Script - object-oriented builder for gnuplot script

SYNOPSIS

    use Gnuplot::Builder::Script;
    
    my $builder = Gnuplot::Builder::Script->new();
    $builder->set(
        terminal => 'png size 500,500 enhanced',
        grid     => 'x y',
        xrange   => '[-10:10]',
        yrange   => '[-1:1]',
        xlabel   => '"x" offset 0,1',
        ylabel   => '"y" offset 1,0',
    );
    $builder->setq(output => 'sin_wave.png');
    $builder->unset("key");
    $builder->define('f(x)' => 'sin(pi * x)');
    print $builder->plot("f(x)"); ## output sin_wave.png
    
    my $child = $builder->new_child;
    $child->define('f(x)' => 'cos(pi * x)'); ## override parent's setting
    $child->setq(output => 'cos_wave.png');  ## override parent's setting
    print $child->plot("f(x)");              ## output cos_wave.png

DESCRIPTION

Gnuplot::Builder::Script is a builder object for a gnuplot script.

The advantages of this module over just printing script text are:

  • It keeps option settings and definitions in a hash-like data structure. So you can change those items individually.

  • It accepts code-refs for script sentences, option settings and definitions. They are evaluated lazily every time it builds the script.

  • It supports prototype-based inheritance similar to JavaScript objects. A child builder can override its parent's settings.

CLASS METHODS

$builder = Gnuplot::Builder::Script->new(@set_args)

The constructor.

The argument @set_args is optional. If it's absent, it creates an empty builder. If it's set, @set_args is directly given to set() method.

OBJECT METHODS - BASICS

Most object methods return the object itself, so that you can chain those methods.

$script = $builder->to_string()

Build and return the gnuplot script string.

$builder = $buider->add($sentence, ...)

Add gnuplot script sentences to the $builder.

This is a low-level method. In most cases you should use set() and define() methods below.

$sentences is a string or a code-ref. A code-ref is evaluated in list context when it builds the script. The returned list of strings are added to the script.

You can pass more than one $sentences.

    $builder->add(<<'EOT');
    set title "sample"
    set xlabel "iteration"
    EOT
    my $unit = "sec";
    $builder->add(sub { qq{set ylabel "Time [$unit]"} });

OBJECT METHODS - GNUPLOT OPTIONS

Methods to manipulate gnuplot options (the "set" and "unset" commands).

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

Set a gnuplot option named $opt_name to $opt_value. You can set more than one name-value pairs.

$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 "unset" command is generated for the option.

  • If $opt_value is a string, the option is set to that string.

  • If $opt_value is an array-ref, the "set" command is repeated for each element in it. If the array is empty, no "set" or "unset" command is generated.

        $builder->set(
            terminal => 'png size 200,200',
            key      => undef,
        );
        $builder->to_string();
        ## => set terminal png size 200,200
        ## => unset key
            
        $builder->set(
            arrow => ['1 from 0,0 to 0,1', '2 from 100,0 to 0,100']
        );
        $builder->to_string();
        ## => set terminal png size 200,200
        ## => unset key
        ## => set arrow 1 0,0 to 0,1
        ## => set arrow 2 from 100,0 to 0,100
  • If $opt_value is a code-ref, it is evaluated in list context when the $builder builds the script.

        @returned_values = $opt_value->($builder, $opt_name)

    The $builder and $opt_name are given to the code-ref.

    Then, the option is generated as if $opt_name => \@returned_values was set. You can return single undef to "unset" the option.

        my %SCALE_LABEL = (1 => "", 1000 => "k", 1000000 => "M");
        my $scale = 1000;
        $builder->set(
            xlabel => sub { qq{"Traffic [$SCALE_LABEL{$scale}bps]"} },
        );
  • If $opt_value is a blessed object, it's stringification (i.e. "$opt_value") is evaluated when $builder builds the parameters. You can retrieve the object by get_option() method.

The options are stored in the $builder's hash-like structure, so you can change those options individually.

Even if the options are changed later, their order in the script is unchanged.

    $builder->set(
        terminal => 'png size 500,500',
        xrange => '[100:200]',
        output => '"foo.png"',
    );
    $builder->to_string();
    ## => set terminal png size 500,500
    ## => set xrange [100:200]
    ## => set output "foo.png"
    
    $builder->set(
        terminal => 'postscript eps size 5.0,5.0',
        output => '"foo.eps"'
    );
    $builder->to_string();
    ## => set terminal postscript eps size 5.0,5.0
    ## => set xrange [100:200]
    ## => set output "foo.eps"

Note that you are free to use any string as $opt_name. In fact, there may be more than one way to build the same script.

    $builder1->set(
        'style data' => 'lines',
        'style fill' => 'solid 0.5'
    );
    $builder2->set(
        style => ['data lines', 'fill solid 0.5']
    );

In the above example, $builder1 and $builder2 generate the same script. However, $builder2 cannot change the style for "data" or "fill" individually, while $builder1 can.

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

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

    $builder->set(<<'EOT');
    xrange = [-5:10]
    output = "foo.png"
    grid
    -key
    
    ## terminal = png size 100,200
    terminal = pngcairo size 400,800
    
    tics = mirror in \
           rotate autojustify
    
    arrow = 1 from 0,10 to 10,0
    arrow = 2 from 5,5  to 10,10
    EOT

Here is the parsing rule:

  • Each line is a "set" or "unset" command.

  • A "set" line is a pair of option name and value with "=" between them.

        OPT_NAME = OPT_VALUE
  • An "unset" line is the option name with leading "-".

        -OPT_NAME
  • White spaces around OPT_NAME and OPT_VALUE are ignored.

  • If OPT_VALUE is an empty string in "set" line, you can omit "=".

  • Lines with a trailing backslash continue to the next line. The effect is as if the backslash and newline were not there.

  • Empty lines are ignored.

  • Lines starting with "#" are ignored.

  • You can write more than one lines for the same OPT_NAME. It's the same effect as set($opt_name => [$opt_value1, $opt_value2, ...]).

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

set_option() is alias of set().

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

setq() method is the same as set() except that eventual option values are quoted.

This method is useful for setting "title", "xlabel", "output" etc.

    $builder->setq(
        output => "hoge.png",
        title  => "hoge's values",
    );
    $builder->to_string;
    ## => set output 'hoge.png'
    ## => set title 'hoge''s values'

If the option value is a list, it quotes the all elements.

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

setq_option() is alias of setq().

$builder = $builder->unset($opt_name, ...)

Short-cut for set($opt_name => undef). It generates "unset" command for the option.

You can specify more that one $opt_names.

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

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

If $opt_name is set in the $builder, it returns its values. If a code-ref is set to the $opt_name, it is evaluated and its results are returned. If a blessed object is set to the $opt_name, that object is returned.

If $opt_name is not set in the $builder, the values of $builder's parent are returned. If $builder does not have parent, it returns an empty list in list context or undef in scalar context.

This method may return both (undef) and (). Returning (undef) means the option is "unset" explicitly, while returning an empty list means no "set" or "unset" sentence for the option. If you want to distinguish those two cases, you must call get_option() in list context.

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

Delete the values for $opt_name from the $builder. You can specify more than one $opt_names.

After $opt_name is deleted, get_option($opt_name) will search the $builder's parent for the values.

Note the difference between delete_option() and unset(). While unset($opt_name) will generate "unset" sentence for the option, delete_option($opt_name) will be likely to generate no sentence (well, strictly speaking, it depends on the parent).

delete_option($opt_name) and set($opt_name => []) are also different if the $builder is a child. set() always overrides the parent setting, while delete_option() resets such overrides.

OBJECT METHODS - GNUPLOT DEFINITIONS

Methods to manipulate user-defined variables and functions.

Most methods in this category are analogous to the methods in "OBJECT METHODS - GNUPLOT OPTIONS".

    +---------------+-------------------+
    |    Options    |    Definitions    |
    +===============+===================+
    | set           | define            |
    | set_option    | set_definition    |
    | setq          | (N/A)             |
    | setq_option   | (N/A)             |
    | unset         | undefine          |
    | get_option    | get_definition    |
    | delete_option | delete_definition |
    +---------------+-------------------+

I'm sure you can understand this analogy by this example.

    $builder->set(
        xtics => 10,
        key   => undef
    );
    $builder->define(
        a      => 100,
        'f(x)' => 'sin(a * x)',
        b      => undef
    );
    $builder->to_string();
    ## => set xtics 10
    ## => unset key
    ## => a = 100
    ## => f(x) = sin(a * x)
    ## => undefine b

$builder = $builder->define($def_name => $def_value, ...)

$builder = $builder->define($definitions)

Set function and variable definitions. See set() method.

$builder = $builder->set_definition(...)

Alias for define() method.

$builder = $builder->undefine($def_name, ...)

Short-cut for define($def_name => undef). See unset() method.

@def_values = $builder->get_definition($def_name)

Get definitions from the $builder. See get_option() method.

$builder = $builder->delete_definition($def_name, ...)

Delete definitions from the $builder. See delete_option() method.

OBJECT METHODS - PLOTTING

Methods for plotting.

All plotting methods are non-mutator, that is, they don't change the state of the $builder. This means you can plot different datasets with the same settings.

By default, plotting methods run a gnuplot process background, and let it do the plotting work. The variable @Gnuplot::Builder::Process::COMMAND is used to start the gnuplot process. See Gnuplot::Builder::Process for detail.

$result = $builder->plot($dataset, ...)

Build the script and plot the given $datasets with gnuplot's "plot" command. This method lets a gnuplot process do the actual job.

You can specify more than one $datasets to plot.

The return value $result is the data that the gnuplot process writes to STDOUT and STDERR (by default).

Usually you should use a Gnuplot::Builder::Dataset object for $dataset. In this case, you can skip the rest of this section.

In detail, $dataset is either a string or an object.

  • If $dataset is a string, it's treated as the dataset parameters for "plot" command.

        $builder->plot(
            'sin(x) with lines lw 2',
            'cos(x) with lines lw 5',
            '"datafile.dat" using 1:3 with points ps 4'
        );
  • The above code plots "sin(x)" and "cos(x)" curves and data points in the file "datafile.dat".

    If $dataset is an object, it must implement params_string() and write_data_to() methods (like Gnuplot::Builder::Dataset).

    params_string() method is supposed to return a string of the dataset parameters, and write_data_to() method provide the inline data if it has.

    The two methods are called like

        ($params_str) = $dataset->params_string();
        $dataset->write_data_to($writer);

    where $writer is a code-ref that you must call with the inline data you have.

        package My::Data;
        
        sub new {
            my ($class, $x_data, $y_data) = @_;
            return bless { x => $x_data, y => $y_data }, $class;
        }
        
        sub params_string { q{"-" using 1:2 title "My Data" with lp} }
        
        sub write_data_to {
            my ($self, $writer) = @_;
            foreach my $i (0 .. $#{$self->{x}}) {
                my ($x, $y) = ($self->{x}[$i], $self->{y}[$i]);
                $writer->("$x $y\n");
            }
        }
        
        $builder->plot(My::Data->new([1,2,3], [1,4,9]));

    If write_data_to() method doesn't pass any data to the $writer, the plot() method doesn't generate the inline data section.

$result = $builder->plot_with(%args)

Plot with more functionalities than plot() method.

Fields in %args are as follows. Note that you can store default values for some arguments in $builder. See "OBJECT METHODS - PLOTTING OPTIONS" for detail.

dataset => DATASETS (mandatory)

Datasets to plot. It is either a dataset or an array-ref of datasets. See plot() for specification of datasets.

output => OUTPUT_FILENAME (optional)

If set, "set output" command is printed just before "plot" command, so that it would output the plot to the specified file. The specified file name is quoted. After "plot" command, it prints "set output" command with no argument to unlock the file.

If not set, it won't print "set output" commands.

no_stderr => BOOL (optional, default: $Gnuplot::Builder::Process::NO_STDERR)

If set to true, the return value $result contains gnuplot's STDOUT only. It doesn't contain STDERR. If false, $result contains both STDOUT and STDERR. This option has no effect if writer or async is set.

By default, it's false. You can change the default by $Gnuplot::Builder::Process::NO_STDERR package varible.

writer => CODE-REF (optional)

A code-ref to receive the whole script string instead of the gnuplot process. If set, it is called one or more times with the script string that $builder builds. In this case, the return value $result will be an empty string, because no gnuplot process is started.

If not set, $builder streams the script into the gnuplot process. The return value $result will be the data the gnuplot process writes to STDOUT and STDERR.

async => BOOL (optional, default: $Gnuplot::Builder::Process::ASYNC)

If set to true, it won't wait for the gnuplot process to finish. In this case, the return value $result will be an empty string.

Using async option, you can run more than one gnuplot processes to do the job. However, the maximum number of gnuplot processes are limited to the variable $Gnuplot::Builder::Process::MAX_PROCESSES. See Gnuplot::Builder::Process for detail.

If set to false, it waits for the gnuplot process to finish and return its output.

By default it's false, but you can change the default by $Gnuplot::Builder::Process::ASYNC package variable.

    my $script = "";
    $builder->plot_with(
        dataset => ['sin(x)', 'cos(x)'],
        output  => "hoge.eps",
        writer  => sub {
            my ($script_part) = @_;
            $script .= $script_part;
        }
    );
    
    $script;
    ## => set output 'hoge.eps'
    ## => plot sin(x),cos(x)
    ## => set output

$result = $builder->splot($dataset, ...)

Same as plot() method except it uses "splot" command.

$result = $builder->splot_with(%args)

Same as plot_with() method except it uses "splot" command.

$result = $builder->multiplot($option, $code)

Build the script, input the script into a new gnuplot process, start a new multiplot context and execute the $code in the context. This method lets a gnuplot process do the actual job.

$option is the option string for "set multiplot" command. $option is optional.

Mandatory argument $code is a code-ref that is executed immediately. The $code is called like

    $code->($writer)

where $writer is a code-ref that you can call to write any data to the gnuplot process.

The return value $result is the data that the gnuplot process writes to STDOUT and STDERR (by default).

The script written to the $writer is enclosed by "set multiplot" and "unset multiplot" commands, and passed to the gnuplot process. So the following example creates a multiplot figure of sin(x) and cos(x).

    $builder->multiplot('layout 2,1', sub {
        my $writer = shift;
        $writer->("plot sin(x)\n");
        $writer->("plot cos(x)\n");
    });

If you call plotting methods (including multiplot() itself) without explicit writer in the $code block, those methods won't start a new gnuplot process. Instead they write the script to the $writer that is given by the enclosing multiplot() method.

    $builder->multiplot(sub {
        my $writer = shift;
        my $another_builder = Gnuplot::Builder::Script->new;
        
        $another_builder->plot("sin(x)");   ## This is the same as below
        $another_builder->plot_with(
            dataset => "sin(x)",
            writer => $writer
        );
    });

You can mix using Gnuplot::Builder::Script objects and using $writer directly in a single code block. A good rule of thumb is that a Gnuplot::Builder::Script object should be a piece of gnuplot script that makes just one plot. If you want to write anything that doesn't belong to a plot, you should use $writer directly.

For example,

    $builder->multiplot('layout 2,2', sub {
        my $writer = shift;
        my $another_builder = Gnuplot::Builder::Script->new(xrange => q{[-pi:pi]}, title => q{"1. sin(x)"});
        $another_builder->plot("sin(x)");
        $writer->("set multiplot next\n");
        $another_builder->new_child()->set(title => q{"2. sin(2x)"})->plot("sin(2 * x)");
    });

The above example uses a Gnuplot::Builder::Script object and its child to make two plots, while it uses $writer to write "set multiplot next" command. The "set multiplot next" command is not part of a plot, but it controls the layout of plots. So we should use $writer to write it.

$result = $builder->multiplot_with(%args)

Multiplot with more functionalities than multiplot() method.

Fields in %args are

do => CODE-REF (mandatory)

A code-ref that is executed in the multiplot context.

option => OPTION_STR (optional, default: "")

An option string for "set multiplot" command.

no_stderr => BOOL (optional, default: $Gnuplot::Builder::Process::NO_STDERR)

If set to true, the return value $result contains STDOUT only. It doesn't contain gnuplot's STDERR.

See plot_with() method for detail.

output => OUTPUT_FILENAME (optional)

If set, "set output" command is printed just before "set multiplot" command.

See plot_with() method for detail.

writer => CODE-REF (optional)

A code-ref to receive the whole script string. If set, the return value $result will be an empty string.

See plot_with() method for detail.

async => BOOL (optional, default: $Gnuplot::Builder::Process::ASYNC)

If set to true, it won't wait for the gnuplot process to finish. In this case, the return value $result will be an empty string.

See plot_with() method for detail.

    my $builder = Gnuplot::Builder::Script->new;
    $builder->set(mxtics => 5, mytics => 5, term => "png");
    
    my $script = "";
    $builder->multiplot_with(
        output => "multi.png",
        writer => sub { $script .= $_[0] },
        option => 'title "multiplot test" layout 2,1',
        do => sub {
            my $another_builder = Gnuplot::Builder::Script->new;
            $another_builder->setq(title => "sin")->plot("sin(x)");
            $aonther_builder->setq(title => "cos")->plot("cos(x)");
        }
    );
    
    $script;
    ## => set mxtics 5
    ## => set mytics 5
    ## => set term png
    ## => set output 'multi.png'
    ## => set multiplot title "multiplot test" layout 2,1
    ## => set title 'sin'
    ## => plot sin(x)
    ## => set title 'cos'
    ## => plot cos(x)
    ## => unset multiplot
    ## => set output

$result = $builder->run($command, ...)

Build the script, input the script into a new gnuplot process and input the $commands to the process as well. This method lets a gnuplot process do the actual job.

run() method is a low-level method of plot(), splot(), multiplot() etc. You should use other plotting methods if possible.

$command is either a string or a code-ref. You can specify more than one $commands, which are executed sequentially.

  • If $command is a string, it is input to the process as a gnuplot sentence.

  • If $command is a code-ref, it is immediately called like

        $command->($writer)

    where $writer is a code-ref that you can call to write any data to the gnuplot process.

The return value $result is the data that the gnuplot process writes to STDOUT and STDERR (by default).

run() method is useful when you want to execute "plot" command more than once in a single gnuplot process. For example,

    my $builder = Gnuplot::Builder::Script->new(<<SET);
    term = gif size 500,500 animate
    output = "waves.gif"
    SET
    
    my $FRAME_NUM = 10;
    $builder->run(sub {
        my $writer = shift;
        foreach my $phase_index (0 .. ($FRAME_NUM-1)) {
            my $phase_deg = 360.0 * $phase_index / $FRAME_NUM;
            $writer->("plot sin(x + $phase_deg / 180.0 * pi)\n");
        }
    });

The above example generates an animated GIF of a traveling sin wave.

Like the $code argument for multiplot() method, if you call plotting methods (including run() itself) without explicit writer inside $command code block, those methods won't start a new gnuplot process. Instead they write the script to the $writer given by the enclosing run() method.

So you can rewrite the run() method of the above example to

    $builder->run(sub {
        my $another_builder = Gnuplot::Builder::Script->new;
        foreach my $phase_index (0 .. ($FRAME_NUM-1)) {
            my $phase_deg = 360.0 * $phase_index / $FRAME_NUM;
            $another_builder->plot("sin(x + $phase_deg / 180.0 * pi)");
        }
    });

run() method may also be useful if you want to enclose some sentences with pairs of sentences. For example,

    $builder->run(
        "set multiplot layout 2,2",
        "do for [name in  'A B C D'] {",
        sub {
            my $another_builder = Gnuplot::Builder::Script->new;
            $another_builder->define(filename => "name . '.dat'");
            $another_builder->plot('filename u 1:2');
        },
        "}",
        "unset multiplot"
    );

Well, maybe this is not a good example, though. In this case I would rather use multiplot() and iteration in Perl. There is more than one way to do it.

$result = $builder->run_with(%args)

Run the script with more functionalities than run() method.

do => COMMANDS (optional)

A command or an array-ref of commands to be executed. See run() for specification of commands.

output => OUTPUT_FILENAME (optional)

If set, "set output" command is printed just before running commands.

See plot_with() method for detail.

no_stderr => BOOL (optional, default: $Gnuplot::Builder::Process::NO_STDERR)

If set to true, the return value $result contains STDOUT only. It doesn't contain gnuplot's STDERR.

See plot_with() method for detail.

writer => CODE-REF (optional)

A code-ref to receive the whole script string. If set, the return value $result will be an empty string.

See plot_with() method for detail.

async => BOOL (optional, default: $Gnuplot::Builder::Process::ASYNC)

If set to true, it won't wait for the gnuplot process to finish. In this case, the return value $result will be an empty string.

See plot_with() method for detail.

    my $builder = Gnuplot::Builder::Script->new;
    my $script = "";
    
    $builder->run_with(
        writer => sub { $script .= $_[0] },
        do => [
            "cd 'subdir1'",
            sub {
                foreach my $name (qw(a b c d)) {
                    $builder->plot("'$name.dat' u 1:2 title '$name'");
                }
            }
        ]
    );
    
    $script;
    ## => cd 'subdir1'
    ## => plot 'a.dat' u 1:2 title 'a'
    ## => plot 'b.dat' u 1:2 title 'b'
    ## => plot 'c.dat' u 1:2 title 'c'
    ## => plot 'd.dat' u 1:2 title 'd'

OBJECT METHODS - PLOTTING OPTIONS

Methods in this section are currently experimental.

As you can see in "OBJECT METHODS - PLOTTING", plot_with(), splot_with(), multiplot_with() and run_with() methods share some arguments. With the methods listed in this section, you can store default values for these arguments in a $builder instance.

You can store default values for the following plotting options:

output => OUTPUT_FILENAME
no_stderr => BOOL
writer => CODE-REF
async => BOOL

For detail about these arguments, see plot_with() method.

Note that those default values also affect the behavior of short-hand methods, i.e. plot(), splot(), multiplot() and run().

The default values stored in a $builder are used when the correponding arguments are not passed to the plotting methods. In other words, arguments directly passed to the plotting methods have precedence over the per-instance default values.

The plotting options stored in a $builder is inheritable, just like the "set" and "define" options.

$builder = $builder->set_plot($arg_name => $arg_value, ...)

Set the plotting option $arg_name to $arg_value. $arg_name must be one of the plotting options listed above. You can set more than one $arg_name => $arg_value pairs.

    $builder->set_plot(
        output => "hoge.png",
        async => 1
    );
    
    $builder->plot('sin(x)');
    ## Same as:
    ##   $builder->plot_with(
    ##       dataset => 'sin(x)',
    ##       output => "hoge.png",
    ##       async => 1
    ##   );
    
    $builder->plot_with(
        dataset => 'cos(x)',
        output => 'foobar.png'
    );
    ## Same as:
    ##   $builder->plot_with(
    ##       dataset => 'cos(x)',
    ##       output => 'foobar.png',
    ##       async => 1
    ##   );

$arg_value = $builder->get_plot($arg_name)

Get the value for $arg_name.

If $arg_name is not set in $builder, it returns the value set in its parent builder. If none of the ancestors have $arg_name, it returns undef.

$builder = $builder->delete_plot($arg_name, ...)

Delete the default value for $arg_name. You can specify more than one $arg_names.

OBJECT METHODS - INHERITANCE

A Gnuplot::Builder::Script object can extend and/or override another Gnuplot::Builder::Script object. This is similar to JavaScript's prototype-based inheritance.

Let $parent and $child be the parent and its child builder, respectively. Then $child builds a script on top of what $parent builds. That is,

  • Sentences added by $child->add() method are appended to the $parent's script.

  • Option settings and definitions in $child are appended to the $parent's script, if they are not set in $parent.

  • Option settings and definitions in $child are substituted in the $parent's script, if they are already set in $parent.

A simlar rule is applied to plotting options. Plotting options in $child are used if those options are set in $child. Otherwise, plotting options in $parent are used.

$builder = $builder->set_parent($parent_builder)

Set $parent_builder as the $builder's parent.

If $parent_builder is undef, $builder doesn't have a parent anymore.

$parent_builder = $builder->get_parent()

Return the $builder's parent. It returns undef if $builder does not have a parent.

$child_builder = $builder->new_child()

Create and return a new child builder of $builder.

This is a short-cut for Gnuplot::Builder::Script->new->set_parent($builder).

OVERLOAD

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

    "$builder" eq $builder->to_string;

Data::Focus COMPATIBLITY

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

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

Note that the lens calls get_option() always in scalar context.

    use Data::Focus qw(focus);
    
    my $scalar = focus($builder)->get("xrange");
    ## same as: my $scalar = scalar($builder->get_option("xrange"));
        
    my @list = focus($builder)->list("style");
    ## same as: my @list = scalar($builder->get_option("style"));
        
    focus($builder)->set(xrange => '[10:100]');
    ## same as: $builder->set_option(xrange => '[10:100]');

This results in a surprising behavior if you pass array-refs to set() method. Use with care.

SEE ALSO

Gnuplot::Builder::Dataset

AUTHOR

Toshio Ito, <toshioito at cpan.org>