–

This file includes an RDoc hack so that links can be made to open up into a new frame rather then the current frame.

The “trick” is to append ““target=”_top” to the URL.

++

Ruby/PLplot

Introduction

This is the first public release of the Ruby bindings to PLplot, a cross-platform software package for creating scientific plots.

This release should be considered a beta release because the Ruby API to PLplot may change slightly based on user feedback.

Installation

Ruby/PLplot can be installed via RubyGems:

gem install plplot

Ruby/PLplot should work with either Ruby 1.8 or 1.9. It was developed mostly using Ruby 1.8.6 and somewhat tested against Ruby 1.9.1.

Ruby/PLplot requires a very recent version of the PLplot libraries. Until a new version of PLplot is released and package maintainers support it, you will likely have to build your own copy of the PLplot libraries from source code checked out from the trunk of the PLplot source code repository. This must be done prior to installing Ruby/PLplot. If you try to install Ruby/PLplot with an inappropriate version of PLplot, you will get the error message “the PLplot library lacks support for arbitrary storage of 2D data”.

Documentation

Documentation for the Ruby aspects of the PLplot API are installed as part of the gem-based installation. To view the documentation, run

gem server

then point your browser to \http://localhost:8808/ and navigate to (and follow) the plplot [rdoc] link. You can get more information about RubyGem’s documenation server by running:

gem help server

The Ruby/PLplot API is mostly very similar to the PLplot C API. For details on PLplot functionality, see the PLplot documentation.

Examples

Ruby/PLplot provides Ruby versions of the extensive suite of PLplot’s standard examples. The only PLplot examples not (yet) supported are those that depend on missing functionality (see below): x17 (stripchart), x19 (maps), and x29 (time handling).

The examples are installed automatically, but not as runnable programs. They are “hidden” in the local gem repository. At some point they will be made more visible, but until then you can find them in $GEMDIR/gems/plplot-X.Y.Z/examples.

Command line option parsing

PLplot has many different drivers and options that can be specified by the user. PLplot provides excellent command line parsing functionality via its plparseopts and related functions. Ruby also provides excellent command line parsing via the OptionParser class. In order to provide the best of both worlds, Ruby/PLplot provides the PLOptionParser class. This class provides OptionParser functionality (it is a subclass of OptionParser) with built-in support for standard PLplot options via a modified option syntax.

Ruby/PLplot users are encouraged to use PLOptionParser for parsing command line arguments, but it is not required. The Ruby plsetopt method is an enhanced version of PLplot’s plsetopt function. In addition to the “standard” calling sequence

plsetopt(opt, optarg)

plsetopt can be called with an Array of Strings (such as ARGV) which provides functionality similar to plparseopts. This allows for a great deal of user control over how command line arguments are handled while still providing a simple way to leverage PLplot’s built-in command line parsing capabilties.

What’s missing

Most of the PLplot API is supported, but there are a few PLplot functions that have yet to be incorporated:

  • Stripchart functions

    • plstripa

    • plstripc

    • plstripd

  • Time functions

    • plbtime

    • plconfigtime

    • plctime

  • Map functions

    • plmap

    • plmeridians

  • Other functions

    • plot3dcl

    • plsmem

    • plparseopts et al (but see above)

    • plsurf3dl