The Bindings
Prev | Chapter 8. Ada Language | Next

## 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 Ada programmer.

The thin binding is a layer between the thick bindings and the underlying C code. It is mainly a programming convenience for the developer of the bindings; this is a common implementation for foreign language bindings and for the most part, the user can ignore it.

There are two thick bindings provided for the convenience of the user. Either may be used and they both provide exactly the same functionality. The thick bindings are the user's main concern with programming for PLplot.

### Thin Binding

The thin binding, in the files `plplotthin.ads` and `plplotthin.adb`, is mostly a direct and obvious mapping of the C application programming interface (API) to Ada. Thus, for example, where a C program such as `plcol0` requires a single integer argument, there is a corresponding Ada program 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. Numeric types as defined in PLplot are associated with numeric types in Ada in the thin binding by use of Ada's type system. Thus, the thin binding refers to the PLplot-centric type `PLFLT` for floating-point types while the thick binding uses the usual Ada type `Long_Float`.

Many of the comments from the C source header file (similar in purpose to an Ada specification file) have been retained in the thin binding, even when they are no longer make sense. These might be pruned at some point to facilitate reading the Ada source.

Also included in the thin binding are some other declarations which help the Ada binding to mesh well with C by emulating certain data structures which are needed in some rather specialized usages as well as providing certain subprogram pointer types.

The Ada programmer working with either of the thick bindings will have to refer to the thin binding relatively rarely, if ever, and mainly to examine the subroutine pointer declarations and the several variant record types which are used mostly for contour and three-dimensional plots. However, some of these have been `subtype`-ed or `renames`-ed in the thick bindings so even less reference to the thin binding will be necessary. The goal is to put everything of interest to the user in the thick bindings and the user need not bother with the thin binding.

### The Thick Bindings

The thick bindings provide most of the information that the Ada programmer needs. Normally, only one of the two thick bindings would be used per user program but it should be possible to include both but that scenario would be unusual.

There are three main aspects of the thick bindings: providing an alternative access to the PLplot API, extending the PLplot functionality with some easy-to-use features, and overlaying Ada data structures and types.

In the first aspect, the thick bindings provide a fully Ada interface to the entire PLplot library. Packages are `with`-ed and `use`-d as normal Ada code. Ada arrays can be passed as usual, not requiring the array length or start or end indices to be passed separately. All necessary Ada types are made to match the underlying C types exactly.

The second aspect of the thick bindings is to provide some simplified ways to get a lot of plotting done with only one or two subroutine calls. For example, a single call to Simple_Plot can display from one to five "y's" as a function of a single "x" with default plot appearances chosen to suit many situations. Other simple plotters are available for three-dimensional and contour plots. Manipulating PLplot's colors is similarly made easy and some default color schemes are provided.

The third main aspect of the thick binding is to use Ada data structures and Ada's type system extensively to reduce the chances of inappropriate actions. For example, Ada arrays are used throughout (as opposed to C's pointer-plus-offset-while-carrying-along-the-size-separately approach). Quantities which have natural range limits are `subtype`-d to reflect those constraints. The hope is that program errors will result in more-familiar Ada compilation or run-time errors rather than error reports from the PLplot library or no reports at all. However, there remain a few instances where the typing could be improved and PLplot errors will still be reported from time to time.

Both the specification and body for the standard thick (and thin) binding contain the C subroutine name as a comment line immediately above the Ada procedure declaration; this should help in making the associations between "Ada" names and "PLplot" names. Also, the subroutine-specific comments from the C API have been retained verbatim.

### Standard Thick Binding Using Enhanced Names

The distinguishing feature of this thick binding (the "standard" binding) is to provide more descriptive names for PLplot subroutines, variables, constants, arguments, and other objects. Most Ada programmers will be more comfortable using these names. For example, in the C API as well as the thin Ada binding and the other thick Ada binding, the procedure `plcol0(1)` sets the drawing color to red. In the standard thick binding, the same thing is accomplished by writing `Set_Pen_Color(Red)`. The Ada program may just as well write `Set_Pen_Color(1)` since the binding merely sets a constant `Red` to be equal to the integer `1`. Many such numeric constants from the C API are given names in this thick binding. These renamed integers are discussed more fully in Section 7.2.

The disadvantage of this renaming is that it makes referring to the PLplot documentation somewhat awkward. There might be, at some time, a utility for easing this problem by providing an HTML file with links so that a "normal" PLplot name can be linked to the "Ada" name along with the appropriate entry in the Ada specification, as well as another HTML file with links from the "Ada" name directly to the PLplot web page that documents that name. It might also be possible to provide an alternate version of the documentation with the enhanced names used. (The developer of the bindings has a sed file prepared which makes most of the subroutine-name substitutions.) However, this thick binding retains the original C subprogram names as comments immediately above the function or procedure name in the code listing so it is relatively easy to locate the relevant item in the PLplot documentation.

One simple rule applies in reading the PLplot API documentation: the argument names are in the same order in Ada as in the PLplot documentation (the names are different) except that all array lengths are eliminated. The PLplot documentation, for each subroutine, shows a "redacted" version which should be correct for Ada as well as other languages which have proper arrays.

The standard bindings are in the Ada files `plplot.ads` and `plplot.adb`.

### Thick Binding Using Traditional Names

This thick binding provides exactly the same functionality as the standard thick binding but retains the original names as used in the C code and the PLplot documentation.

The traditional bindings are in the Ada files `plplot_traditional.ads` and `plplot_traditional.adb`.

Prev | Up | Next
Overview | Home | The Examples