Gnuplot bindings — Pure Language and Library Documentation

### Navigation

- index
- modules |
- next |
- previous |
- Pure Language and Library Documentation »

# Gnuplot bindings

Kay-Uwe Kirstein

## Copying

Copyright (c) 2009, 2010 by Kay-Uwe Kirstein.

pure-gplot is free software: you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

## Introduction

This module contains a pure binding to gnuplot. Communication to gnuplot is performed via pipes. The usual work flow to generate plot via gnuplot is the following:

1. open pipe via `open`
2. send plot commands, e.g., with `plot`
3. close pipe with `close`

## Function Reference

### Open / Closing Functions

> `gplot::open cmd;`

opens a pipe to gnuplot, using cmd. cmd usually is something like `gnuplot` or `/path/to/gnuplot/bin/gnuplot` depending on your path configuration. `open` returns a pointer to the actual pipe for later usage, so a typical call to open might look like this:

> `let gp = gplot::open "/path_to_gnuplot/gnuplot";`

gplot::GPLOT_EXE is a predefined variable with the standard Gnuplot executable. It is set to `pgnuplot` on Windows and to `gnuplot` otherwise and can be overridden bythe GPLOT_EXE environment variable. (`pgnuplot.exe` is a special executable for Windows, which is capable of stdin pipes in contrast to the normal `gnuplot.exe`). Usage of `gplot::GPLOT_EXE` might look like this:

> `let gp = gplot::open gplot::GPLOT_EXE;`

> `gplot::close gp;`

closes a gnuplot session, given by the handle gp.

### Low-Level Commands

> `gplot::puts_no_echo string gp;`

sends the string to the gnuplot session gp points to. As the name states, there is no echo read back from gnuplot (Don’t know whether gnuplot or pgnuplot.exe supports reading/bidirectional pipes at all).

> `gplot::puts string gp;`

is a convenience wrapper to `gplot::puts_no_echo`.

### Plot Commands

The main (versatile) function to generate plots is the simple plot command, which expects a list of the data to be plotted.

> `gplot::plot gp data opt;`

where gp is the pointer to the gnuplot session, data is a list containing the data to be plotted and opt is a tuple, containing options for the plot. opt might be empty () or `DEFAULT` for default options (refer to gnuplot for them).

If data for the x-axis (ordinate) should be explicitely given plotxy should be used instead:

> `gplot::plotxy_deprecated gp (xdata, ydata) opt;`

> `gplot::plotxy gp (xdata, ydata) opt [];`

Multiple datasets can be plotted into a single graph by combining them to tuples of lists:

> `gplot::plotxy gp (xdata, y1data, y2data, ..) opt;`

> `gplot::plotxy gp (xdata, y1data, y2data, ..) opt [];`

> `gplot::plotxy gp (xdata, y1data, y2data, ..) opt titles;`

where the latter form gives additional titles for each y-data set.

### Plot Options

> `gplot::xtics gp list_of_tic_labels;`

Sets the tic labels of the x-axis to the given text labels. The labels can be given aas a simple list of strings, which are taken as successive labels or as a list of tuples with the form `(value, label)`, in which case each label is placed at its `value` position.

> `gplot::xtics gp ()` or `gplot::xtics gp "default";`

This restores the default tics on the y-axis.

> `gplot::title t;`

Sets a title string on top of the plot (default location)

> `gplot::output gp terminal name;`

Sets the terminal and output name for the successive plots. For some terminal additional options might be given:

> `gplot::output gp (terminal, options) name`.

For terminals like x11 or windows, name can be empty `()`.

> `gplot::xlabel gp name` or `gplot::ylabel gp name`

Adds labels to the x- or y-axis, respectively. An empty name removes the label for successive plots, e.g., `gplot::xlabel gp ""`.

### Private Functions

> `gpdata data`, `gpxydata (xdata, y1data, ..)`

Internal functions to handle lists of data point (`gpdata`) or tuples of lists of data points (`gpxydata`) and convert them to be understood by Gnuplot.

> `gpxycmd`, `gpxycmdtitle`

Internal function to generate the plotting command for multiple datasets. `gpxycmdtitle` adds titles to each dataset, a.k.a plot legend.

`gplot::gpopt ("style", style, args);`

Internal function to convert a plot style to the respective gnuplot syntax

> `gplot::gptitle t;`

Internal function to generate title information for individual datasets

### Navigation

- index
- modules |
- next |
- previous |
- Pure Language and Library Documentation »