Foreign.Hoppy.Generator.Spec

The primary data types for specifying C++ interfaces.

Show instances in this module produce strings of the form "<TypeOfObject nameOfObject otherInfo...>". They can be used in error messages without specifying a noun separately, i.e. write show cls instead of "the class " ++ show cls.

Interfaces

data Interface

A complete specification of a C++ API. Generators for different languages, including the binding generator for C++, use these to produce their output.

Instances

Show Interface

type ErrorMsg = String

Indicates strings that are error messages.

interface

Arguments

:: String

interfaceName

-> [Module]

interfaceModules

-> Either ErrorMsg Interface

Constructs an Interface from the required parts. Some validation is performed; if the resulting interface would be invalid, an error message is returned instead.

interfaceName :: Interface -> String

The textual name of the interface.

interfaceModules :: Interface -> Map String Module

All of the individual modules, by moduleName.

interfaceNamesToModules :: Interface -> Map ExtName Module

Maps each ExtName exported by some module to the module that exports the name.

interfaceHaskellModuleBase :: Interface -> [String]

The name of the parent Haskell module under which a Haskell module will be generated for a Hoppy Module. This is a list of Haskell module path components, in other words, intercalate "." on the list produces a Haskell module name. Defaults to interfaceDefaultHaskellModuleBase, and may be overridden with interfaceAddHaskellModuleBase.

interfaceDefaultHaskellModuleBase :: [String]

The default Haskell module under which Hoppy modules will be generated. This is Foreign.Hoppy.Generated, that is:

["Foreign", "Hoppy", "Generated"]

interfaceAddHaskellModuleBase :: [String] -> Interface -> Either String Interface

Sets an interface to generate all of its modules under the given Haskell module prefix. See interfaceHaskellModuleBase.

C++ includes

data Include

An #include directive in a C++ file.

Instances

Eq Include

Ord Include

Show Include

includeStd :: String -> Include

Creates an #include <...> directive.

includeLocal :: String -> Include

Creates an #include "..." directive.

includeToString :: Include -> String

Returns the complete #include ... line for an include, including trailing newline.

Modules

data Module

A portion of functionality in a C++ API. An Interface is composed of multiple modules. A module will generate a single compilation unit containing bindings for all of the module's exports. The C++ code for a generated module will #include everything necessary for what is written to the header and source files separately. You can declare include dependencies with e.g. addReqIncludes, either for individual exports or at the module level. Dependencies between modules are handled automatically, and circularity is supported to a certain extent. See the documentation for the individual language modules for further details.

Instances

Eq Module

Ord Module

Show Module

HasReqs Module

moduleName :: Module -> String

The module's name. A module name must identify a unique module within an Interface.

moduleHppPath :: Module -> String

A relative path under a C++ sources root to which the generator will write a header file for the module's C++ bindings.

moduleCppPath :: Module -> String

A relative path under a C++ sources root to which the generator will write a source file for the module's C++ bindings.

moduleExports :: Module -> Map ExtName Export

All of the exports in a module.

moduleReqs :: Module -> Reqs

Module-level requirements.

moduleHaskellName :: Module -> Maybe [String]

The generated Haskell module name, underneath the interfaceHaskellModuleBase. If absent (by default), the moduleName is used. May be modified with moduleAddHaskellName.

makeModule

Arguments

:: String

moduleName

-> String

moduleHppPath

-> String

moduleCppPath

-> Module

Creates an empty module, ready to be configured with moduleModify.

moduleModify :: Module -> StateT Module (Either String) () -> Either ErrorMsg Module

Extends a module. To be used with the module state-monad actions in this package.

moduleModify' :: Module -> StateT Module (Either String) () -> Module

Same as moduleModify, but calls error in the case of failure, which is okay in for a generator which would abort in this case anyway.

moduleSetHppPath :: MonadState Module m => String -> m ()

Replaces a module's moduleHppPath.

moduleSetCppPath :: MonadState Module m => String -> m ()

Replaces a module's moduleCppPath.

moduleAddExports :: (MonadError String m, MonadState Module m) => [Export] -> m ()

Adds exports to a module. An export must only be added to any module at most once, and must not be added to multiple modules.

moduleAddHaskellName :: (MonadError String m, MonadState Module m) => [String] -> m ()

Changes a module's moduleHaskellName from the default. This can only be called once on a module.

Requirements

data Reqs

A set of requirements of needed to use an identifier in C++ (function, type, etc.), via a set of Includes. The monoid instance has mempty as an empty set of includes, and mappend unions two include sets.

