hoppy-generator-0.4.0: C++ FFI generator - Code generator

Safe HaskellNone
LanguageHaskell2010

Foreign.Hoppy.Generator.Spec

Contents

Description

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.

Synopsis

Interfaces

data Interface Source #

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

Interface does not have a HandlesExceptions instance because modifyExceptionHandlers does not work for it (handled exceptions cannot be modified after an Interface is constructed).

type ErrorMsg = String Source #

Indicates strings that are error messages.

data InterfaceOptions Source #

Optional parameters when constructing an Interface with interface.

defaultInterfaceOptions :: InterfaceOptions Source #

Options used by interface. This contains no exception handlers.

interface Source #

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

This function passes defaultInterfaceOptions to interface'.

interface' Source #

Same as interface, but accepts some optional arguments.

interfaceName :: Interface -> String Source #

The textual name of the interface.

interfaceModules :: Interface -> Map String Module Source #

All of the individual modules, by moduleName.

interfaceNamesToModules :: Interface -> Map ExtName Module Source #

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

interfaceHaskellModuleBase :: Interface -> [String] Source #

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] Source #

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 Source #

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

interfaceHaskellModuleImportNames :: Interface -> Map Module String Source #

Short qualified module import names that generated modules use to refer to each other tersely.

interfaceExceptionHandlers :: Interface -> ExceptionHandlers Source #

Exceptions that all functions in the interface may throw.

interfaceCallbacksThrow :: Interface -> Bool Source #

Whether callbacks within the interface support throwing C++ exceptions from Haskell into C++ during their execution. This may be overridden by moduleCallbacksThrow and callbackThrows.

interfaceSetCallbacksThrow :: Bool -> Interface -> Interface Source #

Changes callbackThrows for all callbacks in an interface that don't have it set explicitly at the module or callback level.

interfaceExceptionClassId :: Interface -> Class -> Maybe ExceptionId Source #

Returns the the exception ID for a class in an interface, if it has one (i.e. if it's been marked as an exception class with classMakeException).

interfaceExceptionSupportModule :: Interface -> Maybe Module Source #

When an interface uses C++ exceptions, then one module needs to manually be selected to contain some interface-specific runtime support. This is the selected module.

interfaceSetExceptionSupportModule :: Module -> Interface -> Interface Source #

Sets an interface's exception support module, for interfaces that use exceptions.

interfaceSetSharedPtr :: String -> Reqs -> Interface -> Interface Source #

Installs a custom std::shared_ptr implementation for use by an interface. Hoppy uses shared pointers for generated callback code. This function is useful for building code with compilers that don't provide a conforming std::shared_ptr implementation.

interfaceSetSharedPtr ident reqs iface modifies iface to use as a shared_ptr class the C++ identifier ident, which needs reqs in order to be accessed. ident should be the name of a template to which an arbitrary <T> can be appended, for example "std::shared_ptr".

A shared_ptr<T> implementation foo must at least provide the following interface:

foo();  // Initialization with a null pointer.
foo(T*);  // Initialization with a given pointer.
foo(const foo&);  // Copy-construction.
T& operator*() const;  // Dereferencing (when non-null).
T* operator->() const;  // Dereferencing and invocation (when non-null).
explicit operator bool() const;  // Is the target object null?

C++ includes

data Include Source #

An #include directive in a C++ file.

includeStd :: String -> Include Source #

Creates an #include <...> directive.

includeLocal :: String -> Include Source #

Creates an #include "..." directive.

includeToString :: Include -> String Source #

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

Modules

data Module Source #

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 (via the HasReqs Module instance). 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.

moduleName :: Module -> String Source #

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

moduleHppPath :: Module -> String Source #

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 Source #

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 Source #

All of the exports in a module.

moduleReqs :: Module -> Reqs Source #

Module-level requirements.

moduleExceptionHandlers :: Module -> ExceptionHandlers Source #

Exceptions that all functions in the module may throw.

moduleCallbacksThrow :: Module -> Maybe Bool Source #

Whether callbacks exported from the module support exceptions being thrown during their execution. When present, this overrides interfaceCallbacksThrow. This maybe overridden by callbackThrows.

moduleSetCallbacksThrow :: MonadState Module m => Maybe Bool -> m () Source #

Changes callbackThrows for all callbacks in a module that don't have it set explicitly.

moduleAddendum :: Module -> Addendum Source #

The module's addendum.

moduleHaskellName :: Module -> Maybe [String] Source #

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

makeModule Source #

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

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

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

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

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 () Source #

Replaces a module's moduleHppPath.

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

Replaces a module's moduleCppPath.

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

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 () Source #

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

Requirements

data Reqs Source #

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

reqsIncludes :: Reqs -> Set Include Source #

The includes specified by a Reqs.

reqInclude :: Include -> Reqs Source #

Creates a Reqs that contains the given include.

class HasReqs a where Source #

Contains the data types for bindings to C++ entities: Function, Class, etc. Use addReqs or addReqIncludes to specify requirements for these entities, e.g. header files that must be included in order to access the underlying entities that are being bound.

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

Minimal complete definition

getReqs, (setReqs | modifyReqs)

Methods

getReqs :: a -> Reqs Source #

Returns an object's requirements.

setReqs :: Reqs -> a -> a Source #

Replaces an object's requirements with new ones.

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

Modifies an object's requirements.

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

Adds to a object's requirements.

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

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

Names and exports

data ExtName Source #

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.

toExtName :: String -> ExtName Source #

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

isValidExtName :: String -> Bool Source #

Returns true if the given string is represents a valid ExtName.

fromExtName :: ExtName -> String Source #

Returns the string an an ExtName contains.

class HasExtNames a where Source #

Types that have an external name, and also optionally have nested entities with external names as well. See getAllExtNames.

Minimal complete definition

getPrimaryExtName

Methods

getPrimaryExtName :: a -> ExtName Source #

Returns the external name by which a given entity is referenced.

getNestedExtNames :: a -> [ExtName] Source #

Returns external names nested within the given entity. Does not include the primary external name.

getAllExtNames :: HasExtNames a => a -> [ExtName] Source #

Returns a list of all of the external names an entity contains. This combines both getPrimaryExtName and getNestedExtNames.

data FnName name Source #

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) Source # 

