-- Hoogle documentation, generated by Haddock -- See Hoogle, http://www.haskell.org/hoogle/ -- | Inline C & Objective-C code in Haskell for language interoperability -- -- This library provides inline C & Objective-C code using GHC's -- support for quasi-quotation. In particular, it enables the use of -- foreign libraries without a dedicated bridge or binding. Here is a -- tiny example: -- -- 
--   nslog :: String -> IO ()
--   nslog msg = $(objc ['msg :> ''String] (void [cexp| NSLog(@"Here is a message from Haskell: %@", msg) |]))
--
-- -- For more information, see -- https://github.com/mchakravarty/language-c-inline/wiki. -- -- Known bugs: -- https://github.com/mchakravarty/language-c-inline/issues -- -- @package language-c-inline @version 0.7.8.0 -- | 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 -- CWchars instead of a terminating NUL (allowing NUL characters -- in the middle of the string). type CWStringLen = (Ptr CWchar, Int) -- | Haskell representation for errno values. The implementation -- is deliberately exposed, to allow users to add their own definitions -- of Errno values. data Errno :: * -- | The type ForeignPtr 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 ForeignPtrs and vanilla memory -- references of type Ptr a is that the former may be associated -- with finalizers. 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 -- ForeignPtr. Typically, the finalizer will, then, invoke -- routines in the foreign language that free the resources bound by the -- foreign object. -- -- The ForeignPtr is parameterised in the same way as Ptr. -- The type argument of ForeignPtr should normally be an instance -- of class Storable. data ForeignPtr a :: * -> * -- | This function casts a ForeignPtr parameterised by one type into -- another type. castForeignPtr :: ForeignPtr a -> ForeignPtr b -- | An abstract type representing names in the syntax tree. -- -- Names can be constructed in several ways, which come with -- different name-capture guarantees (see -- Language.Haskell.TH.Syntax#namecapture for an explanation of -- name capture): -- -- -- -- Names constructed using newName and mkName may be -- used in bindings (such as let x = ... or x -> -- ...), but names constructed using lookupValueName, -- lookupTypeName, 'f, ''T 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 & 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 -- '[-initWithHsNameHsPtr:(HsStablePtr)particleHsPtr]', where -- '<HsName>' 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 -- nil 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-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 Class hints). -- The domain and codomain of the two marshallers must be the opposite -- and both are executing in IO. 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 objc_typecheck. 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 -- '(:>)', 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