Instances

Show Reqs

Monoid Reqs

reqsIncludes :: Reqs -> Set Include

The includes specified by a Reqs.

reqInclude :: Include -> Reqs

Creates a Reqs that contains the given include.

class HasReqs a where

C++ types that have requirements in order to use them in generated bindings.

Minimal complete definition

getReqs, (setReqs | modifyReqs)

Methods

getReqs :: a -> Reqs

Returns an object's requirements.

setReqs :: Reqs -> a -> a

Replaces an object's requirements with new ones.

modifyReqs :: (Reqs -> Reqs) -> a -> a

Modifies an object's requirements.

Instances

HasReqs Callback

HasReqs Class

HasReqs Function

HasReqs Bitspace

HasReqs CppEnum

HasReqs Variable

HasReqs Module

addReqs :: HasReqs a => Reqs -> a -> a

Adds to a object's requirements.

addReqIncludes :: HasReqs a => [Include] -> a -> a

Adds a list of includes to the requirements of an object.

Names and exports

data ExtName

An external name is a string that generated bindings use to uniquely identify an object at runtime. An external name must start with an alphabetic character, and may only contain alphanumeric characters and '_'. You are free to use whatever naming style you like; case conversions will be performed automatically when required. Hoppy does make use of some conventions though, for example with Operators and in the provided bindings for the C++ standard library.

External names must be unique within an interface. They may not be reused between modules. This assumption is used for symbol naming in compiled shared objects and to freely import modules in Haskell bindings.

Instances

Eq ExtName

Ord ExtName

Show ExtName

toExtName :: String -> ExtName

Creates an ExtName that contains the given string, erroring if the string is an invalid ExtName.

fromExtName :: ExtName -> String

Returns the string an an ExtName contains.

data FnName name

The C++ name of a function or method.

Constructors

FnName name

A regular, "alphanumeric" name. The exact type depends on what kind of object is being named.

FnOp Operator

An operator name.

Instances

IsFnName t (FnName t)

Eq name => Eq (FnName name)

Ord name => Ord (FnName name)

Show name => Show (FnName name)

class IsFnName t a where

Enables implementing automatic conversions to a FnName t.

Methods

toFnName :: a -> FnName t

Instances

IsFnName t Operator

IsFnName t t

IsFnName t (FnName t)

data Operator

Overloadable C++ operators.

Constructors

OpCall

x(...)

OpComma

x, y

OpAssign

x = y

OpArray

x[y]

OpDeref

*x

OpAddress

&x

OpAdd

x + y

OpAddAssign

x += y

OpSubtract

x - y

OpSubtractAssign

x -= y

OpMultiply

x * y

OpMultiplyAssign

x *= y

OpDivide

x / y

OpDivideAssign

x /= y

OpModulo

x % y

OpModuloAssign

x %= y

OpPlus

+x

OpMinus

-x

OpIncPre

++x

OpIncPost

x++

OpDecPre

--x

OpDecPost

x--

OpEq

x == y

OpNe

x != y

OpLt

x < y

OpLe

x <= y

OpGt

x > y

OpGe

x >= y

OpNot

!x

OpAnd

x && y

OpOr

x || y

OpBitNot

~x

OpBitAnd

x & y

OpBitAndAssign

x &= y

OpBitOr

x | y

OpBitOrAssign

x |= y

OpBitXor

x ^ y

OpBitXorAssign

x ^= y

OpShl

x << y

OpShlAssign

x <<= y

OpShr

x >> y

OpShrAssign

x >>= y

Instances

Bounded Operator

Enum Operator

Eq Operator

Ord Operator

Show Operator

IsFnName t Operator

data OperatorType

The arity and syntax of an operator.

Constructors

UnaryPrefixOperator String

Prefix unary operators. Examples: !x, *x, ++x.

UnaryPostfixOperator String

Postfix unary operators. Examples: x--, x++.

BinaryOperator String

Infix binary operators. Examples: x * y, x >>= y.

CallOperator

x(...) with arbitrary arity.

ArrayOperator

x[y], a binary operator with non-infix syntax.

operatorPreferredExtName :: Operator -> ExtName

Returns a conventional string to use for the ExtName of an operator.

operatorPreferredExtName' :: Operator -> String

Returns a conventional name for an operator, as with operatorPreferredExtName, but as a string.

operatorType :: Operator -> OperatorType

Returns the type of an operator.

data Export

Specifies some C++ object (function or class) to give access to.

Constructors