Methods

toFnName :: FnName t -> FnName t Source #

Eq name => Eq (FnName name) Source # 

Methods

(==) :: FnName name -> FnName name -> Bool #

(/=) :: FnName name -> FnName name -> Bool #

Ord name => Ord (FnName name) Source # 

Methods

compare :: FnName name -> FnName name -> Ordering #

(<) :: FnName name -> FnName name -> Bool #

(<=) :: FnName name -> FnName name -> Bool #

(>) :: FnName name -> FnName name -> Bool #

(>=) :: FnName name -> FnName name -> Bool #

max :: FnName name -> FnName name -> FnName name #

min :: FnName name -> FnName name -> FnName name #

Show name => Show (FnName name) Source # 

Methods

showsPrec :: Int -> FnName name -> ShowS #

show :: FnName name -> String #

showList :: [FnName name] -> ShowS #

class IsFnName t a where Source #

Enables implementing automatic conversions to a FnName t.

Minimal complete definition

toFnName

Methods

toFnName :: a -> FnName t Source #

Instances

data Operator Source #

Overloadable C++ operators.

data OperatorType Source #

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 Source #

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

operatorPreferredExtName' :: Operator -> String Source #

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

operatorType :: Operator -> OperatorType Source #

Returns the type of an operator.

data Export Source #

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.

exportAddendum :: Export -> Addendum Source #

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 Source #

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).

identifierParts :: Identifier -> [IdPart] Source #

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

data IdPart Source #

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

Instances

idPartBase :: IdPart -> String Source #

The name within the enclosing scope.

idPartArgs :: IdPart -> Maybe [Type] Source #

Template arguments, if present.

ident :: String -> Identifier Source #

Creates an identifier of the form a.

ident' :: [String] -> Identifier Source #

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

ident1 :: String -> String -> Identifier Source #

Creates an identifier of the form a::b.

ident2 :: String -> String -> String -> Identifier Source #

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

ident3 :: String -> String -> String -> String -> Identifier Source #

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

ident4 :: String -> String -> String -> String -> String -> Identifier Source #

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

ident5 :: String -> String -> String -> String -> String -> String -> Identifier Source #

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Basic types

normalizeType :: Type -> Type Source #

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

