[m-rev.] for review: new foreign_type syntax

[Fergus Henderson]

On 28-Nov-2001, Tyson Dowd <trd at cs.mu.OZ.AU> wrote:
> Fix and enable the new foreign_type syntax.  We now accept declarations
> such as:
> 
> :- pragma foreign_type(xmldoc, il("class [System.Xml]System.Xml.XmlDocument")).

I thought we were in agreement that the syntax would be

	:- pragma foreign_type(il, xmldoc,
		"class [System.Xml]System.Xml.XmlDocument").

?

> + at node Using foreign types from Mercury
> + at section Using foreign types from Mercury
> +
> +Types defined in foreign language can be declared in Mercury using 
> +a declaration of the form
> +
> + at example
> +:- pragma foreign_type(@var{MercuryTypeName}, @var{ForeignTypeDescriptor}).
> + at end example
> +
> +This declaration introduces a new abstract type in Mercury which is a
> +synonym for a type defined in a foreign language.

I thought that we agreed that `:- pragma foreign_type' would
only *define* a type, not *declare* it, with the type having
to be explicitly declared in a `:- type <foo>.' declaration.

> @@ -5085,6 +5113,7 @@
>  
>  @menu
>  * Interfacing with C 		:: How to write code to interface with C
> +* Interfacing with .NET 	:: How to write code to interface with .NET

> + at node Interfacing with .NET
> + at subsection Interfacing with .NET

In general, the term ".NET" should be avoided;
we should use a more specific term, such as ".NET CLR"
or ".NET Common Language Runtime".
After all, this section doesn't say anything about
how to interface with web services ;-)

So I suggest s/.NET/.NET CLR/g
and adding a sentence at the start of this section explaining the acronym,
e.g. "This section describes how to interface with the .NET Common Language
Runtime." or "This section describes how to interface with code that has
been compiled to run on the .NET Common Language Runtime.".
It might also be useful to give some approapriate reference for where
to find more information on the .NET CLR.

> + 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{DotNetForeignType})).
> + at end example
> +
> +If the @var{MercuryTypeName} is a parameter of a procedure defined using

A typename can never be a parameter.

> + at samp{pragma foreign_proc}, it will be passed to user code as
> + at var{DotNetForeignType}.
> +Futhermore, any externally visible Mercury
> +procedure will use @var{DotNetForeignType} as the parameter type for
> +parameters whose Mercury type is @var{MercuryTypeName}.

It's not clear to me what you mean by "externally visible" here --
does this mean procedures exported with `pragma export',
or does it mean procedures occurring in a module interface?

I think it should only be guaranteed for procedures exported
with `pragma export'.

> +The CIL assembler syntax is used to specify type names for the .NET
> +backend (this syntax is documented in the ECMA specifications for .NET).
> +Currently on the .NET backend only reference classes are supported using
> + at samp{pragma foreign_type},

An "@c XXX" might be appropriate here.
This restriction really ought to be lifted.

> and hence the only supported syntax for
> +DotNetForeignType is @samp{"class [AssemblyName]ClassName"}.
> +Note that extra whitespace is not handled, there should only be a single
> +space between the class keyword and they assembly specifier.

s/they/the/
s/,/ --- /

> +ensures that on the .NET backend the mercury type @samp{xmldoc} is

s/mercury/Mercury/

> +represented marhsalled by the backend as @samp{System.Xml.XmlDocument}

"represented"?  "marshalled"?  Please make up your mind ;-)

> +from assembly System.Xml.

s/System.Xml/@samp{System.Xml}/

-- 
Fergus Henderson <fjh at cs.mu.oz.au>  |  "I have always known that the pursuit
The University of Melbourne         |  of excellence is a lethal habit"
WWW: <http://www.cs.mu.oz.au/~fjh>  |     -- the last words of T. S. Garp.
--------------------------------------------------------------------------
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
--------------------------------------------------------------------------