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


-- | C++ FFI generator - Runtime support
--   
--   Hoppy generates Haskell bindings to C++ libraries.
--   
--   This package provides common runtime functionality used by generated
--   bindings.
@package hoppy-runtime
@version 0.2.1


-- | Runtime support for generated Haskell bindings.
module Foreign.Hoppy.Runtime

-- | A numeric type representing a C++ boolean.
newtype CBool
CBool :: CUChar -> CBool

-- | Haskell type representing the C <tt>unsigned char</tt> type.
newtype CUChar :: *
CUChar :: Word8 -> CUChar

-- | Converts between integral types by going from <tt>a</tt> to
--   <tt>b</tt>, and also round-tripping the <tt>b</tt> value back to an
--   <tt>a</tt> value. If the two <tt>a</tt> values don't match, then an
--   error is signalled.
coerceIntegral :: (Integral a, Integral b, Typeable a, Typeable b, Show a) => a -> b

-- | An instance of this class represents a pointer to a C++ object. All
--   C++ classes bound by Hoppy have instances of <tt>CppPtr</tt>. The
--   lifetime of such an object can optionally be managed by the Haskell
--   garbage collector. Pointers returned from constructors are unmanaged,
--   and <a>toGc</a> converts an unmanaged pointer to a managed one.
--   <a>delete</a> must not be called on managed pointers.
class CppPtr this

-- | Polymorphic null pointer.
nullptr :: CppPtr this => this

-- | Runs an IO action on the <a>Ptr</a> underlying this pointer.
--   Equivalent to <a>withForeignPtr</a> for managed pointers: the
--   <a>Ptr</a> is only guaranteed to be valid until the action returns.
--   There is no such restriction for unmanaged pointers.
withCppPtr :: CppPtr this => this -> (Ptr this -> IO a) -> IO a

-- | Converts to a regular pointer. For objects managed by the garbage
--   collector, this comes with the warnings associated with
--   <a>unsafeForeignPtrToPtr</a>, namely that the object may be collected
--   immediately after this function returns unless there is a
--   <a>touchCppPtr</a> call later on.
toPtr :: CppPtr this => this -> Ptr this

-- | Equivalent to <a>touchForeignPtr</a> for managed object pointers. Has
--   no effect on unmanaged pointers.
touchCppPtr :: CppPtr this => this -> IO ()

-- | C++ values that can be deleted. All C++ classes bound by Hoppy have
--   instances of <tt>Deletable</tt>.
class Deletable this

-- | Deletes the object with the C++ <tt>delete</tt> operator.
delete :: Deletable this => this -> IO ()

-- | Converts a pointer to one managed by the garbage collector. A
--   <b>new</b> managed pointer is returned, and existing pointers
--   <b>including</b> the argument remain unmanaged, becoming invalid once
--   all managed pointers are unreachable. Calling this on an already
--   managed pointer has no effect and the argument is simply returned. It
--   is no longer safe to call <a>delete</a> on the given object after
--   calling this function. It is also not safe to call this function on
--   unmanaged pointers for a single object multiple times: the object will
--   get deleted more than once.
toGc :: Deletable this => this -> IO this

-- | A typeclass for references to C++ values that can be assigned to. This
--   includes raw pointers (<a>Ptr</a>), as well as pointers to object
--   types that have an assignment operator (see <a>Assignable</a>).
class Assignable cppType value

-- | <tt>assign x v</tt> assigns the value <tt>v</tt> at the location
--   pointed to by <tt>x</tt>.
assign :: Assignable cppType value => cppType -> value -> IO ()

