-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Inline C & Objective-C code in Haskell for language interoperability
--   
@package language-c-inline
@version 0.7.9.1


-- | This module exports the principal API for inline Objective-C.
module Language.C.Inline.ObjC

-- | A C string is a reference to an array of C characters terminated by
--   NUL.
type CString = Ptr CChar

-- | A string with explicit length information in bytes instead of a
--   terminating NUL (allowing NUL characters in the middle of the string).
type CStringLen = (Ptr CChar, Int)

-- | A C wide string is a reference to an array of C wide characters
--   terminated by NUL.
type CWString = Ptr CWchar

-- | A wide character string with explicit length information in
--   <a>CWchar</a>s instead of a terminating NUL (allowing NUL characters
--   in the middle of the string).
type CWStringLen = (Ptr CWchar, Int)

-- | Haskell representation for <tt>errno</tt> values. The implementation
--   is deliberately exposed, to allow users to add their own definitions
--   of <a>Errno</a> values.
data Errno :: *

-- | The type <a>ForeignPtr</a> represents references to objects that are
--   maintained in a foreign language, i.e., that are not part of the data
--   structures usually managed by the Haskell storage manager. The
--   essential difference between <a>ForeignPtr</a>s and vanilla memory
--   references of type <tt>Ptr a</tt> is that the former may be associated
--   with <i>finalizers</i>. A finalizer is a routine that is invoked when
--   the Haskell storage manager detects that - within the Haskell heap and
--   stack - there are no more references left that are pointing to the
--   <a>ForeignPtr</a>. Typically, the finalizer will, then, invoke
--   routines in the foreign language that free the resources bound by the
--   foreign object.
--   
--   The <a>ForeignPtr</a> is parameterised in the same way as <a>Ptr</a>.
--   The type argument of <a>ForeignPtr</a> should normally be an instance
--   of class <a>Storable</a>.
data ForeignPtr a :: * -> *

-- | This function casts a <a>ForeignPtr</a> parameterised by one type into
--   another type.
castForeignPtr :: ForeignPtr a -> ForeignPtr b

-- | An abstract type representing names in the syntax tree.
--   
--   <a>Name</a>s can be constructed in several ways, which come with
--   different name-capture guarantees (see
--   <a>Language.Haskell.TH.Syntax#namecapture</a> for an explanation of
--   name capture):
--   
--   <ul>
--   <li>the built-in syntax <tt>'f</tt> and <tt>''T</tt> can be used to
--   construct names, The expression <tt>'f</tt> gives a <tt>Name</tt>
--   which refers to the value <tt>f</tt> currently in scope, and
--   <tt>''T</tt> gives a <tt>Name</tt> which refers to the type <tt>T</tt>
--   currently in scope. These names can never be captured.</li>
--   <li><a>lookupValueName</a> and <a>lookupTypeName</a> are similar to
--   <tt>'f</tt> and <tt>''T</tt> respectively, but the <tt>Name</tt>s are
--   looked up at the point where the current splice is being run. These
--   names can never be captured.</li>
--   <li><a>newName</a> monadically generates a new name, which can never
--   be captured.</li>
--   <li><a>mkName</a> generates a capturable name.</li>
--   </ul>
--   
--   Names constructed using <tt>newName</tt> and <tt>mkName</tt> may be
--   used in bindings (such as <tt>let x = ...</tt> or <tt>x -&gt;
--   ...</tt>), but names constructed using <tt>lookupValueName</tt>,
--   <tt>lookupTypeName</tt>, <tt>'f</tt>, <tt>''T</tt> may not.
data Name :: *

-- | Specify imported Objective-C files. Needs to be spliced where an
--   import declaration can appear. (Just put it straight after all the
--   import statements in the module.)
--   
--   NB: This inline splice must appear before any other use of inline code
--   in a module.
--   
--   FIXME: need to use TH.addDependentFile on each of the imported ObjC
--   files &amp; read headers
objc_import :: [FilePath] -> Q [Dec]

-- | Inline Objective-C top-level definitions for a header file ('.h').
objc_interface :: [Definition] -> Q [Dec]

