Safe Haskell | None |
---|---|
Language | Haskell2010 |
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.
Synopsis
- data CppEnum
- enumT :: CppEnum -> Type
- makeEnum :: Identifier -> Maybe ExtName -> [(Integer, EnumEntryWords)] -> CppEnum
- makeAutoEnum :: IsAutoEnumValue v => Identifier -> Maybe ExtName -> Scoped -> [v] -> CppEnum
- class IsAutoEnumValue a where
- toAutoEnumValue :: a -> (EnumEntryWords, String)
- enumExtName :: CppEnum -> ExtName
- enumIdentifier :: CppEnum -> Identifier
- enumNumericType :: CppEnum -> Maybe Type
- enumSetNumericType :: Maybe Type -> CppEnum -> CppEnum
- enumValues :: CppEnum -> EnumValueMap
- enumReqs :: CppEnum -> Reqs
- enumAddendum :: CppEnum -> Addendum
- enumValuePrefix :: CppEnum -> String
- enumSetValuePrefix :: String -> CppEnum -> CppEnum
- enumAddEntryNameOverrides :: IsAutoEnumValue v => ForeignLanguage -> [(v, v)] -> CppEnum -> CppEnum
- enumGetOverriddenEntryName :: ForeignLanguage -> CppEnum -> EnumEntryWords -> EnumEntryWords
- class IsEnumUnknownValueEntry a where
- enumUnknownValueEntry :: CppEnum -> Maybe EnumEntryWords
- enumSetUnknownValueEntry :: IsEnumUnknownValueEntry a => a -> CppEnum -> CppEnum
- enumSetNoUnknownValueEntry :: CppEnum -> CppEnum
- enumUnknownValueEntryDefault :: EnumEntryWords
- enumHasBitOperations :: CppEnum -> Bool
- enumSetHasBitOperations :: Bool -> CppEnum -> CppEnum
- cppGetEvaluatedEnumData :: HasCallStack => ExtName -> Generator EvaluatedEnumData
- hsGetEvaluatedEnumData :: HasCallStack => ExtName -> Generator EvaluatedEnumData
- toHsEnumTypeName :: CppEnum -> Generator String
- toHsEnumTypeName' :: CppEnum -> String
- toHsEnumCtorName :: CppEnum -> EnumEntryWords -> Generator String
- toHsEnumCtorName' :: CppEnum -> EnumEntryWords -> String
Data type
A C++ enum declaration.
See EnumInfo
.
Instances
Eq CppEnum Source # | |
Show CppEnum Source # | |
HasAddendum CppEnum Source # | |
Defined in Foreign.Hoppy.Generator.Spec.Enum | |
Exportable CppEnum Source # | |
Defined in Foreign.Hoppy.Generator.Spec.Enum toExport :: CppEnum -> Export Source # castExport :: (Typeable CppEnum, Exportable b, Typeable b) => CppEnum -> Maybe b Source # sayExportCpp :: SayExportMode -> CppEnum -> Generator () Source # sayExportHaskell :: SayExportMode -> CppEnum -> Generator () Source # | |
HasExtNames CppEnum Source # | |
Defined in Foreign.Hoppy.Generator.Spec.Enum getPrimaryExtName :: CppEnum -> ExtName Source # getNestedExtNames :: CppEnum -> [ExtName] Source # | |
HasReqs CppEnum Source # | |
Construction
:: Identifier | |
-> 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 |
-> 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
.
:: IsAutoEnumValue v | |
=> Identifier | |
-> Maybe ExtName | An optional external name; will be automatically derived from the identifier if absent. |
-> Scoped | Is the enum scoped ( |
-> [v] | A list of enum entries to calculate and generate bindings for. See
|
-> 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 temporary, autogenerated C++ helper program.
This helper program needs to be able to access the C++ declaration of the
enum. In addition to any includeStd
or includeLocal
requirements added
to the enum for the generated C++ bindings to use, the interface's compiler
(interfaceCompiler
) will need to be able to use these includes to access
the enum from C++ file built in a temporary directory. To add -I
arguments
or otherwise change the compiler, you can reconfigure the interface:
myInterface =interfaceSetCompiler
(prependArguments ["-I" ++ pathToIncludes] defaultCompiler) $interface
...
class IsAutoEnumValue a where Source #
Represents a mapping to an automatically evaluated C++ enum entry.
The (
instance is the canonical one, with
EnumEntryWords
, String)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 bindings' entry names.
The String
instance takes the C++ name of the entry, and splits it into
words via splitIntoWords
.
toAutoEnumValue :: a -> (EnumEntryWords, String) Source #
Instances
IsAutoEnumValue String Source # | |
Defined in Foreign.Hoppy.Generator.Spec.Enum toAutoEnumValue :: String -> (EnumEntryWords, String) Source # | |
IsAutoEnumValue (EnumEntryWords, String) Source # | |
Defined in Foreign.Hoppy.Generator.Spec.Enum toAutoEnumValue :: (EnumEntryWords, String) -> (EnumEntryWords, String) Source # |
Properties
enumExtName :: CppEnum -> ExtName Source #
The enum's external name.
enumIdentifier :: CppEnum -> Identifier Source #
The identifier used to refer to the enum.
enumNumericType :: CppEnum -> Maybe Type Source #
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 Source #
Sets an explicit numeric type for the enum. See enumNumericType
.
enumValues :: CppEnum -> EnumValueMap Source #
The numeric values and names of the enum entires.
enumReqs :: CppEnum -> Reqs Source #
Requirements for bindings to access this enum. Currently unused, but will be in the future.
enumAddendum :: CppEnum -> Addendum Source #
The enum's addendum.
enumValuePrefix :: CppEnum -> String Source #
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 Source #
Sets the prefix applied to the names of enum values' identifiers in foreign languages.
See enumValuePrefix
.
enumAddEntryNameOverrides :: IsAutoEnumValue v => ForeignLanguage -> [(v, v)] -> CppEnum -> CppEnum Source #
Adds overrides for some of an enum's entry names, in a specific language.
enumGetOverriddenEntryName :: ForeignLanguage -> CppEnum -> EnumEntryWords -> EnumEntryWords Source #
Retrieves the name for an enum entry in a specific foreign language.
class IsEnumUnknownValueEntry a where Source #
Values that can be used as a name for an enum's unknown value entry. See
enumUnknownValueEntry
.
toEnumUnknownValueEntry :: a -> EnumEntryWords Source #
Converts a value to a list of words to use for an enum's unknown entry name.
Instances
enumUnknownValueEntry :: CppEnum -> Maybe EnumEntryWords Source #
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 Source #
Sets the entry name (a list of words, a la the fields in EnumValueMap
)
for the fallback enum entry that holds unknown values.
enumSetNoUnknownValueEntry :: CppEnum -> CppEnum Source #
Sets an enum to have no unknown value entry.
enumUnknownValueEntryDefault :: EnumEntryWords Source #
The default value for enumUnknownValueEntry
. This is ["Unknown"]
.
enumHasBitOperations :: CppEnum -> Bool Source #
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 Source #
Sets whether generated bindings will support bitwise operations on the enum.
See enumHasBitOperations
.
C++ generator
cppGetEvaluatedEnumData :: HasCallStack => ExtName -> Generator EvaluatedEnumData Source #
Reads evaluated data for the named enum from the C++ generator environment.
Haskell generator
hsGetEvaluatedEnumData :: HasCallStack => ExtName -> Generator EvaluatedEnumData Source #
Reads evaluated data for the named enum from the Haskell generator environment.
Names
toHsEnumTypeName :: CppEnum -> Generator String Source #
Returns the Haskell name for an enum.
TODO Clarify, and split into type and data ctor names.
toHsEnumTypeName' :: CppEnum -> String Source #
Pure version of toHsEnumTypeName
that doesn't create a qualified name.
toHsEnumCtorName :: CppEnum -> EnumEntryWords -> Generator String Source #
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 Source #
Pure version of toHsEnumCtorName
that doesn't create a qualified name.