stripConst :: Type -> Type Source #

Strips leading Internal_TConsts off of a type.

Variables

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

Creates a binding for a C++ variable.

varIdentifier :: Variable -> Identifier Source #

The identifier used to refer to the variable.

varExtName :: Variable -> ExtName Source #

The variable's external name.

varType :: Variable -> Type Source #

The variable's type. This may be constT to indicate that the variable is read-only.

varReqs :: Variable -> Reqs Source #

Requirements for bindings to access this variable.

varIsConst :: Variable -> Bool Source #

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

varGetterExtName :: Variable -> ExtName Source #

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

varSetterExtName :: Variable -> ExtName Source #

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

Enums

data CppEnum Source #

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.

makeEnum Source #

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 Source #

The identifier used to refer to the enum.

enumExtName :: CppEnum -> ExtName Source #

The enum's external name.

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

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 Source #

Requirements for bindings to access this enum. Currently unused, but will be in the future.

enumValuePrefix :: CppEnum -> String Source #

The prefix applied to value names (enumValueNames) when determining the names of values in foreign languages. This defaults to the external name of the enum, plus an underscore.

See enumSetValuePrefix.

enumSetValuePrefix :: String -> CppEnum -> CppEnum Source #

Sets the prefix applied to the names of enum values' identifiers in foreign languages.

See enumValuePrefix.

Bitspaces

data Bitspace Source #

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.

makeBitspace Source #

Creates a binding for a C++ bitspace.

bitspaceExtName :: Bitspace -> ExtName Source #

The bitspace's external name.

bitspaceType :: Bitspace -> Type Source #

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

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

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

bitspaceEnum :: Bitspace -> Maybe CppEnum Source #

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

bitspaceAddEnum :: CppEnum -> Bitspace -> Bitspace Source #

Associates an enum with the bitspace. See bitspaceEnum.

bitspaceCppTypeIdentifier :: Bitspace -> Maybe Identifier Source #

The optional C++ type for a bitspace.

bitspaceFromCppValueFn :: Bitspace -> Maybe String Source #

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

bitspaceToCppValueFn :: Bitspace -> Maybe String Source #

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

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

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 Source #

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.

bitspaceValuePrefix :: Bitspace -> String Source #

The prefix applied to value names (bitspaceValueNames) when determining the names of values in foreign languages. This defaults to the external name of the bitspace, plus an underscore.

See bitspaceSetValuePrefix.

bitspaceSetValuePrefix :: String -> Bitspace -> Bitspace Source #

Sets the prefix applied to the names of enum values' identifiers in foreign languages.

See enumValuePrefix.

Functions

data Purity Source #

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

makeFn Source #

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 Source #

The identifier used to call the function.

fnExtName :: Function -> ExtName Source #

The function's external name.

fnPurity :: Function -> Purity Source #

Whether the function is pure.

fnParams :: Function -> [Type] Source #

The function's parameter types.

fnReturn :: Function -> Type Source #

The function's return type.

fnReqs :: Function -> Reqs Source #

Requirements for bindings to access this function.

fnExceptionHandlers :: Function -> ExceptionHandlers Source #

Exceptions that the function might throw.

Classes

data Class Source #

A C++ class declaration. See IsClassEntity for more information about the interaction between a class's names and the names of entities within the class.

Use this data type's HasReqs instance to make the class accessible. You do not need to add requirements for methods' parameter or return types.

makeClass Source #

Arguments

:: Identifier 
-> Maybe ExtName

An optional external name; will be automatically derived from the identifier if absent by dropping leading namespaces, and taking the last component (sans template arguments).

-> [Class]

Superclasses.

-> [ClassEntity] 
-> Class 

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

classIdentifier :: Class -> Identifier Source #

The identifier used to refer to the class.

classExtName :: Class -> ExtName Source #

The class's external name.

classSuperclasses :: Class -> [Class] Source #

The class's public superclasses.

classEntities :: Class -> [ClassEntity] Source #

The class's entities.

classAddEntities :: [ClassEntity] -> Class -> Class Source #

Adds constructors to a class.

classVariables :: Class -> [ClassVariable] Source #

Returns all of the class's variables.

classCtors :: Class -> [Ctor] Source #

Returns all of the class's constructors.

classMethods :: Class -> [Method] Source #

