Foreign.Hoppy.Generator.Spec.Enum

Interface for defining bindings to C++ enumerations.

In generated Haskell code:

An enum gets a single algebraic data type with data constructors for each of the values defined in the interface. If the enum has an unknown value name defined, then an additional data constructor is generated that holds a numeric value, and this constructor is used whenever numeric values for which no name is explicitly defined are encountered (otherwise, error is called).

From the runtime module, a CppEnum instance is generated for the type, and if the enum is declared to permit bit operations, then a Bits instance is also generated. Eq and Ord instances are generated that compare numeric values.

Data type

data CppEnum

A C++ enum declaration.

See EnumInfo.

Instances

Eq CppEnum

Defined in Foreign.Hoppy.Generator.Spec.Enum

Methods

(==) :: CppEnum -> CppEnum -> Bool

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

Show CppEnum

Defined in Foreign.Hoppy.Generator.Spec.Enum

Methods

showsPrec :: Int -> CppEnum -> ShowS

show :: CppEnum -> String

showList :: [CppEnum] -> ShowS

HasAddendum CppEnum

Defined in Foreign.Hoppy.Generator.Spec.Enum

Methods

getAddendum :: CppEnum -> Addendum

setAddendum :: Addendum -> CppEnum -> CppEnum

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

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

HasExtNames CppEnum

Defined in Foreign.Hoppy.Generator.Spec.Enum

Methods

getPrimaryExtName :: CppEnum -> ExtName

getNestedExtNames :: CppEnum -> [ExtName]

HasReqs CppEnum

Defined in Foreign.Hoppy.Generator.Spec.Enum

Methods

getReqs :: CppEnum -> Reqs

setReqs :: Reqs -> CppEnum -> CppEnum

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

enumT :: CppEnum -> Type

Constructs a type value for an enum.

Construction

makeEnum

Arguments

:: Identifier

enumIdentifier

-> Maybe ExtName

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

-> [(Integer, EnumEntryWords)]

A list of (numeric value, symbolic name) pairs describing enum entries to generate bindings for. Each symbolic name is a list of words, which will be combined into a single identifier of appropriate naming style for the target language (title case, for Haskell) with enumValuePrefix prepended.

-> CppEnum

Creates a binding for a C++ enum.

The numeric values of each of the enum's entries must be specified manually using this function. To have these determined automatically, instead use makeAutoEnum.

makeAutoEnum

Arguments

:: IsAutoEnumValue v

=> Identifier

enumIdentifier

-> Maybe ExtName

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

-> Bool

Is the enum scoped (enum class or enum struct)? That is, are its entries scoped underneath its name, rather than being at the same level as its name (as with just enum).

-> [v]

A list of enum entries to calculate and generate bindings for. See IsAutoEnumValue.

-> CppEnum

Creates a binding for a C++ enum.

An enum created using this function will determine its entries' numeric values automatically when the generator is run, by compiling a C++ program.

class IsAutoEnumValue a where

Represents a mapping to an automatically evaluated C++ enum entry.

The (EnumEntryWords, String) instance is the canonical one, with toAutoEnumValue defined as id. The string on the right is the C++ name of the entry, and the list of strings on the left are the words from which to generate foreign binding's entries.

The String instance takes the C++ name of the entry, and splits it into words via splitIntoWords.

Methods

toAutoEnumValue :: a -> (EnumEntryWords, String)

Instances

IsAutoEnumValue String

Defined in Foreign.Hoppy.Generator.Spec.Enum

Methods

toAutoEnumValue :: String -> (EnumEntryWords, String)

IsAutoEnumValue (EnumEntryWords, String)

Defined in Foreign.Hoppy.Generator.Spec.Enum

Methods

toAutoEnumValue :: (EnumEntryWords, String) -> (EnumEntryWords, String)

Properties

enumExtName :: CppEnum -> ExtName

The enum's external name.

enumIdentifier :: CppEnum -> Identifier

The identifier used to refer to the enum.

enumNumericType :: CppEnum -> Maybe Type

An optional, explicit numeric type provided for the enum's values, that matches what the C++ compiler uses. Hoppy will use Hooks to compute this automatically, if not given manually. This does not need to be provided. If absent (default), 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).

enumSetNumericType :: Maybe Type -> CppEnum -> CppEnum

Sets an explicit numeric type for the enum. See enumNumericType.

enumValues :: CppEnum -> EnumValueMap

The numeric values and names of the enum entires.

