NAME

Gnuplot::Builder - object-oriented gnuplot script builder

SYNOPSIS

use Gnuplot::Builder;

my $script = gscript(grid => "y", mxtics => 5, mytics => 5);
$script->setq(
    xlabel => 'x values',
    ylabel => 'y values',
    title  => 'my plot'
);
$script->define('f(x)' => 'sin(x) / x');

print $script->plot(
    gfile('result.dat',
          using => '1:2:3', title => "'Measured'", with => "yerrorbars"),
    gfunc('f(x)', title => "'Theoretical'", with => "lines")
);

gwait();

DESCRIPTION

Gnuplot::Builder is a gnuplot script builder. Its advantages include:

• Object-oriented. Script settings are encapsulated in a Gnuplot::Builder::Script object, and dataset parameters are in a Gnuplot::Builder::Dataset object. It eliminates global variables, which gnuplot uses extensively.

• Thin. Gnuplot::Builder just builds a script text and streams it into a gnuplot process. Its behavior is extremely predictable and easy to debug.

• Hierarchical. Gnuplot::Builder::Script and Gnuplot::Builder::Dataset objects support prototype-based inheritance, just like JavaScript objects. This is useful for hierarchical configuration.

• Interactive. Gnuplot::Builder works well both in batch scripts and in interactive shells. Use Devel::REPL or Reply or whatever you like instead of the plain old gnuplot interative shell.

• Parallel. Gnuplot::Builder's policy is "one gnuplot process for one plot". You can run more than one gnuplot processes in parallel to boost the plotting through-put.

USAGE GUIDE

Gnuplot::Builder module is meant to be used in interactive shells. It exports some easy-to-type functions by default.

For batch scripts, I recommend using Gnuplot::Builder::Script and Gnuplot::Builder::Dataset directly. These modules are purely object-oriented, and won't mess up your namespace.

For Windows Users

Batch scripts using Gnuplot::Builder are fine in Windows.

In interactive shells, plot windows might not persist when you use regular Gnuplot::Builder. As a workaround, try Gnuplot::Builder::Wgnuplot.

Plot Windows

Gnuplot::Builder supports plots in interactive windows. See "CONFIGURATION FOR PLOT WINDOWS" for known issues about that.

Debugging

Because Gnuplot::Builder is a very thin module, it does not guarantee to build valid gnuplot scripts. You need to debug your script when you got an invalid script. See "DEBUGGING TIPS" for detail.

EXPORTED FUNCTIONS

Gnuplot::Builder exports the following functions by default.

$script = gscript(@script_options)

Create a script object. It's just an alias for Gnuplot::Builder::Script->new(...). See Gnuplot::Builder::Script for detail.

$dataset = gfunc($funcion_spec, @dataset_options)

Create a dataset object representing a function, such as "sin(x)" and "f(x)". It's just an alias for Gnuplot::Builder::Dataset->new(...). See Gnuplot::Builder::Dataset for detail.

$dataset = gfile($filename, @dataset_options)

Create a dataset object representing a data file. It's just an alias for Gnuplot::Builder::Dataset->new_file(...). See Gnuplot::Builder::Dataset for detail.

$dataset = gdata($inline_data, @dataset_options)

Create a dataset object representing a data file. It's just an alias for Gnuplot::Builder::Dataset->new_data(...). See Gnuplot::Builder::Dataset for detail.

$help_message = ghelp(@help_args)

Run the gnuplot "help" command and return the help message. @help_args is the arguments for the "help" command. They are joined with white spaces.

ghelp("style data");

## or you can say

ghelp("style", "data");

gwait()

Wait for all gnuplot processes to finish. It's just an alias for Gnuplot::Builder::Process->wait_all().

CONFIGURATION FOR PLOT WINDOWS

Gnuplot::Builder supports plots in interactive windows (terminals such as "x11", "windows" etc). However, plot windows are very tricky, so you might have to configure Gnuplot::Builder in advance.

Design Goals

In terms of plot windows, Gnuplot::Builder aims to achieve the following goals.

• Plotting methods should return immediately, without waiting for plot windows to close.

• Plot windows should persist even after the Perl process using Gnuplot::Builder exits.

• Plot windows should be fully interactive. It should allow zooming and clipping etc.

Configuration Patterns and Their Problems