Returns all of the class's methods, including methods generated from Props.

classDtorIsPublic :: Class -> Bool Source #

The class's methods.

classSetDtorPrivate :: Class -> Class Source #

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

classConversion :: Class -> ClassConversion Source #

Behaviour for converting objects to and from foriegn values.

classReqs :: Class -> Reqs Source #

Requirements for bindings to access this class.

classEntityPrefix :: Class -> String Source #

The prefix applied to the external names of entities (methods, etc.) within this class when determining the names of foreign languages' corresponding bindings. This defaults to the external name of the class, plus an underscore. Changing this allows you to potentially have entities with the same foreign name in separate modules. This may be the empty string, in which case the foreign name will simply be the external name of the entity.

This does not affect the things' external names themselves; external names must still be unique in an interface. For instance, a method with external name bar in a class with external name Flab and prefix Flob_ will use the effective external name Flab_bar, but the generated name in say Haskell would be Flob_bar.

See IsClassEntity and classSetEntityPrefix.

classSetEntityPrefix :: String -> Class -> Class Source #

Sets the prefix applied to foreign languages' entities generated from methods, etc. within the class.

See IsClassEntity and classEntityPrefix.

classIsMonomorphicSuperclass :: Class -> Bool Source #

This is true for classes passed through classSetMonomorphicSuperclass.

classSetMonomorphicSuperclass :: Class -> Class Source #

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 Source #

This is true for classes passed through classSetSubclassOfMonomorphic.

classSetSubclassOfMonomorphic :: Class -> Class Source #

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.

classIsException :: Class -> Bool Source #

Whether to support using the class as a C++ exception.

classMakeException :: Class -> Class Source #

Marks a class as being used as an exception. This makes the class throwable and catchable.

data ClassEntity Source #

A C++ entity that belongs to a class.

class IsClassEntity a where Source #

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".

See classEntityPrefix and classSetEntityPrefix.

Minimal complete definition

classEntityExtNameSuffix

Methods

classEntityExtNameSuffix :: a -> ExtName Source #

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

classEntityExtName :: IsClassEntity a => Class -> a -> ExtName Source #

Computes the external name to use in generated code, containing both the class's and object's external names. This is the concatenation of the class's and entity's external names, separated by an underscore.

classEntityForeignName :: IsClassEntity a => Class -> a -> ExtName Source #

Computes the name under which a class entity is to be exposed in foreign languages. This is the concatenation of a class's entity prefix, and the external name of the entity.

classEntityForeignName' :: Class -> ExtName -> ExtName Source #

Computes the name under which a class entity is to be exposed in foreign languages, given a class and an entity's external name. The result is the concatenation of a class's entity prefix, and the external name of the entity.

makeClassVariable :: String -> Maybe ExtName -> Type -> Staticness -> Bool -> ClassEntity Source #

Creates a ClassVariable with full generality and manual name specification.

The result is wrapped in a CEVar. For an unwrapped value, use makeClassVariable_.

mkClassVariable :: String -> Type -> ClassEntity Source #

Creates a ClassVariable for a nonstatic class variable for class::varName whose external name is class_varName.

The result is wrapped in a CEVar. For an unwrapped value, use mkClassVariable_.

mkStaticClassVariable :: String -> Type -> ClassEntity Source #

Same as mkClassVariable, but returns a static variable instead.

The result is wrapped in a CEVar. For an unwrapped value, use mkStaticClassVariable_.

classVarCName :: ClassVariable -> String Source #

The variable's C++ name.

classVarExtName :: ClassVariable -> ExtName Source #

The variable's external name.

classVarType :: ClassVariable -> Type Source #

The variable's type. This may be constT to indicate that the variable is read-only.

classVarStatic :: ClassVariable -> Staticness Source #

Whether the variable is static (i.e. whether it exists once in the class itself and not in each instance).

classVarGettable :: ClassVariable -> Bool Source #

Whether the variable should have an accompanying getter. Note this exists only for disabling getters on callback variables - as there is currently no functionality to pass callbacks out of c++

classVarGetterExtName :: Class -> ClassVariable -> ExtName Source #

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

classVarGetterForeignName :: Class -> ClassVariable -> ExtName Source #

Returns the foreign name of the getter function for the class variable.

