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.

Documentation

type ErrorMsg = String

Indicates strings that are error messages.

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.

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

Instances

Show Interface

Defined in Foreign.Hoppy.Generator.Spec.Base

Methods

showsPrec :: Int -> Interface -> ShowS

show :: Interface -> String

showList :: [Interface] -> ShowS

newtype InterfaceOptions

Optional parameters when constructing an Interface with interface.

Constructors

InterfaceOptions

Fields

• interfaceOptionsExceptionHandlers :: ExceptionHandlers

defaultInterfaceOptions :: InterfaceOptions

Options used by interface. This contains no exception handlers.

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.

This function passes defaultInterfaceOptions to interface'.

interface'

Arguments

:: String

interfaceName

-> [Module]

interfaceModules

-> InterfaceOptions

-> Either ErrorMsg Interface

Same as interface, but accepts some optional arguments.

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.

interfaceHaskellModuleImportNames :: Interface -> Map Module String

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

interfaceExceptionHandlers :: Interface -> ExceptionHandlers

Exceptions that all functions in the interface may throw.

interfaceCallbacksThrow :: Interface -> Bool

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

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

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

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 :: HasCallStack => Module -> Interface -> Interface

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

interfaceSetSharedPtr :: String -> Reqs -> Interface -> Interface

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?

interfaceCompiler :: Interface -> Maybe SomeCompiler

The C++ compiler for the generator itself to use when building temporary code for the interface. This can be overridden or disabled. This defaults to defaultCompiler.

This is separate from the ./configure && make compilation process used by Foreign.Hoppy.Runtime.Setup.cppMain to build generated C++ bindings (see hoppy-runtime). This compiler is used to evaluate enums' numeric values when the generator is called, and is not used otherwise. See makeAutoEnum and Foreign.Hoppy.Generator.Hooks.

interfaceSetCompiler :: Compiler a => a -> Interface -> Interface

Replaces the default compiler used by the interface.

interfaceSetCompiler c = interfaceSetCompiler' (SomeCompiler c)

interfaceSetCompiler' :: Maybe SomeCompiler -> Interface -> Interface

Replaces the default compiler used by the interface. When given Nothing, the interface will not be allowed to compile any code when it generates bindings.

interfaceSetNoCompiler :: Interface -> Interface

Sets an interface to never compile C++ code during binding generation.

This sets the interface to have no compiler, and also asks the interface not to do things that require a compiler, which would otherwise cause a runtime failure: currently just validation of provided enum numeric types (interfaceSetValidateEnumTypes False).

interfaceValidateEnumTypes :: Interface -> Bool

Whether to validate manually-provided enum numeric types (enumNumericType) using a compiled C++ sizeof(), as is done for enums that don't have an enumNumericType set.

This defaults to true, but can be set to false to discourage requiring a compiler. See interfaceSetNoCompiler.

interfaceSetValidateEnumTypes :: Bool -> Interface -> Interface

Controls whether the interface will validate manually specified enum types (enumNumericType) by compiling a C++ program.

See interfaceValidateEnumTypes.

interfaceHooks :: Interface -> Hooks

Hooks allowing the interface to execute code at various points during the code generator's execution. This defaults to defaultHooks.

interfaceModifyHooks :: (Hooks -> Hooks) -> Interface -> Interface

Modifies the hooks associated with an interface.

C++ includes

data Include

An #include directive in a C++ file.

Instances

Eq Include

Defined in Foreign.Hoppy.Generator.Spec.Base

Methods

(==) :: Include -> Include -> Bool

(/=) :: Include -> Include -> Bool

Ord Include

Defined in Foreign.Hoppy.Generator.Spec.Base

Methods

compare :: Include -> Include -> Ordering

(<) :: Include -> Include -> Bool

(<=) :: Include -> Include -> Bool

(>) :: Include -> Include -> Bool

(>=) :: Include -> Include -> Bool

max :: Include -> Include -> Include

min :: Include -> Include -> Include

Show Include

Defined in Foreign.Hoppy.Generator.Spec.Base

Methods

showsPrec :: Int -> Include -> ShowS

show :: Include -> String

showList :: [Include] -> ShowS

includeStd :: String -> Include

Creates an #include <...> directive.

This can be added to most types of C++ entities with addReqIncludes.

includeLocal :: String -> Include

Creates an #include "..." directive.

This can be added to most types of C++ entities with addReqIncludes.

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

Instances

Eq Module

Defined in Foreign.Hoppy.Generator.Spec.Base

Methods

(==) :: Module -> Module -> Bool

(/=) :: Module -> Module -> Bool

Ord Module

Defined in Foreign.Hoppy.Generator.Spec.Base

Methods

compare :: Module -> Module -> Ordering

(<) :: Module -> Module -> Bool

(<=) :: Module -> Module -> Bool

(>) :: Module -> Module -> Bool

(>=) :: Module -> Module -> Bool

max :: Module -> Module -> Module

min :: Module -> Module -> Module

Show Module

Defined in Foreign.Hoppy.Generator.Spec.Base

Methods

showsPrec :: Int -> Module -> ShowS

show :: Module -> String

showList :: [Module] -> ShowS

HasAddendum Module

Defined in Foreign.Hoppy.Generator.Spec.Base

Methods

getAddendum :: Module -> Addendum

setAddendum :: Addendum -> Module -> Module

modifyAddendum :: (Addendum -> Addendum) -> Module -> Module

HandlesExceptions Module

Defined in Foreign.Hoppy.Generator.Spec.Base

Methods

getExceptionHandlers :: Module -> ExceptionHandlers

modifyExceptionHandlers :: (ExceptionHandlers -> ExceptionHandlers) -> Module -> Module

HasReqs Module

Defined in Foreign.Hoppy.Generator.Spec.Base

Methods

getReqs :: Module -> Reqs

setReqs :: Reqs -> Module -> Module

modifyReqs :: (Reqs -> Reqs) -> Module -> 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.

moduleExceptionHandlers :: Module -> ExceptionHandlers

Exceptions that all functions in the module may throw.

moduleCallbacksThrow :: Module -> Maybe Bool

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

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

moduleAddendum :: Module -> Addendum

The module's addendum.

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' :: HasCallStack => 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

Defined in Foreign.Hoppy.Generator.Spec.Base

Methods

showsPrec :: Int -> Reqs -> ShowS

show :: Reqs -> String

showList :: [Reqs] -> ShowS

Semigroup Reqs

Defined in Foreign.Hoppy.Generator.Spec.Base

Methods

(<>) :: Reqs -> Reqs -> Reqs