-- | Inline Objective-C top-level definitions for an implementation file
--   ('.m').
--   
--   The top-level Haskell variables given in the first argument will be
--   foreign exported to be accessed from the generated Objective-C code.
--   In C, these Haskell variables will always be represented as functions.
--   (In particular, if the Haskell variable refers to a CAF, it will be a
--   nullary function in C — after all, a thunk may still need to be
--   evaluated.)
objc_implementation :: [Annotated Name] -> [Definition] -> Q [Dec]

-- | Specification of a bridge for a Haskell structure that can be queried
--   and updated from Objective-C.
--   
--   The first argument is the name of the Objective-C class that will be a
--   proxy for the Haskell structure. The second argument the name of the
--   Haskell type of the bridged Haskell structure.
--   
--   The generated class is immutable. When a property is updated, a new
--   instance is allocated. This closely mirrors the behaviour of the
--   Haskell structure for which the class is a proxy.
--   
--   The designated initialiser of the generated class is
--   '[-initWith<a>HsName</a>HsPtr:(HsStablePtr)particleHsPtr]', where
--   '&lt;HsName&gt;' is the type name of the Haskell structure. This
--   initialiser is generated if it is not explicitly provided. The
--   generated method '[-init]' calls the designated initialiser with
--   <tt>nil</tt> for the stable pointer.
--   
--   WARNING: This is a very experimental feature and it will SURELY change
--   in the future!!!
--   
--   FIXME: don't generate the designated initialiser if it is explicitly
--   provided
objc_record :: String -> String -> Name -> [Annotated Name] -> [PropertyAccess] -> [ObjCIfaceDecl] -> [Definition] -> Q [Dec]

-- | Declare a Haskell<a>-</a>Objective-C marshaller pair to be used in all
--   subsequent marshalling code generation.
--   
--   On the Objective-C side, the marshallers must use a wrapped foreign
--   pointer to an Objective-C class (just as those of <a>Class</a> hints).
--   The domain and codomain of the two marshallers must be the opposite
--   and both are executing in <a>IO</a>.
objc_marshaller :: Name -> Name -> Q [Dec]

-- | Force type checking of all declaration appearing earlier in this
--   module.
--   
--   Template Haskell performs type checking on declaration groups
--   seperated by toplevel splices. In order for a type declaration to be
--   available to an Objective-C inline directive, the type declaration
--   must be in an earlier declaration group than the Objective-C inline
--   directive. A toplevel Objective-C inline directive always is the start
--   of a new declaration group; hence, it can be considered to be
--   implicitly preceded by an <a>objc_typecheck</a>.
objc_typecheck :: Q [Dec]

-- | Inline Objective-C expression.
--   
--   The inline expression will be wrapped in a C function whose arguments
--   are marshalled versions of the Haskell variables given in the first
--   argument. The marshalling of the variables and of the result is
--   determined by the marshalling annotations at the variables and the
--   inline expression.
objc :: [Annotated Name] -> Annotated Exp -> Q Exp

-- | Emit the Objective-C file and return the foreign declarations. Needs
--   to be the last use of an 'objc...' function. (Just put it at the end
--   of the Haskell module.)
objc_emit :: Q [Dec]

-- | Annotating entities with hints.
--   
--   The alternatives are to provide an explicit marshalling hint with
--   '(:&gt;)', or to leave the marshalling implicitly defined by the
--   name's type.
data Annotated e
(:>) :: e -> hint -> Annotated e
Typed :: Name -> Annotated Name

-- | We provide additional syntax where the hint is to the left of the
--   annotated entity.
(<:) :: Hint hint => hint -> e -> Annotated e

-- | Annotation for irrelevant results
void :: e -> Annotated e

-- | Hint indicating to marshal an Objective-C object as a foreign pointer,
--   where the argument is the Haskell type representing the Objective-C
--   class. The Haskell type name must coincide with the Objective-C class
--   name.
data Class
Class :: t -> Class

-- | Class of entities that can be used as TH types.
class IsType ty

-- | Maps a quoted property to a quoted projection and a quoted update
--   function in addition to the type of the projected value.
data PropertyAccess

-- | Map a property to explicit projection and update functions.
(==>) :: ObjCIfaceDecl -> (TypeQ, ExpQ, ExpQ) -> PropertyAccess

-- | Map a property to a field label. This function assumes that the field
--   name is typed and can be reified.
(-->) :: ObjCIfaceDecl -> Name -> PropertyAccess