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):

  program      => 'gnuplot' # fully qualified name of the Gnuplot executable
  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
  plot_titles  => [],       # array of strings; titles used in the legend
  scriptfile   => '',       # write all plot commands to the specified file
  plot_also    => 0,        # write all plot commands to the specified file,
                            # in addition show the plots
  persist      => 0,        # let plot windows survive after gnuplot exits
                            # 0 : close / 1 : survive
  objectname   => '',       # an optional name for the object
  silent_pause => 1,        # 0 suppress message from gnuplot_pause()
  no_error_log => 0,        # suppress ".gnuplot.${$}.${object_number}.stderr.log" file

These attributes are stored in each object.

Allowed line styles are

  boxes     dots   filledcurves  fsteps  histeps
  impulses  lines  linespoints   points  steps

The generated gnuplot commands can be stored to a file instead of being executed immediately. This file can be used as input to gnuplot, e.g.

  gnuplot < function_set_1.gnuplot

A script file can also be used for checking the commands send to gnuplot.

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" .

The program argument is provided to allow Graphics::GnuplotIF to be used with Gnuplot on Windows using "gnuplot.exe", a compilation which includes code that emulates a unix pipe.

GnuplotIF

The short form of the constructor above ("new"):

  use Graphics::GnuplotIF qw(GnuplotIF);
  $plot1  = GnuplotIF;

This subroutine is exported only on request.

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_xy_style

  %y1 = ( 'y_values' => \@y1, 'style_spec' => "lines lw 3" );
  %y2 = ( 'y_values' => \@y2,
          'style_spec' => "points pointtype 4 pointsize 5" );
  $plot1->gnuplot_plot_xy_style( \@x, \%y1, \%y2 );

"gnuplot_plot_xy_style" takes one array reference and one or more hash references. The first array is assumed to contain the x-values for the following function values. The following hashes are assumed to contain pairs of y-values and individual style specifications for use in the plot command. The 'style_spec' settings are placed between "with" and "title" of gnuplot's "plot" command.

gnuplot_plot_many

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

"gnuplot_plot_many" takes pairs of array references. Each pair represents a function and is a reference to the arrays of x- and y-values for that function.

gnuplot_plot_many_style

  %f1 = ( 'x_values' => \@x1, 'y_values' => \@y1,
          'style_spec' => "lines lw 3" );
  %f2 = ( 'x_values' => \@x2, 'y_values' => \@y2,
          'style_spec' => "points pointtype 4 pointsize 5" );
  $plot1->gnuplot_plot_many_style( \%f1, \%f2 );

"gnuplot_plot_many_style" takes one or more hash references. The hashes are assumed to contain array referenses to x-values and y-values and individual style specifications for use in the plot command. The 'style_spec' settings are placed between "with" and "title" of gnuplot's "plot" command.

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_plot_3d

  $plot2->gnuplot_plot_3d( \@array );    # 3-D-plot

"gnuplot_plot_3d" takes one reference to an 2-D-array of z-values.

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. The message can be suppressed by

  silent_pause => 0

given to the constructor (see new ).

"time" may be any constant or expression. Choosing 0 (default) will wait until a carriage return is hit, a negative value 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_plot_y( \@y1 );
  $plot1->gnuplot_pause( 5.5 );          # delay is 5.5 seconds
  $plot1->gnuplot_plot_y( \@y2 );
  $plot1->gnuplot_pause( );
  $plot1->gnuplot_plot_y( \@y3 );
  $plot1->gnuplot_pause( );

will display 3 plots with 5.5 seconds delay.

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.

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.

gnuplot_hardcopy

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

  $plot1->gnuplot_hardcopy( 'function1.gnuplot.ps',
                            'postscript',
                            'color lw 3' );
  $plot1->gnuplot_plot_xy( \@x, \@y1, \@y2 );
  $plot1->gnuplot_restore_terminal();

The 1. parameter is a file name, the 2. parameter is a gnuplot terminal type, the 3. parameter is a string with additional terminal parameters (optional). The current terminal settings will be saved.

gnuplot_restore_terminal

Restores the saved terminal settings after a call to "gnuplot_hardcopy()". Output will go to "STDOUT" again.

Print a plot directly

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_get_object_id

Get the (internal) object number (and the object name):

   $obj_number              = $plot1->gnuplot_get_object_id();
  ($obj_number, $obj_name)  = $plot1->gnuplot_get_object_id();

The object number is set automatically by the constructor. The object name can be set by the constructor (objectname => 'MyName').

gnuplot_get_plotnumber

Get the (internal) plot number of the next plot:

   $plot_number             = $plot1->gnuplot_get_plotnumber()

The plot number is set automatically by the constructor starting with 1. Each call to

  gnuplot_plot_y
  gnuplot_plot_xy
  gnuplot_plot_xy_style
  gnuplot_plot_many
  gnuplot_plot_many_style
  gnuplot_plot_equation
  gnuplot_plot_3d

increments this number by 1. This can be used to identify single plots, e.g. with

  $plot->gnuplot_cmd( "set timestamp \"plot number ${plot_number} / %c\"" );