++ed by:
1 non-PAUSE user

# NAME

Graphics::GnuplotIF - A dynamic Perl interface to gnuplot

# VERSION

This documentation refers to Graphics::GnuplotIF version 1.2

# SYNOPSIS

``````  use Graphics::GnuplotIF;

my  @x   = ( -2, -1.50,  -1,  -0.50,  0,  0.50,  1, 1.50, 2 ); # x values
my  @y1  = (  4,  2.25,   1,   0.25,  0,  0.25,  1, 2.25, 4 ); # function 1
my  @y2  = (  2,  0.25,  -1,  -1.75, -2, -1.75, -1, 0.25, 2 ); # function 2

my  \$plot1  = Graphics::GnuplotIF->new( title => "line", style => "points" );

\$plot1->gnuplot_plot_y( \@x );              # plot 9 points over 0..8

\$plot1->gnuplot_set_title( "parabola" );    # new title
\$plot1->gnuplot_set_style( "lines" );       # new line style

\$plot1->gnuplot_plot_xy( \@x, \@y1, \@y2 ); # rewrite plot1 : y1 and y2 over x

my  \$plot2  = Graphics::GnuplotIF->new;

\$plot2->gnuplot_set_xrange(  0, 4 );        # set x range
\$plot2->gnuplot_set_yrange( -2, 2 );        # set y range
\$plot2->gnuplot_cmd( "set grid" );          # send a gnuplot command
\$plot2->gnuplot_plot_equation(              # 3 equations in one plot
"y1(x) = sin(x)",
"y2(x) = cos(x)",
"y3(x) = sin(x)/x" );

\$plot2->gnuplot_plot_equation(              # rewrite plot 2
"y4(x) = 2*exp(-x)*sin(4*x)" );

# DESCRIPTION

Graphics::GnuplotIF is a simple and easy to use dynamic Perl interface to gnuplot. gnuplot is a freely available, command-driven graphical display tool for Unix. It compiles and works quite well on a number of Unix flavours as well as other operating systems.

This module enables sending display requests asynchronously to gnuplot through simple Perl subroutine calls.

Graphics::GnuplotIF starts gnuplot as a separate process. The plot commands are send through a pipe. The graphical output from gnuplot will be displayed immediately.

Several independent plots can be started from one script. Each plot has its own pipe. All pipes will be closed automatically when the script terminates. The gnuplot processes terminate when the corresponding pipes are closed. Their graphical output will now disappear.

