  The Binding Generator C->Haskell
  Manuel M. T. Chakravarty, chak@cse.unsw.edu.au
  v0.15, 22 May 2003

  C->Haskell is an interface generator that simplifies the development
  of 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 corre-
  sponding C header file.  Another noteworthy property is the
  lightweight nature of the approach.  More background information is
  available in a research paper discussing C->Haskell, which is at
  <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.
  ______________________________________________________________________

  Table of Contents














































  1. Installation

     1.1 Where is the Source?
     1.2 What Else Do I Need?
     1.3 I Got Everything, and Now?
     1.4 Packages

  2. Usage of C->Haskell

     2.1 Usage of
     2.2 Compilation of a Generated Haskell API

  3. Implementation of Haskell Binding Modules

     3.1 Import Hooks
     3.2 Context Hooks
     3.3 Type Hooks
     3.4 Sizeof Hooks
     3.5 Enumeration Hooks
     3.6 Call Hooks
     3.7 Function Hooks
     3.8 Get Hooks
     3.9 Set Hooks
     3.10 Pointer Hooks
     3.11 Class Hooks
     3.12 CPP Directives and Inline C Code
     3.13 Grammar Rules

  4. The Haskell FFI Marshalling Library

  5. Bug Reports and Suggestions

  6. Copyright

  7. GNU Free Documentation License

  8. Release Notes

     8.1 Version 0.11.5 "Powder Snow"
     8.2 Version 0.10.17 "Altocumulus Stratiformis Perlucidus Undulatus"
     8.3 Version 0.9.9 "Blue Ginger"
     8.4 Version 0.8.2 "Gentle Moon"
     8.5 Version 0.8.1 "Gentle Moon"
     8.6 Version 0.7.10 "Afterthought"
     8.7 Version 0.7.9 "Afterthought"
     8.8 Version 0.7.8
     8.9 Version 0.7.7
     8.10 Version 0.7.6
     8.11 Version 0.7.5


  ______________________________________________________________________

  CCooppyyrriigghhtt && DDiissttrriibbuuttiioonn

  Copyright (c) [1999..2003] by Manuel M. T. Chakravarty.  The manual is
  distributed under the terms GNU Free Documentation License available
  from <http://www.fsf.org/copyleft/fdl.html>.

  The master copy of this document is at
  <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.



  CCoonnttrriibbuuttiioonnss

  If you have any comments, suggestions, or contributions, please send
  them to chak@cse.unsw.edu.au.



  11..  IInnssttaallllaattiioonn

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


  11..11..  WWhheerree iiss tthhee SSoouurrccee??

  The master site of C->Haskell is at
  <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->Haskell's repository and may have pre-
  compiled binaries for easier installation.


  11..22..  WWhhaatt EEllssee DDoo II NNeeeedd??

  You need a Haskell system supported by C->Haskell.  Currently this is
  only the _G_l_a_s_g_o_w _H_a_s_k_e_l_l _C_o_m_p_i_l_e_r _(_G_H_C_), which you can obtain from
  <http://haskell.org/ghc/>.  You need a fairly recent version of the
  Haskell compiler.  C->Haskell uses a compiler support library called
  the _C_o_m_p_i_l_e_r _T_o_o_l_k_i_t.  In the main distribution, the Compiler Toolkit
  is already contained in the source tar ball -- be sure to download a
  file named c2hs-_x._y._z.tar.gz, were _x._y._z is the version number of the
  package.

  To build the documentation, you will also need the _S_G_M_L _T_o_o_l_s, which
  you find at your nearest sunsite or Linux mirror or at
  <ftp://ftp.lip6.fr/pub/sgml-tools/>.  On an up-to-date Linux system,
  the tools are probably already installed.


  11..33..  II GGoott EEvveerryytthhiinngg,, aanndd NNooww??

  The short answer is


       % 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




  In the INSTALL file, there are more details.

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


  11..44..  PPaacckkaaggeess

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



       c2hs-conf --package-conf | ghc-pkg --add-package





  22..  UUssaaggee ooff CC-->>HHaasskkeellll

  Let's have a brief look at how to call the tool and how to use the
  generated interfaces.


  22..11..  UUssaaggee ooff cc22hhss

  C->Haskell is implemented by the executable c2hs.  The simplest form
  of usage is


       c2hs _l_i_b.h _L_i_b.chs


  where _l_i_b.h is the header file and _L_i_b.chs the Haskell binding module,
  which define the C- and Haskell-side interface, respectively.  If no
  errors occur, the result is a pure Haskell module _L_i_b.hs, which
  implements the Haskell API of the library.  It is possible to omit the
  C header file _l_i_b.h if instead appropriate CPP directives or inline C
  code is used in the Haskell binding module _L_i_b.chs (see ``the section
  on CPP directives'' for details.)  In any case, in addition to the
  Haskell module _L_i_b.hs, a C header file _L_i_b.h is generated.  This
  header file should be provided to the Haskell compiler when compiling
  _L_i_b.hs.  Please ensure that no user-supplied header file is
  overwritten.

  The executable c2hs has a couple more options:



       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)
         -v          --version           show version information
                     --old-ffi[=OLDFFI]  use the FFI without `Ptr a'

       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)



  The most useful of these is probably --cppopts= (or -C).  If the C
  header file needs any special options (like -D or -I) to go through
  the C pre-processor, here is the place to pass them.  A call may look
  like this:


       c2hs --cppopts='-I/some/obscure/dir -DEXTRA' _l_i_b.h _L_i_b.chs


  Do not forget the quotes if you have more than one option that you
  want to pass to the pre-processor.

  Often, _l_i_b.h will not be in the current directory, but in one of the
  header file directories.  C->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 /usr/include and /usr/local/include; and
  second, it will look in every directory that is mentioned in a -IDIR
  option passed to the pre-processor via --cppopts.

  If the compiled binding module contains import hooks, C->Haskell needs
  to find the .chi (C->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 --include=INCLUDE option has to be used to indicate the location,
  where INCLUDE is a colon-separated list of directories.  Multiple such
  options are admissible.  Paths specified later are searched first.


  22..22..  CCoommppiillaattiioonn ooff aa GGeenneerraatteedd HHaasskkeellll AAPPII

  C->Haskell comes with a marshalling library, called 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 C2HS.  To simplify this usually
  operating and compilation system-dependent process, C->Haskell comes
  with a simple configuration manager, in the form of the executable
  c2hs-conf.  It can be used to inquire information for compilation and
  linking and pass that information on to the Haskell compiler.  The
  call


       c2hs-config --cflags


  returns all flags that need to be given to the Haskell compiler for
  compilation and


       c2hs-config --lib


  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:


       ghc `c2hs-config --cflags` -#include\"_L_i_b.h\" -c _L_i_b.hs


  The backquotes cause the shell to call 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->Haskell-
  generated header file _L_i_b.h into the generated code.

  As an alternative, if you have registered C->Haskell's support
  libraries with GHC's package manager, you do not need to use c2hs-
  config, but instead, you can simply pass the option -package c2hs to
  GHC (both when compiling and when linking).

  Furthermore, c2hs-config can also be used to locate the executable of
  the tool itself, by calling


       c2hs-config --c2hs


  This slightly simplifies configuration management of libraries
  generated by C->Haskell, as it is sufficient to know the location of
  c2hs-config to access all other components of C->Haskell.



  33..  IImmpplleemmeennttaattiioonn ooff HHaasskkeellll BBiinnddiinngg MMoodduulleess

  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
  <http://www.cse.unsw.edu.au/~chak/papers/papers.html#c2hs>.  All
  features described in the paper, except 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->Haskell.  In the source distribution, these examples are
  located below the directories tests and examples.  The latter contains
  a binding for the Gnome <http://www.gnome.org> HTTP 1.1 library ghttp.
  The sources of the marshalling library C2HS are in the directory 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 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
  C2HSDeprecated instead of C2HS.

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


  33..11..  IImmppoorrtt HHooookkss


       {#import [qualified] _m_o_d_i_d#}


  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 _m_o_d_i_d is also generated by C->Haskell and
  instructs the tool to read the file _m_o_d_i_d.chi.

  If an explicit output file name is given (--output option), this name
  determines the basename for the .chi file of the currently translated
  module.

  Currently, only pointer hooks generate information that is stored in a
  .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->Haskell.

  _R_e_s_t_r_i_c_t_i_o_n_: 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.


  33..22..  CCoonntteexxtt HHooookkss


       {#context [lib = _l_i_b] [prefix = _p_r_e_f_i_x]#}


  Context hooks define a set of global configuration options.
  Currently, there are three parameters all of which are strings:

  +o  _l_i_b is a dynamic library that contains symbols needed by the
     present binding.

  +o  _p_r_e_f_i_x 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 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.

  All three parameters are optional.  An example of a context hook is
  the following:

       {#context prefix = "gtk"#}


  If a binding module contains a binding hook, it must be the first hook
  in the module.


  33..33..  TTyyppee HHooookkss


       {#type _i_d_e_n_t#}


  A type hooks maps a C type to a Haskell type.  As an example, consider


       type GInt = {#type gint#}


  The type must be a defined type, primitive types, such as int, are not
  admissible.


  33..44..  SSiizzeeooff HHooookkss


       {#sizeof _i_d_e_n_t#}


  A sizeof hooks maps a C type to its size in bytes.  As an example,
  consider



  gIntSize :: Int
  gIntSize  = {#sizeof gint#}




  The type must be a defined type, primitive types, such as int, are not
  admissible.  The size of primitive types can always be obtained using
  Storable.sizeOf.


  33..55..  EEnnuummeerraattiioonn HHooookkss


       {#enum _c_i_d [as _h_s_i_d] {_a_l_i_a_s_1 , ... , _a_l_i_a_s_n} [with prefix = _p_r_e_f]
       [deriving (_c_l_i_d_1 , ... , _c_l_i_d_n)]#}


  Rewrite the C enumeration called _c_i_d into a Haskell data type
  declaration, which is made an instance of 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 _h_s_i_d is
  given, this is the name of the Haskell data type.  The identifiers
  _c_l_i_d_1 to _c_l_i_d_n are added to the deriving clause of the Haskell type.

  By default, the names of the C enumeration are used for the
  constructors in Haskell.  If _a_l_i_a_s_1 is underscoreToCase, the original
  C names are capitalised and the use of underscores is rewritten to
  caps.  Moreover, _a_l_i_a_s_1 to _a_l_i_a_s_n may be aliases of the form _c_i_d as
  _h_s_i_d, which map individual C names to Haskell names.  Instead of the
  global prefix introduced by a context hook, a local prefix _p_r_e_f can
  optionally be specified.

  As an example, consider


       {#enum WindowType {underscoreToCase} deriving (Eq)#}


  NNoottee:: The enum define hooks described in the C->Haskell are not
  implemented yet.


  33..66..  CCaallll HHooookkss


       {#call [pure] [unsafe] _c_i_d [as (_h_s_i_d | ^)]#}


  A call hook rewrites to a call to the C function _c_i_d and also ensures
  that the appropriate foreign import declaration is generated.  The
  tags pure and unsafe specify that the external function is purely
  functional and cannot re-enter the Haskell runtime, respectively.  If
  _h_s_i_d is present, it is used as the identifier for the foreign
  declaration, which otherwise defaults to the _c_i_d.  When instead of
  _h_s_i_d, the symbol ^ is given, the _c_i_d after conversion from C's
  underscore notation to a capitalised identifier is used.

  As an example, consider



       sin :: Float -> Float
       sin  = {#call pure sin as "_sin"#}


  33..77..  FFuunnccttiioonn HHooookkss


       {#fun  [pure] [unsafe] _c_i_d [as (_h_s_i_d | ^)] [_c_t_x_t =>] { _p_a_r_m_1 , ... ,
       _p_a_r_m_n } -> _p_a_r_m


  Function hooks are call hooks including parameter marshalling.  Thus,
  the components of a function hook up to and including the as alias are
  the same as for call hooks.  The remaining components use literals
  enclosed in backwards and foward single quotes (` and ') to denote
  Haskell code fragments (or more precisely, parts of the Haskell type
  signature for the bound function).  The first one is the phrase _c_t_x_t
  preceding =>, which denotes the type context.  This is followed by
  zero or more type and marshalling specifications _p_a_r_m_1 to _p_a_r_m_n for
  the function arguments and one _p_a_r_m for the function result.  Each
  such specification _p_a_r_m has the form


       [_i_n_m_a_r_s_h [* | -]] _h_s_t_y [&] [_o_u_t_m_a_r_s_h [* | -]]


  where _h_s_t_y 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 _i_n and _o_u_t marshaller, respectively.

  Each marshalling specification _p_a_r_m 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 & follows the Haskell
  type corresponds to two C function arguments; otherwise, it
  corresponds only to one argument.  The _p_a_r_m following the left arrow
  -> determines the marshalling of the result of the C function and may
  not contain the symbol &.

  Both _i_n_m_a_r_s_h and _o_u_t_m_a_r_s_h are identifiers of Haskell marshalling
  functions.  By default they are assumed to be pure functions; if they
  have to be executed in the IO monad, the function name needs to be
  followed by a star symbol *.  Alternatively, the identifier may be
  followed by a minux sign -, in which case the Haskell type does _n_o_t
  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.

  For a set of commonly occuring Haskell and C type combinations,
  _d_e_f_a_u_l_t _m_a_r_s_h_a_l_l_e_r_s are provided by C->Haskell if no explicit
  marshaller is given.   The out marshaller for function arguments is by
  default void-.  The defaults for the in marshallers for function
  arguments are as follows:

  +o  Bool and integral C type: cFromBool

  +o  Integral Haskell and integral C type: cIntConv

  +o  Floating Haskell and floating C type: cFloatConv

  +o  String and char*: withCString*

  +o  String and char* with explicit length: withCStringLen*

  +o  _T and _T*: with*

  +o  _T and _T* where _T is an integral type: withIntConv*

  +o  _T and _T* where _T is a floating type: withFloatConv*

  +o  Bool and _T* where _T is an integral type: withFromBool*

  The defaults for the out marshaller of the result are the converse of
  the above; i.e., instead of the with functions, the corresponding peek
  functions are used.  Moreover, when the Haskell type is (), the
  default marshaller is void-.

  As an example, consider



       {#fun notebook_query_tab_label_packing as ^
         `(NotebookClass nb, WidgetClass cld)' =>
         {notebook `nb'                ,
          widget   `cld'               ,
          alloca-  `Bool'     peekBool*,
          alloca-  `Bool'     peekBool*,
          alloca-  `PackType' peekEnum*} -> `()'#}




  which results in the Haskell type signature



       notebookQueryTabLabelPacking :: (NotebookClass nb, WidgetClass cld)
                                    => nb -> cld -> IO (Bool, Bool, PackType)




  which binds the following C function:



       void gtk_notebook_query_tab_label_packing (GtkNotebook *notebook,
                                                  GtkWidget   *child,
                                                  gboolean    *expand,
                                                  gboolean    *fill,
                                                  GtkPackType *pack_type);





  33..88..  GGeett HHooookkss


       {#get _a_p_a_t_h#}


  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 _a_p_a_t_h.
  Access paths are formed as follows (following a subset of the C
  expression syntax):
  +o  The root of any access path is a simple identifier, which denotes
     either a type name or struct tag.

  +o  An access path of the form *_a_p_a_t_h denotes dereferencing of the
     pointer yielded by accessing the access path _a_p_a_t_h.

  +o  An access path of the form _a_p_a_t_h._c_i_d specifies that the value of
     the struct member called _c_i_d should be accessed.

  +o  Finally, an access path of the form _a_p_a_t_h->_c_i_d, as in C, specifies
     a combination of dereferencing and member selection.

  For example, we may have



       visualGetType              :: Visual -> IO VisualType
       visualGetType (Visual vis)  = liftM cToEnum $ {#get Visual->type#} vis





  33..99..  SSeett HHooookkss


       {#set _a_p_a_t_h#}


  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


       {#set sockaddr_in.sin_family#} addr_in (cFromEnum AF_NET)



  33..1100..  PPooiinntteerr HHooookkss


       {#pointer [*] _c_i_d [as _h_s_i_d] [foreign | stable] [newtype | -> _h_s_i_d_2]#}


  A pointer hook facilitates the mapping of C to Haskell pointer types.
  In particular, it enables the use of ForeignPtr and 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
  _c_i_d or *_c_i_d and the Haskell type _h_s_i_d, where the latter defaults to
  _c_i_d if not explicitly given.  The identifier _c_i_d will usually be a
  type name, but in the case of *_c_i_d 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 ForeignPtr or StablePtr
  instead of a plain Ptr.  If the newtype tag is given, the Haskell type
  _h_s_i_d is defined as a newtype rather than a transparent type synonym.
  In case of a newtype, the type argument to the Haskell pointer type
  will be _h_s_i_d, which gives a cyclic definition, but the type argument
  is here really only used as a unique type tag.  Without newtype, the
  default type argument is (), but another type can be specified after
  the symbol ->.

  For example, we may have


       {#pointer *GtkObject as Object foreign newtype#}




  This will generate a new type Object as follows:



       newtype Object = Object (ForeignPtr Object)




  which allows to export Object as an abstract type and facilitates type
  checking at call sites of imported functions using the encapsulated
  foreign pointer.  The latter is achieved by C->Haskell as follows.
  The tool remembers the association of the C type *GtkObject with the
  Haskell type Object, and so, it generates for the C function



       void gtk_unref_object (GtkObject *obj);




  the import declaration



       foreign import gtk_unref_object :: Object -> IO ()




  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.

  However, as the Haskell FFI does not allow to return ForeignPtrs from
  function calls, the tool will use the type Ptr HsName in this case,
  where HsName is the Haskell name of the type.  In the above example,
  that would be Ptr Object.

  As an example that does not represent the pointer as an abstract type,
  consider the C type declaration:



       typedef struct {int x, y;} *point;




  We can represent it in Haskell as




       data Point = Point {x :: Int, y :: Int}
       {#pointer point as PointPtr -> Point#}




  which will translate to



       data Point = Point {x :: Int, y :: Int}
       type PointPtr = Ptr Point




  and establish a type association between point and PointPtr.

  _R_e_s_t_r_i_c_t_i_o_n_: The name _c_i_d cannot be a basic C type (such as int), it
  must be a defined name.


  33..1111..  CCllaassss HHooookkss


       {#class [_h_s_i_d_1 =>] _h_s_i_d_2 _h_s_i_d_3#}


  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.

  All classes in a hierarchy, except the root, will have a superclass
  identified by _h_s_i_d_1.  The new class is given by _h_s_i_d_2 and the
  corresponding external pointer is identified by _h_s_i_d_3.  Both the
  superclass and the pointer type must already have been defined by
  binding hooks that precede the class hook.

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

  The newly defined class has two members whose names are derived from
  the type name _h_s_i_d_3.  The name of first member is derived from _h_s_i_d_3
  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 _h_s_i_d_3 with the 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.

  As an example, consider



       {#pointer *GtkObject newtype#}
       {#class GtkObjectClass GtkObject#}

       {#pointer *GtkWidget newtype#}
       {#class GtkObjectClass => GtkWidgetClass GtkWidget#}





  The second class hook generates an instance for GtkWidget for both the
  GtkWidgetClass as well as for the GtkObjectClass.


  33..1122..  CCPPPP DDiirreeccttiivveess aanndd IInnlliinnee CC CCooddee

  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.

  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 #c and #endc.  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 #include directive, which can
  be used instead of specifying a C header file as an argument to 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 _l_i_b.h is specified as an argument to c2hs,
  the tool will emit the directive #include"_l_i_b.h" into the generated C
  header before any other CPP directive or inline C code.

  As an artificial example of these features consider the following
  code:



       #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




  One of two versions of the Haskell function foo (having different
  arities) is selected in dependence on the value of the CPP macro
  VERSION, which in this example is defined in the same file.  In
  realistic code, 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 fooC.

  CCuurrrreenntt lliimmiittaattiioonn ooff tthhee iimmpplleemmeennttaattiioonn:: Inline C code can currently
  not contain any code blocks; i.e., only declarations as typically
  found in header files may be included.



  33..1133..  GGrraammmmaarr RRuulleess

  The following grammar rules define the syntax of binding hooks:


       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]





  44..  TThhee HHaasskkeellll FFFFII MMaarrsshhaalllliinngg LLiibbrraarryy

  The Haskell FFI Marshalling Library is a proposed standard library for
  foreign function interoperability.  The interface of the 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.

  The library is partitioned into a language independent and a C
  specific component.  All features of the former are available from the
  module Foreign and all features of the later from CForeign.
  Nevertheless, the following module hierarchy is part of the interface
  definition:

  +o  Foreign

  +o  Int

  +o  Word

  +o  Ptr

  +o  ForeignPtr

  +o  StablePtr

  +o  Storable


  +o  MarshalAlloc

  +o  MarshalArray

  +o  MarshalError

  +o  MarshalUtils

  +o  CForeign

  +o  CTypes

  +o  CTypesISO

  +o  CError

  +o  CString

     It is recommended to access this functionality in C->Haskell
     binding modules by merely importing C2HS.



  55..  BBuugg RReeppoorrttss aanndd SSuuggggeessttiioonnss

  Please address any bug reports and suggestions to
  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->Haskell that you have been using.  You can obtain the version
  information by running c2hs-config --version.  If possible a concise
  example illustrating your problem would be appreciated.



  66..  CCooppyyrriigghhtt

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


  77..  GGNNUU FFrreeee DDooccuummeennttaattiioonn LLiicceennssee

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

  88..  RReelleeaassee NNootteess

  Important changes (especially those affecting the semantics of the
  tool) are documented in the following.


  88..11..  VVeerrssiioonn 00..1111..55 ""PPoowwddeerr SSnnooww""


  +o  Bug fixes

  +o  Constant expression can now contain enumerators

  +o  header label removed from context hooks

  +o  WWAARRNNIINNGG:: This version of c2hs may _o_v_e_r_w_r_i_t_e C header files in the
     current directory.  More precisely, if a binding module with the
     name Foo.chs is processed, a header file with the name Foo.h is
     generated and will _o_v_e_r_w_r_i_t_e any file of the same name in the
     current directory or the directory specified via the -o option.

  +o  Added support for CPP directives, including special treatment of
     conditions, and for inline C code; specification of a header file
     as an argument to c2hs is now option.

  +o  GHC line pragmas are emitted into generated Haskell code

  +o  Swap the order of reading the binding module and the C header
     (i.e., we now read the binding module first)


  88..22..  VVeerrssiioonn 00..1100..1177 ""AAllttooccuummuulluuss SSttrraattiiffoorrmmiiss PPeerrlluucciidduuss UUnndduullaattuuss""


  +o  Worked around a bug in GHC 5.04.1

  +o  Solaris-related fix

  +o  Marshalling support for bit masks represented as enumeration types

  +o  Added fun hooks

  +o  as aliases can use ^ convert the orignal identifier with
     underscore2case

  +o  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)

  +o  GHC's package system is now supported

  +o  If two import hooks add a type mapping for a pointer hook with the
     same name, the textual later one dominates.

  +o  Bug fixes

  +o  Support for bitfields (they are correctly handled when computing
     struct offsets and they can be accessed using set and get hooks)

  +o  Some more support for GNU C extensions ("alignof" and better
     support "__attribute__")

  +o  Added class hooks



  88..33..  VVeerrssiioonn 00..99..99 ""BBlluuee GGiinnggeerr""


  +o  Bug fixes

  +o  Library names in foreign imports have been removed until the
     convention of the new FFI is implemented (they are currently
     _s_i_l_e_n_t_l_y omitted)

  +o  Added sizeof hooks; sizeof of type names is now also supported in
     constant expressions

  +o  Local prefix for enum hooks; courtesy of Armin Sander

  +o  Added import hooks

  +o  The documentation includes a description of binding hooks

  +o  Added pointer hooks, which were derived from code for a similar
     feature by Axel Simon; this includes proper treatment of
     parametrised pointers

  +o  Integrated deriving option for enum hooks, which was contributed by
     Axel Simon

  +o  Adapted to GHC 5.0


  88..44..  VVeerrssiioonn 00..88..22 ""GGeennttllee MMoooonn""


  +o  Adaptation layer for legacy StablePtr interface

  +o  Forgot to export FunPtr and associated functions from C2HS

  +o  Forgot to export some names in C2HSDeprecated

  +o  Added support for gcc's __builtin_va_list


  88..55..  VVeerrssiioonn 00..88..11 ""GGeennttllee MMoooonn""


  +o  Library adapted to New FFI; the old interface can still be used by
     importing C2HSDeprecated

  +o  FFI Library specification added to the documentation


  88..66..  VVeerrssiioonn 00..77..1100 ""AAfftteerrtthhoouugghhtt""


  +o  CygWin support; based on suggestions by Anibal Maffioletti
     Rodrigues de DEUS <anibaldedeus@email.com>

  +o  IntConv instances for Int8, Word8, and Char


  88..77..  VVeerrssiioonn 00..77..99 ""AAfftteerrtthhoouugghhtt""


  +o  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


  +o  Comma now correctly required after underscoreToCase.  WWAARRNNIINNGG:: TThhiiss
     bbrreeaakkss ssoouurrccee ccoommppaattiibbiilliittyy wwiitthh pprreevviioouuss vveerrssiioonnss..


  88..88..  VVeerrssiioonn 00..77..88


  +o  Provisional support for GHC 4.08

  +o  Corrected constant folding


  88..99..  VVeerrssiioonn 00..77..77

  Ignores any occurrence of #pragma.


  88..1100..  VVeerrssiioonn 00..77..66

  Bug fixes and support for long long.


  88..1111..  VVeerrssiioonn 00..77..55

  This is mainly a bug fix release.  In particular, the space behaviour
  of C->Haskell has been significantly improved.

  IMPORTANT NOTE: From this release on, library names in lib tags in
  context hooks should _n_o_t contain a suffix (i.e., omit .so etc).





































