X-Git-Url: http://git.megacz.com/?a=blobdiff_plain;f=ghc%2Fdocs%2Fusers_guide%2Futils.sgml;h=ae5039131a70233a5238fac836a262c69de65c9e;hb=721713b5d825b893ba0f29dce1fc237c963ecc18;hp=796ee90adcec4f42ae38478b86618891f3be4945;hpb=6ebcfc5d2f1702ad1bac50a6aae8d78b72a5b4ae;p=ghc-hetmet.git
diff --git a/ghc/docs/users_guide/utils.sgml b/ghc/docs/users_guide/utils.sgml
index 796ee90..ae50391 100644
--- a/ghc/docs/users_guide/utils.sgml
+++ b/ghc/docs/users_guide/utils.sgml
@@ -116,7 +116,7 @@ tags:
that gets included into the C code to which the Haskell module
will be compiled (when compiled via C) and into the C file. These
two files are created when the #def construct
- is used.
+ is used (see below).
Actually hsc2hs does not output the Haskell
file directly. It creates a C program that includes the headers,
@@ -135,8 +135,8 @@ tags:
Command line syntax
- glue-hsc takes input files as arguments, and flags that
- modify its behavior:
+ hsc2hs takes input files as arguments,
+ and flags that modify its behavior:
@@ -171,6 +171,13 @@ tags:
+ -I DIR
+
+ Passed to the C compiler.
+
+
+
+
--lflag=FLAG
An extra flag to pass to the linker.
@@ -178,6 +185,14 @@ tags:
+ --include=FILE
+
+ As if the appropriate #include
+ directive was placed in the source.
+
+
+
+
--help
Display a summary of the available flags.
@@ -186,21 +201,21 @@ tags:
The input file should end with .hsc. Output files get
- names with the .hsc suffix replaced:
+ names with the *.hsc pattern replaced:
- .hs
+ *.hs
Haskell file
- _hsc.h
+ Hs*.h
C header
- _hsc.c
+ Hs*.c
C file
@@ -214,20 +229,28 @@ tags:
Input syntax
- All special processing is triggered by the
- # character. To output a literal
- #, write it twice: ##.
-
- Otherwise # is followed by optional
- spaces and tabs, an alphanumeric key that describes the kind of
- processing, and its arguments. Arguments look like C expressions
- and extend up to the nearest unmatched ),
- ], or }, or to the end of
- line outside any () [] {} '' "" /* */. Any
- character may be preceded by a backslash and will not be treated
- specially.
-
- Meanings of specific keys:
+ All special processing is triggered by
+ the # operator. To output
+ a literal #, write it twice:
+ ##. Inside string literals and comments
+ # characters are not processed.
+
+ A # is followed by optional
+ spaces and tabs, an alphanumeric keyword that describes
+ the kind of processing, and its arguments. Arguments look
+ like C expressions separated by commas (they are not
+ written inside parens). They extend up to the nearest
+ unmatched ), ] or
+ }, or to the end of line if it occurs outside
+ any () [] {} '' "" /**/ and is not preceded
+ by a backslash. Backslash-newline pairs are stripped.
+
+ In addition #{stuff} is equivalent
+ to #stuff except that it's self-delimited
+ and thus needs not to be placed at the end of line or in some
+ brackets.
+
+ Meanings of specific keywords:
@@ -274,18 +297,6 @@ tags:
- #option opt
-
- The specified Haskell compiler command-line option
- is placed in the {-# OPTIONS #-} pragma
- at the top of the Haskell file (see ). This is needed because
- glue-hsc emits its own OPTIONS pragma,
- and only one such pragma is interpreted by GHC.
-
-
-
-
#def C_definition
The definition (of a function, variable, struct or
@@ -307,6 +318,7 @@ tags:
#else
#endif
#error message
+ #warning message
Conditional compilation directives are passed
unmodified to the C program, C file, and C header. Putting
@@ -373,6 +385,28 @@ tags:
Ptr a -> Ptr b.
+
+
+ #enum type, constructor, value, value, ...
+
+ A shortcut for multiple definitions which use
+ #const. Each value
+ is a name of a C integer constant, e.g. enumeration value.
+ The name will be translated to Haskell by making each
+ letter following an underscore uppercase, making all the rest
+ lowercase, and removing underscores. You can supply a different
+ translation by writing hs_name = c_value
+ instead of a value, in which case
+ c_value may be an arbitrary expression.
+ The hs_name will be defined as having the
+ specified type. Its definition is the specified
+ constructor (which in fact may be an expression
+ or be empty) applied to the appropriate integer value. You can
+ have multiple #enum definitions with the same
+ type; this construct does not emit the type
+ definition itself.
+
+
@@ -393,6 +427,13 @@ tags:
prefixed by hsc_ that handles the construct
by emitting the expansion to stdout. See
template-hsc.h for examples.
+
+ Such macros can also be defined directly in the
+ source. They are useful for making a #let-like
+ macro whose expansion uses other #let macros.
+ Plain #let prepends hsc_
+ to the macro name and wraps the defininition in a
+ printf call.