-- | For a C++ class that also has a native Haskell representation (e.g.
--   value types such as <tt>std::string</tt>), this typeclass allows
--   converting a Haskell value into a C++ object on the heap. Encoding to
--   both the non-const and const objects is supported.
--   
--   Because the functional dependency points in the direction it does,
--   calls of the form <tt><a>encode</a> value</tt> are ambiguously typed,
--   so <a>encodeAs</a> is provided to resolve the ambiguity.
--   
--   Prefer <a>withCppObj</a> over calling <a>encode</a> directly, to
--   manage the lifetime of the object.
--   
--   See also <a>Decodable</a>.
class Encodable cppPtrType hsType | cppPtrType -> hsType
encode :: Encodable cppPtrType hsType => hsType -> IO cppPtrType

-- | Takes a dummy argument to help with type resolution of <a>encode</a>,
--   a la <a>asTypeOf</a>. For example, for a C++ pointer type
--   <tt>StdString</tt> that gets converted to a regular haskell
--   <a>String</a>, the expected usage is:
--   
--   <pre>
--   str :: String
--   encodeAs (undefined :: StdString) str
--   </pre>
encodeAs :: Encodable cppPtrType hsType => cppPtrType -> hsType -> IO cppPtrType

-- | A typeclass for converting references to C++ values into Haskell
--   values. What this means depends on the type of C++ value. Pointers to
--   numeric types and to other pointers (i.e. <tt><a>Ptr</a> (<a>Ptr</a>
--   ...)</tt>) are decodable by peeking at the value.
--   
--   For a C++ class that also has a native Haskell representation (e.g.
--   value types such as <tt>std::string</tt>), this typeclass allows
--   converting a C++ heap object into a Haskell value based on the defined
--   conversion. Decoding from both the non-const and const objects is
--   supported.
--   
--   See also <a>Encodable</a>.
class Decodable cppPtrType hsType | cppPtrType -> hsType
decode :: Decodable cppPtrType hsType => cppPtrType -> IO hsType

-- | Decodes a C++ object to a Haskell value with <a>decode</a>, releases
--   the original object with <a>delete</a>, then returns the Haskell
--   value.
decodeAndDelete :: (Deletable cppPtrType, Decodable cppPtrType hsType) => cppPtrType -> IO hsType

-- | Temporarily encodes the Haskell value into a C++ object and passes it
--   to the given function. When the function finishes, the C++ object is
--   deleted.
withCppObj :: (Deletable cppPtrType, Encodable cppPtrType hsType) => hsType -> (cppPtrType -> IO a) -> IO a

-- | <tt>withScopedPtr m f</tt> runs <tt>m</tt> to get a pointer, which is
--   given to <tt>f</tt> to execute. When <tt>f</tt> finishes, the pointer
--   is deleted.
withScopedPtr :: Deletable cppPtrType => IO cppPtrType -> (cppPtrType -> IO a) -> IO a

-- | Containers whose contents can be convered to a list.
--   
--   For a container <tt>Cont</tt> holding values with C-side type
--   <tt>Foo</tt> and Haskell-side type <tt>Bar</tt>, if the container uses
--   <a>ConvertPtr</a> then the following instances are recommended:
--   
--   <pre>
--   instance HasContents ContConst FooConst
--   instance HasContents Cont Foo
--   </pre>
--   
--   If the container uses <a>ConvertValue</a> then the following instances
--   are recommended:
--   
--   <pre>
--   instance HasContents ContConst Bar
--   instance HasContents Cont Bar
--   </pre>
class HasContents c e | c -> e

-- | Extracts the contents of a container, returning the elements in a
--   list.
toContents :: HasContents c e => c -> IO [e]

-- | Containers that can be created from a list.
--   
--   For a container <tt>Cont</tt> holding values with C-side type
--   <tt>Foo</tt> and Haskell-side type <tt>Bar</tt>, if the container uses
--   <a>ConvertPtr</a> then the following instance is recommended:
--   
--   <pre>
--   instance FromContents Cont Foo
--   </pre>
--   
--   If the container uses <a>ConvertValue</a> then the following instance
--   is recommended:
--   
--   <pre>
--   instance HasContents Cont Bar
--   </pre>
--   
--   No instances for <tt>ContConst</tt> are needed because it is easy
--   enough to cast the resulting collection to a const pointer.
class FromContents c e | c -> e

