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

[Tyson Dowd]

On 06-Dec-2001, Fergus Henderson <fjh at cs.mu.OZ.AU> wrote:
> On 06-Dec-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(il, xmldoc, "class [System.Xml]System.Xml.XmlDocument").
> > Index: doc/reference_manual.texi
> ...
> > @@ -5004,6 +5007,38 @@
> >  
> >  @c -----------------------------------------------------------------------
> >  
> > + at node Using foreign types from Mercury
> > + at section Using foreign types from Mercury
> > +
> > +Types defined in foreign language can be defined in Mercury using 
> 
> s/foreign language/a foreign language/
> 
> Also s/defined in Mercury/accessed in Mercury/ ?
> 
> > @@ -5085,6 +5120,7 @@
> >  
> >  @menu
> >  * Interfacing with C 		:: How to write code to interface with C
> > +* Interfacing with .NET CLR	:: How to write code to interface with .NET CLR
> >  * 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
> 
> This is in a section titled "language specific bindings".
> All the other entries here are languages, but ".NET CLR"
> is not really a language.  So I don't think it belongs here.

I will see whether I can make it a subsection of its own (with C#, IL
and MC++ underneath it).

> > + 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.
> 
> s/not implemented for C backends/not supported for C/
> (We should be talking about languages, not backends.)
> 
> Also it would be a good idea to mention here that the
> `c_pointer' type can be used instead (giving an example).

I can mention it, but perhaps we should have given examples when
we added c_pointer to the library...

(I might do this because I have to write something about it in my
thesis, otherwise I would say no).

> 
> > + at node Interfacing with .NET CLR
> > + at subsection Interfacing with .NET CLR
> > +
> > +This section describes how to interface with the .NET Common Language
> > +Runtime, as specified by the ECMA Common Language Infrastructure (ECMA
> > +TC39/TG3) standards.
> 
> Currently these are only draft standards, not standards yet.
> 
> So I suggesting adding a footnote
> 
> 	...
> 	TC39/TG3) standards at footnote{
> 		At the time of writing, these are only draft standards,
> 		not official ECMA standards.
> 	}.

I suspect by the time I commit this change, I'll have to delete this
again, but whatever...

> 
> Also I think this section describes how to interface with
> code compiled for the .NET CLR, rather than how to interface
> with the .NET CLR itself.

Actually it allows you to interface to code that runs on the
.NET CLR or can be interfaced to by the CLR.  It doesn't necessarily
have to be compiled for the .NET CLR, consider the case of COM interop
-- COM components are often specifically *not* compiled for the .NET CLR.

I don't think the distinction adds any clarity, and it isn't correct
anyway.   I know it's slightly sloppy terminology, but I don't think it
is so bad.  Anything that goes in this section should be a subset of the
idea "interfacing with the .NET CLR".

If there is sloppy terminology in the specific descriptions of features
that should be fixed.

> > + at c XXX
> > +Currently much of this section is still undocumented, sorry.
> > +
> > + at menu
> > +* Using pragma foreign_type for .NET CLR :: Declaring .NET CLR types in Mercury
> > + at end menu
> > +
> > + at node Using pragma foreign_type for .NET CLR
> > + at subsubsection Using pragma foreign_type for .NET CLR
> > +
> > +The .NET CLR @samp{pragma foreign_type} declaration is of
> > +the form:
> > +
> > + at example
> > +:- pragma foreign_type(il, @var{MercuryTypeName}, @var{DotNetForeignType}).
> > + at end example
> 
> The language in this `foreign_type' declaration is `il'.
> So why isn't this in the "interfacing with IL" section?

The foreign_type works for all .NET backends.

il is the syntax used to specify the types.

If you put it in the IL section, people who want to find out how to
interface to C# or MC++ won't find it.

I guess you could duplicated it in every section (triple update problem)
or remove the feature of being able to use 1 syntax (then I have to
write parsers for other syntaxes, and we have to debate the syntax).


Other suggestions are ok and I am working on them.

-- 
       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
--------------------------------------------------------------------------