Green Card pays attention only to Green Card directives, each of which
starts with a ``%
'' at the beginning of a line. All other lines
are passed through to the output Haskell file unchanged.
The syntax of Green Card directives is given in Figure
fig:GC-grammar
. The syntax for dis is given later
(Figure
fig:dis-syntax
.) The form Any_x
means any
symbol except x
.
Green Card understands the following directives:
%fun
begins a procedure specification, which describes
the interface to a single C procedure, see Section
sec:proc-spec
.
%dis
allows the programmer to describe a new
Data Interface Scheme (DIS). A DIS describes how to translate,
or marshall, data from Haskell to C and back again, see Section
sec:dis
.
%const
makes it easy to generate a collection of new Haskell
constants derived from C constants. This can be done with %fun
, but
%const
is much more concise, see Section
sec:consts
.
%enum
is similar to %const
, but supports the mapping
of external constants to a corresponding Haskell data type, see
Section
sec:consts
.
%prefix
makes it easy to remove standard prefixes from the
Haskell function name, those are usually not needed since Haskell
allows qualified imports, see Section
sec:prefix
.
%#include
tells Green Card to arrange that a specified
C header file will be included with the C code in the procedure
specifications when the latter is fed to a C compiler, see
Section
sec:import
.
%C
'' allows you to write fragments of C code which sits
outside any procedure specification. (We shall later see how to
include fragments of C code within procedures.) The entire line
of text following this directive is simply copied verbatim to the
generated C module.
A directive can span more than one line, but the continuation lines
must each start with a %
followed by some whitespace. For
example:
%fun draw :: Int -- Length in pixels
% -> Maybe Int -- Width in pixels
% -> IO ()
Haskell-style comments are permitted in Green Card directives (except,
for obvious reasons, ``%C
''.)
A general principle we have followed is to define a single, explicit (and hence long-winded) general mechanism, that should deal with just about anything, and then define convenient abbreviations that save the programmer from writing out the general mechanism in many common cases. We have erred on the conservative side in defining such abbreviations; that is, we have only defined an abbreviation where doing without it seemed unreasonably long-winded, and where there seemed to be a systematic way of defining an abbreviation.