The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
Gnuplot-Builder-0.21
River stage one • 1 direct dependent • 1 total dependent
/ Gnuplot::Builder

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

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.

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.

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");

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. This makes a fully functional plot window whose process gracefully exits when you close the window.

Do not use the pause mode if you use "qt" terminal. 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.

The second best is "persist: ON, pause: OFF". However, plot windows of "x11" or "qt" terminals in "persist" mode lack interactive functionality such as zooming and clipping. "wxt" terminal may be unstable (it crashes or freezes) in some environments.

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>

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.