c2hs-0.15.1: doc/users_guide/implementing.html
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Implementation of Haskell Binding Modules</title><link rel="stylesheet" href="fptools.css" type="text/css" /><meta name="generator" content="DocBook XSL Stylesheets V1.70.1" /><link rel="start" href="index.html" title="The Binding Generator C➔Haskell" /><link rel="up" href="index.html" title="The Binding Generator C➔Haskell" /><link rel="prev" href="usage.html" title="Usage of C➔Haskell" /><link rel="next" href="bugs.html" title="Bug Reports and Suggestions" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Implementation of Haskell Binding Modules</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="usage.html">Prev</a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="bugs.html">Next</a></td></tr></table><hr /></div><div class="sect1" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="implementing"></a>Implementation of Haskell Binding Modules</h2></div></div></div><p>
A discussion of binding modules, the principles behind the tool, and a
discussion of related work can be found in a research paper located at <a href="http://www.cse.unsw.edu.au/~chak/papers/papers.html#c2hs" target="_top">http://www.cse.unsw.edu.au/~chak/papers/papers.html#c2hs</a>. All
features described in the paper, except <code class="literal">enum define</code> hooks
are implemented in the tool, but since the publication of the paper, the tool
has been extended further. The library interface essentially consists of the
new Haskell FFI Marshalling Library. More details about this library are
provided in the next section.
</p><p>
The remainder of this section describes the hooks that are available in
binding modules.
</p><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="import"></a>Import Hooks</h3></div></div></div><p>
</p><pre class="programlisting">
{#import [qualified] <em class="replaceable"><code>modid</code></em>#}
</pre><p>
Is translated into the same syntactic form in Haskell, which implies that
it may be followed by an explicit import list. Moreover, it implies that
the module <em class="replaceable"><code>modid</code></em> is also generated by C➔Haskell and
instructs the tool to read the file
<em class="replaceable"><code>modid</code></em><code class="literal">.chi</code>.
</p><p>
If an explicit output file name is given (<code class="literal">--output</code>
option), this name determines the basename for the <code class="literal">.chi</code>
file of the currently translated module.
</p><p>
Currently, only pointer hooks generate information that is stored in a
<code class="literal">.chi</code> file and needs to be incorporated into any client
module that makes use of these pointer types. It is, however, regarded as
good style to use import hooks for any module generated by C➔Haskell.
</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Restriction</h3><p>
C➔Haskell does not use qualified names. This can be a problem, for example,
if two pointer hooks are defined to have the same unqualified Haskell
name in two different modules, which are then imported by a third module.
To partially work around this problem, it is guaranteed that the
declaration of the textually later import hook dominates.
</p></div></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="id314578"></a>Context Hooks</h3></div></div></div><p>
</p><pre class="programlisting">
{#context [lib = <em class="replaceable"><code>lib</code></em>] [prefix = <em class="replaceable"><code>prefix</code></em>]#}
</pre><p>
Context hooks define a set of global configuration options. Currently,
there are two parameters which are both strings
</p><div class="itemizedlist"><ul type="disc"><li><p>
<em class="replaceable"><code>lib</code></em> is a dynamic library that contains
symbols needed by the present binding.
</p></li><li><p><em class="replaceable"><code>prefix</code></em> is an identifier prefix that
may be omitted in the lexemes of identifiers referring to C definitions
in any binding hook. The is useful as C libraries often use a prefix,
such as <code class="literal">gtk_</code>, as a form of poor man's name spaces.
Any occurrence of underline characters between a prefix and the main
part of an identifier must also be dropped. Case is not relevant in a
prefix. In case of a conflict of the abbreviation with an explicitly
defined identifier, the explicit definition takes preference.
</p></li></ul></div><p>
Both parameters are optional. An example of a context hook is the
following:
</p><pre class="programlisting">
{#context prefix = "gtk"#}
</pre><p>
</p><p>
If a binding module contains a binding hook, it must be the first hook in
the module.
</p></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="id314646"></a>Type Hooks</h3></div></div></div><p>
</p><pre class="programlisting">
{#type <em class="replaceable"><code>ident</code></em>#}
</pre><p>
A type hooks maps a C type to a Haskell type. As an example, consider
</p><pre class="programlisting">
type GInt = {#type gint#}
</pre><p>
The type must be a defined type, primitive types, such as
<code class="literal">int</code>, are not admissible.
</p></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="id314678"></a>Sizeof Hooks</h3></div></div></div><p>
</p><pre class="programlisting">
{#sizeof <em class="replaceable"><code>ident</code></em>#}
</pre><p>
A sizeof hooks maps a C type to its size in bytes. As an example, consider
</p><pre class="programlisting">
gIntSize :: Int
gIntSize = {#sizeof gint#}
</pre><p>
The type must be a defined type, primitive types, such as
<code class="literal">int</code>, are not admissible. The size of primitive types can
always be obtained using <code class="literal">Storable.sizeOf</code>.
</p></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="id314717"></a>Enumeration Hooks</h3></div></div></div><p>
</p><pre class="programlisting">
{#enum <em class="replaceable"><code>cid</code></em> [as <em class="replaceable"><code>hsid</code></em>] {<em class="replaceable"><code>alias1</code></em> , ... , <em class="replaceable"><code>aliasn</code></em>}
[with prefix = <em class="replaceable"><code>pref</code></em>] [deriving (<em class="replaceable"><code>clid1</code></em> , ... , <em class="replaceable"><code>clidn</code></em>)]#}
</pre><p>
Rewrite the C enumeration called <em class="replaceable"><code>cid</code></em> into a
Haskell data type declaration, which is made an instance of
<code class="literal">Enum</code> such that the ordinals match those of the
enumeration values in C. This takes explicit enumeration values in the C
definitions into account. If <em class="replaceable"><code>hsid</code></em> is given, this
is the name of the Haskell data type. The identifiers
<em class="replaceable"><code>clid1</code></em> to <em class="replaceable"><code>clidn</code></em> are
added to the deriving clause of the Haskell type.
</p><p>
By default, the names of the C enumeration are used for the constructors in
Haskell. If <em class="replaceable"><code>alias1</code></em> is
<code class="literal">underscoreToCase</code>, the original C names are capitalised
and the use of underscores is rewritten to caps. If it is
<code class="literal">upcaseFirstLetter</code> or
<code class="literal">downcaseFirstLetter</code>, the first letter of the original C
name changes case correspondingly. It is also possible to combine
<code class="literal">underscoreToCase</code> with one of
<code class="literal">upcaseFirstLetter</code> or
<code class="literal">downcaseFirstLetter</code>. Moreover,
<em class="replaceable"><code>alias1</code></em> to <em class="replaceable"><code>aliasn</code></em> may
be aliases of the form <em class="replaceable"><code>cid</code></em> <code class="literal">as</code>
<em class="replaceable"><code>hsid</code></em>, which map individual C names to Haskell
names. Instead of the global prefix introduced by a context hook, a local
prefix <em class="replaceable"><code>pref</code></em> can optionally be specified.
</p><p>
As an example, consider
</p><pre class="programlisting">
{#enum WindowType {underscoreToCase} deriving (Eq)#}
</pre><p>
</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>The <code class="literal">enum define</code> hooks described in the C➔Haskell
paper are not implemented yet.
</p></div><p>
</p></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="id314876"></a>Call Hooks</h3></div></div></div><p>
</p><pre class="programlisting">
{#call [pure] [unsafe] <em class="replaceable"><code>cid</code></em> [as (<em class="replaceable"><code>hsid</code></em> | ^)]#}
</pre><p>
A call hook rewrites to a call to the C function
<em class="replaceable"><code>cid</code></em> and also ensures that the appropriate foreign
import declaration is generated. The tags <code class="literal">pure</code> and
<code class="literal">unsafe</code> specify that the external function is purely
functional and cannot re-enter the Haskell runtime, respectively. If
<em class="replaceable"><code>hsid</code></em> is present, it is used as the identifier for
the foreign declaration, which otherwise defaults to the
<em class="replaceable"><code>cid</code></em>. When instead of
<em class="replaceable"><code>hsid</code></em>, the symbol <code class="literal">^</code> is given,
the <em class="replaceable"><code>cid</code></em> after conversion from C's underscore
notation to a capitalised identifier is used.
</p><p>
As an example, consider
</p><pre class="programlisting">
sin :: Float -> Float
sin = {#call pure sin as "_sin"#}
</pre><p>
</p></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="id314947"></a>Function Hooks</h3></div></div></div><p>
</p><pre class="programlisting">
{#fun [pure] [unsafe] <em class="replaceable"><code>cid</code></em> [as (<em class="replaceable"><code>hsid</code></em> | ^)]
[<em class="replaceable"><code>ctxt</code></em> =>] { <em class="replaceable"><code>parm1</code></em> , ... , <em class="replaceable"><code>parmn</code></em> } -> <em class="replaceable"><code>parm</code></em>
</pre><p>
Function hooks are call hooks including parameter marshalling. Thus, the
components of a function hook up to and including the <code class="literal">as</code>
alias are the same as for call hooks. However, an <code class="literal">as</code>
alias has a different meaning; it specifies the name of the generated
Haskell function. The remaining components use literals enclosed in
backwards and foward single quotes (<code class="literal">`</code> and
<code class="literal">'</code>) to denote Haskell code fragments (or more precisely,
parts of the Haskell type signature for the bound function). The first one
is the phrase <em class="replaceable"><code>ctxt</code></em> preceding
<code class="literal">=></code>, which denotes the type context. This is followed by
zero or more type and marshalling specifications
<em class="replaceable"><code>parm1</code></em> to <em class="replaceable"><code>parmn</code></em> for the
function arguments and one <em class="replaceable"><code>parm</code></em> for the function
result. Each such specification <em class="replaceable"><code>parm</code></em> has the
form
</p><pre class="programlisting">
[<em class="replaceable"><code>inmarsh</code></em> [* | -]] <em class="replaceable"><code>hsty</code></em>[&] [<em class="replaceable"><code>outmarsh</code></em> [*] [-]]
</pre><p>
where <em class="replaceable"><code>hsty</code></em> is a Haskell code fragment denoting a
Haskell type. The optional information to the left and right of this type
determines the marshalling of the corresponding Haskell value to and from C;
they are called the <em class="firstterm">in</em> and <em class="firstterm">out</em>
marshaller, respectively.
</p><p>
Each marshalling specification <em class="replaceable"><code>parm</code></em> corresponds
to one or two arguments of the C function, in the order in which they are
given. A marshalling specification in which the symbol
<code class="literal">&</code> follows the Haskell type corresponds to two C
function arguments; otherwise, it corresponds only to one argument. The
<em class="replaceable"><code>parm</code></em> following the left arrow
<code class="literal">-></code> determines the marshalling of the result of the C
function and may not contain the symbol <code class="literal">&</code>.
</p><p>
The <code class="literal">*-</code> output marshal specification is for monadic
actions that must be executed but whose results are discarded. This is very
useful for e.g. checking an error value and throwing an exception if needed.
</p><p>
Both <em class="replaceable"><code>inmarsh</code></em> and
<em class="replaceable"><code>outmarsh</code></em> are identifiers of Haskell marshalling
functions. By default they are assumed to be pure functions; if they have
to be executed in the <code class="literal">IO</code> monad, the function name needs
to be followed by a star symbol <code class="literal">*</code>. Alternatively, the
identifier may be followed by a minux sign <code class="literal">-</code>, in which
case the Haskell type does <span class="emphasis"><em>not</em></span> appear as an argument
(in marshaller) or result (out marshaller) of the generated Haskell
function. In other words, the argument types of the Haskell function is
determined by the set of all marshalling specifications where the in
marshaller is not followed by a minus sign. Conversely, the result tuple of
the Haskell function is determined by the set of all marshalling
specifications where the out marshaller is not followed by a minus sign.
The order of function arguments and components in the result tuple is the
same as the order in which the marshalling specifications are given, with
the exception that the value of the result marshaller is always the first
component in the result tuple if it is included at all.
</p><p>
For a set of commonly occuring Haskell and C type combinations,
<span class="emphasis"><em>default marshallers</em></span> are provided by C➔Haskell if no
explicit marshaller is given. The out marshaller for function arguments
is by default <code class="literal">void-</code>. The defaults for the in marshallers
for function arguments are as follows:
</p><div class="itemizedlist"><ul type="disc"><li><p>
<code class="literal">Bool</code> and integral C type (including chars):
<code class="literal">cFromBool</code>
</p></li><li><p>
Integral Haskell and integral C type: <code class="literal">cIntConv</code>
</p></li><li><p>
Floating Haskell and floating C type: <code class="literal">cFloatConv</code>
</p></li><li><p>
<code class="literal">String</code> and <code class="literal">char*</code>:
<code class="literal">withCString*</code>
</p></li><li><p>
<code class="literal">String</code> and <code class="literal">char*</code> with
explicit length: <code class="literal">withCStringLen*</code>
</p></li><li><p>
<em class="replaceable"><code>T</code></em> and
<em class="replaceable"><code>T</code></em><code class="literal">*</code>:
<code class="literal">with*</code>
</p></li><li><p>
<em class="replaceable"><code>T</code></em> and
<em class="replaceable"><code>T</code></em><code class="literal">*</code> where
<em class="replaceable"><code>T</code></em> is an integral type:
<code class="literal">withIntConv*</code>
</p></li><li><p>
<em class="replaceable"><code>T</code></em> and
<em class="replaceable"><code>T</code></em><code class="literal">*</code> where
<em class="replaceable"><code>T</code></em> is a floating type:
<code class="literal">withFloatConv*</code>
</p></li><li><p>
<code class="literal">Bool</code> and
<em class="replaceable"><code>T</code></em><code class="literal">*</code> where
<em class="replaceable"><code>T</code></em> is an integral type:
<code class="literal">withFromBool*</code>
</p></li></ul></div><p>
The defaults for the out marshaller of the result are the converse of the
above; i.e., instead of the <code class="literal">with</code> functions, the
corresponding <code class="literal">peek</code> functions are used. Moreover, when
the Haskell type is <code class="literal">()</code>, the default marshaller is
<code class="literal">void-</code>.
</p><p>
As an example, consider
</p><pre class="programlisting">
{#fun notebook_query_tab_label_packing as ^
`(NotebookClass nb, WidgetClass cld)' =>
{notebook `nb' ,
widget `cld' ,
alloca- `Bool' peekBool*,
alloca- `Bool' peekBool*,
alloca- `PackType' peekEnum*} -> `()'#}
</pre><p>
which results in the Haskell type signature
</p><pre class="programlisting">
notebookQueryTabLabelPacking :: (NotebookClass nb, WidgetClass cld)
=> nb -> cld -> IO (Bool, Bool, PackType)
</pre><p>
which binds the following C function:
</p><pre class="programlisting">
void gtk_notebook_query_tab_label_packing (GtkNotebook *notebook,
GtkWidget *child,
gboolean *expand,
gboolean *fill,
GtkPackType *pack_type);
</pre><p>
</p></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="id315420"></a>Get Hooks</h3></div></div></div><p>
</p><pre class="programlisting">
{#get <em class="replaceable"><code>apath</code></em>#}
</pre><p>
A get hook supports accessing a member value of a C structure. The hook
itself yields a function that, when given the address of a structure of the
right type, performs the structure access. The member that is to be
extracted is specified by the access path <em class="replaceable"><code>apath</code></em>.
Access paths are formed as follows (following a subset of the C expression
syntax):
</p><div class="itemizedlist"><ul type="disc"><li><p>
The root of any access path is a simple identifier, which denotes either
a type name or <code class="literal">struct</code> tag.
</p></li><li><p>
An access path of the form
<code class="literal">*</code><em class="replaceable"><code>apath</code></em> denotes
dereferencing of the pointer yielded by accessing the access path
<em class="replaceable"><code>apath</code></em>.
</p></li><li><p>
An access path of the form
<em class="replaceable"><code>apath</code></em><code class="literal">.</code><em class="replaceable"><code>cid</code></em>
specifies that the value of the <code class="literal">struct</code> member called
<em class="replaceable"><code>cid</code></em> should be accessed.
</p></li><li><p>Finally, an access path of the form
<em class="replaceable"><code>apath</code></em><code class="literal">-></code><em class="replaceable"><code>cid</code></em>,
as in C, specifies a combination of dereferencing and member selection.
</p></li></ul></div><p>
For example, we may have
</p><pre class="programlisting">
visualGetType :: Visual -> IO VisualType
visualGetType (Visual vis) = liftM cToEnum $ {#get Visual->type#} vis
</pre><p>
</p></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="id315534"></a>Set Hooks</h3></div></div></div><p>
</p><pre class="programlisting">
{#set <em class="replaceable"><code>apath</code></em>#}
</pre><p>
Set hooks are formed in the same way as get hooks, but yield a function that
assigns a value to a member of a C structure. These functions expect a
pointer to the structure as the first and the value to be assigned as the
second argument. For example, we may have
</p><pre class="programlisting">
{#set sockaddr_in.sin_family#} addr_in (cFromEnum AF_NET)
</pre><p>
</p></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="id315561"></a>Pointer Hooks</h3></div></div></div><p>
</p><pre class="programlisting">
{#pointer [*] <em class="replaceable"><code>cid</code></em> [as <em class="replaceable"><code>hsid</code></em>] [foreign | stable] [newtype | ->
<em class="replaceable"><code>hsid2</code></em>] [nocode]#}
</pre><p>
A pointer hook facilitates the mapping of C to Haskell pointer types. In
particular, it enables the use of <code class="literal">ForeignPtr</code> and
<code class="literal">StablePtr</code> types and defines type name translations for
pointers to non-basic types. In general, such a hook establishes an
association between the C type <em class="replaceable"><code>cid</code></em> or
<code class="literal">*</code><em class="replaceable"><code>cid</code></em> and the Haskell type
<em class="replaceable"><code>hsid</code></em>, where the latter defaults to
<em class="replaceable"><code>cid</code></em> if not explicitly given. The identifier
<em class="replaceable"><code>cid</code></em> will usually be a type name, but in the case
of <code class="literal">*</code><em class="replaceable"><code>cid</code></em> may also be a struct,
union, or enum tag. If both a type name and a tag of the same name are
available, the type name takes precedence. Optionally, the Haskell
representation of the pointer can be by a <code class="literal">ForeignPtr</code> or
<code class="literal">StablePtr</code> instead of a plain <code class="literal">Ptr</code>. If
the <code class="literal">newtype</code> tag is given, the Haskell type
<em class="replaceable"><code>hsid</code></em> is defined as a <code class="literal">newtype</code>
rather than a transparent type synonym. In case of a
<code class="literal">newtype</code>, the type argument to the Haskell pointer type
will be <em class="replaceable"><code>hsid</code></em>, which gives a cyclic definition,
but the type argument is here really only used as a unique type tag.
Without <code class="literal">newtype</code>, the default type argument is
<code class="literal">()</code>, but another type can be specified after the symbol
<code class="literal">-></code>.
</p><p>
For example, we may have
</p><pre class="programlisting">
{#pointer *GtkObject as Object newtype#}
</pre><p>
This will generate a new type <code class="literal">Object</code> as follows:
</p><pre class="programlisting">
newtype Object = Object (Ptr Object)
</pre><p>
which enables exporting <code class="literal">Object</code> as an abstract type and
facilitates type checking at call sites of imported functions using the
encapsulated pointer. The latter is achieved by C➔Haskell as follows. The
tool remembers the association of the C type <code class="literal">*GtkObject</code>
with the Haskell type <code class="literal">Object</code>, and so, it generates for
the C function
</p><pre class="programlisting">
void gtk_unref_object (GtkObject *obj);
</pre><p>
the import declaration
</p><pre class="programlisting">
foreign import gtk_unref_object :: Object -> IO ()
</pre><p>
This function can obviously only be applied to pointers of the right type,
and thus, protects against the common mistake of confusing the order of
pointer arguments in function calls.
</p><p>
However, as the Haskell FFI does not permit to directly pass
<code class="literal">ForeignPtr</code>s to function calls or return them, the tool
will use the type <code class="literal">Ptr HsName</code> in this case, where
<code class="literal">HsName</code> is the Haskell name of the type. So, if we modify
the above declaration to be
</p><pre class="programlisting">
{#pointer *GtkObject as Object foreign newtype#}
</pre><p>
the type <code class="literal">Ptr Object</code> will be used instead of a plain
<code class="literal">Object</code> in import declarations; i.e., the previous
<code class="literal">import</code> declaration will become
</p><pre class="programlisting">
foreign import gtk_unref_object :: Ptr Object -> IO ()
</pre><p>
To simplify the required marshalling code for such pointers,
the tool automatically generates a function
</p><pre class="programlisting">
withObject :: Object -> (Ptr Object -> IO a) -> IO a
</pre><p>
As an example that does not represent the pointer as an abstract type,
consider the C type declaration:
</p><pre class="programlisting">
typedef struct {int x, y;} *point;
</pre><p>
We can represent it in Haskell as
</p><pre class="programlisting">
data Point = Point {x :: Int, y :: Int}
{#pointer point as PointPtr -> Point#}
</pre><p>
which will translate to
</p><pre class="programlisting">
data Point = Point {x :: Int, y :: Int}
type PointPtr = Ptr Point
</pre><p>
and establish a type association between <code class="literal">point</code> and
<code class="literal">PointPtr</code>.
</p><p>
If the keyword <code class="literal">nocode</code> is added to the end of a pointer
hook, C➔Haskell will not emit a type declaration. This is useful when a C➔Haskell
module wants to make use of an existing type declaration in a binding not
generated by C➔Haskell (i.e., where there are no <code class="literal">.chi</code>
files).
</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Restriction</h3><p>
The name <em class="replaceable"><code>cid</code></em> cannot be a basic C type (such as
<code class="literal">int</code>), it must be a defined name.
</p></div></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="id315886"></a>Class Hooks</h3></div></div></div><p>
</p><pre class="programlisting">
{#class [<em class="replaceable"><code>hsid1</code></em> =>] <em class="replaceable"><code>hsid2</code></em> <em class="replaceable"><code>hsid3</code></em>#}
</pre><p>
Class hooks facilitate the definition of a single inheritance class hierachy
for external pointers including up and down cast functionality. This is
meant to be used in cases where the objects referred to by the external
pointers are order in such a hierachy in the external API - such structures
are encountered in C libraries that provide an object-oriented interface.
Each class hook rewrites to a class declaration and one or more instance
declarations.
</p><p>
All classes in a hierarchy, except the root, will have a superclass
identified by <em class="replaceable"><code>hsid1</code></em>. The new class is given by
<em class="replaceable"><code>hsid2</code></em> and the corresponding external pointer is
identified by <em class="replaceable"><code>hsid3</code></em>. Both the superclass and the
pointer type must already have been defined by binding hooks that precede
the class hook.
</p><p>
The pointers in a hierachy must either all be foreign pointers or all be
normal pointers. Stable pointers are not allowed. Both pointer defined as
<code class="literal">newtype</code>s and those defined by type synonyms may be used
in class declarations and they may be mixed. In the case of synonyms,
Haskell's usual restrictions regarding overlapping instance declarations
apply.
</p><p>
The newly defined class has two members whose names are derived from the
type name <em class="replaceable"><code>hsid3</code></em>. The name of first member is
derived from <em class="replaceable"><code>hsid3</code></em> by converting the first
character to lower case. This function casts from any superclass to the
current class. The name of the second member is derived by prefixing
<em class="replaceable"><code>hsid3</code></em> with the <code class="literal">from</code>. It casts
from the current class to any superclass. A class hook generates an
instance for the pointer in the newly defined class as well as in all its
superclasses.
</p><p>
As an example, consider
</p><pre class="programlisting">
{#pointer *GtkObject newtype#}
{#class GtkObjectClass GtkObject#}
{#pointer *GtkWidget newtype#}
{#class GtkObjectClass => GtkWidgetClass GtkWidget#}
</pre><p>
The second class hook generates an instance for <code class="literal">GtkWidget</code>
for both the <code class="literal">GtkWidgetClass</code> as well as for the
<code class="literal">GtkObjectClass</code>.
</p></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="cpp"></a>CPP Directives and Inline C Code</h3></div></div></div><p>
A Haskell binding module may include arbitrary C pre-processor directives
using the standard C syntax. The directives are used in two ways: Firstly,
they are included in the C header file generated by C➔Haskell in exactly
the same order in which they appear in the binding module. Secondly, all
conditional directives are honoured by C➔Haskell in that all Haskell
binding code in alternatives that are discarded by the C pre-processor are
also discarded by C➔Haskell. This latter feature is, for example, useful
to maintain different bindings for multiple versions of the same C API in a
single Haskell binding module.
</p><p>
In addition to C pre-processor directives, vanilla C code can be maintained
in a Haskell binding module by bracketing this C code with the pseudo
directives <code class="literal">#c</code> and <code class="literal">#endc</code>. Such inline
C code is emitted into the C header generated by C➔Haskell at exactly the same
position relative to CPP directives as it occurs in the binding module.
Pre-processor directives may encompass the <code class="literal">#include</code>
directive, which can be used instead of specifying a C header file as an
argument to <code class="literal">c2hs</code>. In particular, this enables the
simultaneous use of multiple header files without the need to provide a
custom header file that binds them together. If a header file
<em class="replaceable"><code>lib</code></em><code class="literal">.h</code> is specified as an
argument to <code class="literal">c2hs</code>, the tool will emit the directive
<code class="literal">#include"</code><em class="replaceable"><code>lib</code></em><code class="literal">.h"</code>
into the generated C header before any other CPP directive or inline C code.
</p><p>
As an artificial example of these features consider the following code:
</p><pre class="programlisting">
#define VERSION 2
#if (VERSION == 1)
foo :: CInt -> CInt
foo = {#call pure fooC#}
#else
foo :: CInt -> CInt -> CInt
foo = {#call pure fooC#}
#endif
#c
int fooC (int, int);
#endc
</pre><p>
One of two versions of the Haskell function <code class="literal">foo</code> (having
different arities) is selected in dependence on the value of the CPP macro
<code class="literal">VERSION</code>, which in this example is defined in the same
file. In realistic code, <code class="literal">VERSION</code> would be defined in
the header file supplied with the C library that is made accessible from
Haskell by a binding module. The above code fragment also includes one
line of inline C code that declares a C prototype for
<code class="literal">fooC</code>.
</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Current limitation of the implementation</h3><p>
Inline C code can currently not contain any code blocks; i.e., only
declarations as typically found in header files may be included.
</p></div></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="id316129"></a>Grammar Rules</h3></div></div></div><p>
The following grammar rules define the syntax of binding hooks:
</p><pre class="programlisting">
hook -> `{#' inner `#}'
inner -> `import' ['qualified'] ident
| `context' ctxt
| `type' ident
| `sizeof' ident
| `enum' idalias trans [`with' prefix] [deriving]
| `call' [`pure'] [`unsafe'] idalias
| `fun' [`pure'] [`unsafe'] idalias parms
| `get' apath
| `set' apath
| `pointer' ['*'] idalias ptrkind
| `class' [ident `=>'] ident ident
ctxt -> [`lib' `=' string] [prefix]
idalias -> ident [(`as' ident | `^')]
prefix -> `prefix' `=' string
deriving -> `deriving' `(' ident_1 `,' ... `,' ident_n `)'
parms -> [verbhs `=>'] `{' parm_1 `,' ... `,' parm_n `}' `->' parm
parm -> [ident_1 [`*' | `-']] verbhs [`&'] [ident_2 [`*'] [`-']]
apath -> ident
| `*' apath
| apath `.' ident
| apath `->' ident
trans -> `{' alias_1 `,' ... `,' alias_n `}'
alias -> `underscoreToCase' | `upcaseFirstLetter' | `downcaseFirstLetter'
| ident `as' ident
ptrkind -> [`foreign' | `stable'] ['newtype' | '->' ident]
</pre><p>
Identifier <code class="literal">ident</code> follow the lexis of Haskell. They may
be enclosed in single quotes to disambiguate them from C->Haskell keywords.
</p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="usage.html">Prev</a> </td><td width="20%" align="center"> </td><td width="40%" align="right"> <a accesskey="n" href="bugs.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Usage of C➔Haskell </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Bug Reports and Suggestions</td></tr></table></div></body></html>