[m-rev.] document Java foreign language interface

[Ralph Becket]

Fergus Henderson, Wednesday,  3 December 2003:
> On 03-Dec-2003, Ralph Becket <rafe at cs.mu.OZ.AU> wrote:
> > I think the last two paragraphs could be made clearer.  How about
> > this:
> > 
> >    The arguments to the Java function will be precisely the input
> >    arguments of the corresponding Mercury procedure (in the same order).
> >    (If the Mercury procedure is a function with an input mode result,
> >    then this will be the last argument to the Java function.)
> 
> I'm happy to consider suggestions for better wording.
> But I don't like the specific wording that you have proposed.
> 
> In the Mercury language reference manual, the term "arguments"
> does NOT include function results.  So what you suggest above
> is roughly analagous to
> 
> 	All swans are white.
> 	(If you live in the southern hemisphere, swans' wings are black.)
> 
> ;-)
> In particular
> 	- The first sentence is not really true.
> 	- The second parenthetical sentence contradicts the first sentence
> 	- It's not immediately clear how the contraction should be resolved
> 	  (In the southern hemisphere, we know that the swans' wings are
> 	  black, but what colour is the rest of the swan?
> 	  If the Mercury procedure is a function with an input mode result,
> 	  we know that the last Java argument will be the function result,
> 	  but what about the other arguments?)

Point taken.  How about s/input arguments/inputs/?

> >    The result of the Java function will be a vector comprised of the
> >    output arguments of the Mercury procedure (in the same order).
> >    (If the Mercury procedure can fail then the last item in the vector
> >    will be a @samp{boolean} success indicator, with a @samp{true} value
> >    denoting success and a @samp{false} value denoting failure.)
> 
> Again, that wording does not seem appropriate, because
> in the Mercury language reference manual, the term "arguments"
> does not include function results.

s/output arguments/outputs/?

> Also, the term vector is a bit too strongly suggestive of arrays.
> I'd rather just use the term "sequence".

Sounds good.

> > Does this apply to nested values of type MercuryTypeName or just
> > top-level arguments?
> 
> It applies to nested values, but generally they won't show up in the
> Java interface.  The exception is arrays, where e.g. a Mercury type
> `array(foo)' will map to a Java type `Foo[]' if the Mercury type
> `foo' is a declared as a Java foreign_type for `Foo'.
> 
> I'm not sure if this needs any explicit wording to make this clear,
> or what form such wording would take; suggestions welcome.

Hmmm... what's the mapping from data constructors to Java classes?  Or
is this private, in the sense that the programmer has to export field
accessor predicates to Java if they want to manipulate Mercury values
from within Java?

Also, is there any harm in letting the programmer treat arrays as
though they we Objects?

> 
> > > +The input and output variables for a Java @samp{pragma
> > > foreign_proc} will +have Java types corresponding to their Mercury
> > > types.  The exact rules +for mapping Mercury types to Java types
> > > are described in + at ref{Java data passing conventions}.
> > 
> > How about:
> > 
> >    Values are passed to and from Java foreign_procs using the
> >    mapping between Mercury and Java types described in @ref{Java
> >    data passing conventions}.
> 
> The section on Java data passing conventions contains both the mapping
> from Mercury to Java types and also an argument passing / result
> returning convention; here we're only interested in the former.
> 
> If we were to say "values are passed ... using the mapping ... in
> @ref{...}", then I would be worried that some readers might be mislead
> into thinking that the argument passing / result returning convention
> applied too.

I see - in that case I can't think of anything clearer than your
original wording.

> Like this?
> 
> 	With our current implementation, the Java code must set the
> 	values even if the procedure fails setting @samp{succeeded} to
> 	@code{false}.
> 
> That doesn't parse properly. 

It doesn't?  How about

	With our current implementation, the Java code must set the
	values even if the procedure fails (i.e. sets @samp{succeeded} to
	@code{false}.)

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