== Generating Haskell wrappers to .NET types: hswrap ==

Included with the hs-dotnet package is a tool (hswrap) that lets you
generate a Haskell module from a .NET class. Along with a Haskell type
representing the .NET class (or for interfaces: type classes), each
method, field and property of the .NET class is given a corresponding
Haskell IO function/action that presents a type-safe and
Haskell-friendly interface to them. 

For bigger classes and entire APIs / assemblies, it has proven to be
of some utility (e.g., almost all of the modules that hs-dotnet
supplies in its distribution were generated using this tool.) 

This document briefly introduces 'hswrap', outlining how to generate
such Haskell wrapper modules.

== Basic invocation ==

Generate a Haskell module wrapper to a standard class:

c:\src> hswrap -v -d --outdir=NET System.Decimal
  -- creates the wrapper module NET/System/Decimal.hs
  -- If System.Decimal uses other types for which 'hswrap' cannot
  -- locate a wrapper for in NET/ , it will also prompt the
  -- user if he/she wants to generate wrappers for these.

c:\src> hswrap -d --outdir=NET System.Collections.Generic.Queue
  -- generates a wrapper module for the (generic/parameterized) type Queue.
c:\src> hswrap -d --outdir=NET System.Collections.Generic.Queue`1
  -- same as above, but using lower-level .NET syntax for indicating
  -- the number of types that Queue is parameterized over.

== Options ==

List of supported options: 

 --help print out this usage message and exit.
 -v  be verbose about actions performed.
 -q  generate wrapper modules without making a song and dance about it on stdout/stderr.
 -d  output into a dir hierarchy; creating it if needed.
     (e.g., System.Object.Futon will be emitted as System/Object/Futon.hs)
 -n  don't output the Haskell type into a separate module (default is to do so.)
 --interactive
     have user verify the generation of wrappers
 --non-interactive
     don't ask for permission; just go.
 --no-chase
     if uses of non-bound types are encountered, don't try to generate wrappers
     for these
 --dry-run
     disable generation of wrapper modules, just print out what they are/would be.
 --ignore=<PAT>
     don't generate wrappers for types matching PAT --
        --ignore=System.Xml.* turns off wrapper generation for the System.Xml namespace.
 --ignore-file=<FILE>
     don't generate wrappers for type patterns in FILE.
 --file=<FILE>
     generate wrappers for types listed in FILE; one per-line.
 --outdir=<DIR>
     emit the generated wrappers to DIR, i.e., the type System.X will be generated as
        DIR/System/X.hs
 --module-dir=<DIR>
     add DIR to the wrapper module search path. DIR will then be probed when the tool
     tries to determine if a referenced type already has a wrapper module (and generating
     another one isn't needed.) Notice that DIR is assumed to be at the toplevel of the
     module hierarchy, i.e., a DIR of 'Foo' will match 'System.X' if 'Foo/System/X.hs' is
     present. The 'hswrap' assumes that the _module name_ in that X.hs is 'System.X'.

== Bugs / feedback ==

Feedback on the tool and how well it supports your tasks most welcome.
As is improvements and contribution to the code itself; I apologize
for its hacky nature ;-)