classVarSetterExtName :: Class -> ClassVariable -> ExtName Source #

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

classVarSetterForeignName :: Class -> ClassVariable -> ExtName Source #

Returns the foreign name of the setter function for the class variable.

makeCtor Source #

Arguments

:: ExtName 
-> [Type]

Parameter types.

-> ClassEntity 

Creates a Ctor with full generality.

The result is wrapped in a CECtor. For an unwrapped value, use makeCtor_.

makeCtor_ :: ExtName -> [Type] -> Ctor Source #

The unwrapped version of makeCtor.

mkCtor Source #

Arguments

:: String 
-> [Type]

Parameter types.

-> ClassEntity 

mkCtor name creates a Ctor whose external name is className_name.

The result is wrapped in a CECtor. For an unwrapped value, use makeCtor_.

mkCtor_ :: String -> [Type] -> Ctor Source #

The unwrapped version of mkCtor.

ctorExtName :: Ctor -> ExtName Source #

The constructor's external name.

ctorParams :: Ctor -> [Type] Source #

The constructor's parameter types.

ctorExceptionHandlers :: Ctor -> ExceptionHandlers Source #

Exceptions that the constructor may throw.

data Method Source #

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++.

data MethodImpl Source #

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.

constNegate :: Constness -> Constness Source #

Returns the opposite constness value.

makeMethod Source #

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.

-> ClassEntity 

Creates a Method with full generality and manual name specification.

The result is wrapped in a CEMethod. For an unwrapped value, use makeMethod_.

makeMethod_ :: IsFnName String name => name -> ExtName -> MethodApplicability -> Purity -> [Type] -> Type -> Method Source #

The unwrapped version of makeMethod.

makeFnMethod :: IsFnName Identifier name => name -> String -> MethodApplicability -> Purity -> [Type] -> Type -> ClassEntity Source #

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.

The result is wrapped in a CEMethod. For an unwrapped value, use makeFnMethod_.

makeFnMethod_ :: IsFnName Identifier name => name -> String -> MethodApplicability -> Purity -> [Type] -> Type -> Method Source #

The unwrapped version of makeFnMethod.

mkMethod Source #

Arguments

:: IsFnName String name 
=> name

The C++ name of the method.

-> [Type]

Parameter types.

-> Type

Return type.

-> ClassEntity 

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'.

The result is wrapped in a CEMethod. For an unwrapped value, use mkMethod_.

mkMethod_ :: IsFnName String name => name -> [Type] -> Type -> Method Source #

The unwrapped version of mkMethod.

mkMethod' Source #

Arguments

:: IsFnName String name 
=> name

The C++ name of the method.

-> String

A foreign name for the method.

-> [Type]

Parameter types.

-> Type

Return type.

-> ClassEntity 

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.

The result is wrapped in a CEMethod. For an unwrapped value, use mkMethod'_.

mkMethod'_ :: IsFnName String name => name -> String -> [Type] -> Type -> Method Source #

The unwrapped version of mkMethod'.

mkConstMethod :: IsFnName String name => name -> [Type] -> Type -> ClassEntity Source #

Same as mkMethod, but returns an MConst method.

The result is wrapped in a CEMethod. For an unwrapped value, use mkConstMethod_.

mkConstMethod_ :: IsFnName String name => name -> [Type] -> Type -> Method Source #

The unwrapped version of mkConstMethod.

mkConstMethod' :: IsFnName String name => name -> String -> [Type] -> Type -> ClassEntity Source #

Same as mkMethod', but returns an MConst method.

The result is wrapped in a CEMethod. For an unwrapped value, use mkConstMethod'_.

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

The unwrapped version of mkConstMethod'.

mkStaticMethod :: IsFnName String name => name -> [Type] -> Type -> ClassEntity Source #

Same as mkMethod, but returns an MStatic method.

The result is wrapped in a CEMethod. For an unwrapped value, use mkStaticMethod_.

mkStaticMethod_ :: IsFnName String name => name -> [Type] -> Type -> Method Source #

The unwrapped version of mkStaticMethod.

mkStaticMethod' :: IsFnName String name => name -> String -> [Type] -> Type -> ClassEntity Source #

Same as mkMethod', but returns an MStatic method.

The result is wrapped in a CEMethod. For an unwrapped value, use mkStaticMethod'_.

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

