| Safe Haskell | Safe-Inferred |
|---|---|
| Language | GHC2021 |
HsBindgen.Runtime.Prelude
Description
Common definitions for interfacing with hs-bindgen generated code.
Synopsis
- class Integral (CEnumZ a) => CEnum a where
- type CEnumZ a
- toCEnum :: CEnumZ a -> a
- fromCEnum :: a -> CEnumZ a
- declaredValues :: proxy a -> DeclaredValues a
- showsUndeclared :: proxy a -> Int -> CEnumZ a -> ShowS
- readPrecUndeclared :: ReadPrec a
- isDeclared :: a -> Bool
- mkDeclared :: CEnumZ a -> Maybe a
- class CEnum a => SequentialCEnum a where
- minDeclaredValue :: a
- maxDeclaredValue :: a
- newtype AsCEnum a = WrapCEnum {
- unwrapCEnum :: a
- newtype AsSequentialCEnum a = WrapSequentialCEnum {}
- class HasCField (a :: Type) (field :: Symbol) where
- class HasCBitfield (a :: Type) (field :: Symbol) where
- type CBitfieldType (a :: Type) (field :: Symbol) :: Type
- bitfieldOffset# :: Proxy# a -> Proxy# field -> Int
- bitfieldWidth# :: Proxy# a -> Proxy# field -> Int
- data BitfieldPtr a where
- pattern BitfieldPtr :: Ptr a -> Int -> Int -> BitfieldPtr a
- class ToFunPtr a where
- class FromFunPtr a where
- fromFunPtr :: FunPtr a -> a
- withFunPtr :: ToFunPtr a => a -> (FunPtr a -> IO b) -> IO b
- plusPtrElem :: forall a. Storable a => Ptr a -> Int -> Ptr a
- data ConstantArray (n :: Nat) a
- data IncompleteArray a
- class StaticSize a where
- staticSizeOf :: Proxy a -> Int
- staticAlignment :: Proxy a -> Int
- class ReadRaw a where
- class WriteRaw a where
- newtype EquivStorable a = EquivStorable a
- newtype Block t = Block (Ptr ())
- type PtrConst a = ConstPtr a
C enumerations
class Integral (CEnumZ a) => CEnum a where Source #
C enumeration
This class implements an API for Haskell representations of C enumerations.
C enum declarations only declare values; they do not limit the range of the
corresponding integral type. They may have negative values, non-sequential
values, and multiple names for a single value.
At a low level, hs-bindgen generates a newtype wrapper around the
integral representation type to represent a C enum. An instance of this
class is generated automatically. A Show instance defined using
showsCEnum is also generated by default. Bounded and Enum instances are
not generated automatically because values do not technically need to be
declared. Users may optionally derive these instances using AsCEnum or
AsSeqentialCEnum when appropriate.
This class may also be used with Haskell sum-type representations of enumerations.
Minimal complete definition
Methods
toCEnum :: CEnumZ a -> a Source #
Construct a value from the integral representation
fromCEnum . toCEnum === id
fromCEnum :: a -> CEnumZ a Source #
Get the integral representation for a value
toCEnum . fromCEnum === id
If a has an Ord instance, it should be compatible with the Ord
instance on the underlying integral value:
\x y -> (x <= y) === (fromCEnum x <= fromCEnum y)
declaredValues :: proxy a -> DeclaredValues a Source #
Declared values and associated names
showsUndeclared :: proxy a -> Int -> CEnumZ a -> ShowS Source #
Show undeclared value
Like any Show related function, this should generate a valid Haskell
expression. In this case, a valid Haskell expression for values outside
of the set of declared values (that is, for which isDeclared will return
False).
The default definition just shows the underlying integer value; this is
valid if the Haskell wrapper has a Num instance. If the Haskell type is
simply a newtype wrapper around the underlying C type, you can use
showsWrappedUndeclared. Finally, if the Haskell type cannot represent
undeclared values, this can be defined using error.
showsUndeclared _ = \_ x -> error $ "Unexpected value " ++ show x ++ " for type Foo"
readPrecUndeclared :: ReadPrec a Source #
Read undeclared value
See showsUndeclared, showsWrappedUndeclared, and
readPrecWrappedUndeclared.
isDeclared :: a -> Bool Source #
Determine if the specified value is declared
This has a default definition in terms of getDeclaredValues, but you may
wish to override this with a more efficient implementation (in particular,
see seqIsDeclared).
mkDeclared :: CEnumZ a -> Maybe a Source #
Construct a value only if it is declared
See also seqMkDeclared.
class CEnum a => SequentialCEnum a where Source #
C enumeration with sequential values
Bounded and Enum methods may be implemented more efficiently when the
values of an enumeration are sequential. An instance of this class is
generated automatically in this case. Users may optionally derive these
instances using AsSequentialCEnum when appropriate.
This class may also be used with Haskell sum-type representations of enumerations.
all isDeclared [minDeclaredValue..maxDeclaredValue]
Methods
minDeclaredValue :: a Source #
The minimum declared value
minDeclaredValue == minimum (filter isDeclared (map toCEnum [minBound..]))
maxDeclaredValue :: a Source #
The maximum declared value
maxDeclaredValue == maximum (filter isDeclared (map toCEnum [minBound..]))
Type used to derive classes using DerivingVia a type with a CEnum
instance
When the values are sequential, AsSequentialCEnum provides better
performance and should therefore be used instead.
The following classes may be derived:
Boundedmay be derived using the bounds of the declared values. This is not derived by default.Enummay be derived using the bounds of the declared values. This instance assumes that only the declared values are valid and throws aCEnumExceptionif passed a value that is not declared. This is not derived by default.
For declared values we have
toEnum === coerce . toCENum . fromIntegral
fromEnum === fromIntegral . fromCEnum . coerce
In addition we guarantee that where pred or succ are defined, we have
\x -> (pred x < x) && (x < succ x)
Constructors
| WrapCEnum | |
Fields
| |
Instances
| CEnum a => Bounded (AsCEnum a) Source # | |
| CEnum a => Enum (AsCEnum a) Source # | |
Defined in HsBindgen.Runtime.CEnum Methods succ :: AsCEnum a -> AsCEnum a # pred :: AsCEnum a -> AsCEnum a # fromEnum :: AsCEnum a -> Int # enumFrom :: AsCEnum a -> [AsCEnum a] # enumFromThen :: AsCEnum a -> AsCEnum a -> [AsCEnum a] # enumFromTo :: AsCEnum a -> AsCEnum a -> [AsCEnum a] # enumFromThenTo :: AsCEnum a -> AsCEnum a -> AsCEnum a -> [AsCEnum a] # | |
newtype AsSequentialCEnum a Source #
Type used to derive classes using DerivingVia a type with a
SequentialCEnum instance
The following classes may be derived:
Boundedmay be derived using the bounds of the declared values. This is not derived by default.Enummay be derived using the bounds of the declared values. This instance assumes that only the declared values are valid and throws aCEnumExceptionif passed a value that is not declared. This is not derived by default.
AsSequentialCEnum should have the same properties as AsCEnum.
Constructors
| WrapSequentialCEnum | |
Fields | |
Instances
| SequentialCEnum a => Bounded (AsSequentialCEnum a) Source # | |
Defined in HsBindgen.Runtime.CEnum | |
| SequentialCEnum a => Enum (AsSequentialCEnum a) Source # | |
Defined in HsBindgen.Runtime.CEnum Methods succ :: AsSequentialCEnum a -> AsSequentialCEnum a # pred :: AsSequentialCEnum a -> AsSequentialCEnum a # toEnum :: Int -> AsSequentialCEnum a # fromEnum :: AsSequentialCEnum a -> Int # enumFrom :: AsSequentialCEnum a -> [AsSequentialCEnum a] # enumFromThen :: AsSequentialCEnum a -> AsSequentialCEnum a -> [AsSequentialCEnum a] # enumFromTo :: AsSequentialCEnum a -> AsSequentialCEnum a -> [AsSequentialCEnum a] # enumFromThenTo :: AsSequentialCEnum a -> AsSequentialCEnum a -> AsSequentialCEnum a -> [AsSequentialCEnum a] # | |
Fields and bit-fields
class HasCField (a :: Type) (field :: Symbol) where Source #
Evidence that a C object a has a field with the name field.
Fields can be part of structs and unions. Typedefs are a degenerate use case.
Struct
If we have the C struct S:
struct S {
int x;
int y;
}And an accompanying Haskell datatype S:
data S = S { s_x :: CInt, s_y :: CInt }Then we can define two instances
HasCField S "s_x" HasCField S "s_y"
Union
If we have the C union U:
union U {
int x;
int y;
}And an accompanying Haskell datatype U:
data U = U ... {- details elided -}
... {- getters and setters elided -}Then we can define two instances
HasCField U "u_x" HasCField U "u_y"
Typedef
If we have the C typedef T:
typedef int T;
And an accompanying Haskell newtype T:
newtype T = T { unwrapT :: Int }Then we can define the instance:
HasCField T "unwrapT"
Methods
offset# :: Proxy# a -> Proxy# field -> Int Source #
The offset (in number of bytes) of the field with respect to the parent object.
Instances
class HasCBitfield (a :: Type) (field :: Symbol) where Source #
Evidence that a C object a has a bit-field with the name field.
Bit-fields can be part of structs and unions.
Struct
If we have the C struct S:
struct S {
int x : 2;
int y : 3;
}And an accompanying Haskell datatype S:
data S = S { s_x :: CInt, s_y :: CInt }Then we can define two instances
HasCBitfield S "s_x" HasCBitfield S "s_y"
Union
If we have the C union U:
union U {
int x : 2;
int y : 3;
}And an accompanying Haskell datatype U:
data U = U ... {- details elided -}
... {- getters and setters elided -}Then we can define two instances
HasCBitfield U "u_x" HasCBitfield U "u_y"
data BitfieldPtr a where Source #
A pointer to a bit-field of a C object
Bundled Patterns
| pattern BitfieldPtr :: Ptr a -> Int -> Int -> BitfieldPtr a |
Function pointers and instances
class ToFunPtr a where Source #
Type class for converting Haskell functions to C function pointers.
Methods
toFunPtr :: a -> IO (FunPtr a) Source #
Convert a Haskell function to a C function pointer.
The caller is responsible for freeing the function pointer using
freeHaskellFunPtr when it is no longer needed.
Instances
class FromFunPtr a where Source #
Type class for converting C function pointers to Haskell functions.
Instances
withFunPtr :: ToFunPtr a => a -> (FunPtr a -> IO b) -> IO b Source #
This function makes sure that freeHaskellFunPtr is called after
toFunPtr has allocated memory for a FunPtr.
Pointers
plusPtrElem :: forall a. Storable a => Ptr a -> Int -> Ptr a Source #
Advances the given address by the given offset in number of elements of
type a.
Examples:
plusPtr (_ :: Ptr Word32) 2 -- moves the pointer by 2 bytes plusPtrElem (_ :: Ptr Word32) 2 -- moves the pointer by 2*4=8 bytes
NOTE: if a is an instance of Prim, then you can
alternatively use advancePtr.
Arrays
data ConstantArray (n :: Nat) a Source #
A C array of known size
Instances
data IncompleteArray a Source #
A C array of unknown size
Instances
| HasField "toFirstElemPtr" (Ptr (IncompleteArray a)) (Ptr a) Source # |
|
Defined in HsBindgen.Runtime.IncompleteArray Methods getField :: Ptr (IncompleteArray a) -> Ptr a # | |
| (Show a, Storable a) => Show (IncompleteArray a) Source # | |
Defined in HsBindgen.Runtime.IncompleteArray Methods showsPrec :: Int -> IncompleteArray a -> ShowS # show :: IncompleteArray a -> String # showList :: [IncompleteArray a] -> ShowS # | |
| (Storable a, Eq a) => Eq (IncompleteArray a) Source # | |
Defined in HsBindgen.Runtime.IncompleteArray Methods (==) :: IncompleteArray a -> IncompleteArray a -> Bool # (/=) :: IncompleteArray a -> IncompleteArray a -> Bool # | |
Marshaling and serialization
class StaticSize a where Source #
Size and alignment for values that have a static size in memory
Types that are instances of Storable can derive this instance.
Minimal complete definition
Nothing
Methods
staticSizeOf :: Proxy a -> Int Source #
Storage requirements (bytes)
staticAlignment :: Proxy a -> Int Source #
Alignment (bytes)
Instances
class ReadRaw a where Source #
Values that can be read from memory
Types that are instances of Storable can derive this instance.
Minimal complete definition
Nothing
Methods
readRaw :: Ptr a -> IO a Source #
Read a value from the given memory location
This function might require a properly aligned address to function correctly, depending on the architecture.
Instances
class WriteRaw a where Source #
Values that can be written to memory
Types that are instances of Storable can derive this instance.
Minimal complete definition
Nothing
Methods
writeRaw :: Ptr a -> a -> IO () Source #
Write a value to the given memory location
This function might require a properly aligned address to function correctly, depending on the architecture.
Instances
newtype EquivStorable a Source #
Type used to derive a Storable instance when the type has StaticSize,
ReadRaw, and WriteRaw instances
Use the DerivingVia GHC extension as follows:
{-# LANGUAGE DerivingVia #-}
data Foo = Foo { ... }
deriving Storable via EquivStorable Foo
Constructors
| EquivStorable a |
Instances
| (ReadRaw a, StaticSize a, WriteRaw a) => Storable (EquivStorable a) Source # | |
Defined in HsBindgen.Runtime.Marshal Methods sizeOf :: EquivStorable a -> Int # alignment :: EquivStorable a -> Int # peekElemOff :: Ptr (EquivStorable a) -> Int -> IO (EquivStorable a) # pokeElemOff :: Ptr (EquivStorable a) -> Int -> EquivStorable a -> IO () # peekByteOff :: Ptr b -> Int -> IO (EquivStorable a) # pokeByteOff :: Ptr b -> Int -> EquivStorable a -> IO () # peek :: Ptr (EquivStorable a) -> IO (EquivStorable a) # poke :: Ptr (EquivStorable a) -> EquivStorable a -> IO () # | |
Block
See https://clang.llvm.org/docs/BlockLanguageSpec.html
The type index is the type of the bloc, for example:
typedef int(^VarCounter)(int increment);
corresponds to
newtype VarCounter = VarCounter (Block (CInt -> IO CInt))
Read-only pointers
type PtrConst a = ConstPtr a Source #
A read-only pointer.
A PtrConst aa with a C const qualifier. For
instance, the Haskell type PtrConst CInt is equivalent to the C type const
int*. const-qualified contents of a pointer should not be modified, but
reading the contents is okay.