Values of Mercury enumeration types can be made available to code in the bodies of ‘foreign_proc’ and ‘foreign_code’ pragmas via a declaration of the form:
:- pragma foreign_export_enum("Lang", MercuryType, Attributes, Overrides).
This causes the compiler to create a symbolic name in language Lang for each of the constructors of MercuryType. The symbolic name allows the foreign code to create a value corresponding to that of the constructor it represents. (The exact mechanism used depends upon the foreign language; see the language specific information below for further details.)
For each foreign language there is a default mapping between the name of a Mercury constructor and its symbolic name in the language Lang. This default mapping is not required to map every valid constructor name to a valid name in language Lang; where it does not the programmer must specify a valid symbolic name. The programmer may also choose to map a constructor to a symbolic name that differs from the one supplied by the default mapping for language Lang. Overrides is a list whose elements are pairs of constructor names and strings. The latter specify the name that the implementation should use as the symbolic name in the foreign language. Overrides has the following form:
[cons_I - "symbol_I", …, cons_J - "symbol_J"]
This can be used to provide either a valid symbolic name where the default mapping does not, or to override a valid symbolic name generated by the default mapping. This argument may be omitted if Overrides is empty.
The argument Attributes is a list of optional attributes. If empty, it may be omitted from the ‘pragma foreign_export_enum’ declaration if the Overrides argument is also omitted. The following attributes must be supported by all Mercury implementations.
Prefix each symbolic name, regardless of how it was generated, with the string Prefix. At most one ‘prefix’ attribute may be specified for a ‘pragma foreign_export_enum’ declaration.
Convert any alphabetic characters in a Mercury constructor name to uppercase when generating the symbolic name using the default mapping. Symbolic names specified by the programmer using Overrides are not affected by this attribute. If the ‘prefix’ attribute is also specified, then the prefix is added to the symbolic name after the conversion to uppercase has been performed, i.e. the characters in the prefix are not affected by the ‘uppercase’ attribute.
The implementation does not check the validity of a symbolic name in the foreign language until after the effects of any attributes have been applied. This means that attributes may cause an otherwise valid symbolic name to become invalid or vice versa.
It is an error if the mapping between constructors and symbolic names does not form a bijection. A program can contain multiple ‘pragma foreign_export_enum’ declarations for a single Mercury type. The implementation is not required to check that the symbolic names generated by separate ‘pragma foreign_export_enum’ declarations are unique.
A module may contain ‘pragma foreign_export_enum’ declarations that refer to imported types, subject to the usual visibility restrictions.
A ‘pragma foreign_export_enum’ declaration may only occur in the implementation section of a module.