sconcat :: NonEmpty Reqs -> Reqs

stimes :: Integral b => b -> Reqs -> Reqs

Monoid Reqs

Defined in Foreign.Hoppy.Generator.Spec.Base

Methods

mempty :: Reqs

mappend :: Reqs -> Reqs -> Reqs

mconcat :: [Reqs] -> 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

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

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 Class

Defined in Foreign.Hoppy.Generator.Spec.Class

Methods

getReqs :: Class -> Reqs

setReqs :: Reqs -> Class -> Class

modifyReqs :: (Reqs -> Reqs) -> Class -> Class

HasReqs Export

Defined in Foreign.Hoppy.Generator.Spec.Base

Methods

getReqs :: Export -> Reqs

setReqs :: Reqs -> Export -> Export

modifyReqs :: (Reqs -> Reqs) -> Export -> Export

HasReqs Module

Defined in Foreign.Hoppy.Generator.Spec.Base

Methods

getReqs :: Module -> Reqs

setReqs :: Reqs -> Module -> Module

modifyReqs :: (Reqs -> Reqs) -> Module -> Module

HasReqs Callback

Defined in Foreign.Hoppy.Generator.Spec.Callback

Methods

getReqs :: Callback -> Reqs

setReqs :: Reqs -> Callback -> Callback

modifyReqs :: (Reqs -> Reqs) -> Callback -> Callback

HasReqs CppEnum

Defined in Foreign.Hoppy.Generator.Spec.Enum

Methods

getReqs :: CppEnum -> Reqs

setReqs :: Reqs -> CppEnum -> CppEnum

modifyReqs :: (Reqs -> Reqs) -> CppEnum -> CppEnum

HasReqs Function

Defined in Foreign.Hoppy.Generator.Spec.Function

Methods

getReqs :: Function -> Reqs

setReqs :: Reqs -> Function -> Function

modifyReqs :: (Reqs -> Reqs) -> Function -> Function

HasReqs Variable

Defined in Foreign.Hoppy.Generator.Spec.Variable

Methods

getReqs :: Variable -> Reqs

setReqs :: Reqs -> Variable -> Variable

modifyReqs :: (Reqs -> Reqs) -> Variable -> Variable

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

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

Defined in Foreign.Hoppy.Generator.Spec.Base

Methods

(==) :: ExtName -> ExtName -> Bool

(/=) :: ExtName -> ExtName -> Bool

Ord ExtName

Defined in Foreign.Hoppy.Generator.Spec.Base

Methods

compare :: ExtName -> ExtName -> Ordering

(<) :: ExtName -> ExtName -> Bool

(<=) :: ExtName -> ExtName -> Bool

(>) :: ExtName -> ExtName -> Bool

(>=) :: ExtName -> ExtName -> Bool

max :: ExtName -> ExtName -> ExtName

min :: ExtName -> ExtName -> ExtName

Show ExtName

Defined in Foreign.Hoppy.Generator.Spec.Base

Methods

showsPrec :: Int -> ExtName -> ShowS

show :: ExtName -> String

showList :: [ExtName] -> ShowS

Semigroup ExtName

Defined in Foreign.Hoppy.Generator.Spec.Base

Methods

(<>) :: ExtName -> ExtName -> ExtName

sconcat :: NonEmpty ExtName -> ExtName

stimes :: Integral b => b -> ExtName -> ExtName

Monoid ExtName

Defined in Foreign.Hoppy.Generator.Spec.Base

Methods

mempty :: ExtName

mappend :: ExtName -> ExtName -> ExtName

mconcat :: [ExtName] -> ExtName

toExtName :: HasCallStack => String -> ExtName

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

extNameOrIdentifier :: HasCallStack => Identifier -> Maybe ExtName -> ExtName

Generates an ExtName from an Identifier, if the given name is absent.

extNameOrFnIdentifier :: HasCallStack => FnName Identifier -> Maybe ExtName -> ExtName

Generates an ExtName from an FnName Identifier, if the given name is absent.

extNameOrString :: String -> Maybe ExtName -> ExtName

Generates an ExtName from a string, if the given name is absent.

isValidExtName :: String -> Bool

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

fromExtName :: ExtName -> String

Returns the string an an ExtName contains.

class HasExtNames a where

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

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

getNestedExtNames :: a -> [ExtName]

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

Instances

HasExtNames Class

Defined in Foreign.Hoppy.Generator.Spec.Class

Methods

getPrimaryExtName :: Class -> ExtName

getNestedExtNames :: Class -> [ExtName]

HasExtNames Export

Defined in Foreign.Hoppy.Generator.Spec.Base

Methods

getPrimaryExtName :: Export -> ExtName

getNestedExtNames :: Export -> [ExtName]

HasExtNames Callback

Defined in Foreign.Hoppy.Generator.Spec.Callback

Methods

getPrimaryExtName :: Callback -> ExtName

getNestedExtNames :: Callback -> [ExtName]

HasExtNames CppEnum

Defined in Foreign.Hoppy.Generator.Spec.Enum

Methods

getPrimaryExtName :: CppEnum -> ExtName

getNestedExtNames :: CppEnum -> [ExtName]

HasExtNames Function

Defined in Foreign.Hoppy.Generator.Spec.Function

Methods

getPrimaryExtName :: Function -> ExtName

getNestedExtNames :: Function -> [ExtName]

HasExtNames Variable

Defined in Foreign.Hoppy.Generator.Spec.Variable

Methods

getPrimaryExtName :: Variable -> ExtName

getNestedExtNames :: Variable -> [ExtName]

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

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

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)

Defined in Foreign.Hoppy.Generator.Spec.Base

Methods

toFnName :: FnName t -> FnName t

Eq name => Eq (FnName name)

Defined in Foreign.Hoppy.Generator.Spec.Base

Methods

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

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

Ord name => Ord (FnName name)

Defined in Foreign.Hoppy.Generator.Spec.Base

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)

Defined in Foreign.Hoppy.Generator.Spec.Base

Methods

showsPrec :: Int -> FnName name -> ShowS

show :: FnName name -> String

showList :: [FnName name] -> ShowS

class IsFnName t a where

Enables implementing automatic conversions to a FnName t.

Methods

toFnName :: a -> FnName t

Instances

IsFnName t Operator

Defined in Foreign.Hoppy.Generator.Spec.Base

Methods

toFnName :: Operator -> FnName t

IsFnName t t

Defined in Foreign.Hoppy.Generator.Spec.Base

Methods

toFnName :: t -> FnName t

IsFnName t (FnName t)

