[m-rev.] for review: documentation for pragma foreign_type

[Tyson Dowd]

Hi,

And here are the docs...

===================================================================


Estimated hours taken: 3
Branches: main

doc/reference_manual.texi:
	Documentation for pragma foreign_type.


Index: doc/reference_manual.texi
===================================================================
RCS file: /home/mercury1/repository/mercury/doc/reference_manual.texi,v
retrieving revision 1.204.2.11
diff -u -r1.204.2.11 reference_manual.texi
--- doc/reference_manual.texi	2001/10/17 12:31:10	1.204.2.11
+++ doc/reference_manual.texi	2001/10/29 05:46:15
@@ -4738,6 +4738,9 @@
 * Adding foreign definitions::         How to add definitions of
   				       entities in other programming
 				       languages.
+* Adding foreign types::               How to add declarations of
+  				       types defined in other programming
+				       languages.
 * Language specific bindings::         Information specific to each
   				       foreign language.
 @end menu
@@ -4951,11 +4954,40 @@
 
 @c -----------------------------------------------------------------------
 
+ at node Adding foreign types
+ at section Adding foreign types
+
+Types defined in foreign language can be declared in Mercury using 
+a declaration of the form
+
+ at example
+:- pragma foreign_type(@var{MercuryTypeName}, @var{BackendDescriptor}).
+ at end example
+
+This declaration introduces a new abstract type in Mercury which is a
+synonym for a type defined in the specified backend language.
+
+ at var{BackendDescriptor} is a backend specific parameter, and defines how
+the foreign type is mapped for a particular backend.  
+Different backends support different sets of foreign languages, and so
+the mapping of the foreign type to individual foreign languages is also 
+defined by the backend specific code in the language specific
+information below.
+
+ at var{MercuryTypeName} is treated as an abstract type at all times in
+Mercury code.
+However, if @var{MercuryTypeName} is one of the parameters of a
+foreign_proc, it will be marshalled as a foreign type as specified by
+ at var{BackendDescriptor}.
+
+ at c -----------------------------------------------------------------------
+
 @node Language specific bindings
 @section Language specific bindings
 
 @menu
 * Interfacing with C 		:: How to write code to interface with C
+* Interfacing with .NET 	:: How to write code to interface with .NET
 * Interfacing with C# 		:: How to write code to interface with C#
 * Interfacing with IL 		:: How to write code to interface with IL
 * Interfacing with Managed C++ 	:: How to write code to interface with
@@ -4997,6 +5029,7 @@
 * Using pragma foreign_proc for C 	:: Calling C code from Mercury
 * Using pragma foreign_decl for C 	:: Including C declarations in Mercury
 * Using pragma foreign_code for C 	:: Including C code in Mercury
+* Using pragma foreign_type for C 	:: Declaring C types in Mercury
 @end menu
 
 @node Using pragma foreign_proc for C
@@ -5109,6 +5142,67 @@
 @end example
 
 Such code is copied verbatim into the generated C file.
+
+ at node Using pragma foreign_type for C
+ at subsubsection Using pragma foreign_type for C
+
+This pragma is currently not implemented for C backends.
+
+ at c ----------------------------------------------------------------------------
+
+ at node Interfacing with .NET
+ at subsection Interfacing with .NET
+
+ at c XXX
+Currently much of this section is still undocumented, sorry.
+
+ at menu
+* Using pragma foreign_type for .NET 	:: Declaring .NET types in Mercury
+ at end menu
+
+ at node Using pragma foreign_type for .NET
+ at subsubsection Using pragma foreign_type for .NET
+
+The .NET pragma foreign_type declaration is of the form:
+
+ at example
+:- pragma foreign_type(@var{MercuryTypeName}, 
+        il(@var{AssemblyName}, @var{DotNetForeignType})).
+ at end example
+
+If the @var{MercuryTypeName} is a parameter of a procedure defined using
+pragma foreign_proc, it will be passed to user code as @var{DotNetForeignType}.
+Futhermore, any externally visible Mercury procedure will use
+ at var{DotNetForeignType} as the parameter type for parameters with
+ at var{MercuryTypeName}.
+
+Since there is no universal syntax for .NET types, we use the Mercury
+module qualifier as a namespace separator for the .NET namespaces.
+Currently on the .NET backend only classes are supported using the
+foreign_type pragma, and hence the only supported syntax for
+DotNetForeignType is @samp{class(ClassName)}.
+
+For example:
+
+ at example
+:- pragma foreign_type(xmldoc, 
+	il("System.Xml", class('System__Xml__XmlDocument'))).
+ at end example
+
+ensures that on the IL backend the mercury type @samp{xmldoc} is
+represented marhsalled by the backend as @samp{System.Xml.XmlDocument}.
+The following example shows how one can use the marshalled data from C#. 
+
+ at example
+:- pred loadxml(string::in, xmldoc::di, xmldoc::uo) is det.
+
+:- pragma foreign_proc("C#", load(String::in, XML0::di, XML::uo),
+        [will_not_call_mercury],
+"
+    XML0.LoadXml(String);
+    XML = XML0;
+").
+ at end example
 
 @c ----------------------------------------------------------------------------
 


-- 
       Tyson Dowd           # 
                            #  Surreal humour isn't everyone's cup of fur.
     trd at cs.mu.oz.au        # 
http://www.cs.mu.oz.au/~trd #
--------------------------------------------------------------------------
mercury-reviews mailing list
post:  mercury-reviews at cs.mu.oz.au
administrative address: owner-mercury-reviews at cs.mu.oz.au
unsubscribe: Address: mercury-reviews-request at cs.mu.oz.au Message: unsubscribe
subscribe:   Address: mercury-reviews-request at cs.mu.oz.au Message: subscribe
--------------------------------------------------------------------------