<!doctype linuxdoc system>

<!-- C->Haskell documentation
 -->

<article>

<title>The Binding Generator C->Haskell
<author>Manuel M. T. Chakravarty, <tt/chak@cse.unsw.edu.au/
<date>v0.18, 13 October 2004
<abstract>
C-&gt;Haskell is an interface generator that simplifies the development of
<htmlurl url="http://haskell.org" name="Haskell"> bindings to C libraries.  The
tool processes existing C header files that determine data layout and function
signatures on the C side in conjunction with Haskell modules that specify
Haskell-side type signatures and marshaling details.  Hooks embedded in the
Haskell code signal access to C structures and functions -- they are expanded
by the interfacing tool in dependence on information from the corresponding C
header file.  Another noteworthy property is the lightweight nature of the
approach.

More background information is available in a research paper discussing
C-&gt;Haskell, which is at
<url url="http://www.cse.unsw.edu.au/~chak/papers/papers.html#c2hs">.
However, this paper does not cover the more recent advanced features such as
function hooks and conditional compilation.
</abstract>

<toc>

<p>
<bf>Copyright &amp; Distribution</bf>
<p>
Copyright (c) [1999..2004] by <htmlurl
url="http://www.cse.unsw.edu.au/~chak/" name="Manuel M. T. Chakravarty">.  
The manual is distributed under the terms GNU Free Documentation License
available from
<url url="http://www.fsf.org/copyleft/fdl.html">.
<p>
The master copy of this document is at <url
url="http://www.cse.unsw.edu.au/~chak/haskell/c2hs/">; the source is in
SGML, which allows you to produce a selection of standard formats, including
HTML and Postscript.

<p>
<bf>Contributions</bf>
<p>
If you have any comments, suggestions, or contributions, please send them to
<htmlurl url="mailto:chak@cse.unsw.edu.au" name="chak@cse.unsw.edu.au">.


<sect>Installation
<p>
It follows a brief discussion of the installation from source.  There is,
however, a file <tt/INSTALL/ in the source distribution, which is more
frequently updated and should be consulted in any case.

<sect1>Where is the Source?
<p>
The master site of C-&gt;Haskell is at <url
url="http://www.cse.unsw.edu.au/~chak/haskell/c2hs/">.  It has all the
latest information and sources.  Furthermore, it explains how to get anonymous 
CVS access to C-&gt;Haskell's repository and may have pre-compiled binaries
for easier installation.

<sect1>What Else Do I Need?
<p>
You need a Haskell system supported by C-&gt;Haskell.  Currently this is only
the <em/Glasgow Haskell Compiler (GHC)/, which you can obtain from <url
url="http://haskell.org/ghc/">.  You need a fairly recent version of the
Haskell compiler.  C-&gt;Haskell uses a compiler support library called the
<em/Compiler Toolkit/.  In the main distribution, the Compiler Toolkit is
already contained in the source tar ball -- be sure to download a file named
<tt/c2hs-/<em/x/<tt/./<em/y/<tt/./<em/z/<tt/.tar.gz/, were
<em/x/<tt/./<em/y/<tt/./<em/z/ is the version number of the package.

To build the documentation, you will also need the <em/SGML Tools/, which you
find at your nearest sunsite or Linux mirror or at <url
url="ftp://ftp.lip6.fr/pub/sgml-tools/">.  On an up-to-date Linux system, the
tools are probably already installed.

<sect1>I Got Everything, and Now?
<p>
The short answer is
<tscreen><verb>
% gzip -cd c2hs.X.Y.Z.tar.gz | tar xvf -  # unpack the sources
% cd c2hs.X.Y.Z			          # change to the toplevel directory
% ./configure				  # run the `configure' script
% make				          # build everything
[ Become root if necessary ]
% make install			          # install the tool
</verb></tscreen>
<p>
In the <tt/INSTALL/ file, there are more details.

Optionally, you can build the documentation by issuing <tt/make doc/.

<sect1>Packages
<p>
If you are using GHC, you may want to register C-&gt;Haskell's support
libraries as a package.  This can be achieved in two ways.  Firstly, if you
pass the option <tt/--enable-add-package/ to <tt/configure/, the build system
will register the package for you when you execute <tt/make install/.
Alternatively, the configuration oracle <tt/c2hs-conf/, which is installed as
part of the C-&gt;Haskell distribution, produces a package configuration
suitable for the package tool <tt/ghc-pkg/ when given the option
<tt/--package-conf/.  In short, you can register the libraries after
installation by invoking
<p>
<tscreen><verb>
c2hs-conf --package-conf | ghc-pkg --add-package
</verb></tscreen>

<sect>Usage of C-&gt;Haskell
<p>
Let's have a brief look at how to call the tool and how to use the generated
interfaces.

