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

Indicates strings that are error messages.

Optional parameters when constructing an Interface with interface.

Options used by interface. This contains no exception handlers.

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

Same as interface, but accepts some optional arguments.

The textual name of the interface.

All of the individual modules, by moduleName.

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

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.

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

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

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

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

Exceptions that all functions in the interface may throw.

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

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

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

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.

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

An #include directive in a C++ file.

Creates an #include <...> directive.

Creates an #include "..." directive.

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

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

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

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

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

All of the exports in a module.

Module-level requirements.

Exceptions that all functions in the module may throw.

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

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

The module's addendum.

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

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

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

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.

Replaces a module's moduleHppPath.

Replaces a module's moduleCppPath.

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.

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

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.

The includes specified by a Reqs.

Creates a Reqs that contains the given include.

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

Adds to a object's requirements.

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

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.

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

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

Returns the string an an ExtName contains.

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

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

The C++ name of a function or method.

Enables implementing automatic conversions to a FnName t.

Overloadable C++ operators.

The arity and syntax of an operator.

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

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

Returns the type of an operator.

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

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

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 separate parts of the identifier, between ::s.

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

The name within the enclosing scope.

Template arguments, if present.

Creates an identifier of the form a.

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

Creates an identifier of the form a::b.

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

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

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

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

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

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

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

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

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

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

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

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.

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

Strips leading Internal_TConsts off of a type.

A C++ variable.

Creates a binding for a C++ variable.

The identifier used to refer to the variable.

The variable's external name.

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

Requirements for bindings to use this variable.

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

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

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

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.

Creates a binding for a C++ enum.

The identifier used to refer to the enum.

The enum's external name.

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.

Requirements for a Type to reference this enum.

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.

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

See enumValuePrefix.

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.

Creates a binding for a C++ bitspace.

The bitspace's external name.

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

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

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

Associates an enum with the bitspace. See bitspaceEnum.

The optional C++ type for a bitspace.

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

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

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.

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.

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.

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

See enumValuePrefix.

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.

A C++ function declaration.

Creates a binding for a C++ function.

The identifier used to call the function.

The function's external name.

Whether the function is pure.

The function's parameter types.

The function's return type.

Requirements for a binding to call the function.

Exceptions that the function might throw.

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.

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

The identifier used to refer to the class.

The class's external name.

The class's public superclasses.

The class's entities.

Adds constructors to a class.

Returns all of the class's variables.

Returns all of the class's constructors.

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

The class's methods.

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

Behaviour for converting objects to and from foriegn values.

Requirements for a Type to reference this class.

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.

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

See IsClassEntity and classEntityPrefix.

This is true for classes passed through classSetMonomorphicSuperclass.

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.

This is true for classes passed through classSetSubclassOfMonomorphic.

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.

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

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

A C++ entity that belongs to a class.

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.

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.

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.

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.

A C++ member variable.

Creates a ClassVariable with full generality and manual name specification.

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

The unwrapped version of makeClassVariable.

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

The unwrapped version of mkClassVariable.

Same as mkClassVariable, but returns a static variable instead.

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

The unwrapped version of mkStaticClassVariable.

The variable's C++ name.

The variable's external name.

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

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

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

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

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

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

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

A C++ class constructor declaration.

Creates a Ctor with full generality.

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

The unwrapped version of makeCtor.

mkCtor name creates a Ctor whose external name is className_name.

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

The unwrapped version of mkCtor.

The constructor's external name.

The constructor's parameter types.

Exceptions that the constructor may throw.

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

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

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

Whether or not a method is const.

Returns the opposite constness value.

Whether or not a method is static.

Creates a Method with full generality and manual name specification.

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

The unwrapped version of makeMethod.

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

The unwrapped version of makeFnMethod.

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

The unwrapped version of mkMethod.

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

The unwrapped version of mkMethod'.

Same as mkMethod, but returns an MConst method.

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

The unwrapped version of mkConstMethod.

Same as mkMethod', but returns an MConst method.

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

The unwrapped version of mkConstMethod'.

Same as mkMethod, but returns an MStatic method.

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

The unwrapped version of mkStaticMethod.

Same as mkMethod', but returns an MStatic method.

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

The unwrapped version of mkStaticMethod'.

A "property" getter/setter pair.

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

The unwrapped version of mkProp.

Creates a getter/setter binding pair for static methods:

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

The unwrapped version of mkStaticProp.

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