ExportVariable Variable

Exports a variable.

ExportEnum CppEnum

Exports an enum.

ExportBitspace Bitspace

Exports a bitspace.

ExportFn Function

Exports a function.

ExportClass Class

Exports a class with all of its contents.

ExportCallback Callback

Exports a callback.

Instances

Show Export

exportExtName :: Export -> ExtName

Returns the external name of an export.

exportAddendum :: Export -> Addendum

Returns the export's addendum. Export doesn't have a HasAddendum instance because you normally wouldn't want to modify the addendum of one.

data Identifier

A path to some C++ object, including namespaces. An identifier consists of multiple parts separated by "::". Each part has a name string followed by an optional template argument list, where each argument gets rendered from a Type (non-type arguments for template metaprogramming are not supported).

Instances

Eq Identifier

Show Identifier

identifierParts :: Identifier -> [IdPart]

The separate parts of the identifier, between ::s.

data IdPart

A single component of an Identifier, between ::s.

Instances

Eq IdPart

Show IdPart

idPartBase :: IdPart -> String

The name within the enclosing scope.

idPartArgs :: IdPart -> Maybe [Type]

Template arguments, if present.

ident :: String -> Identifier

Creates an identifier of the form a.

ident' :: [String] -> Identifier

Creates an identifier of the form a1::a2::...::aN.

ident1 :: String -> String -> Identifier

Creates an identifier of the form a::b.

ident2 :: String -> String -> String -> Identifier

Creates an identifier of the form a::b::c.

ident3 :: String -> String -> String -> String -> Identifier

Creates an identifier of the form a::b::c::d.

ident4 :: String -> String -> String -> String -> String -> Identifier

Creates an identifier of the form a::b::c::d::e.

ident5 :: String -> String -> String -> String -> String -> String -> Identifier

Creates an identifier of the form a::b::c::d::e::f.

identT :: String -> [Type] -> Identifier

Creates an identifier of the form a<...>.

identT' :: [(String, Maybe [Type])] -> Identifier

Creates an identifier with arbitrary many templated and non-templated parts.

ident1T :: String -> String -> [Type] -> Identifier

Creates an identifier of the form a::b<...>.

ident2T :: String -> String -> String -> [Type] -> Identifier

Creates an identifier of the form a::b::c<...>.

ident3T :: String -> String -> String -> String -> [Type] -> Identifier

Creates an identifier of the form a::b::c::d<...>.

ident4T :: String -> String -> String -> String -> String -> [Type] -> Identifier

Creates an identifier of the form a::b::c::d::e<...>.

ident5T :: String -> String -> String -> String -> String -> String -> [Type] -> Identifier

Creates an identifier of the form a::b::c::d::e::f<...>.

Basic types

data Type

Concrete C++ types. It is possible to represent invalid C++ types with this, but we try to catch these and fail cleanly as much as possible.

Constructors

TVoid

C++ void, Haskell ().

TBool

C++ bool, Haskell Bool.

TChar

C++ char, Haskell CChar.

TUChar

C++ unsigned char, Haskell CUChar.

TShort

C++ short int, Haskell CShort.

TUShort

C++ unsigned short int, Haskell CUShort.

TInt

C++ int, Haskell CInt.

TUInt

C++ unsigned int, Haskell CUInt.

TLong

C++ long int, Haskell CLong.

TULong

C++ unsigned long int, Haskell CULong.

TLLong

C++ long long int, Haskell CLLong.

TULLong

C++ unsigned long long int, Haskell CULLong.

TFloat

C++ float, Haskell CFloat.

TDouble

C++ double, Haskell CDouble.

TInt8

C++ int8_t, Haskell Int8.

TInt16

C++ int16_t, Haskell Int16.

TInt32

C++ int32_t, Haskell Int32.

TInt64

C++ int64_t, Haskell Int64.

TWord8

C++ uint8_t, Haskell Word8.

TWord16

C++ uint16_t, Haskell Word16.

TWord32

C++ uint32_t, Haskell Word32.

TWord64

C++ uint64_t, Haskell Word64.

TPtrdiff

C++ ptrdiff_t, Haskell CPtrdiff.

TSize

C++ size_t, Haskell CSize.

TSSize

C++ ssize_t, Haskell CSsize.

TEnum CppEnum

A C++ enum value.

TBitspace Bitspace

A C++ bitspace value.

TPtr Type

A poiner to another type.

TRef Type

A reference to another type.

TFn [Type] Type

A function taking parameters and returning a value (or TVoid). Function pointers must wrap a TFn in a TPtr.