enumReqs :: CppEnum -> Reqs

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

enumAddendum :: CppEnum -> Addendum

The enum's addendum.

enumValuePrefix :: CppEnum -> String

The prefix applied to value names (enumValues) 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

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

See enumValuePrefix.

enumAddEntryNameOverrides :: IsAutoEnumValue v => ForeignLanguage -> [(v, v)] -> CppEnum -> CppEnum

Adds overrides for some of an enum's entry names, in a specific language.

enumGetOverriddenEntryName :: ForeignLanguage -> CppEnum -> EnumEntryWords -> EnumEntryWords

Retrieves the name for an enum entry in a specific foreign language.

class IsEnumUnknownValueEntry a where

Values that can be used as a name for an enum's unknown value entry. See enumUnknownValueEntry.

Methods

toEnumUnknownValueEntry :: a -> EnumEntryWords

Converts a value to a list of words to use for an enum's unknown entry name.

Instances

IsEnumUnknownValueEntry String

Defined in Foreign.Hoppy.Generator.Spec.Enum

Methods

toEnumUnknownValueEntry :: String -> EnumEntryWords

IsEnumUnknownValueEntry EnumEntryWords

Defined in Foreign.Hoppy.Generator.Spec.Enum

Methods

toEnumUnknownValueEntry :: EnumEntryWords -> EnumEntryWords

enumUnknownValueEntry :: CppEnum -> Maybe EnumEntryWords

A name (a list of words, a la the fields in EnumValueMap) for an optional fallback enum "entry" in generated bindings for holding unknown values. See enumUnknownValueEntryDefault.

When this is a Just, then the generated foreign binding gets an extra entry that takes an argument holding an arbitrary numeric value (an extra data constructor in Haskell), and this value is used whenever an unknown value is seen.

When this is Nothing, the enum will not support unknown values. toCppEnum in the Foreign.Hoppy.Runtime.CppEnum typeclass, as well as calls or returns from C++ that pass a value not defined in the interface, will raise an error.

Enums that have this set to Nothing should also have enumHasBitOperations set to false, to avoid potential errors at runtime; see that function's documentation.

The enumValuePrefix applies to this name, just as it does to other enum entries.

enumSetUnknownValueEntry :: IsEnumUnknownValueEntry a => a -> CppEnum -> CppEnum

Sets the entry name (a list of words, a la the fields in EnumValueMap) for the fallback enum entry that holds unknown values.

Set enumUnknownValueEntry, enumSetNoUnknownValueEntry.

enumSetNoUnknownValueEntry :: CppEnum -> CppEnum

Sets an enum to have no unknown value entry.

Set enumUnknownValueEntry, enumSetUnknownValueEntry.

enumUnknownValueEntryDefault :: EnumEntryWords

The default value for enumUnknownValueEntry. This is ["Unknown"].

enumHasBitOperations :: CppEnum -> Bool

Whether generated bindings should support bitwise operations on the enum. This defaults to true.

It is not recommended to disable the unknown value entry (enumUnknownValueEntry) while having this be true, because any computation involving enum values not explicitly defined will cause a runtime error. This includes undefined combinations of defined values.

enumSetHasBitOperations :: Bool -> CppEnum -> CppEnum

Sets whether generated bindings will support bitwise operations on the enum.

See enumHasBitOperations.

C++ generator

cppGetEvaluatedEnumData :: HasCallStack => ExtName -> Generator EvaluatedEnumData

Reads evaluated data for the named enum from the C++ generator environment.

Haskell generator

hsGetEvaluatedEnumData :: HasCallStack => ExtName -> Generator EvaluatedEnumData

Reads evaluated data for the named enum from the Haskell generator environment.

Names

toHsEnumTypeName :: CppEnum -> Generator String

Returns the Haskell name for an enum.

TODO Clarify, and split into type and data ctor names.

toHsEnumTypeName' :: CppEnum -> String

Pure version of toHsEnumTypeName that doesn't create a qualified name.

toHsEnumCtorName :: CppEnum -> EnumEntryWords -> Generator String

Constructs the data constructor name for a value in an enum. Like C++ and unlike say Java, Haskell enum values aren't in a separate enum-specific namespace, so we prepend the enum name to the value name to get the data constructor name. The value name is a list of words.

toHsEnumCtorName' :: CppEnum -> EnumEntryWords -> String

Pure version of toHsEnumCtorName that doesn't create a qualified name.