-- | Creates and returns a new container holding the given elements.
fromContents :: FromContents c e => [e] -> IO c

-- | Internal type that represents a pointer to a C++ callback object
--   (callback impl object, specifically).
newtype CCallback fnHsCType
CCallback :: (Ptr ()) -> CCallback fnHsCType

-- | A global constant function pointer that points to
--   <a>freeHaskellFunPtr</a>.
freeHaskellFunPtrFunPtr :: FunPtr (FunPtr (IO ()) -> IO ())
instance Foreign.Storable.Storable Foreign.Hoppy.Runtime.CBool
instance GHC.Show.Show Foreign.Hoppy.Runtime.CBool
instance GHC.Real.Real Foreign.Hoppy.Runtime.CBool
instance GHC.Classes.Ord Foreign.Hoppy.Runtime.CBool
instance GHC.Num.Num Foreign.Hoppy.Runtime.CBool
instance GHC.Real.Integral Foreign.Hoppy.Runtime.CBool
instance GHC.Classes.Eq Foreign.Hoppy.Runtime.CBool
instance GHC.Enum.Bounded Foreign.Hoppy.Runtime.CBool
instance GHC.Enum.Enum Foreign.Hoppy.Runtime.CBool
instance Foreign.Hoppy.Runtime.Assignable (GHC.Ptr.Ptr Foreign.Hoppy.Runtime.CBool) GHC.Types.Bool
instance Foreign.Hoppy.Runtime.Assignable (GHC.Ptr.Ptr Foreign.C.Types.CInt) GHC.Types.Int
instance Foreign.Hoppy.Runtime.Assignable (GHC.Ptr.Ptr Foreign.C.Types.CFloat) GHC.Types.Float
instance Foreign.Hoppy.Runtime.Assignable (GHC.Ptr.Ptr Foreign.C.Types.CDouble) GHC.Types.Double
instance Foreign.Storable.Storable a => Foreign.Hoppy.Runtime.Assignable (GHC.Ptr.Ptr a) a
instance Foreign.Hoppy.Runtime.Decodable (GHC.Ptr.Ptr Foreign.Hoppy.Runtime.CBool) GHC.Types.Bool
instance Foreign.Hoppy.Runtime.Decodable (GHC.Ptr.Ptr Foreign.C.Types.CChar) Foreign.C.Types.CChar
instance Foreign.Hoppy.Runtime.Decodable (GHC.Ptr.Ptr Foreign.C.Types.CUChar) Foreign.C.Types.CUChar
instance Foreign.Hoppy.Runtime.Decodable (GHC.Ptr.Ptr Foreign.C.Types.CShort) Foreign.C.Types.CShort
instance Foreign.Hoppy.Runtime.Decodable (GHC.Ptr.Ptr Foreign.C.Types.CUShort) Foreign.C.Types.CUShort
instance Foreign.Hoppy.Runtime.Decodable (GHC.Ptr.Ptr Foreign.C.Types.CInt) GHC.Types.Int
instance Foreign.Hoppy.Runtime.Decodable (GHC.Ptr.Ptr Foreign.C.Types.CUInt) Foreign.C.Types.CUInt
instance Foreign.Hoppy.Runtime.Decodable (GHC.Ptr.Ptr Foreign.C.Types.CLong) Foreign.C.Types.CLong
instance Foreign.Hoppy.Runtime.Decodable (GHC.Ptr.Ptr Foreign.C.Types.CULong) Foreign.C.Types.CULong
instance Foreign.Hoppy.Runtime.Decodable (GHC.Ptr.Ptr Foreign.C.Types.CLLong) Foreign.C.Types.CLLong
instance Foreign.Hoppy.Runtime.Decodable (GHC.Ptr.Ptr Foreign.C.Types.CULLong) Foreign.C.Types.CULLong
instance Foreign.Hoppy.Runtime.Decodable (GHC.Ptr.Ptr Foreign.C.Types.CFloat) GHC.Types.Float
instance Foreign.Hoppy.Runtime.Decodable (GHC.Ptr.Ptr Foreign.C.Types.CDouble) GHC.Types.Double
instance Foreign.Hoppy.Runtime.Decodable (GHC.Ptr.Ptr GHC.Int.Int8) GHC.Int.Int8
instance Foreign.Hoppy.Runtime.Decodable (GHC.Ptr.Ptr GHC.Int.Int16) GHC.Int.Int16
instance Foreign.Hoppy.Runtime.Decodable (GHC.Ptr.Ptr GHC.Int.Int32) GHC.Int.Int32
instance Foreign.Hoppy.Runtime.Decodable (GHC.Ptr.Ptr GHC.Int.Int64) GHC.Int.Int64
instance Foreign.Hoppy.Runtime.Decodable (GHC.Ptr.Ptr GHC.Word.Word8) GHC.Word.Word8
instance Foreign.Hoppy.Runtime.Decodable (GHC.Ptr.Ptr GHC.Word.Word16) GHC.Word.Word16
instance Foreign.Hoppy.Runtime.Decodable (GHC.Ptr.Ptr GHC.Word.Word32) GHC.Word.Word32
instance Foreign.Hoppy.Runtime.Decodable (GHC.Ptr.Ptr GHC.Word.Word64) GHC.Word.Word64
instance Foreign.Hoppy.Runtime.Decodable (GHC.Ptr.Ptr Foreign.C.Types.CPtrdiff) Foreign.C.Types.CPtrdiff
instance Foreign.Hoppy.Runtime.Decodable (GHC.Ptr.Ptr Foreign.C.Types.CSize) Foreign.C.Types.CSize
instance Foreign.Hoppy.Runtime.Decodable (GHC.Ptr.Ptr System.Posix.Types.CSsize) System.Posix.Types.CSsize
instance Foreign.Hoppy.Runtime.Decodable (GHC.Ptr.Ptr (GHC.Ptr.Ptr Foreign.Hoppy.Runtime.CBool)) (GHC.Ptr.Ptr Foreign.Hoppy.Runtime.CBool)
instance Foreign.Hoppy.Runtime.Decodable (GHC.Ptr.Ptr (GHC.Ptr.Ptr Foreign.C.Types.CChar)) (GHC.Ptr.Ptr Foreign.C.Types.CChar)
instance Foreign.Hoppy.Runtime.Decodable (GHC.Ptr.Ptr (GHC.Ptr.Ptr Foreign.C.Types.CUChar)) (GHC.Ptr.Ptr Foreign.C.Types.CUChar)
instance Foreign.Hoppy.Runtime.Decodable (GHC.Ptr.Ptr (GHC.Ptr.Ptr Foreign.C.Types.CShort)) (GHC.Ptr.Ptr Foreign.C.Types.CShort)
instance Foreign.Hoppy.Runtime.Decodable (GHC.Ptr.Ptr (GHC.Ptr.Ptr Foreign.C.Types.CUShort)) (GHC.Ptr.Ptr Foreign.C.Types.CUShort)
instance Foreign.Hoppy.Runtime.Decodable (GHC.Ptr.Ptr (GHC.Ptr.Ptr Foreign.C.Types.CInt)) (GHC.Ptr.Ptr Foreign.C.Types.CInt)
instance Foreign.Hoppy.Runtime.Decodable (GHC.Ptr.Ptr (GHC.Ptr.Ptr Foreign.C.Types.CUInt)) (GHC.Ptr.Ptr Foreign.C.Types.CUInt)
instance Foreign.Hoppy.Runtime.Decodable (GHC.Ptr.Ptr (GHC.Ptr.Ptr Foreign.C.Types.CLong)) (GHC.Ptr.Ptr Foreign.C.Types.CLong)
instance Foreign.Hoppy.Runtime.Decodable (GHC.Ptr.Ptr (GHC.Ptr.Ptr Foreign.C.Types.CULong)) (GHC.Ptr.Ptr Foreign.C.Types.CULong)
instance Foreign.Hoppy.Runtime.Decodable (GHC.Ptr.Ptr (GHC.Ptr.Ptr Foreign.C.Types.CLLong)) (GHC.Ptr.Ptr Foreign.C.Types.CLLong)
instance Foreign.Hoppy.Runtime.Decodable (GHC.Ptr.Ptr (GHC.Ptr.Ptr Foreign.C.Types.CULLong)) (GHC.Ptr.Ptr Foreign.C.Types.CULLong)
instance Foreign.Hoppy.Runtime.Decodable (GHC.Ptr.Ptr (GHC.Ptr.Ptr Foreign.C.Types.CFloat)) (GHC.Ptr.Ptr Foreign.C.Types.CFloat)
instance Foreign.Hoppy.Runtime.Decodable (GHC.Ptr.Ptr (GHC.Ptr.Ptr Foreign.C.Types.CDouble)) (GHC.Ptr.Ptr Foreign.C.Types.CDouble)
instance Foreign.Hoppy.Runtime.Decodable (GHC.Ptr.Ptr (GHC.Ptr.Ptr GHC.Int.Int8)) (GHC.Ptr.Ptr GHC.Int.Int8)
instance Foreign.Hoppy.Runtime.Decodable (GHC.Ptr.Ptr (GHC.Ptr.Ptr GHC.Int.Int16)) (GHC.Ptr.Ptr GHC.Int.Int16)
instance Foreign.Hoppy.Runtime.Decodable (GHC.Ptr.Ptr (GHC.Ptr.Ptr GHC.Int.Int32)) (GHC.Ptr.Ptr GHC.Int.Int32)
instance Foreign.Hoppy.Runtime.Decodable (GHC.Ptr.Ptr (GHC.Ptr.Ptr GHC.Int.Int64)) (GHC.Ptr.Ptr GHC.Int.Int64)
instance Foreign.Hoppy.Runtime.Decodable (GHC.Ptr.Ptr (GHC.Ptr.Ptr GHC.Word.Word8)) (GHC.Ptr.Ptr GHC.Word.Word8)
instance Foreign.Hoppy.Runtime.Decodable (GHC.Ptr.Ptr (GHC.Ptr.Ptr GHC.Word.Word16)) (GHC.Ptr.Ptr GHC.Word.Word16)
instance Foreign.Hoppy.Runtime.Decodable (GHC.Ptr.Ptr (GHC.Ptr.Ptr GHC.Word.Word32)) (GHC.Ptr.Ptr GHC.Word.Word32)
instance Foreign.Hoppy.Runtime.Decodable (GHC.Ptr.Ptr (GHC.Ptr.Ptr GHC.Word.Word64)) (GHC.Ptr.Ptr GHC.Word.Word64)
instance Foreign.Hoppy.Runtime.Decodable (GHC.Ptr.Ptr (GHC.Ptr.Ptr Foreign.C.Types.CPtrdiff)) (GHC.Ptr.Ptr Foreign.C.Types.CPtrdiff)
instance Foreign.Hoppy.Runtime.Decodable (GHC.Ptr.Ptr (GHC.Ptr.Ptr Foreign.C.Types.CSize)) (GHC.Ptr.Ptr Foreign.C.Types.CSize)
instance Foreign.Hoppy.Runtime.Decodable (GHC.Ptr.Ptr (GHC.Ptr.Ptr System.Posix.Types.CSsize)) (GHC.Ptr.Ptr System.Posix.Types.CSsize)
instance Foreign.Hoppy.Runtime.Decodable (GHC.Ptr.Ptr (GHC.Ptr.Ptr (GHC.Ptr.Ptr a))) (GHC.Ptr.Ptr (GHC.Ptr.Ptr a))