[m-dev.] for discussion: foreign_export_enum syntax

[Julien Fischer]

I have been working on the change to allow Mercury enumeration constants
to be exported to foreign languages.  The majority of the changes to
the compiler were made last year; what remains undecided is the
concrete syntax.  Below is change to the reference manual that describes
the current version of this new feature.  Here is a small example of
how it would look and work in the case where C is the foreign language.

Example
-------

:- type foo
 		--->	foo
 		;		bar
 		;		baz.

 	:- pragma foreign_export_enum("C", foo, [bar - "BAR],
 		[prefix("MR_"]).

would cause the following declaration to be generated in the .mh file.

 	enum {
 			MR_foo = 0,
 			MR_BAR = 1,
 			MR_baz = 2
 	};

(The following diff does not yet contain the language specific information
for pragma foreign_export_enum.)

Any comments or suggestions welcome.

Julien.

Index: reference_manual.texi
===================================================================
RCS file: /home/mercury1/repository/mercury/doc/reference_manual.texi,v
retrieving revision 1.397
diff -u -r1.397 reference_manual.texi
--- reference_manual.texi	12 Jun 2007 06:53:57 -0000	1.397
+++ reference_manual.texi	27 Jun 2007 08:44:15 -0000
@@ -6176,7 +6176,10 @@
                                         programming language.
  * Using foreign types from Mercury::   How to use a type defined in
  				       a different programming language
-				       in Mercury code. 
+				       in Mercury code.
+* Using Mercury enumerations in foreign code:: How to use a enumeration type
+                                               defined in Mercury in a
+                                               different programming language.
  * Data passing conventions::	       How Mercury types are passed to
  				       different languages.
  * Adding foreign declarations::        How to add declarations of
@@ -6867,6 +6870,71 @@

  @c -----------------------------------------------------------------------

+ at node Using Mercury enumerations in foreign code
+ at section Using Mercury enumerations in foreign code
+
+Values of Mercury enumeration types can be made available to code in the
+bodies of @samp{foreign_proc} and @samp{foreign_code} pragmas via
+a declaration of the form:
+
+ at example
+:- pragma foreign_export_enum(@var{Lang}, @var{MercuryType},
+        @var{Overrides}, @var{Attributes}).
+ at end example
+
+This causes the compiler to create a symbolic name in language
+ at var{Lang} for each of the constructors of @var{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 @var{Lang}.
+This default mapping is not required to map every valid constructor name
+to a valid name in language @var{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
+ at var{Lang}.
+ at var{Overrides} is a list of pairs of constructor names and strings of
+the following form:
+
+ at example
+[consI - "symbolI", ..., consJ - "symbolJ"]
+ at end example
+
+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.
+
+The argument @var{Attributes} is a list of optional attributes.
+If empty, it may be omitted from the @samp{pragma foreign_export_enum}
+declaration.
+The following attribute must be supported by all Mercury implementations.
+
+ at table @asis
+ 
+ at item @samp{prefix(Prefix)}
+Prefix each symbolic name, regardless of how it was generated, with
+the string @var{Prefix}.
+This occurs @emph{before} the validity of the symbolic name in the
+foreign language is checked, i.e. the effect of the @samp{prefix}
+attribute may cause an otherwise valid symbolic name to become invalid or
+vice versa.
+ 
+ at end table
+
+It is an error for a single constructor to be mapped to two different symbolic
+names by a single @samp{pragma foreign_export_enum} declaration.
+A program can contain multiple @samp{pragma foreign_export_enum}
+declarations for a single Mercury type.
+
+A module may contain @samp{pragma foreign_export_enum} declarations that
+refer to imported types, subject to the usual visibility restrictions.
+
+ at c -----------------------------------------------------------------------
+
  @node Adding foreign declarations
  @section Adding foreign declarations


--------------------------------------------------------------------------
mercury-developers mailing list
Post messages to:       mercury-developers at csse.unimelb.edu.au
Administrative Queries: owner-mercury-developers at csse.unimelb.edu.au
Subscriptions:          mercury-developers-request at csse.unimelb.edu.au
--------------------------------------------------------------------------