TCallback Callback

A handle for calling foreign code from C++.

TObj Class

An instance of a class.

TObjToHeap Class

A special case of TObj that is only allowed when passing values from C++ to a foreign language. Rather than looking at the object's ClassConversion, the object will be copied to the heap, and a pointer to the new object will be passed. The object must be copy-constructable.

The foreign language owns the pointer, even for callback arguments.

TConst Type

A const version of another type.

Instances

Eq Type

Show Type

normalizeType :: Type -> Type

Canonicalizes a Type without changing its meaning. Multiple nested TConsts are collapsed into a single one.

stripConst :: Type -> Type

Strips leading TConsts off of a type.

Variables

data Variable

A C++ variable.

Instances

Eq Variable

Show Variable

HasAddendum Variable

HasReqs Variable

makeVariable :: Identifier -> Maybe ExtName -> Type -> Variable

Creates a binding for a C++ variable.

varIdentifier :: Variable -> Identifier

The identifier used to refer to the variable.

varExtName :: Variable -> ExtName

The variable's external name.

varType :: Variable -> Type

The type of the variable. This may be TConst to indicate that the variable is read-only.

varReqs :: Variable -> Reqs

Requirements for bindings to use this variable.

varIsConst :: Variable -> Bool

Returns whether the variable is constant, i.e. whether its type is TConst ....

varGetterExtName :: Variable -> ExtName

Returns the external name of the getter function for the variable.

varSetterExtName :: Variable -> ExtName

Returns the external name of the setter function for the variable.

Enums

data CppEnum