Defined in Foreign.Hoppy.Generator.Spec.Base

Methods

toFnName :: FnName 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

Defined in Foreign.Hoppy.Generator.Spec.Base

Methods

minBound :: Operator

maxBound :: Operator

Enum Operator

Defined in Foreign.Hoppy.Generator.Spec.Base

Methods

succ :: Operator -> Operator

pred :: Operator -> Operator

toEnum :: Int -> Operator

fromEnum :: Operator -> Int

enumFrom :: Operator -> [Operator]

enumFromThen :: Operator -> Operator -> [Operator]

enumFromTo :: Operator -> Operator -> [Operator]

enumFromThenTo :: Operator -> Operator -> Operator -> [Operator]

Eq Operator

Defined in Foreign.Hoppy.Generator.Spec.Base

Methods

(==) :: Operator -> Operator -> Bool

(/=) :: Operator -> Operator -> Bool

Ord Operator

Defined in Foreign.Hoppy.Generator.Spec.Base

Methods

compare :: Operator -> Operator -> Ordering

(<) :: Operator -> Operator -> Bool

(<=) :: Operator -> Operator -> Bool

(>) :: Operator -> Operator -> Bool

(>=) :: Operator -> Operator -> Bool

max :: Operator -> Operator -> Operator

min :: Operator -> Operator -> Operator

Show Operator

Defined in Foreign.Hoppy.Generator.Spec.Base

Methods

showsPrec :: Int -> Operator -> ShowS

show :: Operator -> String

showList :: [Operator] -> ShowS

IsFnName t Operator

Defined in Foreign.Hoppy.Generator.Spec.Base

Methods

toFnName :: Operator -> FnName t

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 :: HasCallStack => 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 :: HasCallStack => Operator -> OperatorType

Returns the type of an operator.

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

The Monoid instance inserts a :: between joined identifiers. Usually an identifier needs to contain at least one part, so mempty is an invalid argument to many functions in Hoppy, but it is useful as a base case for appending.

Instances

Eq Identifier

Defined in Foreign.Hoppy.Generator.Spec.Base

Methods

(==) :: Identifier -> Identifier -> Bool

(/=) :: Identifier -> Identifier -> Bool

Show Identifier

Defined in Foreign.Hoppy.Generator.Spec.Base

Methods

showsPrec :: Int -> Identifier -> ShowS

show :: Identifier -> String

showList :: [Identifier] -> ShowS

Semigroup Identifier

Defined in Foreign.Hoppy.Generator.Spec.Base

Methods

(<>) :: Identifier -> Identifier -> Identifier

sconcat :: NonEmpty Identifier -> Identifier

stimes :: Integral b => b -> Identifier -> Identifier

Monoid Identifier

Defined in Foreign.Hoppy.Generator.Spec.Base

Methods

mempty :: Identifier

mappend :: Identifier -> Identifier -> Identifier

mconcat :: [Identifier] -> Identifier

makeIdentifier :: [IdPart] -> Identifier

Creates an identifier from a collection of IdParts, with ::s between.

identifierParts :: Identifier -> [IdPart]

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

data IdPart

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

Instances

Eq IdPart

Defined in Foreign.Hoppy.Generator.Spec.Base

Methods

(==) :: IdPart -> IdPart -> Bool

(/=) :: IdPart -> IdPart -> Bool

Show IdPart

Defined in Foreign.Hoppy.Generator.Spec.Base

Methods

showsPrec :: Int -> IdPart -> ShowS

show :: IdPart -> String

showList :: [IdPart] -> ShowS

makeIdPart :: String -> Maybe [Type] -> IdPart

Creates an object representing one component of an identifier.

idPartBase :: IdPart -> String

The name within the enclosing scope.

idPartArgs :: IdPart -> Maybe [Type]

Template arguments, if present.

ident :: String -> Identifier

Creates a identifier of the form a, without any namespace operators (::).

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

Exports

class (HasAddendum a, HasExtNames a, HasReqs a, Typeable a, Show a) => Exportable a where

Instances of this typeclass are C++ entities that Hoppy can expose to foreign languages: functions, classes, global variables, etc. Interfaces are largely composed of exports (grouped into modules). Hoppy uses this interface to perform code generation for each entity.

Minimal complete definition

sayExportCpp, sayExportHaskell

Methods

toExport :: a -> Export

Wraps an exportable object in an existential data type.

The default instance is just toExport = Export, which does not need to be overridden in general.

castExport :: (Typeable a, Exportable b, Typeable b) => a -> Maybe b

Attempts to cast an exportable object to a specific type, pulling off Export wrappers as necessary.

The default castExport = cast is fine.

sayExportCpp :: SayExportMode -> a -> Generator ()

Generates the C++ side of the binding for an entity.

For an entity, Hoppy invokes this function once with SayHeader when generating the header file for a module, and once with SaySource when generating the corresponding source file.

sayExportHaskell :: SayExportMode -> a -> Generator ()

Generates the Haskell side of the binding for an entity.

For an entity, Hoppy invokes this function once with SayExportForeignImports when it is time to emit foreign imports, and once with SayExportDecls when it is time to generate Haskell binding code later in the module. Hoppy may also call the function with SayExportBoot, if necessary.

See SayExportMode.

getExportEnumInfo :: a -> Maybe EnumInfo

If the export is backed by an C++ enum, then this returns known structural information about the enum. This provides information to the "evaluate enums" hook so that Hoppy can determine enum values on its own.

By default, this returns Nothing.

See Hooks.

getExportExceptionClass :: a -> Maybe Class

If the export is backed by a C++ class that is marked as supporting exceptions, then this returns the class definition.

By default, this returns Nothing.

Instances

Exportable Class

Defined in Foreign.Hoppy.Generator.Spec.Class

Methods

toExport :: Class -> Export

castExport :: (Typeable Class, Exportable b, Typeable b) => Class -> Maybe b

sayExportCpp :: SayExportMode -> Class -> Generator ()

sayExportHaskell :: SayExportMode -> Class -> Generator ()

getExportEnumInfo :: Class -> Maybe EnumInfo

getExportExceptionClass :: Class -> Maybe Class

Exportable Export

Defined in Foreign.Hoppy.Generator.Spec.Base

Methods

toExport :: Export -> Export

castExport :: (Typeable Export, Exportable b, Typeable b) => Export -> Maybe b

sayExportCpp :: SayExportMode -> Export -> Generator ()

sayExportHaskell :: SayExportMode -> Export -> Generator ()

getExportEnumInfo :: Export -> Maybe EnumInfo

getExportExceptionClass :: Export -> Maybe Class

