[m-rev.] for post-commit review: doc of foreign_enum and foreign_export_enum

[Julien Fischer]

Hi Zoltan,

On Thu, 30 Nov 2017, Zoltan Somogyi wrote:

> For post commit review by anyone.
>
> By the way, what is the situation with foreign_enums for Erlang?
> Section 14.9.4 should have subsection on foreign_enums, but it doesn't.

I'm not sure. Peter?

> diff --git a/doc/reference_manual.texi b/doc/reference_manual.texi
> index e14ff94..58ac2eb 100644
> --- a/doc/reference_manual.texi
> +++ b/doc/reference_manual.texi
> @@ -7667,15 +7667,69 @@ compatibility is described in the language specific information below.
>  @node Using foreign enumerations in Mercury code
>  @section Using foreign enumerations in Mercury code
> 
> -The values used to represent a Mercury enumeration type in a foreign
> -language may be explicitly assigned by the programmer using a declaration
> -of the form:
> +While a @samp{pragma foreign_type} declaration
> +imports a foreign @emph{type} into Mercury,
> +a @samp{pragma foreign_enum} declaration
> +imports @emph{the values of the constants of an enumeration type} into Mercury.

We should probably define what is meant by an "enumeration type" in Mercury,
since we don't appear to do so anywhere. (e.g. it's a discriminated union
type whose data constructors all have no arguments.)

> +Given an enumeration type such as
> + at example
> +:- type unix_file_permissions
> +    --->    user_read
> +    ;       user_write
> +    ;       user_executable
> +    ;       group_read
> +    ;       group_write
> +    ;       group_executable
> +    ;       other_read
> +    ;       other_write
> +    ;       other_executable.
> + at end example
> +
> +the values used to represent each constant
> +are usually decided by the Mercury compiler.
> +However, the values assigned this way
> +may not match the values expected by foreign language code
> +that uses values of the enumeration,
> +and even if they happen to match,
> +programmers probably would not want to @emph{rely} on this coincidence.
> +
> +This is why Mercury supports a mechanism that allows programmers
> +to specify the representation of each constant in an enumeration type
> +when generating code for a given target language.
> +This mechanism is the @samp{pragma foreign_enum} declaration,
> +which looks like this:
> +
> + at example
> + at group
> +:- pragma foreign_enum("C", unix_file_permissions,

That doesn't compile; the second argument requires the arity
to be given as well.

> +[
> +    user_read        - "S_IRUSR",
> +    user_write       - "S_IWUSR",
> +    user_executable  - "S_IXUSR",
> +    group_read       - "S_IRGRP",
> +    group_write      - "S_IWGRP",
> +    group_executable - "S_IXGRP",
> +    other_read       - "S_IROTH",
> +    other_write      - "S_IWOTH",
> +    other_executable - "S_IXOTH"
> +]).
> + at end group
> + at end example
> +
> +(Unix systems have a standard header file
> +that defines each of @samp{S_IRUSR}, @dots{}, @samp{S_IXOTH}
> +as macros that each expand to an integer constant;
> +these constants happen @emph{not} to be the ones
> +that the Mercury compiler would assign to those constants.)
> +
> +The general form of @samp{pragma foreign_enum} declarations is
>
>  @example
>  :- pragma foreign_enum("@var{Lang}", @var{MercuryType}, @var{CtorValues}).
>  @end example
> 
> - at var{CtorValues} is a list of pairs of the form:
> +where @var{CtorValues} is a list of pairs of the form:
>
>  @example
>  @group
> @@ -7688,74 +7742,96 @@ of the form:
>  @end group
>  @end example
> 
> -The first element of each pair is a constructor of the type @var{MercuryType},
> -and the second is a value in the language @var{Lang} that will be used
> -to represent that constructor.
> -The mapping defined by this list of pairs must form a bijection.
> +The first element of each pair
> +is a constant (function symbol of arity 0) of the type @var{MercuryType},
> +and the second is either a numeric or a symbolic name
> +for the integer value in the language @var{Lang}
> +that the programmer wants to be used to represent that constructor.
> 
> -Mercury implementations may impose further foreign language-specific 
> -restrictions on the form that values used to represent enumeration
> -constructors may take.
> +The mapping defined by this list of pairs must form a bijection,
> +i.e. the list must map distinct constructors to distinct values,
> +and vice versa.
> +The Mercury compiler is not required to check this, because it can't;

s/can't/cannot/

> +even if two symbolic names (such as C macros) are distinct,
> +they may expand to the same integer in the target language.

The diff looks fine otherwise.

Julien.