The unwrapped version of mkStaticMethod'.

data Prop Source #

A "property" getter/setter pair.

mkProp :: String -> Type -> ClassEntity Source #

Creates a getter/setter binding pair for methods:

T foo() const
void setFoo(T)

The result is wrapped in a CEProp. For an unwrapped value, use mkProp_.

mkProp_ :: String -> Type -> Prop Source #

The unwrapped version of mkProp.

mkStaticProp :: String -> Type -> ClassEntity Source #

Creates a getter/setter binding pair for static methods:

static T foo() const
static void setFoo(T)

mkStaticProp_ :: String -> Type -> Prop Source #

The unwrapped version of mkStaticProp.

mkBoolIsProp :: String -> ClassEntity Source #

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

bool isFoo() const
void setFoo(bool)

The result is wrapped in a CEProp. For an unwrapped value, use mkBoolIsProp_.

mkBoolIsProp_ :: String -> Prop Source #

The unwrapped version of mkBoolIsProp.

mkBoolHasProp :: String -> ClassEntity Source #

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

bool hasFoo() const
void setFoo(bool)

The result is wrapped in a CEProp. For an unwrapped value, use mkBoolHasProp_.

mkBoolHasProp_ :: String -> Prop Source #

The unwrapped version of mkBoolHasProp.

methodImpl :: Method -> MethodImpl Source #

The underlying code that the binding calls.

methodExtName :: Method -> ExtName Source #

The method's external name.

methodApplicability :: Method -> MethodApplicability Source #

How the method is associated to its class.

methodPurity :: Method -> Purity Source #

Whether the method is pure.

methodParams :: Method -> [Type] Source #

The method's parameter types.

methodReturn :: Method -> Type Source #

The method's return type.

methodExceptionHandlers :: Method -> ExceptionHandlers Source #

Exceptions that the method might throw.

methodConst :: Method -> Constness Source #

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

methodStatic :: Method -> Staticness Source #

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

Conversion to and from foreign values

data ClassConversion Source #

Separately from passing object handles between C++ and foreign languages, objects can also be made to implicitly convert to native values in foreign languages. A single such type may be associated with any C++ class for each foreign language. The foreign type and the conversion process in each direction are specified using this object. Converting a C++ object to a foreign value is also called decoding, and vice versa is called encoding. A class may be convertible in one direction and not the other.

To use these implicit conversions, instead of specifying an object handle type such as ptrT . objT or refT . objT, use objT directly.

The subfields in this object specify how to do conversions between C++ and foreign languages.

Constructors

ClassConversion 

Fields

classConversionNone :: ClassConversion Source #

Conversion behaviour for a class that is not convertible.

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

Modifies a class's ClassConversion structure with a given function.

classSetConversion :: ClassConversion -> Class -> Class Source #

Replaces a class's ClassConversion structure.

data ClassHaskellConversion Source #

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

Constructors

ClassHaskellConversion 

Fields

classHaskellConversionNone :: ClassHaskellConversion Source #

Conversion behaviour for a class that is not convertible to or from Haskell.

Callbacks

data Callback Source #

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

Use this data type's HasReqs instance to add extra requirements, however manually adding requirements for parameter and return types is not necessary.

makeCallback Source #

Arguments

:: ExtName 
-> [Type]

Parameter types.

-> Type

Return type.

-> Callback 

Creates a binding for constructing callbacks into foreign code.

callbackExtName :: Callback -> ExtName Source #

The callback's external name.

callbackParams :: Callback -> [Type] Source #

The callback's parameter types.

callbackReturn :: Callback -> Type Source #

The callback's return type.

callbackThrows :: Callback -> Maybe Bool Source #

Whether the callback supports throwing C++ exceptions from Haskell into C++ during its execution. When absent, the value is inherited from moduleCallbacksThrow and interfaceCallbacksThrow.

callbackReqs :: Callback -> Reqs Source #

Extra requirements for the callback.

callbackSetThrows :: Bool -> Callback -> Callback Source #

Sets whether a callback supports handling thrown C++ exceptions and passing them into C++.

Exceptions

newtype ExceptionId Source #

Each exception class has a unique exception ID.

Constructors

ExceptionId 

Fields

exceptionCatchAllId :: ExceptionId Source #