Exportable Callback

Defined in Foreign.Hoppy.Generator.Spec.Callback

Methods

toExport :: Callback -> Export

castExport :: (Typeable Callback, Exportable b, Typeable b) => Callback -> Maybe b

sayExportCpp :: SayExportMode -> Callback -> Generator ()

sayExportHaskell :: SayExportMode -> Callback -> Generator ()

getExportEnumInfo :: Callback -> Maybe EnumInfo

getExportExceptionClass :: Callback -> Maybe Class

Exportable CppEnum

Defined in Foreign.Hoppy.Generator.Spec.Enum

Methods

toExport :: CppEnum -> Export

castExport :: (Typeable CppEnum, Exportable b, Typeable b) => CppEnum -> Maybe b

sayExportCpp :: SayExportMode -> CppEnum -> Generator ()

sayExportHaskell :: SayExportMode -> CppEnum -> Generator ()

getExportEnumInfo :: CppEnum -> Maybe EnumInfo

getExportExceptionClass :: CppEnum -> Maybe Class

Exportable Function

Defined in Foreign.Hoppy.Generator.Spec.Function

Methods

toExport :: Function -> Export

castExport :: (Typeable Function, Exportable b, Typeable b) => Function -> Maybe b

sayExportCpp :: SayExportMode -> Function -> Generator ()

sayExportHaskell :: SayExportMode -> Function -> Generator ()

getExportEnumInfo :: Function -> Maybe EnumInfo

getExportExceptionClass :: Function -> Maybe Class

Exportable Variable

Defined in Foreign.Hoppy.Generator.Spec.Variable

Methods

toExport :: Variable -> Export

castExport :: (Typeable Variable, Exportable b, Typeable b) => Variable -> Maybe b

sayExportCpp :: SayExportMode -> Variable -> Generator ()

sayExportHaskell :: SayExportMode -> Variable -> Generator ()

getExportEnumInfo :: Variable -> Maybe EnumInfo

getExportExceptionClass :: Variable -> Maybe Class

data Export

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

Constructors

forall a.Exportable a => Export a

Instances

Show Export

Defined in Foreign.Hoppy.Generator.Spec.Base

Methods

showsPrec :: Int -> Export -> ShowS

show :: Export -> String

showList :: [Export] -> ShowS

HasAddendum Export

Defined in Foreign.Hoppy.Generator.Spec.Base

Methods

getAddendum :: Export -> Addendum

setAddendum :: Addendum -> Export -> Export

modifyAddendum :: (Addendum -> Addendum) -> Export -> Export

Exportable Export

Defined in Foreign.Hoppy.Generator.Spec.Base

Methods

toExport :: Export -> Export

castExport :: (Typeable Export, Exportable b, Typeable b) => Export -> Maybe b

sayExportCpp :: SayExportMode -> Export -> Generator ()

sayExportHaskell :: SayExportMode -> Export -> Generator ()

getExportEnumInfo :: Export -> Maybe EnumInfo

getExportExceptionClass :: Export -> Maybe Class

HasExtNames Export

Defined in Foreign.Hoppy.Generator.Spec.Base

Methods

getPrimaryExtName :: Export -> ExtName

getNestedExtNames :: Export -> [ExtName]

HasReqs Export

Defined in Foreign.Hoppy.Generator.Spec.Base

Methods

getReqs :: Export -> Reqs

setReqs :: Reqs -> Export -> Export

modifyReqs :: (Reqs -> Reqs) -> Export -> Export

Basic types

data Type

A concrete C++ type. Use the bindings in Foreign.Hoppy.Generator.Types for values of this type; these data constructors are subject to change without notice.

Constructors

Internal_TVoid

Internal_TPtr Type

Internal_TRef Type

Internal_TFn [Parameter] Type

Internal_TObj Class

Internal_TObjToHeap Class

Internal_TToGc Type

Internal_TManual ConversionSpec

Internal_TConst Type

Instances

Eq Type

Defined in Foreign.Hoppy.Generator.Spec.Base

Methods

(==) :: Type -> Type -> Bool

(/=) :: Type -> Type -> Bool

Show Type

Defined in Foreign.Hoppy.Generator.Spec.Base

Methods

showsPrec :: Int -> Type -> ShowS

show :: Type -> String

showList :: [Type] -> ShowS

IsParameter Type

Defined in Foreign.Hoppy.Generator.Spec.Base

Methods

toParameter :: Type -> Parameter

normalizeType :: Type -> Type

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

stripConst :: Type -> Type

Strips leading Internal_TConsts off of a type.

stripToGc :: Type -> Type

Strips a leading Internal_TToGc off of a type.

data Scoped

Indicates whether an entity is scoped or unscoped.

This is used to distinguish unscoped enums (enum) or scoped ones (enum class or enum struct).

Constructors

Unscoped

Indicates an unscoped entity (e.g. an enum).

Scoped

Indicates a scoped entity (e.g. an enum).

Instances

Eq Scoped

Defined in Foreign.Hoppy.Generator.Spec.Base

Methods

(==) :: Scoped -> Scoped -> Bool

(/=) :: Scoped -> Scoped -> Bool

Ord Scoped

Defined in Foreign.Hoppy.Generator.Spec.Base

Methods

compare :: Scoped -> Scoped -> Ordering

(<) :: Scoped -> Scoped -> Bool

(<=) :: Scoped -> Scoped -> Bool

(>) :: Scoped -> Scoped -> Bool

(>=) :: Scoped -> Scoped -> Bool

max :: Scoped -> Scoped -> Scoped

min :: Scoped -> Scoped -> Scoped

Show Scoped

Defined in Foreign.Hoppy.Generator.Spec.Base

Methods

showsPrec :: Int -> Scoped -> ShowS

show :: Scoped -> String

showList :: [Scoped] -> ShowS

isScoped :: Scoped -> Bool

Returns true if a Scoped value is scoped, and false if it is unscoped.

Functions and parameters

data Constness

Whether or not const is applied to an entity.

Constructors

Nonconst

Const

Instances

Bounded Constness

Defined in Foreign.Hoppy.Generator.Spec.Base

Methods

minBound :: Constness

maxBound :: Constness

Enum Constness

Defined in Foreign.Hoppy.Generator.Spec.Base

Methods

succ :: Constness -> Constness

pred :: Constness -> Constness

toEnum :: Int -> Constness

fromEnum :: Constness -> Int

enumFrom :: Constness -> [Constness]

enumFromThen :: Constness -> Constness -> [Constness]

enumFromTo :: Constness -> Constness -> [Constness]

