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