A C++ enum declaration. An enum should actually be enumerable (in the sense of Haskell's Enum); if it's not, consider using a Bitspace instead.

Instances

Eq CppEnum

Show CppEnum

HasAddendum CppEnum

HasReqs CppEnum

makeEnum

Arguments

:: Identifier

enumIdentifier

-> Maybe ExtName

An optional external name; will be automatically derived from the identifier if absent.

-> [(Int, [String])]

enumValueNames

-> CppEnum

Creates a binding for a C++ enum.

enumIdentifier :: CppEnum -> Identifier

The identifier used to refer to the enum.

enumExtName :: CppEnum -> ExtName

The enum's external name.

enumValueNames :: CppEnum -> [(Int, [String])]

The numeric values and names of the enum values. A single value's name is broken up into words. How the words and ext name get combined to make a name in a particular foreign language depends on the language.

enumReqs :: CppEnum -> Reqs

Requirements for a Type to reference this enum.

Bitspaces

data Bitspace

A C++ numeric space with bitwise operations. This is similar to a CppEnum, but in addition to the extra operations, this differs in that these values aren't enumerable.

Additionally, as a kludge for Qtah, a bitspace may have a C++ type (bitspaceCppTypeIdentifier) separate from its numeric type (bitspaceType). Qt bitspaces aren't raw numbers but are instead type-safe QFlags objects that don't implicitly convert from integers, so we need a means to do so manually. Barring general ad-hoc argument and return value conversion support, we allow this as follows: when given a C++ type, then a bitspace may also have a conversion function between the numeric and C++ type, in each direction. If a conversion function is present, it will be used for conversions in its respective direction. The C++ type is not a full Type, but only an Identifier, since additional information is not needed. See bitspaceAddCppType.

Instances

Eq Bitspace

Show Bitspace

HasAddendum Bitspace

HasReqs Bitspace

makeBitspace

Arguments

:: ExtName

bitspaceExtName

-> Type

bitspaceType

-> [(Int, [String])]

bitspaceValueNames

-> Bitspace

Creates a binding for a C++ bitspace.

bitspaceExtName :: Bitspace -> ExtName

The bitspace's external name.

bitspaceType :: Bitspace -> Type

The C++ type used for bits values. This should be a primitive numeric type.

bitspaceValueNames :: Bitspace -> [(Int, [String])]

The numeric values and names of the bitspace values. See enumValueNames.

bitspaceEnum :: Bitspace -> Maybe CppEnum

An associated enum, whose values may be converted to values in the bitspace.

bitspaceAddEnum :: CppEnum -> Bitspace -> Bitspace

Associates an enum with the bitspace. See bitspaceEnum.

bitspaceCppTypeIdentifier :: Bitspace -> Maybe Identifier

The optional C++ type for a bitspace.

bitspaceFromCppValueFn :: Bitspace -> Maybe String

The name of a C++ function to convert from the bitspace's C++ type to bitspaceType.

bitspaceToCppValueFn :: Bitspace -> Maybe String

The name of a C++ function to convert from bitspaceType to the bitspace's C++ type.

bitspaceAddCppType :: Identifier -> Maybe String -> Maybe String -> Bitspace -> Bitspace

bitspaceAddCppType cppTypeIdentifier toCppValueFn fromCppValueFn associates a C++ type (plus optional conversion functions) with a bitspace. At least one conversion should be specified, otherwise adding the C++ type will mean nothing. You should also add use requirements to the bitspace for all of these arguments; see HasReqs.

bitspaceReqs :: Bitspace -> Reqs

Requirements for emitting the bindings for a bitspace, i.e. what's necessary to reference bitspaceCppTypeIdentifier, bitspaceFromCppValueFn, and bitspaceToCppValueFn. bitspaceType can take some numeric types that require includes as well, but you don't need to list these here.

Functions

data Purity

Whether or not a function may cause side-effects.

Haskell bindings for pure functions will not be in IO, and calls to pure functions will be executed non-strictly. Calls to impure functions will execute in the IO monad.

Member functions for mutable classes should not be made pure, because it is difficult in general to control when the call will be made.

Constructors

Nonpure

Side-affects are possible.

Pure

Side-affects will not happen.

Instances

Eq Purity

Show Purity

data Function

A C++ function declaration.

Instances

Show Function

HasAddendum Function

HasReqs Function

makeFn

Arguments

:: IsFnName Identifier name

=> name

-> Maybe ExtName

An optional external name; will be automatically derived from the identifier if absent.

-> Purity

-> [Type]

Parameter types.

-> Type

Return type.

-> Function

Creates a binding for a C++ function.

fnCName :: Function -> FnName Identifier

The identifier used to call the function.

fnExtName :: Function -> ExtName

The function's external name.

fnPurity :: Function -> Purity

Whether the function is pure.

fnParams :: Function -> [Type]

The function's parameter types.

fnReturn :: Function -> Type

The function's return type.

fnReqs :: Function -> Reqs

Requirements for a binding to call the function.

Classes

data Class

A C++ class declaration. A class's external name is automatically combined with the external names of things inside the class, by way of HasClassyExtName.

Instances

Eq Class

Show Class

HasAddendum Class

HasReqs Class

makeClass

Arguments

:: Identifier

-> Maybe ExtName

An optional external name; will be automatically derived from the identifier if absent.

-> [Class]

Superclasses.

-> [Ctor]

-> [Method]

-> Class

Creates a binding for a C++ class and its contents.

classIdentifier :: Class -> Identifier

The identifier used to refer to the class.

classExtName :: Class -> ExtName

The class's external name.

classSuperclasses :: Class -> [Class]

The class's public superclasses.

classCtors :: Class -> [Ctor]

The class's constructors.

classDtorIsPublic :: Class -> Bool

Whether the class's destructor has public visibility.

classMethods :: Class -> [Method]

The class's methods.

classConversion :: Class -> ClassConversion

Behaviour for converting objects to and from foriegn values.

classReqs :: Class -> Reqs

Requirements for a Type to reference this class.

classAddCtors :: [Ctor] -> Class -> Class

Adds constructors to a class.

classSetDtorPrivate :: Class -> Class

Marks a class's destructor as private, so that a binding for it won't be generated.

classAddMethods :: [Method] -> Class -> Class

Adds methods to a class.

classIsMonomorphicSuperclass :: Class -> Bool

This is true for classes passed through classSetMonomorphicSuperclass.

classSetMonomorphicSuperclass :: Class -> Class

Explicitly marks a class as being monomorphic (i.e. not having any virtual methods or destructors). By default, Hoppy assumes that a class that is derived is also polymorphic, but it can happen that this is not the case. Downcasting with dynamic_cast from such classes is not available. See also classSetSubclassOfMonomorphic.

classIsSubclassOfMonomorphic :: Class -> Bool

This is true for classes passed through classSetSubclassOfMonomorphic.

classSetSubclassOfMonomorphic :: Class -> Class

Marks a class as being derived from some monomorphic superclass. This prevents any downcasting to this class. Generally it is better to use classSetMonomorphicSuperclass on the specific superclasses that are monomorphic, but in cases where this is not possible, this function can be applied to the subclass instead.

class HasClassyExtName a where

Things that live inside of a class, and have the class's external name prepended to their own in generated code. With an external name of "bar" and a class with external name "foo", the resulting name will be "foo_bar".

Minimal complete definition

getClassyExtNameSuffix

Methods

getClassyExtNameSuffix :: a -> ExtName

Extracts the external name of the object, without the class name added.

getClassyExtName :: Class -> a -> ExtName

Computes the external name to use in generated code, containing both the class's and object's external names.

See also toHsMethodName.

Instances

HasClassyExtName Method

HasClassyExtName Ctor

data Ctor

A C++ class constructor declaration.

Instances

Show Ctor

HasClassyExtName Ctor

makeCtor

Arguments

:: ExtName

-> [Type]

Parameter types.

-> Ctor

Creates a Ctor with full generality.

mkCtor

Arguments

:: String

-> [Type]

Parameter types.

-> Ctor

mkCtor name creates a Ctor whose external name is className_name.

ctorExtName :: Ctor -> ExtName

The constructor's external name.

ctorParams :: Ctor -> [Type]

The constructor's parameter types.

data Method

A C++ class method declaration.

Any operator function that can be written as a method may have its binding be written either as part of the associated class or as a separate entity, independently of how the function is declared in C++.

Instances

Show Method

HasClassyExtName Method

data MethodImpl

The C++ code to which a Method is bound.

Constructors

RealMethod (FnName String)

The Method is bound to an actual class method.

FnMethod (FnName Identifier)

The Method is bound to a wrapper function. When wrapping a method with another function, this is preferrable to just using a Function binding because a method will still appear to be part of the class in foreign bindings.

Instances

Eq MethodImpl

Show MethodImpl

data MethodApplicability

How a method is associated to its class. A method may be static, const, or neither (a regular method).

Constructors

MNormal

MStatic

MConst

Instances

Bounded MethodApplicability

Enum MethodApplicability

Eq MethodApplicability

Show MethodApplicability

data Constness

Whether or not a method is const.

Constructors

Nonconst

Const

Instances

Bounded Constness

Enum Constness

Eq Constness

Show Constness

constNegate :: Constness -> Constness

Returns the opposite constness value.

data Staticness

Whether or not a method is static.

Constructors

Nonstatic

Static

Instances

Bounded Staticness

Enum Staticness

Eq Staticness

Show Staticness

makeMethod

Arguments

:: IsFnName String name

=> name

The C++ name of the method.

-> ExtName

The external name of the method.

-> MethodApplicability

-> Purity

-> [Type]

Parameter types.

-> Type

Return type.

-> Method

Creates a Method with full generality and manual name specification.

makeFnMethod :: IsFnName Identifier name => name -> String -> MethodApplicability -> Purity -> [Type] -> Type -> Method

Creates a Method that is in fact backed by a C++ non-member function (a la makeFn), but appears to be a regular method. This is useful for wrapping a method on the C++ side when its arguments aren't right for binding directly.

A this pointer parameter is not automatically added to the parameter list for non-static methods created with makeFnMethod.

mkMethod

Arguments

:: IsFnName String name

=> name

The C++ name of the method.

-> [Type]

Parameter types.

-> Type

Return type.

-> Method

Creates a nonconst, nonstatic Method for class::methodName and whose external name is class_methodName. If the name is an operator, then the operatorPreferredExtName will be used in the external name.

For creating multiple bindings to a method, see mkMethod'.

mkMethod'

Arguments

:: IsFnName String name

=> name

The C++ name of the method.

-> String

A foreign name for the method.

-> [Type]

Parameter types.

-> Type

Return type.

-> Method

Creates a nonconst, nonstatic Method for method class::methodName and whose external name is class_methodName. This enables multiple Methods with different foreign names (and hence different external names) to bind to the same method, e.g. to make use of optional arguments or overloading. See mkMethod for a simpler form.

mkConstMethod :: IsFnName String name => name -> [Type] -> Type -> Method

Same as mkMethod, but returns an MConst method.

mkConstMethod' :: IsFnName String name => name -> String -> [Type] -> Type -> Method

Same as mkMethod', but returns an MConst method.

mkStaticMethod :: IsFnName String name => name -> [Type] -> Type -> Method

Same as mkMethod, but returns an MStatic method.

mkStaticMethod' :: IsFnName String name => name -> String -> [Type] -> Type -> Method

Same as mkMethod', but returns an MStatic method.

mkProps :: [[Method]] -> [Method]

Used in conjunction with mkProp and friends, this creates a list of Methods for binding to getter/setter method pairs. This can be used as follows:

myClass =
  makeClass ... $
  [ methods... ] ++
  mkProps
  [ mkBoolIsProp myClass "adjustable"
  , mkProp myClass "maxWidth" TInt
  ]

mkProp :: String -> Type -> [Method]

Creates a getter/setter binding pair for methods:

T getFoo() const
void setFoo(T)

mkStaticProp :: String -> Type -> [Method]

Creates a getter/setter binding pair for static methods:

static T getFoo() const
static void setFoo(T)

mkBoolIsProp :: String -> [Method]

Creates a getter/setter binding pair for boolean methods, where the getter is prefixed with is:

bool isFoo() const
void setFoo(bool)

mkBoolHasProp :: String -> [Method]

Creates a getter/setter binding pair for boolean methods, where the getter is prefixed with has:

bool hasFoo() const
void setFoo(bool)

methodImpl :: Method -> MethodImpl

The underlying code that the binding calls.

methodExtName :: Method -> ExtName

The method's external name.

methodApplicability :: Method -> MethodApplicability

How the method is associated to its class.

methodPurity :: Method -> Purity

Whether the method is pure.

methodParams :: Method -> [Type]

The method's parameter types.

methodReturn :: Method -> Type

The method's return type.

methodConst :: Method -> Constness

Returns the constness of a method, based on its methodApplicability.

methodStatic :: Method -> Staticness

Returns the staticness of a method, based on its methodApplicability.

Conversion to and from foreign values

data ClassConversion

When a class object is returned from a function or taken as a parameter by value (i.e. with TObj), it will be converted to or from a foreign (non-C++) object. Conversion may also be performed explicitly. This data type describes how to perform those conversions. A class may or may not support conversion, for any particular foreign language; what is said below only applies to classes that are convertible for a language.

When converting between a C++ value and a foreign value, a pointer to the object is passed between C++ and the foreign language. Then, for each foreign language, a binding author can provide pieces of code in that language to translate between the pointer and a foreign value (usually by invoking the FFI functions generated by Hoppy), and generated bindings will perform these conversions automatically. The code supplied to convert in each direction should leave the original object unchanged (and alive, in case of manual memory management). (Internally, during a function call in either direction, the side that creates a value is in charge of its lifetime, but this is managed by Hoppy.)

In foreign code, foreign values can be explicitly converted to new C++ (heap) objects, and C++ object pointers can be explicitly converted to foreign values, via special functions generated for the class.

Constructors

ClassConversion

Fields

classHaskellConversion :: Maybe ClassHaskellConversion

Conversions to and from Haskell.

classConversionNone :: ClassConversion

Encoding parameters for a class that is not encodable or decodable.

classModifyConversion :: (ClassConversion -> ClassConversion) -> Class -> Class

Modifies classes' ClassEncoding structures with a given function.

data ClassHaskellConversion

Controls how conversions between C++ objects and Haskell values happen in Haskell bindings.

Constructors

ClassHaskellConversion

Fields

classHaskellConversionType :: Generator HsType

Produces the Haskell type that represents a value of the corresponding C++ class. This generator may add imports, but must not output code or add exports.

classHaskellConversionToCppFn :: Generator ()

Produces a Haskell expression that evaluates to a function that takes an object of the type that classHaskellConversionType generates, and returns a pointer to a new non-const C++ class object in IO. The generator must output code and may add imports, but must not add exports.

classHaskellConversionFromCppFn :: Generator ()

Produces a Haskell expression that evaluates to a function that takes a pointer to a const C++ class object, and returns an object of the type that classHaskellConversionType generates, in IO. The generator must output code and may add imports, but must not add exports.

Callbacks

data Callback

A non-C++ function that can be invoked via a C++ functor.

Instances

Eq Callback

Show Callback

HasAddendum Callback

HasReqs Callback

makeCallback

Arguments

:: ExtName

-> [Type]

Parameter types.

-> Type

Return type.

-> Callback

Creates a binding for constructing callbacks into foreign code.

callbackExtName :: Callback -> ExtName

The callback's external name.

callbackParams :: Callback -> [Type]

The callback's parameter types.

callbackReturn :: Callback -> Type

The callback's return type.

callbackReqs :: Callback -> Reqs

Requirements for the callback.

callbackToTFn :: Callback -> Type

Creates a TFn from a callback's parameter and return types.

Addenda

data Addendum

A literal piece of code that will be inserted into a generated source file after the regular binding glue. The Monoid instance concatenates code (actions).

Constructors

Addendum

Fields

addendumHaskell :: Generator ()

Code to be output into the Haskell binding. May also add imports and exports.

Instances

Monoid Addendum

class HasAddendum a

A typeclass for types that have an addendum.

Minimal complete definition

getAddendum, (setAddendum | modifyAddendum)

Instances

HasAddendum Callback

HasAddendum Class

HasAddendum Function

HasAddendum Bitspace

HasAddendum CppEnum

HasAddendum Variable

addAddendumHaskell :: HasAddendum a => Generator () -> a -> a

Adds a Haskell addendum to an object.

Haskell imports

type HsModuleName = String

A Haskell module name.

data HsImportSet

A collection of imports for a Haskell module. This is a monoid: import Statements are merged to give the union of imported bindings.

This structure supports two specific types of imports: - import Foo (...) - import qualified Foo as Bar Imports with as but without qualified, and qualified imports with a spec list, are not supported. This satisfies the needs of the code generator, and keeps the merging logic simple.

Instances

Show HsImportSet

Monoid HsImportSet

data HsImportKey

References an occurrence of an import statement, under which bindings can be imported. Only imported specs under equal HsImportKeys may be merged.

Constructors

HsImportKey

Fields

hsImportModule :: HsModuleName

hsImportQualifiedName :: Maybe HsModuleName

Instances

Eq HsImportKey

Ord HsImportKey

Show HsImportKey

data HsImportSpecs

A specification of bindings to import from a module. If Nothing, then the entire module is imported. If Just empty, then only instances are imported.

Constructors

HsImportSpecs

Fields

getHsImportSpecs :: Maybe (Map HsImportName HsImportVal)

hsImportSource :: Bool

Instances

Show HsImportSpecs

type HsImportName = String

An identifier that can be imported from a module. Symbols may be used here when surrounded by parentheses. Examples are "fmap" and "(++)".

data HsImportVal

Specifies how a name is imported.

Constructors

HsImportVal

The name is imported, and nothing underneath it is.

HsImportValSome [HsImportName]

The name is imported, as are specific names underneath it. This is a X (a, b, c) import.

HsImportValAll

The name is imported, along with all names underneath it. This is a X (..) import.

Instances

Show HsImportVal

hsWholeModuleImport :: HsModuleName -> HsImportSet

An import for the entire contents of a Haskell module.

hsQualifiedImport :: HsModuleName -> HsModuleName -> HsImportSet

A qualified import of a Haskell module.

hsImport1 :: HsModuleName -> HsImportName -> HsImportSet

An import of a single name from a Haskell module.

hsImport1' :: HsModuleName -> HsImportName -> HsImportVal -> HsImportSet

A detailed import of a single name from a Haskell module.

hsImports :: HsModuleName -> [HsImportName] -> HsImportSet

An import of multiple names from a Haskell module.

hsImports' :: HsModuleName -> [(HsImportName, HsImportVal)] -> HsImportSet

A detailed import of multiple names from a Haskell module.

hsImportSetMakeSource :: HsImportSet -> HsImportSet

Sets all of the import specifications in an import set to be {--} imports.

Internal to Hoppy

stringOrIdentifier :: Identifier -> Maybe String -> String

Like extNameOrIdentifier, but works with strings rather than ExtNames.

Haskell imports

makeHsImportSet :: Map HsImportKey HsImportSpecs -> HsImportSet

Constructor for an import set.

getHsImportSet :: HsImportSet -> Map HsImportKey HsImportSpecs

Returns the import set's internal map from module names to imported bindings.

hsImportForBits :: HsImportSet

Imports Data.Bits qualified as HoppyDB.

hsImportForInt :: HsImportSet

Imports Data.Int qualified as HoppyDI.

hsImportForWord :: HsImportSet

Imports Data.Word qualified as HoppyDW.

hsImportForForeign :: HsImportSet

Imports Foreign qualified as HoppyF.

hsImportForForeignC :: HsImportSet

Imports Foreign.C qualified as HoppyFC.

hsImportForPrelude :: HsImportSet

Imports Prelude qualified as HoppyP.

hsImportForRuntime :: HsImportSet

Imports Foreign.Hoppy.Runtime qualified as HoppyFHR.

hsImportForSystemPosixTypes :: HsImportSet

Imports System.Posix.Types qualified as HoppySPT.

hsImportForUnsafeIO :: HsImportSet

Imports System.IO.Unsafe qualified as HoppySIU.

Error messages

tObjToHeapWrongDirectionErrorMsg :: Maybe String -> Class -> String

Returns an error message indicating that TObjToHeap is used where data is going from a foreign langauge into C++.