enumFromThenTo :: Constness -> Constness -> Constness -> [Constness]

Eq Constness

Defined in Foreign.Hoppy.Generator.Spec.Base

Methods

(==) :: Constness -> Constness -> Bool

(/=) :: Constness -> Constness -> Bool

Show Constness

Defined in Foreign.Hoppy.Generator.Spec.Base

Methods

showsPrec :: Int -> Constness -> ShowS

show :: Constness -> String

showList :: [Constness] -> ShowS

constNegate :: Constness -> Constness

Returns the opposite constness value.

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

Defined in Foreign.Hoppy.Generator.Spec.Base

Methods

(==) :: Purity -> Purity -> Bool

(/=) :: Purity -> Purity -> Bool

Show Purity

Defined in Foreign.Hoppy.Generator.Spec.Base

Methods

showsPrec :: Int -> Purity -> ShowS

show :: Purity -> String

showList :: [Purity] -> ShowS

data Parameter

A parameter to a function, including a type and an optional name. A name can be conveniently associated with a type with the (~:) operator.

Two Parameters are equal if their types are equal.

Instances

Show Parameter

Defined in Foreign.Hoppy.Generator.Spec.Base

Methods

showsPrec :: Int -> Parameter -> ShowS

show :: Parameter -> String

showList :: [Parameter] -> ShowS

IsParameter Parameter

Defined in Foreign.Hoppy.Generator.Spec.Base

Methods

toParameter :: Parameter -> Parameter

parameterType :: Parameter -> Type

The parameter's data type.

onParameterType :: (Type -> Type) -> Parameter -> Parameter

Maps a function over a parameter's type.

parameterName :: Parameter -> Maybe String

An optional variable name to describe the parameter. This name should follow the same rules as ExtName for its contents.

class Show a => IsParameter a where

Objects that can be coerced to function parameter definitions.

Methods

toParameter :: a -> Parameter

Instances

IsParameter Parameter

Defined in Foreign.Hoppy.Generator.Spec.Base

Methods

toParameter :: Parameter -> Parameter

IsParameter Type

Defined in Foreign.Hoppy.Generator.Spec.Base

Methods

toParameter :: Type -> Parameter

toParameters :: IsParameter a => [a] -> [Parameter]

Converts a list of parameter-like objects to parameters.

np :: [Parameter]

An empty parameter list. This should be used instead of a literal [] when declaring an empty parameter list, because in the context of IsParameter a => [a], the empty list is ambiguously typed, even though it doesn't matter which instance is selected.

(~:) :: IsParameter a => String -> a -> Parameter infixr 0

Associates a name string with a type to create a Parameter that can be given as a function or method parameter, instead of a raw Type. The name given here will be included as documentation in the generated code.

An empty string given for the name means not to associate a name with the parameter. This is useful to leave some parameters unnamed in a parameter list while naming other parameters, since the list must either contain all Types or all Parameters.

Conversions

data ConversionMethod c

Defines the process for converting a value in one direction between C++ and a foreign language. The type parameter varies depending on the actual conversion being defined.

Constructors

ConversionUnsupported

The conversion is unsupported. If part of an interface depends on performing this conversion, code generation will fail.

BinaryCompatible

The input value and its corresponding output have the same binary representation in memory, and require no explicit conversion. Numeric types may use this conversion method.

CustomConversion c

Conversion requires a custom process as specified by the argument.

TODO Split into pure (let) vs nonpure (<-)?

Instances

Show c => Show (ConversionMethod c)

Defined in Foreign.Hoppy.Generator.Spec.Base

Methods

showsPrec :: Int -> ConversionMethod c -> ShowS

show :: ConversionMethod c -> String

showList :: [ConversionMethod c] -> ShowS

data ConversionSpec

The root data type for specifying how conversions happen between C++ and foreign values.

The Cpp component of this data structure specifies a C++ type, and conversions between it and something that can be marshalled over a C FFI layer, if such a conversion is possible in each direction.

Each foreign language has its own component that must be specified in order for types using this specification to be usable in that language.

Instances

Eq ConversionSpec

Defined in Foreign.Hoppy.Generator.Spec.Base

Methods

(==) :: ConversionSpec -> ConversionSpec -> Bool

(/=) :: ConversionSpec -> ConversionSpec -> Bool

Show ConversionSpec

Defined in Foreign.Hoppy.Generator.Spec.Base

Methods

showsPrec :: Int -> ConversionSpec -> ShowS

show :: ConversionSpec -> String

showList :: [ConversionSpec] -> ShowS

makeConversionSpec

Arguments

:: String

conversionSpecName

-> ConversionSpecCpp

conversionSpecCpp

-> ConversionSpec

Creates a ConversionSpec from an identifying name and a specification of the C++ conversion behaviour. By default, no foreign language conversion behaviour is configured. For Haskell, this should be done by using makeConversionSpecHaskell to specify behaviour, then writing that to the conversionSpecHaskell field of the ConversionSpec returned here.

data ConversionSpecCpp

For a ConversionSpec, defines the C++ type and conversions to and from a C FFI layer.

Prefer makeConversionSpecCpp to using this data constructor directly.

conversionSpecCppName specifies the C++ type of the conversion. This will be the type that is passed over the C FFI as well, unless conversionSpecCppConversionType overrides it. conversionSpecCppConversionToCppExpr and conversionSpecCppConversionFromCppExpr may define custom code generation for passing values over the FFI.

Constructors

ConversionSpecCpp

Fields

• conversionSpecCppName :: String

  The name of the C++ type. May identify a primitive C++ type such as "unsigned int", or a more complex type like std::list<std::string>.

• conversionSpecCppReqs :: Generator Reqs

  Computes requirements to refer to the C++ type. Being in the generator monad, this may use its environment, but should not emit code or Reqs to the generator directly.

• conversionSpecCppConversionType :: Generator (Maybe Type)

  Specifies the type that will be passed over the C FFI.

  If absent (default), then the type named by conversionSpecCppName is also used for marshalling to foreign languages.

  If present, this represents a type distinct from conversionSpecCppName that will be exchanged across the FFI boundary. In this case, you may also want to define one or both of conversionSpecCppConversionToCppExpr and conversionSpecCppConversionFromCppExpr.

  This is a monadic value so that it has access to the generator's environment. The action should not add imports or emit code.