<sect1>Usage of <tt/c2hs/
<p>
C-&gt;Haskell is implemented by the executable <tt/c2hs/.  The simplest form
of usage is
<p>
<quote>
<tt/c2hs /<em/Lib/<tt/.chs/
</quote>
<p>
where <em/Lib/<tt/.chs/ is the Haskell binding module defining the Haskell
interface to a C library together with the required marshalling code.  If
C-&gt;Haskell is invoked in this manner, the binding module must contain a cpp
<tt/#include/ directive to determine the C-side interface of the library.
Alternatively, a C header file can be specified on the command line, as in
<p>
<quote>
<tt/c2hs /<em/lib/<tt/.h /<em/Lib/<tt/.chs/
</quote>
<p>
However, the latter option is only preserved for backwards compatibility and
not recommended.  If no errors occur, C-&gt;Haskell generates three files: (1)
a pure Haskell module <em/Lib/<tt/.hs/, which implements the Haskell API of
the library, (2) a C header file <em/Lib/<tt/.h/ which some Haskell systems
need to compile the generated Haskell code, and (3) a C-&gt;Haskell interface
file <em/Lib/<tt/.chi/ that is used by other binding modules that import
<em/Lib/<tt/.hs/ using an import hook (see <ref id="import" name="the section
on import hooks"> for details).

The executable <tt/c2hs/ has a couple more options:
<p>
<tscreen><verb>
Usage: c2hs [ option... ] [header-file] binding-file

  -C CPPOPTS  --cppopts=CPPOPTS  pass CPPOPTS to the C preprocessor         
  -c CPP      --cpp=CPP          use executable CPP to invoke C preprocessor
  -d TYPE     --dump=TYPE        dump internal information (for debugging)  
  -h, -?      --help             brief help (the present message)           
  -i INCLUDE  --include=INCLUDE  include paths for .chi files               
  -k          --keep             keep pre-processed C header                
  -o FILE     --output=FILE      output result to FILE (should end in .hs)  
  -t PATH     --output-dir=PATH  place generated files in PATH              
  -v          --version          show version information                   

The header file must be a C header file matching the given binding file.
The dump TYPE can be
  trace   -- trace compiler phases
  genbind -- trace binding generation
  ctrav   -- trace C declaration traversal
  chs     -- dump the binding file (adds `.dump' to the name)
</verb></tscreen>
<p>
The most useful of these is probably <tt/--cppopts=/ (or <tt/-C/).  If the C
header file needs any special options (like <tt/-D/ or <tt/-I/) to go through
the C pre-processor, here is the place to pass them.  A call may look like
this:
<p>
<quote>
<tt>c2hs --cppopts='-I/some/obscure/dir -DEXTRA' </tt><em/Lib/<tt/.chs/
</quote>
<p>
Do not forget the quotes if you have more than one option that you want to
pass to the pre-processor.
<p>
Often, <em/lib/<tt/.h/ will not be in the current directory, but in one of the
header file directories.  C-&gt;Haskell leaves locating the header file to the
standard C preprocessor, which usually looks in two places for the header:
first, in the standard include directory of the used system, this is usually
<tt>/usr/include</tt> and <tt>/usr/local/include</tt>; and second, it will
look in every directory that is mentioned in a <tt/-IDIR/ option passed to the
pre-processor via <tt/--cppopts/.
<p>
If the compiled binding module contains import hooks, C-&gt;Haskell needs to
find the <tt/.chi/ (C-&gt;Haskell interface files) produced while compiling
the corresponding binding modules.  By default, they will be searched for in
the current working directory.  If they are located elsewhere, the
<tt/--include=INCLUDE/ option has to be used to indicate the location, where
<tt/INCLUDE/ is a colon-separated list of directories.  Multiple such options
are admissible.  Paths specified later are searched first.

<sect1>Compilation of a Generated Haskell API
<p>
C-&gt;Haskell comes with a marshalling library, called <tt/C2HS/, which is
imported by virtually all library bindings.  Consequently, you will have to
tell the Haskell compiler where to find the interface files when you compile a
generated interface and you have to tell the linker where to find the library
archive of <tt/C2HS/.  To simplify this usually operating and compilation
system-dependent process, C-&gt;Haskell comes with a simple configuration
manager, in the form of the executable <tt/c2hs-conf/.  It can be used to
inquire information for compilation and linking and pass that information on
to the Haskell compiler.  The call
<p>
<tscreen>
c2hs-config --cflags
</tscreen>
<p>
returns all flags that need to be given to the Haskell compiler for
compilation and
<p>
<tscreen>
c2hs-config --lib
</tscreen>
<p>
returns all flags necessary for linking.  Overall, you may want to use a call
like the following to compile a generated library module with GHC:
<p>
<quote>
<tt/ghc `c2hs-config --cflags` -#include\"/<em/Lib/<tt/.h\" -c /<em/Lib/<tt/.hs/
</quote>
<p>
The backquotes cause the shell to call <tt/c2hs-config/ and substitute the
call by the flags returned.  This, of course, also works in a makefile.  Note
how this call makes GHC include the C-&gt;Haskell-generated header file
<em/Lib/<tt/.h/ into the generated code.
<p>
As an alternative, if you have registered C-&gt;Haskell's support libraries
with GHC's package manager, you do not need to use <tt/c2hs-config/, but
instead, you can simply pass the option <tt/-package c2hs/ to GHC (both when
compiling and when linking).

Furthermore, <tt/c2hs-config/ can also be used to locate the executable of the 
tool itself, by calling
<p>
<tscreen>
c2hs-config --c2hs
</tscreen>
<p>
This slightly simplifies configuration management of libraries generated by
C-&gt;Haskell, as it is sufficient to know the location of <tt/c2hs-config/ to 
access all other components of C-&gt;Haskell.


<sect>Implementation of Haskell Binding Modules
<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
<url url="http://www.cse.unsw.edu.au/~chak/papers/papers.html#c2hs">.  All
features described in the paper, except <tt/enum define/ hooks are implemented
in the tool, but since the publication of the paper, the tool has been
extended further.

Furthermore, the distribution contains examples that illustrate the use of
C-&gt;Haskell.  In the source distribution, these examples are located below
the directories <tt/tests/ and <tt/examples/.  The latter contains a binding 
for the <url url="http://www.gnome.org" name="Gnome"> HTTP 1.1 library
<tt/ghttp/.  The sources of the marshalling library <tt/C2HS/ are in the
directory <tt/lib/ and contain a fair amount of comments, which should help
getting you started.

Since version 0.8.1 the interface of the marshalling library <tt/C2HS/
changed.  The new interface essentially consists of the new Haskell FFI
Marshalling Library.  More details about this library are provided in the next
section.  For backward compatibilitym the old interface (i.e., the pre-0.8.1
interface) can still be used by importing <tt/C2HSDeprecated/ instead of
<tt/C2HS/.

The remainder of this section describes the hooks that are available in
binding modules.

<sect1>Import Hooks<label id="import">
<p>
<tscreen>
{#import [qualified] <it/modid/#}
</tscreen>
<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 <it/modid/ is also generated by C-&gt;Haskell and instructs the
tool to read the file <it/modid/<tt/.chi/.
<p>
If an explicit output file name is given (<tt/--output/ option), this name
determines the basename for the <tt/.chi/ file of the currently translated
module. 
<p>
Currently, only pointer hooks generate information that is stored in a
<tt/.chi/ 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-&gt;Haskell.
<p>
<em>Restriction:</em> C-&gt;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.

<sect1>Context Hooks
<p>
<tscreen>
{#context [lib = <it/lib/] [prefix = <it/prefix/]#}
</tscreen>
<p>
Context hooks define a set of global configuration options.  Currently, there
are three parameters all of which are strings:
<itemize>
<item><em/lib/ is a dynamic library that contains symbols needed by the
present binding.
<item><em/prefix/ 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 <tt/gtk_/, 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.
</itemize>
<p>
All three parameters are optional.  An example of a context hook is the
following:
<tscreen>
{#context prefix = "gtk"#}
</tscreen>
<p>
If a binding module contains a binding hook, it must be the first hook in the
module.

<sect1>Type Hooks
<p>
<tscreen>
{#type <it/ident/#}
</tscreen>
<p>
A type hooks maps a C type to a Haskell type.  As an example, consider
<p>
<tscreen>
type GInt = {#type gint#}
</tscreen>
<p>
The type must be a defined type, primitive types, such as <tt/int/, are not
admissible.

<sect1>Sizeof Hooks
<p>
<tscreen>
{#sizeof <it/ident/#}
</tscreen>
<p>
A sizeof hooks maps a C type to its size in bytes.  As an example, consider
<p>
<tscreen><verb>
gIntSize :: Int
gIntSize  = {#sizeof gint#}
</verb></tscreen>
<p>
The type must be a defined type, primitive types, such as <tt/int/, are not
admissible.  The size of primitive types can always be obtained using
<tt/Storable.sizeOf/. 

<sect1>Enumeration Hooks
<p>
<tscreen>
{#enum <it/cid/ [as <it/hsid/] {<it/alias1/ , ... , <it/aliasn/}
  [with prefix = <it/pref/] [deriving (<it/clid1/ , ... , <it/clidn/)]#}
</tscreen>
<p>
Rewrite the C enumeration called <it/cid/ into a Haskell data type
declaration, which is made an instance of <tt/Enum/ such that the ordinals
match those of the enumeration values in C.  This takes explicit enumeration
values in the C definitions into account.  If <it/hsid/ is given, this is
the name of the Haskell data type.  The identifiers <it/clid1/ to <it/clidn/
are added to the deriving clause of the Haskell type.
<p>
By default, the names of the C enumeration are used for the constructors in
Haskell.  If <it/alias1/ is <tt/underscoreToCase/, the original C names are
capitalised and the use of underscores is rewritten to caps.  Moreover,
<it/alias1/ to <it/aliasn/ may be aliases of the form <it/cid/ <tt/as/
<it/hsid/, which map individual C names to Haskell names.  Instead of the
global prefix introduced by a context hook, a local prefix <it/pref/ can
optionally be specified.
<p>
As an example, consider
<p>
<tscreen>
{#enum WindowType {underscoreToCase} deriving (Eq)#}
</tscreen>
<p>
<bf/Note:/ The <tt/enum define/ hooks described in the C-&gt;Haskell paper are
not implemented yet.

<sect1>Call Hooks
<p>
<tscreen>
{#call [pure] [unsafe] <it/cid/ [as (<it/hsid/ | ^)]#}
</tscreen>
<p>
A call hook rewrites to a call to the C function <it/cid/ and also ensures
that the appropriate foreign import declaration is generated.  The tags
<tt/pure/ and <tt/unsafe/ specify that the external function is purely
functional and cannot re-enter the Haskell runtime, respectively.  If
<it/hsid/ is present, it is used as the identifier for the foreign
declaration, which otherwise defaults to the <it/cid/.  When instead of
<it/hsid/, the symbol <tt/^/ is given, the <it/cid/ after conversion from C's
underscore notation to a capitalised identifier is used.
<p>
As an example, consider
<p>
<tscreen><verb>
sin :: Float -> Float
sin  = {#call pure sin as "_sin"#}
</verb></tscreen>

<sect1>Function Hooks
<p>
<tscreen>
{#fun  [pure] [unsafe] <it/cid/ [as (<it/hsid/ | ^)]
[<it/ctxt/ =>] { <it/parm1/ , ... , <it/parmn/ } -> <it/parm/
</tscreen>
<p>
Function hooks are call hooks including parameter marshalling.  Thus, the
components of a function hook up to and including the <tt/as/ alias are the
same as for call hooks.  However, an <tt/as/ 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 (<tt/`/
and <tt/'/) to denote Haskell code fragments (or more precisely, parts of the
Haskell type signature for the bound function).  The first one is the phrase
<it/ctxt/ preceding <tt/=>/, which denotes the type context.  This is followed
by zero or more type and marshalling specifications <it/parm1/ to <it/parmn/
for the function arguments and one <it/parm/ for the function result.  Each
such specification <it/parm/ has the form
<p>
<tscreen>
[<it/inmarsh/ [* | -]] <it/hsty/ [&] [<it/outmarsh/ [* | -]]
</tscreen>
<p>
where <it/hsty/ 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/in/ and <em/out/ marshaller, respectively.
<p>
Each marshalling specification <it/parm/ 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 <tt/&/ follows the Haskell type corresponds
to two C function arguments; otherwise, it corresponds only to one argument.
The <it/parm/ following the left arrow <tt/->/ determines the marshalling of
the result of the C function and may not contain the symbol <tt/&/.
<p>
Both <it/inmarsh/ and <it/outmarsh/ are identifiers of Haskell marshalling
functions.  By default they are assumed to be pure functions; if they have to
be executed in the <tt/IO/ monad, the function name needs to be followed by a
star symbol <tt/*/.  Alternatively, the identifier may be followed by a minux
sign <tt/-/, in which case the Haskell type does <em/not/ 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>
For a set of commonly occuring Haskell and C type combinations, <em/default
marshallers/ are provided by C-&gt;Haskell if no explicit marshaller is
given.   The out marshaller for function arguments is by default <tt/void-/.
The defaults for the in marshallers for function arguments are as follows:
<itemize>
<item><tt/Bool/ and integral C type (including chars): <tt/cFromBool/
<item>Integral Haskell and integral C type: <tt/cIntConv/
<item>Floating Haskell and floating C type: <tt/cFloatConv/
<item><tt/String/ and <tt/char*/: <tt/withCString*/
<item><tt/String/ and <tt/char*/ with explicit length: <tt/withCStringLen*/
<item><it/T/ and <it/T/<tt/*/: <tt/with*/
<item><it/T/ and <it/T/<tt/*/ where <it/T/ is an integral type:
<tt/withIntConv*/ 
<item><it/T/ and <it/T/<tt/*/ where <it/T/ is a floating type:
<tt/withFloatConv*/
<item><tt/Bool/ and <it/T/<tt/*/ where <it/T/ is an integral type:
<tt/withFromBool*/
</itemize>
<p>
The defaults for the out marshaller of the result are the converse of the
above; i.e., instead of the <tt/with/ functions, the corresponding <tt/peek/
functions are used.  Moreover, when the Haskell type is <tt/()/, the default
marshaller is <tt/void-/.
<p>
As an example, consider
<p>
<tscreen><verb>
{#fun notebook_query_tab_label_packing as ^
  `(NotebookClass nb, WidgetClass cld)' => 
  {notebook `nb'                , 
   widget   `cld'               , 
   alloca-  `Bool'     peekBool*, 
   alloca-  `Bool'     peekBool*,
   alloca-  `PackType' peekEnum*} -> `()'#}
</verb></tscreen>
<p>
which results in the Haskell type signature
<p>
<tscreen><verb>
notebookQueryTabLabelPacking :: (NotebookClass nb, WidgetClass cld)
			     => nb -> cld -> IO (Bool, Bool, PackType)
</verb></tscreen>
<p>
which binds the following C function:
<p>
<tscreen><verb>
void gtk_notebook_query_tab_label_packing (GtkNotebook *notebook,
					   GtkWidget   *child,
					   gboolean    *expand,
					   gboolean    *fill,
					   GtkPackType *pack_type);
</verb></tscreen>

<sect1>Get Hooks
<p>
<tscreen>
{#get <it/apath/#}
</tscreen>
<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 <it/apath/.  Access paths are formed as
follows (following a subset of the C expression syntax):
<itemize>
<item>The root of any access path is a simple identifier, which denotes either
a type name or <tt/struct/ tag.
<item>An access path of the form <tt/*/<it/apath/ denotes dereferencing of
the pointer yielded by accessing the access path <it/apath/.
<item>An access path of the form <it/apath/<tt/./<it/cid/ specifies that the
value of the <tt/struct/ member called <it/cid/ should be accessed.
<item>Finally, an access path of the form <it/apath/<tt/->/<it/cid/, as in
C, specifies a combination of dereferencing and member selection.
</itemize>
<p>
For example, we may have
<p>
<tscreen><verb>
visualGetType              :: Visual -> IO VisualType
visualGetType (Visual vis)  = liftM cToEnum $ {#get Visual->type#} vis
</verb></tscreen>

<sect1>Set Hooks
<p>
<tscreen>
{#set <it/apath/#}
</tscreen>
<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>
<tscreen>
{#set sockaddr_in.sin_family#} addr_in (cFromEnum AF_NET)
</tscreen>

<sect1>Pointer Hooks
<p>
<tscreen>
{#pointer [*] <it/cid/ [as <it/hsid/] [foreign | stable] [newtype | -&gt; <it/hsid2/]#}
</tscreen>
<p>
A pointer hook facilitates the mapping of C to Haskell pointer types.  In
particular, it enables the use of <tt/ForeignPtr/ and <tt/StablePtr/ types and
defines type name translations for pointers to non-basic types.  In general,
such a hook establishes an association between the C type <it/cid/ or
<tt/*/<it/cid/ and the Haskell type <it/hsid/, where the latter defaults to
<it/cid/ if not explicitly given.  The identifier <it/cid/ will usually be a
type name, but in the case of <tt/*/<it/cid/ 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 <tt/ForeignPtr/ or <tt/StablePtr/ instead of a plain
<tt/Ptr/.  If the <tt/newtype/ tag is given, the Haskell type <it/hsid/ is
defined as a <tt/newtype/ rather than a transparent type synonym.  In case of
a <tt/newtype/, the type argument to the Haskell pointer type will be
<it/hsid/, which gives a cyclic definition, but the type argument is here
really only used as a unique type tag.  Without <tt/newtype/, the default
type argument is <tt/()/, but another type can be specified after the symbol
<tt/-&gt;/.
<p>
For example, we may have
<p>
<tscreen><verb>
{#pointer *GtkObject as Object newtype#}
</verb></tscreen>
<p>
This will generate a new type <tt/Object/ as follows:
<p>
<tscreen><verb>
newtype Object = Object (Ptr Object)
</verb></tscreen>
<p>
which enables exporting <tt/Object/ as an abstract type and facilitates type
checking at call sites of imported functions using the encapsulated
pointer.  The latter is achieved by C-&gt;Haskell as follows.  The tool
remembers the association of the C type <tt/*GtkObject/ with the Haskell type
<tt/Object/, and so, it generates for the C function
<p>
<tscreen><verb>
void gtk_unref_object (GtkObject *obj);
</verb></tscreen>
<p>
the import declaration
<p>
<tscreen><verb>
foreign import gtk_unref_object :: Object -> IO ()
</verb></tscreen>
<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>
However, as the Haskell FFI does not permit to directly pass <tt/ForeignPtr/s
to function calls or return them, the tool will use the type <tt/Ptr HsName/
in this case, where <tt/HsName/ is the Haskell name of the type.  So, if we
modify the above declaration to be
<p>
<tscreen><verb>
{#pointer *GtkObject as Object foreign newtype#}
</verb></tscreen>
<p>
the type <tt/Ptr Object/ will be used instead of a plain <tt/Object/ in import
declarations; i.e., the previous <tt/import/ declaration will become
<p>
<tscreen><verb>
foreign import gtk_unref_object :: Ptr Object -> IO ()
</verb></tscreen>
<p>
To simplify the required marshalling code for such pointers,
the tool automatically generates a function
<p>
<tscreen><verb>
withObject :: Object -> (Ptr Object -> IO a) -> IO a
</verb></tscreen>
<p>
As an example that does not represent the pointer as an abstract type,
consider the C type declaration:
<p>
<tscreen><verb>
typedef struct {int x, y;} *point;
</verb></tscreen>
<p>
We can represent it in Haskell as
<p>
<p>
<tscreen><verb>
data Point = Point {x :: Int, y :: Int}
{#pointer point as PointPtr -> Point#}
</verb></tscreen>
<p>
which will translate to
<p>
<tscreen><verb>
data Point = Point {x :: Int, y :: Int}
type PointPtr = Ptr Point
</verb></tscreen>
<p>
and establish a type association between <tt/point/ and <tt/PointPtr/.
<p>
<em/Restriction:/ The name <it/cid/ cannot be a basic C type (such as
<tt/int/), it must be a defined name.

<sect1>Class Hooks
<p>
<tscreen>
{#class [<it/hsid1/ =>] <it/hsid2/ <it/hsid3/#}
</tscreen>
<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>
All classes in a hierarchy, except the root, will have a superclass identified
by <it/hsid1/.  The new class is given by <it/hsid2/ and the corresponding
external pointer is identified by <it/hsid3/.  Both the superclass and the
pointer type must already have been defined by binding hooks that precede the
class hook.
<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
<tt/newtype/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>
The newly defined class has two members whose names are derived from the type
name <it/hsid3/.  The name of first member is derived from <it/hsid3/ 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 <it/hsid3/ with the <tt/from/.  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>
As an example, consider
<p>
<tscreen><verb>
{#pointer *GtkObject newtype#}
{#class GtkObjectClass GtkObject#}

{#pointer *GtkWidget newtype#}
{#class GtkObjectClass => GtkWidgetClass GtkWidget#}
</verb></tscreen>
<p>
The second class hook generates an instance for <tt/GtkWidget/ for both the
<tt/GtkWidgetClass/ as well as for the <tt/GtkObjectClass/.

<sect1>CPP Directives and Inline C Code<label id="cpp">
<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-&gt;Haskell in exactly
the same order in which they appear in the binding module.  Secondly, all
conditional directives are honoured by C-&gt;Haskell in that all Haskell
binding code in alternatives that are discarded by the C pre-processor are
also discarded by C-&gt;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>
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
<tt/#c/ and <tt/#endc/.  Such inline C code is emitted into the C header
generated by C-&gt;Haskell at exactly the same position relative to CPP
directives as it occurs in the binding module.  Pre-processor directives may
encompass the <tt/#include/ directive, which can be used instead of specifying
a C header file as an argument to <tt/c2hs/.  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/lib/<tt/.h/ is
specified as an argument to <tt/c2hs/, the tool will emit the directive
<tt/#include"/<em/lib/<tt/.h"/ into the generated C header before any other
CPP directive or inline C code.
<p>
As an artificial example of these features consider the following code:
<p>
<tscreen><verb>
#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
</verb></tscreen>
<p>
One of two versions of the Haskell function <tt/foo/ (having different arities)
is selected in dependence on the value of the CPP macro <tt/VERSION/, which in
this example is defined in the same file.  In realistic code, <tt/VERSION/
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 <tt/fooC/.
<p>
<bf>Current limitation of the implementation:</bf> Inline C code can currently
not contain any code blocks; i.e., only declarations as typically found in
header files may be included.

<sect1>Grammar Rules
<p>
The following grammar rules define the syntax of binding hooks:
<tscreen>
<verb>
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'
          | ident `as' ident
ptrkind  -> [`foreign' | `stable'] ['newtype' | '->' ident]
</verb>
</tscreen>
<p>
Identifier <tt/ident/ follow the lexis of Haskell.  They may be enclosed in
single quotes to disambiguate them from C->Haskell keywords.

<sect>The Haskell FFI Marshalling Library
<p>
The Haskell FFI Marshalling Library is a proposed standard library for foreign
function interoperability.  The interface of the <tt/C2HS/ marshalling library
as of version 0.8.1 of the tool is a slight extension of the Haskell FFI
Marshalling Library, which is documented in the following.
<p>
The library is partitioned into a language independent and a C specific
component.  All features of the former are available from the module
<tt/Foreign/ and all features of the later from <tt/CForeign/.  Nevertheless,
the following module hierarchy is part of the interface definition:
<itemize>
  <item><htmlurl url="lib/Foreign.hs" name="Foreign">
    <itemize>
      <item><htmlurl url="lib/Int.hs" name="Int">
      <item><htmlurl url="lib/Word.hs" name="Word">
      <item><htmlurl url="lib/Ptr.hs" name="Ptr">
      <item><htmlurl url="lib/ForeignPtr.hs" name="ForeignPtr">
      <item><htmlurl url="lib/StablePtr.hs" name="StablePtr">
      <item><htmlurl url="lib/Storable.hs" name="Storable">
      <item><htmlurl url="lib/MarshalAlloc.hs" name="MarshalAlloc">
      <item><htmlurl url="lib/MarshalArray.hs" name="MarshalArray">
      <item><htmlurl url="lib/MarshalError.hs" name="MarshalError">
      <item><htmlurl url="lib/MarshalUtils.hs" name="MarshalUtils">
    </itemize>
  <item><htmlurl url="lib/CForeign.hs" name="CForeign">
    <itemize>
      <item><htmlurl url="lib/CTypes.hs" name="CTypes">
      <item><htmlurl url="lib/CTypesISO.hs" name="CTypesISO">
      <item><htmlurl url="lib/CError.hs" name="CError">
      <item><htmlurl url="lib/CString.hs" name="CString">
    </itemize>
</itemize>
It is recommended to access this functionality in C-&gt;Haskell binding
modules by merely importing <tt/C2HS/.


<sect>Bug Reports and Suggestions
<p>
Please address any bug reports and suggestions to <htmlurl
url="mailto:chak@cse.unsw.edu.au" name="chak@cse.unsw.edu.au">.  A good bug
report contains information on the used operating system and Haskell compiler
as well as the version of C-&gt;Haskell that you have been using.  You can
obtain the version information by running <tt/c2hs-config --version/.  If
possible a concise example illustrating your problem would be appreciated.


<sect>Copyright
<p>
C-&gt;Haskell is Copyright (C) [1999..2003] Manuel M. T. Chakravarty

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.

This manual is Copyright (c) [2000..2003] by Manuel M. T. Chakravarty. 
Permission is granted to copy, distribute and/or modify this document under
the terms of the GNU Free Documentation License, Version 1.1 or any later
version published by the Free Software Foundation; with no Invariant Sections,
with no Front-Cover Texts, and with the no Back-Cover Texts.  A copy of the
license is included in the section entitled "GNU Free Documentation License".

<sect>GNU Free Documentation License
<p>
The GNU Free Documentation License is available at
<url url="http://www.fsf.org/copyleft/fdl.html">.

<sect>Release Notes
<p>
Important changes (especially those affecting the semantics of the tool) are
documented in the following.

<sect1>Version 0.13.4 "Pressing Forward"
<p>
<itemize>
<item>Identifier may optionally be put in single quotes.  (This is useful if
they would otherwise collide with a C-&gt;Haskell keyword.)
<item>Some smaller bug fixes
<item>C chars are treated as integral types for marshalling purposes.
<item>If there is no explicit output file specified, the generated header file
is put in the same directory as the binding file; otherwise, it goes in the
directory where the output file is put.  Moreover, the <tt/--output-dir/
option enables the specification of directory where all generated files are to
be put.
<item>Foreign import declarations include the name of the header file
generated by C-&gt;Haskell (ie, it needs neither be passed to the Haskell
compiler at the command line nor in an OPTIONS pragma).
<item>We allow structs and unions with no declarations.
<item>Headers including function bodies are now parsed correctly.
<item>Duncan Coutts identified a space leak in the parser whose removal
improved performance significantly.
</itemize>

<sect1>Version 0.12.1 "Springtime"
<p>
<itemize>
<item>Removed support for deprecated <tt/C2HS/ interface and for old versions
of the FFI libraries
<item>Improved line pragma generation
<item>Works with GHC 6.3
<item>Builds on Mac OS X thanks to a patch by Sean Seefried
</itemize>

<sect1>Version 0.11.5 "Powder Snow"
<p>
<itemize>
<item>Bug fixes
<item>Constant expression can now contain enumerators
<item><tt/header/ label removed from <tt/context/ hooks
<item><bf>WARNING:</bf> This version of <tt/c2hs/ may <em/overwrite/ C
header files in the current directory.  More precisely, if a binding module
with the name <tt/Foo.chs/ is processed, a header file with the name
<tt/Foo.h/ is generated and will <em/overwrite/ any file of the same name in
the current directory or the directory specified via the <tt/-o/ option.
<item>Added support for CPP directives, including special treatment of
conditions, and for inline C code; specification of a header file as an
argument to <tt/c2hs/ is now option.  <item>GHC line pragmas are emitted into
generated Haskell code <item>Swap the order of reading the binding module and
the C header (i.e., we now read the binding module first)
</itemize>

<sect1>Version 0.10.17 "Altocumulus Stratiformis Perlucidus Undulatus"
<p>
<itemize>
<item>Worked around a bug in GHC 5.04.1
<item>Solaris-related fix
<item>Marshalling support for bit masks represented as enumeration types
<item>Added <tt/fun/ hooks
<item><tt/as/ aliases can use <tt/^/ convert the orignal identifier with
underscore2case
<item>In call hooks, the attributes `fun' was replaced by `pure' (`fun' is
will still be recognised for a while to ensure backwards compatibility, but
it's use is deprecated)
<item>GHC's package system is now supported
<item>If two import hooks add a type mapping for a pointer hook with the same
name, the textual later one dominates.
<item>Bug fixes
<item>Support for bitfields (they are correctly handled when computing struct
offsets and they can be accessed using <tt/set/ and <tt/get/ hooks)
<item>Some more support for GNU C extensions ("alignof" and better support
"__attribute__")
<item>Added <tt/class/ hooks
</itemize>

<sect1>Version 0.9.9 "Blue Ginger"
<p>
<itemize>
<item>Bug fixes
<item>Library names in <tt/foreign import/s have been removed until
the convention of the new FFI is implemented (they are currently <em/silently/
omitted)
<item>Added <tt/sizeof/ hooks; sizeof of type names is now also supported in
constant expressions
<item>Local prefix for <tt/enum/ hooks; courtesy of Armin Sander
<item>Added <tt/import/ hooks
<item>The documentation includes a description of binding hooks
<item>Added <tt/pointer/ hooks, which were derived from code for a similar
feature by Axel Simon; this includes proper treatment of parametrised pointers
<item>Integrated <tt/deriving/ option for <tt/enum/ hooks, which was
contributed by Axel Simon 
<item>Adapted to GHC 5.0
</itemize>

<sect1>Version 0.8.2 "Gentle Moon"
<p>
<itemize>
<item>Adaptation layer for legacy <tt/StablePtr/ interface
<item>Forgot to export <tt/FunPtr/ and associated functions from <tt/C2HS/
<item>Forgot to export some names in <tt/C2HSDeprecated/
<item>Added support for gcc's <tt/__builtin_va_list/
</itemize>

<sect1>Version 0.8.1 "Gentle Moon"
<p>
<itemize>
<item>Library adapted to New FFI; the old interface can still be used by
importing <tt/C2HSDeprecated/
<item>FFI Library specification added to the documentation
</itemize>

<sect1>Version 0.7.10 "Afterthought"
<p>
<itemize>
<item>CygWin support; based on suggestions by Anibal Maffioletti Rodrigues de
DEUS &lt;anibaldedeus@email.com&gt;
<item><tt/IntConv/ instances for <tt/Int8/, <tt/Word8/, and <tt/Char/
</itemize>

<sect1>Version 0.7.9 "Afterthought"
<p>
<itemize>
<item>Debugged the stripping of prefixes from enumerators; prefixes are now
generally stripped, independent of whether they can be stripped from all
enumerators of a given enumeration type
<item>Comma now correctly required after <tt/underscoreToCase/.  <bf>WARNING:
This breaks source compatibility with previous versions.</bf>
</itemize>

<sect1>Version 0.7.8
<p>
<itemize>
<item>Provisional support for GHC 4.08
<item>Corrected constant folding
</itemize>

<sect1>Version 0.7.7
<p>
Ignores any occurrence of <tt/#pragma/.

<sect1>Version 0.7.6
<p>
Bug fixes and support for <tt/long long/.

<sect1>Version 0.7.5
<p>
This is mainly a bug fix release.  In particular, the space behaviour of
C-&gt;Haskell has been significantly improved.
<p>
IMPORTANT NOTE: From this release on, library names in <tt/lib/ tags in
<tt/context/ hooks should <em/not/ contain a suffix (i.e., omit <tt/.so/
etc).


</article>