The best configuration to achieve the above goals depends on your platform OS, version of your gnuplot, the terminal to use and the libraries it uses. Unfortunately there is no one-size-fits-all solution.

If you use Windows, just use Gnuplot::Builder::Wgnuplot.

Otherwise, you have two configuration points.

persist mode

Whether or not gnuplot's "persist" mode is used. This is configured by @Gnuplot::Builder::Process::COMMAND variable.

@Gnuplot::Builder::Process::COMMAND = qw(gnuplot);           ## persist OFF
@Gnuplot::Builder::Process::COMMAND = qw(gnuplot --persist); ## persist ON

By default, it's ON.

pause mode

Whether or not "pause mouse close" command is used. This is configured by $Gnuplot::Builder::Process::PAUSE_FINISH variable.

$Gnuplot::Builder::Process::PAUSE_FINISH = 0; ## pause OFF
$Gnuplot::Builder::Process::PAUSE_FINISH = 1; ## pause ON

By default, it's OFF.

The above configurations can be set via environment variables. See Gnuplot::Builder::Process for detail. Note that the default values for these configurations may be changed in future releases.

I recommend "persist: OFF, pause: ON" unless you use "qt" terminal with gnuplot 4.6.5 or below. This makes a fully functional plot window whose process gracefully exits when you close the window.

If you use "qt" terminal with gnuplot 4.6.5 or below, use "persist: ON, pause: OFF". This is because, as of gnuplot 4.6.5, "qt" terminal doesn't respond to the "pause" command, leading to a never-ending process. This process-leak can be dangerous, so the "pause" mode is OFF by default. This bug is fixed in gnuplot 4.6.6.

The default setting "persist: ON, pause: OFF" doesn't cause process-leak in all environments I tested. However, plot windows of "x11" or "qt" terminals in "persist" mode lack interactive functionality such as zooming and clipping. This is gnuplot's limitation in "persist" mode. "wxt" terminal may be unstable (it crashes or freezes) in some environments.

DEBUGGING TIPS

Plotting methods of Gnuplot::Builder::Script returns the output from the gnuplot process. Always show the return value, because it contains an error message when something is wrong.

my $script = Gnuplot::Builder::Script->new();
## my $script = gscript();   ## same

print $script->plot("sin(x)");

Sometimes you need to peek the script text written to the gnuplot process. To do that, run your program with Gnuplot::Builder::Tap loaded.

$ perl -MGnuplot::Builder::Tap your_program.pl

Or you can set $Gnuplot::Builder::Process::TAP variable. See Gnuplot::Builder::Process for detail.

Common Errors

• Quote string literals explicitly.

  $script->set(xlabel => 'hogehoge');   ## NG!
  $script->set(xlabel => '"hogehoge"'); ## OK
  $script->setq(xlabel => 'hogehoge');  ## OK

• Arrange dataset options in valid order.

  $dataset = gfile('data.txt', with => "linespoints", using => "1:3"); ## NG!
  $dataset = gfile('data.txt', using => "1:3", with => "linespoints"); ## OK

• Encode wide characters appropriately.

  use utf8;
  use Gnuplot::Builder::Process;
  
  ## Let Gnuplot::Builder automatically encode input data for gnuplot process
  $Gnuplot::Builder::Process::ENCODING = 'utf8';
  
  $script->set(title => '"日本語のタイトル"');
  $script->plot('sin(x)');

  Otherwise, a warning like Wide character in print would appear. See also: "$ENCODING" in Gnuplot::Builder::Process.

REPOSITORY

https://github.com/debug-ito/Gnuplot-Builder

BUGS AND FEATURE REQUESTS

Please report bugs and feature requests to my Github issues https://github.com/debug-ito/Gnuplot-Builder/issues.

Although I prefer Github, non-Github users can use CPAN RT https://rt.cpan.org/Public/Dist/Display.html?Name=Gnuplot-Builder. Please send email to bug-Gnuplot-Builder at rt.cpan.org to report bugs if you do not have CPAN RT account.

AUTHOR

Toshio Ito, <toshioito at cpan.org>

CONTRIBUTORS

• Moritz Grosch (LittleFox)

LICENSE AND COPYRIGHT

Copyright 2014 Toshio Ito.

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.

cpanm Gnuplot::Builder

perl -MCPAN -e shell
install Gnuplot::Builder