• conversionSpecCppConversionToCppExpr :: Maybe (Generator () -> Maybe (Generator ()) -> Generator ())

  This controls behaviour for receiving a value passed into C++ over the FFI. Specifically, this powers the ConversionSpec being used as Function arguments and Callback return values.

  When absent (default), generated code assumes that it can implicitly convert a value passed over the FFI from the C FFI type (see conversionSpecCppConversionType) to the C++ type (i.e. conversionSpecCppName). When the former is absent, this is always fine.

  When present, this provides custom conversion behaviour for receiving a value passed into C++ over the FFI. The function should generate C++ code to convert a value from the type passed over the C FFI into the actual C++ type.

  This is a function of the form:

  \emitFromExpr maybeEmitToVar -> ...

  If the function's second argument is present, then the function should emit a variable declaration for that name, created from the expression emitted by the first argument.

  If the function's second argument is absent, then the function should emit an expression that converts the expression emitted by the first argument into the appropriate type.

  In both cases, the first generator argument should only be evaluated once by the resulting C++ expression; it is not guaranteed to be pure.

• conversionSpecCppConversionFromCppExpr :: Maybe (Generator () -> Maybe (Generator ()) -> Generator ())

  This is the opposite of conversionSpecCppConversionToCppExpr. This being present enables custom conversion behaviour for passing a value out of C++ through the FFI. This powers the ConversionSpec being used as Function return values and Callback arguments.

makeConversionSpecCpp :: String -> Generator Reqs -> ConversionSpecCpp

Builds a ConversionSpecCpp with a C++ type, with no conversions defined.

data ConversionSpecHaskell

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

Prefer makeConversionSpecHaskell to using this data constructor directly.

Constructors

ConversionSpecHaskell

Fields

• conversionSpecHaskellHsType :: Generator HsType

  The type exposed to users of the Haskell side of a binding. Functions that take one of these values as an argument will expect this type, and functions returning one of these values will return this type.

  This type is wrapped in a generator in order to be able to specify any necessary imports. This generator should not generate code or add exports.

• conversionSpecHaskellHsArgType :: Maybe (HsName -> Generator HsQualType)

  If present, then for bindings for C++ functions that expect one of these values as an argument, rather than taking a fixed concrete type (conversionSpecHaskellHsType), this qualified type will be used instead. The HsName parameter receives a unique name from the generator that can be used with HsTyVar like so:

  \name -> return $ HsQualType [...constraints...] (HsTyVar name)

  conversionSpecHaskellHsType should satisfy this constraint, when present.

  This type is wrapped in a generator in order to be able to specify any necessary imports. This generator should not generate code or add exports.

• conversionSpecHaskellCType :: Maybe (Generator HsType)

  If present, then rather than passing a value of native Haskell type (conversionSpecHaskellHsType) directly over the FFI, this is an intermediate type that will be passed instead. This is needed any time that the former type isn't a simple type that the FFI supports.

  conversionSpecHaskellToCppFn and conversionSpecHaskellFromCppFn marshal values into and out of this type, respsectively.

  This type is wrapped in a generator in order to be able to specify any necessary imports. This generator should not generate code or add exports.

• conversionSpecHaskellToCppFn :: ConversionMethod (Generator ())

  This defines how a Haskell value is passed to C++. If this is CustomConversion, then conversionSpecHaskellCType must be present, and the generator should output a function that takes a value of type conversionSpecHaskellHsType and return a value of conversionSpecHaskellCType.

  If conversionSpecHaskellHsArgType is present, then the function should be able to accept that more general type instead. This is used for bindings that call into C++ functions. This function is still specialized to conversionSpecHaskellHsType when generating code for callback return values.

  The generator should output code and may add imports, but should not add exports.

• conversionSpecHaskellFromCppFn :: ConversionMethod (Generator ())

  This defines how a Haskell value is passed from C++. If this is CustomConversion, then conversionSpecHaskellCType must be present, and the generator should output a function that takes a value of type conversionSpecHaskellCType and return a value of conversionSpecHaskellHsType.

  The generator should output code and may add imports, but should not add exports.

makeConversionSpecHaskell

Arguments

:: Generator HsType

conversionSpecHaskellHsType

-> Maybe (Generator HsType)

conversionSpecHaskellCType

-> ConversionMethod (Generator ())

conversionSpecHaskellToCppFn

-> ConversionMethod (Generator ())

conversionSpecHaskellFromCppFn

-> ConversionSpecHaskell

Builds a ConversionSpecHaskell with the mandatory parameters given.

Exceptions

newtype ExceptionId

Each exception class has a unique exception ID.

Constructors

ExceptionId

Fields

• getExceptionId :: Int

  Internal.

Instances

Eq ExceptionId

Defined in Foreign.Hoppy.Generator.Spec.Base

Methods

(==) :: ExceptionId -> ExceptionId -> Bool

(/=) :: ExceptionId -> ExceptionId -> Bool

Show ExceptionId

Defined in Foreign.Hoppy.Generator.Spec.Base

Methods

showsPrec :: Int -> ExceptionId -> ShowS

show :: ExceptionId -> String

showList :: [ExceptionId] -> ShowS

exceptionCatchAllId :: ExceptionId

The exception ID that represents the catch-all type.

data ExceptionHandler

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

Instances

Eq ExceptionHandler

Defined in Foreign.Hoppy.Generator.Spec.Base

Methods

(==) :: ExceptionHandler -> ExceptionHandler -> Bool

(/=) :: ExceptionHandler -> ExceptionHandler -> Bool

Ord ExceptionHandler

Defined in Foreign.Hoppy.Generator.Spec.Base

Methods

compare :: ExceptionHandler -> ExceptionHandler -> Ordering

(<) :: ExceptionHandler -> ExceptionHandler -> Bool

(<=) :: ExceptionHandler -> ExceptionHandler -> Bool

(>) :: ExceptionHandler -> ExceptionHandler -> Bool

(>=) :: ExceptionHandler -> ExceptionHandler -> Bool

max :: ExceptionHandler -> ExceptionHandler -> ExceptionHandler

min :: ExceptionHandler -> ExceptionHandler -> ExceptionHandler

newtype ExceptionHandlers

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

• exceptionHandlersList :: [ExceptionHandler]

  Extracts the list of exception handlers.

Instances

Semigroup ExceptionHandlers

Defined in Foreign.Hoppy.Generator.Spec.Base

Methods

(<>) :: ExceptionHandlers -> ExceptionHandlers -> ExceptionHandlers

sconcat :: NonEmpty ExceptionHandlers -> ExceptionHandlers

stimes :: Integral b => b -> ExceptionHandlers -> ExceptionHandlers

Monoid ExceptionHandlers

Defined in Foreign.Hoppy.Generator.Spec.Base

Methods

