Gnuplot::Builder::Template - predefined Gnuplot::Builder objects as templates
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
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.
The following functions are exported only by request.
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).
$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.
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.
gusing()
$Gnuplot::Builder::Template::USING
Some keys may be added to the template in the future. See "COMPATIBILITY" for detail.
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).
$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.
-point_incr
gevery()
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.
$Gnuplot::Builder::Template::EVERY
The template Gnuplot::Builder::JoinDict object for gusing() function.
The template Gnuplot::Builder::JoinDict object for gevery() function.
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.
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.
Toshio Ito, <toshioito at cpan.org>
<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.