[update documentation with new extensions
John Meacham <john@repetae.net>**20120214172359
 Ignore-this: 2f412f29f20127ce3f97f200674ed8b6
] hunk ./docs/unboxed.mkd 9
-# foreign imports with multiple return values.
+# extensions to the FFI
+
+## foreign imports with multiple return values.
hunk ./docs/unboxed.mkd 34
+## 'capi' calling convention
+
+The 'capi' calling convention may be used instead of 'ccall' for static
+imports. The convention means that the foreign function may not be addressable
+as an address, but rather may be implemnted as a macro, builtin, or other
+compiler specific feature. jhc will ensure that the routine is never used as a
+pointer and the headers specified in the dependency string are included
+anywhere the imported function appears. This differs from 'ccall' in that ccall
+makes no guarentees the given header file will be in scope and that a linker
+symbol of the exact name is exported.
+
+## package relative dependencies
+
+dependecies in a foreign import may be written as p:foo.c or p:foo.h, this
+means that the file should be interpreted as part of the internal
+implementation of the package. jhc willl ensure the files do not clash with
+those of other packages that may have the same name. The files should be listed
+in the c-files and c-headers sections of the library config file.
+
hunk ./docs/unboxed.mkd 55
-jhc allows explicit namespaces in import export lists. In haskell 98, a name
-such as 'Foo' in an export list will indicate that all of a class named Foo, a
-type named 'Foo' and a data constructor named 'Foo' shoud be exported. Jhc
-allows finer grained control by prefixing exports with a namespace indicator.
-The valid namespace indicators are
+jhc allows explicit namespaces in import and export lists. These may be used to
+restrict or modiy what is imported/exported by a declaration.
hunk ./docs/unboxed.mkd 64
-In addition, classes and types are in independent namespaces, so a type and a
-class of the same name may be in scope and not conflict.
+In addition, another extension is that classes and types are in independent
+namespaces, so a type and a class of the same name may be in scope and not
+conflict.
+
+# user defined kinds
+
+Jhc allows users to define custom kinds when the -fuser-kinds extension is
+enabled. The syntax is:
+
+~~~~
+data kind Nat = Z | S Nat
+~~~~
hunk ./docs/unboxed.mkd 77
-When an unqualified name is given in a import/export list then all names that
-match it that are in scope are matched. The only exception is a holdover from
-haskell 98 where in hiding lists data constructors are not matched. This
-behavior may change in the future when explicit namespaces are used, so it
-should not be relied upon when using explicit namespaces.
+This will define a new kind 'Nat' and two types 'Z' and 'S' which inhabit it.
+The types introduced by kind declarations represent unboxed values with no
+values, So they have no run-time representation (notably, not even ⊥)
hunk ./docs/unboxed.mkd 89
-will be infered. For instance, user supplied type annotations and arguments to
-data constructors defined to by polymorphic will work.
+will be used. For instance, user supplied type annotations and arguments to
+data constructors defined to by polymorphic will get the correct polymorphic
+type.
hunk ./docs/unboxed.mkd 95
-Jhc supports first class existential types, using the 'exists' keyword. It also supports
-existential data types in a similar fashion to ghc.
+Jhc supports first class existential types, using the 'exists' keyword. It also
+supports existential data types in a similar fashion to ghc.
hunk ./docs/unboxed.mkd 101
-lexical syntax is not changed to allow # in identifiers. # is still used in
-the syntax for various unboxed constructs, but normal Haskell rules apply to
+lexical syntax is not changed to allow # in identifiers. # is still used in the
+syntax for various unboxed constructs, but normal Haskell rules apply to
hunk ./docs/unboxed.mkd 139
-To operate on unboxed vaules you need to bring the appropriate primitive operators into
-scope. You can do this via the special form of FFI declaration for importing primitives.
-Any C-- primitive may be imported as well as a variety of utility routines. the primitive
-import mechanism is 'smart' in that it will dig through newtypes and take care of boxing/unboxing
-values as needed. So you can import a primitive on Char and it will take care of boxing the
-value up in the 'Char' constructor as well as the Char_ newtype for Bits32_, ultimately choosing
-the right Bits32_ primitive. imported primitives are normal haskell declarations so may be
-exported/imported from modules or passed as higher order functions like normal.
+To operate on unboxed vaules you need to bring the appropriate primitive
+operators into scope. You can do this via the special form of FFI declaration
+for importing primitives.  Any C-- primitive may be imported as well as a
+variety of utility routines. the primitive import mechanism is 'smart' in that
+it will dig through newtypes and take care of boxing/unboxing values as needed.
+So you can import a primitive on Char and it will take care of boxing the value
+up in the 'Char' constructor as well as the Char_ newtype for Bits32_,
+ultimately choosing the right Bits32_ primitive. imported primitives are normal
+haskell declarations so may be exported/imported from modules or passed as
+higher order functions like normal.
hunk ./rts/README.txt 6
+rts/  - core rts implementation