mempty :: ExceptionHandlers

mappend :: ExceptionHandlers -> ExceptionHandlers -> ExceptionHandlers

mconcat :: [ExceptionHandlers] -> ExceptionHandlers

class HandlesExceptions a where

Types that can handle exceptions.

Methods

getExceptionHandlers :: a -> ExceptionHandlers

Extracts the exception handlers for an object.

modifyExceptionHandlers :: (ExceptionHandlers -> ExceptionHandlers) -> a -> a

Modifies an object's exception handlers with a given function.

Instances

HandlesExceptions Module

Defined in Foreign.Hoppy.Generator.Spec.Base

Methods

getExceptionHandlers :: Module -> ExceptionHandlers

modifyExceptionHandlers :: (ExceptionHandlers -> ExceptionHandlers) -> Module -> Module

HandlesExceptions Function

Defined in Foreign.Hoppy.Generator.Spec.Function

Methods

getExceptionHandlers :: Function -> ExceptionHandlers

modifyExceptionHandlers :: (ExceptionHandlers -> ExceptionHandlers) -> Function -> Function

HandlesExceptions Method

Defined in Foreign.Hoppy.Generator.Spec.Class

Methods

getExceptionHandlers :: Method -> ExceptionHandlers

modifyExceptionHandlers :: (ExceptionHandlers -> ExceptionHandlers) -> Method -> Method

HandlesExceptions Ctor

Defined in Foreign.Hoppy.Generator.Spec.Class

Methods

getExceptionHandlers :: Ctor -> ExceptionHandlers

modifyExceptionHandlers :: (ExceptionHandlers -> ExceptionHandlers) -> Ctor -> Ctor

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

Appends additional exception handlers to an object.

Addenda

newtype 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

Semigroup Addendum

Defined in Foreign.Hoppy.Generator.Spec.Base

Methods

(<>) :: Addendum -> Addendum -> Addendum

sconcat :: NonEmpty Addendum -> Addendum

stimes :: Integral b => b -> Addendum -> Addendum

Monoid Addendum

Defined in Foreign.Hoppy.Generator.Spec.Base

Methods

mempty :: Addendum

mappend :: Addendum -> Addendum -> Addendum

mconcat :: [Addendum] -> Addendum

class HasAddendum a where

A typeclass for types that have an addendum.

Minimal complete definition

getAddendum, (setAddendum | modifyAddendum)

Methods

getAddendum :: a -> Addendum

Returns an object's addendum.

setAddendum :: Addendum -> a -> a

Replaces and object's addendum with another.

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

Modified an object's addendum.

Instances

HasAddendum Class

Defined in Foreign.Hoppy.Generator.Spec.Class

Methods

getAddendum :: Class -> Addendum

setAddendum :: Addendum -> Class -> Class

modifyAddendum :: (Addendum -> Addendum) -> Class -> Class

HasAddendum Export

Defined in Foreign.Hoppy.Generator.Spec.Base

Methods

getAddendum :: Export -> Addendum

setAddendum :: Addendum -> Export -> Export

modifyAddendum :: (Addendum -> Addendum) -> Export -> Export

HasAddendum Module

Defined in Foreign.Hoppy.Generator.Spec.Base

Methods

getAddendum :: Module -> Addendum

setAddendum :: Addendum -> Module -> Module

modifyAddendum :: (Addendum -> Addendum) -> Module -> Module

HasAddendum Callback

Defined in Foreign.Hoppy.Generator.Spec.Callback

Methods

getAddendum :: Callback -> Addendum

setAddendum :: Addendum -> Callback -> Callback

modifyAddendum :: (Addendum -> Addendum) -> Callback -> Callback

HasAddendum CppEnum

Defined in Foreign.Hoppy.Generator.Spec.Enum

Methods

getAddendum :: CppEnum -> Addendum

setAddendum :: Addendum -> CppEnum -> CppEnum

modifyAddendum :: (Addendum -> Addendum) -> CppEnum -> CppEnum

HasAddendum Function

Defined in Foreign.Hoppy.Generator.Spec.Function

Methods

getAddendum :: Function -> Addendum

setAddendum :: Addendum -> Function -> Function

modifyAddendum :: (Addendum -> Addendum) -> Function -> Function

HasAddendum Variable

Defined in Foreign.Hoppy.Generator.Spec.Variable

Methods

getAddendum :: Variable -> Addendum

setAddendum :: Addendum -> Variable -> Variable

modifyAddendum :: (Addendum -> Addendum) -> Variable -> Variable

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

Adds a Haskell addendum to an object.

Enum support

data EnumInfo

Structural information about a C++ enum. This is used when Hoppy is evaluating enum data, see getExportEnumInfo.

See CppEnum.

Constructors

EnumInfo

Fields

• enumInfoExtName :: ExtName

  The external name of the enum.

• enumInfoIdentifier :: Identifier

  The enum's identifier.

• enumInfoNumericType :: Maybe Type

  The enum's numeric type, if explicitly known to the bindings. This does not need to be provided. If absent, then Hoppy will calculate the enum's numeric type on its own, using a C++ compiler. If this is present however, Hoppy will use it, and additionally validate it against what the C++ compiler thinks, if validation is enabled (see interfaceValidateEnumTypes).

• enumInfoReqs :: Reqs

  Requirements for accessing the enum.

• enumInfoScoped :: Scoped

  Whether the enum is scoped or unscoped.

• enumInfoValues :: EnumValueMap

  The entries in the enum.

type EnumEntryWords = [String]

A list of words that comprise the name of an enum entry. Each string in this list is treated as a distinct word for the purpose of performing case conversion to create identifiers in foreign languages. These values are most easily created from a C++ identifier using splitIntoWords.

data EnumValueMap

Describes the entries in a C++ enum.

Equality is defined as having the same enumValueMapValues.

Constructors

EnumValueMap

Fields

• enumValueMapNames :: [EnumEntryWords]

  The names of all entries in the enum being generated, in the order specified by the enum definition. These are the strings used to name generated bindings. Each name is broken up into words. How the words and get combined to make a name in a particular foreign language depends on the language.

• enumValueMapForeignNames :: MapWithForeignLanguageOverrides EnumEntryWords EnumEntryWords

  Per-language renames of enum value entries.

• enumValueMapValues :: Map EnumEntryWords EnumValue

  A map specifying for each entry in enumValueMapNames, how to determine the entry's numeric value.

Instances

Eq EnumValueMap

Defined in Foreign.Hoppy.Generator.Spec.Base

Methods

(==) :: EnumValueMap -> EnumValueMap -> Bool

