/ 
Gnuplot-Builder-0.32
River stage one • 1 direct dependent • 1 total dependent
/ Gnuplot::Builder::Template

NAME

Gnuplot::Builder::Template - predefined Gnuplot::Builder objects as templates

SYNOPSIS

use Gnuplot::Builder::Dataset;
use Gnuplot::Builder::Template qw(gusing gevery);
    
my $dataset = Gnuplot::Builder::Dataset->new_file("sample.dat");
$dataset->set(
    using => gusing(
        -x => 1, -xlow => 2, -xhigh => 3,
        -y => 4, -ylow => 5, -yhigh => 6
    ),
    every => gevery(
        -start_point => 1, -end_point => 50
    ),
    with => "xyerrorbars",
);
"$dataset";  ## => 'sample.dat' using 1:4:2:3:5:6 every 1::1::50 with xyerrorbars

$dataset->get_option("using")->get("-xlow");        ## => 2
$dataset->get_option("every")->get("-start_point"); ## => 1

DESCRIPTION

This module is in alpha state. API and object specification may be changed in the future.

Gnuplot::Builder::Template provides template objects useful to build some gnuplot script elements. These objects are structured, so you can modify their parameters partially.

EXPORTABLE FUNCTIONS

The following functions are exported only by request.

$using_joindict = gusing(@key_value_pairs)

Create and return a Gnuplot::Builder::JoinDict object useful for "using" parameters. Actually it's just a short for $Gnuplot::Builder::Template::USING->set(@key_value_pairs).

The Gnuplot::Builder::JoinDict object returned by this function has predifined keys. By default, values for the predefined keys are all undef.

The predefined keys are listed in the right column of the following table. Typical use cases for the keys are listed in the left column.

USE CASES       | KEYS
================+==============================================
                | -x -y
filledcurves    | -y1 -y2
                | -z
polar           | -t
image           | -value
smooth kdensity | -weight -bandwidth
rgbalpha        | -r -g -b -a
labels          | -string -label
vectors         | -xdelta -ydelta -zdelta
xerrorbars      | -xlow -xhigh
yerrorbars      | -ylow -yhigh
financebars     | -date -open -low -high -close
candlesticks    | -box_min -whisker_min -whisker_high -box_high
boxes           | -x_width
boxplot         | -boxplot_factor
circles         | -radius -start_angle -end_angle
ellipses        | -major_diam -minor_diam -angle
variable style  | -pointsize -arrowstyle -linecolor

Note that these keys are in the same order as shown in the table, so you would always get the "using" parameter in the correct order.

For example,

my $using = gusing(-y => 5, -x => 3);
"$using"  ## => 3:5

OK, that doesn't seem very useful, but how about this?

my $using = gusing(-x => 1,
                   -whisker_min => 2, -box_min => 3,
                   -box_high => 4, -whisker_high => 5);
"$using";  ## 1:3:2:5:4

Now you don't have to remember the complicated "using" spec of "candlesticks" style. Just give the parameters with the keys, and the Gnuplot::Builder::JoinDict object arranges them in the correct order.

You can add your own key-value pairs to the parameters. For example,

my $using = gusing(-x => 1, -y => 2, -x_width => "(0.7)", tics => "xticlabels(3)");
"$using";  ## 1:2:(0.7):xticlabels(3)

Keys that start with "-" are preserved. If you add a key that starts with "-" but is not listed in the above table, this function dies.

gusing() function uses $Gnuplot::Builder::Template::USING package variable as the template. You can customize it.

Some keys may be added to the template in the future. See "COMPATIBILITY" for detail.

$every_joindict = gevery(@key_value_pairs)

Like gusing(), it creates and returns a Gnuplot::Builder::JoinDict object useful for "every" parameters. Actually it's just a short for $Gnuplot::Builder::Template::EVERY->set(@key_value_pairs).

The Gnuplot::Builder::JoinDict object returned by this function has the following predifined keys.

-point_incr
-block_incr
-start_point
-start_block
-end_point
-end_block

By default, -point_incr is 1 and everything else is undef. This makes it possible to casually pass gevery() for "every" parameter and alter it afterward.

my $dataset = Gnuplot::Builder::Dataset->new_file(
    "data", every => gevery
);
"$dataset";  ## => 'data' every 1
$dataset->set(
    every => $dataset->get_option("every")->set(-start_point => 5)
);
"$dataset";  ## => 'data' every 1::5

Like gusing(), keys that start with "-" are preserved. If you add a key that starts with "-" but is not listed in the above list, this function dies.

gevery() function uses $Gnuplot::Builder::Template::EVERY package variable as the template. You can customize it.

Some keys may be added to the template in the future. See "COMPATIBILITY" for detail.

PACKAGE VARIABLES

$USING

The template Gnuplot::Builder::JoinDict object for gusing() function.

$EVERY

The template Gnuplot::Builder::JoinDict object for gevery() function.

COMPATIBILITY

This module is still in alpha, so any part of this module (including this section) may be changed in the future. For now you can think of this section as a draft of our compatibility policy.

This section describes what part of this module may be changed in the future releases and what part is NOT gonna be changed.

gusing() and gevery()

  • No predefined key will be removed. (although some of them may get deprecated)

  • Predefined keys may be added/inserted at any part in the current list of predefined keys.

  • All predefined keys start with "-".

  • The relative order of predefined keys will always be preserved.

AUTHOR

Toshio Ito, <toshioito at cpan.org>