The exception ID that represents the catch-all type.

data ExceptionHandler Source #

Indicates the ability to handle a certain type of C++ exception.

Constructors

CatchClass Class

Indicates that instances of the given class are handled (including derived types).

CatchAll

Indicates that all C++ exceptions are handled, i.e. catch (...).

data ExceptionHandlers Source #

Represents a list of exception handlers to be used for a body of code. Order is important; a CatchAll will prevent all subsequent handlers from being invoked.

Constructors

ExceptionHandlers 

Fields

handleExceptions :: HandlesExceptions a => [ExceptionHandler] -> a -> a Source #

Appends additional exception handlers to an object.

Addenda

data Addendum Source #

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

class HasAddendum a where Source #

A typeclass for types that have an addendum.

Minimal complete definition

getAddendum, (setAddendum | modifyAddendum)

Methods

getAddendum :: a -> Addendum Source #

Returns an object's addendum.

setAddendum :: Addendum -> a -> a Source #

Replaces and object's addendum with another.

modifyAddendum :: (Addendum -> Addendum) -> a -> a Source #

Modified an object's addendum.

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

Adds a Haskell addendum to an object.

Haskell imports

type HsModuleName = String Source #

A Haskell module name.

data HsImportSet Source #

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.

data HsImportKey Source #

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

data HsImportSpecs Source #

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.

type HsImportName = String Source #

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

data HsImportVal Source #

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.

hsWholeModuleImport :: HsModuleName -> HsImportSet Source #

An import for the entire contents of a Haskell module.

hsQualifiedImport :: HsModuleName -> HsModuleName -> HsImportSet Source #

A qualified import of a Haskell module.

hsImport1 :: HsModuleName -> HsImportName -> HsImportSet Source #

An import of a single name from a Haskell module.

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

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

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

An import of multiple names from a Haskell module.

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

A detailed import of multiple names from a Haskell module.

hsImportSetMakeSource :: HsImportSet -> HsImportSet Source #

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

Internal to Hoppy

interfaceAllExceptionClasses :: Interface -> [Class] Source #

Returns all of the exception classes in an interface.

interfaceSharedPtr :: Interface -> (Reqs, String) Source #

The name of the shared_ptr class to use, and the requirements to use it. This defaults to using std::shared_ptr from memory, but can be changed if necessary via interfaceSetSharedPtr.

classFindCopyCtor :: Class -> Maybe Ctor Source #

Searches a class for a copy constructor, returning it if found.

Haskell imports

makeHsImportSet :: Map HsImportKey HsImportSpecs -> HsImportSet Source #

Constructor for an import set.

getHsImportSet :: HsImportSet -> Map HsImportKey HsImportSpecs Source #

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

hsImportForBits :: HsImportSet Source #

Imports Data.Bits qualified as HoppyDB.

hsImportForInt :: HsImportSet Source #

Imports Data.Int qualified as HoppyDI.

hsImportForWord :: HsImportSet Source #

Imports Data.Word qualified as HoppyDW.

hsImportForForeign :: HsImportSet Source #

Imports Foreign qualified as HoppyF.

hsImportForForeignC :: HsImportSet Source #

Imports Foreign.C qualified as HoppyFC.

hsImportForMap :: HsImportSet Source #

Imports Data.Map qualified as HoppyDM.

hsImportForPrelude :: HsImportSet Source #

Imports Prelude qualified as HoppyP.

hsImportForTypeable :: HsImportSet Source #

Imports Data.Typeable qualified as HoppyDT.

hsImportForUnsafeIO :: HsImportSet Source #

Imports System.IO.Unsafe qualified as HoppySIU.

Error messages

objToHeapTWrongDirectionErrorMsg :: Maybe String -> Class -> String Source #

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

tToGcInvalidFormErrorMessage :: Maybe String -> Type -> String Source #

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

toGcTWrongDirectionErrorMsg :: Maybe String -> Type -> String Source #

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

Advanced class conversions

classSetConversionToHeap :: Class -> Class Source #

Modifies a class's ClassConversion structure by setting all languages to use ClassConversionToHeap.

classSetConversionToGc :: Class -> Class Source #

Modifies a class's ClassConversion structure by setting all languages that support garbage collection to use ClassConversionToGc.