(/=) :: EnumValueMap -> EnumValueMap -> Bool

Show EnumValueMap

Defined in Foreign.Hoppy.Generator.Spec.Base

Methods

showsPrec :: Int -> EnumValueMap -> ShowS

show :: EnumValueMap -> String

showList :: [EnumValueMap] -> ShowS

data EnumValue

Describes the value of an entry in a C++ enum. A numeric value may either be provided manually, or if omitted, Hoppy can determine it automatically.

Constructors

EnumValueManual Integer

A manually specified numeric enum value.

EnumValueAuto Identifier

A numeric enum value that will be determined when the generator is run, by means of compiling a C++ program.

Instances

Eq EnumValue

Defined in Foreign.Hoppy.Generator.Spec.Base

Methods

(==) :: EnumValue -> EnumValue -> Bool

(/=) :: EnumValue -> EnumValue -> Bool

Show EnumValue

Defined in Foreign.Hoppy.Generator.Spec.Base

Methods

showsPrec :: Int -> EnumValue -> ShowS

show :: EnumValue -> String

showList :: [EnumValue] -> ShowS

Languages

data ForeignLanguage

Languages that Hoppy supports binding to. Currently this is only Haskell.

Constructors

Haskell

The Haskell language.

Instances

Eq ForeignLanguage

Defined in Foreign.Hoppy.Generator.Spec.Base

Methods

(==) :: ForeignLanguage -> ForeignLanguage -> Bool

(/=) :: ForeignLanguage -> ForeignLanguage -> Bool

Ord ForeignLanguage

Defined in Foreign.Hoppy.Generator.Spec.Base

Methods

compare :: ForeignLanguage -> ForeignLanguage -> Ordering

(<) :: ForeignLanguage -> ForeignLanguage -> Bool

(<=) :: ForeignLanguage -> ForeignLanguage -> Bool

(>) :: ForeignLanguage -> ForeignLanguage -> Bool

(>=) :: ForeignLanguage -> ForeignLanguage -> Bool

max :: ForeignLanguage -> ForeignLanguage -> ForeignLanguage

min :: ForeignLanguage -> ForeignLanguage -> ForeignLanguage

Show ForeignLanguage

Defined in Foreign.Hoppy.Generator.Spec.Base

Methods

showsPrec :: Int -> ForeignLanguage -> ShowS

show :: ForeignLanguage -> String

showList :: [ForeignLanguage] -> ShowS

type WithForeignLanguageOverrides = WithOverrides ForeignLanguage

A value that may be overridden based on a ForeignLanguage.

type MapWithForeignLanguageOverrides = MapWithOverrides ForeignLanguage

A map whose values may be overridden based on a ForeignLanguage.

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

Defined in Foreign.Hoppy.Generator.Spec.Base

Methods

showsPrec :: Int -> HsImportSet -> ShowS

show :: HsImportSet -> String

showList :: [HsImportSet] -> ShowS

Semigroup HsImportSet

Defined in Foreign.Hoppy.Generator.Spec.Base

Methods

(<>) :: HsImportSet -> HsImportSet -> HsImportSet

sconcat :: NonEmpty HsImportSet -> HsImportSet

stimes :: Integral b => b -> HsImportSet -> HsImportSet

Monoid HsImportSet

Defined in Foreign.Hoppy.Generator.Spec.Base

Methods

mempty :: HsImportSet

mappend :: HsImportSet -> HsImportSet -> HsImportSet

mconcat :: [HsImportSet] -> 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

Defined in Foreign.Hoppy.Generator.Spec.Base

Methods

(==) :: HsImportKey -> HsImportKey -> Bool

(/=) :: HsImportKey -> HsImportKey -> Bool

Ord HsImportKey

Defined in Foreign.Hoppy.Generator.Spec.Base

Methods

compare :: HsImportKey -> HsImportKey -> Ordering

(<) :: HsImportKey -> HsImportKey -> Bool

(<=) :: HsImportKey -> HsImportKey -> Bool

(>) :: HsImportKey -> HsImportKey -> Bool

(>=) :: HsImportKey -> HsImportKey -> Bool

max :: HsImportKey -> HsImportKey -> HsImportKey

min :: HsImportKey -> HsImportKey -> HsImportKey

Show HsImportKey

Defined in Foreign.Hoppy.Generator.Spec.Base

Methods

showsPrec :: Int -> HsImportKey -> ShowS

show :: HsImportKey -> String

showList :: [HsImportKey] -> ShowS

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

Defined in Foreign.Hoppy.Generator.Spec.Base

Methods

showsPrec :: Int -> HsImportSpecs -> ShowS

show :: HsImportSpecs -> String

showList :: [HsImportSpecs] -> ShowS

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

Defined in Foreign.Hoppy.Generator.Spec.Base

Methods

showsPrec :: Int -> HsImportVal -> ShowS

show :: HsImportVal -> String

showList :: [HsImportVal] -> ShowS

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

interfaceAllExceptionClasses :: Interface -> [Class]

Returns all of the exception classes in an interface.

interfaceSharedPtr :: Interface -> (Reqs, String)

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.

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.

hsImportForException :: HsImportSet

Imports Control.Exception qualified as HoppyCE.

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.

hsImportForMap :: HsImportSet

Imports Data.Map qualified as HoppyDM.

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

objToHeapTWrongDirectionErrorMsg :: Maybe String -> Class -> String

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

tToGcInvalidFormErrorMessage :: Maybe String -> Type -> String

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

toGcTWrongDirectionErrorMsg :: Maybe String -> Type -> String

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

module Foreign.Hoppy.Generator.Spec.Callback

module Foreign.Hoppy.Generator.Spec.Class

module Foreign.Hoppy.Generator.Spec.ClassFeature

module Foreign.Hoppy.Generator.Spec.Computed

Advanced class conversions

classSetConversionToHeap :: Class -> Class

Modifies a class's ClassConversion structure by setting all languages to copy objects to the heap when being passed out of C++. Lifetimes of the resulting objects must be managed by code in the foreign language.

Calling this on a class makes objT behave like objToHeapT for values being passed out of C++.

classSetConversionToGc :: Class -> Class

Modifies a class's ClassConversion structure by setting all languages that support garbage collection to copy objects to the heap when being passed out of C++, and put those objects under the care of the foreign language's garbage collector.

Calling this on a class makes objT behave like toGcT for values being passed out of C++.

module Foreign.Hoppy.Generator.Spec.Enum

module Foreign.Hoppy.Generator.Spec.Function

module Foreign.Hoppy.Generator.Spec.Variable