Graphics::GnuplotIF is similar to ` gnuplot_i `, a C interface to gnuplot ( http://ndevilla.free.fr/gnuplot/ ), and to ` gnuplot_i++ `, a C++ interface to gnuplot ( http://jijo.cjb.net/code/cc++ ).

# SUBROUTINES/METHODS

An object of this class represents an interface to a running gnuplot process. During the creation of an object such an process will be started for each such object. Communication is done through an unidirectional pipe; the resulting stream is write-only.

## new

The constructor creates a new gnuplot session object, referenced by a handle:

``  \$plot1  = Graphics::GnuplotIF->new( );``

A few named arguments can be passed as key - value pairs (here shown with their default values):

``````  style   => "lines",     # one of the gnuplot line styles (see below)
title   => "",          # string
xlabel  => "x",         # string
ylabel  => "y",         # string
xrange  => [],          # array reference; autoscaling, if empty
xrange  => [],          # array reference; autoscaling, if empty``````

These attributes are stored in each object. Allowed line styles are

``````  boxes     dots   filledcurves  fsteps  histeps
impulses  lines  linespoints   points  steps``````

The objects are automatically deleted by a destructor. The destructor closes the pipe to the gnuplot process belonging to that object. The gnuplot process will also terminate and remove the graphic output. The termination can be controlled by the method `gnuplot_pause` .

## gnuplot_plot_y

``  \$plot1->gnuplot_plot_y( \@y1, \@y2 );``

`gnuplot_plot_y` takes one or more array references and plots the values over the x-values 0, 1, 2, 3, ...

## gnuplot_plot_xy

``  \$plot1->gnuplot_plot_xy( \@x, \@y1, \@y2 );``

`gnuplot_plot_xy` takes two or more array references. The first array is assumed to contain the x-values for the following function values.

## gnuplot_plot_equation

``````  \$plot2->gnuplot_plot_equation(         # 3 equations in one plot
"y1(x) = sin(x)",
"y2(x) = cos(x)",
"y3(x) = sin(x)/x" );``````

`gnuplot_plot_equation` takes one or more gnuplot function descriptions as strings. The plot ranges can be controlled by `gnuplot_set_xrange` and `gnuplot_set_yrange` .

## gnuplot_pause

``  \$plot1->gnuplot_pause( [time] [,text] );``

This is an emulation of the gnuplot `pause` command. It displays any text associated with the command and waits a specified amount of time or until the carriage return is pressed.

`time` may be any constant or expression. Choosing -1 (default) will wait until a carriage return is hit, zero (0) won't pause at all, and a positive number will wait the specified number of seconds.

The time value and the text are stored in the object and reused. A sequence like

``````  \$plot1->gnuplot_pause( 5 );            # delay is 5 seconds
\$plot1->gnuplot_plot_y( \@y1 );

\$plot1->gnuplot_pause( );
\$plot1->gnuplot_plot_y( \@y2 );

\$plot1->gnuplot_pause( );
\$plot1->gnuplot_plot_y( \@y3 );

\$plot1->gnuplot_pause( -1 );``````

will display 3 plots with 5 seconds delay and wait for a final carriage return.

## gnuplot_cmd

``````  \$plot2->gnuplot_cmd( 'set grid',
'set timestamp "%d/%m/%y %H:%M" 0,0 "Helvetica"'
);``````

`gnuplot_cmd` can be used to send one or more gnuplot commands, especially those not wrapped by a Graphics::GnuplotIF method.

### Write a plot into a file

`gnuplot_cmd` can be used to write a plot into a file or make a hardcopy by setting/resetting the terminal and the output file:

``````  \$plot1->gnuplot_cmd( 'set terminal png color',
'set output   "plot1.png" ' );

\$plot1->gnuplot_plot_xy( \@x, \@y1, \@y2 );

\$plot1->gnuplot_cmd( 'set output',
'set terminal x11' );``````

### Make a hardcopy

A hardcopy can be made with an appropriate output format and a pipe to a printer:

``````  \$plot1->gnuplot_cmd( 'set terminal postscript',
'set output   " | lpr " ' );

\$plot1->gnuplot_plot_xy( \@x, \@y1, \@y2 );

\$plot1->gnuplot_cmd( 'set output',
'set terminal x11' );``````

## gnuplot_reset

``  \$plot1->gnuplot_reset();``

Set all options set with the `set` command to their gnuplot default values.

## gnuplot_set_style

``  \$plot1->gnuplot_set_style( "steps" );   # new line style``

Sets one of the allowed line styles (see new ) in a plot command.

## gnuplot_set_title

``  \$plot1->gnuplot_set_title("parabola");  # new title``

Sets the plot title. Equivalent to the gnuplot command `set title "parabola"`.

## gnuplot_set_xlabel

``  \$plot1->gnuplot_set_xlabel("time (days)");``

Sets the x axis label. Equivalent to the gnuplot command `set xlabel "time (days)"`.

## gnuplot_set_ylabel

``  \$plot1->gnuplot_set_ylabel("bugs fixed");``

Sets the y axis label. Equivalent to the gnuplot command `set ylabel "bugs fixed"`.

## gnuplot_set_xrange

``  \$plot1->gnuplot_set_xrange( left, right );``

Sets the horizontal range that will be displayed. Equivalent to the gnuplot command `set xrange [left:right]`.

## gnuplot_set_yrange

``  \$plot1->gnuplot_set_yrange( low, high );``

Sets the vertical range that will be displayed. Equivalent to the gnuplot command `set yrange [low:high]`.

## gnuplot_set_plot_titles

``  \$plot1->gnuplot_set_plot_titles( @ytitles );``

Sets the list of titles used in the key for each of the y-coordinate data sets specified in subsequent calls to gnuplot_plot_xy or gnuplot_plot_y commands. This is not equivalent to a complete gnuplot command; rather it adds a `title` clause to each data set specified in a gnuplot `plot` command.

# DIAGNOSTICS

Dialog messages and diagnostic messages start with ` Graphics::GnuplotIF (NR): ... ` .

`NR` is the number of the corresponding Graphics::GnuplotIF object and output stream. NR counts the objects in the order of their generation.

# CONFIGURATION AND ENVIRONMENT

The environment variable DISPLAY is checked for the display.

# DEPENDENCIES

• gnuplot ( http://sourceforge.net/projects/gnuplot ) must be installed.

• The module IO::Handle is used to handle output pipes. Your operating system must support pipes, of course.

# INCOMPATIBILITIES

There are no known incompatibilities.

# BUGS AND LIMITATIONS

``  \$plot1->gnuplot_cmd("pause -1");     # send the gnuplot pause command``

does not work. Use

``  \$plot1->gnuplot_pause( );``

There are no known bugs in this module. Please report problems to author. Patches are welcome.

# AUTHOR

Dr.-Ing. Fritz Mehner (mehner@fh-swf.de)

# CREDITS

Stephen Marshall (smarshall@wsi.com) contributed `gnuplot_set_plot_titles`.

`gnuplot(1)`.