The Bindings

The bindings are a re-expression and extension of the C-language API and as such are a kind of abstract layer between the user's code and the PLplot binary library. Additionally, there are a few capabilities not in the official API but nonetheless which are available to the C programmer which are included in the bindings and thus are directly available to the OCaml programmer. The OCaml PLplot API is all defined within the Plplot module. In general, it is suggested to include the line "open Plplot" in OCaml code using PLplot. The function and constant definitions are named such that they should avoid namespace collisions with other libraries. PLplot functions have a "pl" prefix while constants/variant types have a "PL_" prefix.

The core binding provides a close to direct mapping to the underlying C code. It follows the C API very closely, with the exception of a few parameters which become redundant under OCaml (ex. array lengths are determined automatically by OCaml and function callbacks which are handled slightly differently than in C).

There are also a selection of functions which provide support for operations outside of the base C API.

Core Binding

The core binding is mostly a direct and obvious mapping of the C application programming interface (API) to OCaml. Thus, for example, where a C function such as plcol0 requires a single integer argument, there is a corresponding OCaml function also called plcol0 which also requires a single integer argument. (plcol0 happens to set the drawing color using a number which is associated with a set of colors). Various constants from the C API are also included here as OCaml variant types with a "PL_" prefix to avoid namespace clashes when the Plplot module is opened. For example, where the C PLplot API uses GRID_* to select between the data gridding methods, the OCaml API uses PL_GRID_*.

OCaml specific functions and functionality

Several of the PLplot core functions allow the user to provide a transformation callback function to adjust the location of the plotted data. This is handled differently in the OCaml bindings than in order to keep the interface between C and OCaml as simple as possible. Rather than passing transformation functions directly to each PLplot function which supports a coordinate transformation, the coordinate tranform functions are set globally using the plset_pltr and plset_mapform functions. Similarly, the functions plunset_pltr and plunset_mapform can be used to clear the globally defined coordinate transformation function. Note that the transform functions are only used in the functions which support them in the C API (ex. plmap)- they are not automatically applied to plotted data in other function calls (ex. plline). For demonstrations of their use, see OCaml PLplot examples 16 and 20 for plset_pltr and example 19 for plset_mapform.