[m-dev.] for review: Aditi update doc extract

[Fergus Henderson]

On 06-Jul-1999, Simon Taylor <stayl at cs.mu.OZ.AU> wrote:

>  Insertion
>  .........
>  
> -     aditi_insert(PREDNAME(VAR1, VAR2, ...), DB0, DB).
> +     aditi_insert(PREDNAME(ARG1, ARG2, ...), DB0, DB).
>       
> -     aditi_insert(FUNCNAME(VAR1, VAR2, ...) = RETVAR, DB0, DB).
> +     aditi_insert(FUNCNAME(ARG1, ARG2, ...) = RETVAL, DB0, DB).
>  
>     Insert the specified tuple into a relation. The tuple to be inserted
>  must have the same type signature as the relation. All the arguments of
>  the tuple have mode `in', except the `aditi__state' argument which has
>  mode `unused'.

You should mention here that the return value also has mode `in'.

Also, you should specify the determinism of all the Aditi update goals.

> +   The following naming conventions are used in the specification of
> +the Aditi update syntax:
> +   * `PREDNAME' is the name of a predicate.
> +
> +   * `FUNCNAME' is the name of a function.
> +
> +   * `NAME' is the name of a predicate or a function.
> +
> +   * `PREDORFUNC' is either `pred' or `func', depending on whether a
> +     predicate or function is being updated.
> +
> +   * `ARITY' is the arity of the predicate or function being updated.
> +
> +   * `GOAL' is any Mercury goal.
> +
> +   * `CLOSURE' is a term which has a higher-order type.

These are not exactly just naming conventions, in that they
have a semantic effect.  They are constructs with a definite formal
meaning, used to abbreviate the description of the syntax, not just
a naming convention like the one in the Mercury coding guidelines.
Therefore I'd call them "syntax conventions" rather than "naming conventions".

It's not quite enough to just say that e.g. `FUNCNAME' _is_ the name of a
function, because that makes it unclear what is supposed to happen in the
case when `FUNCNAME' is _not_ the name of a function.
Really you ought to say that `FUNCNAME' _must be_ the name of
a function.  This makes it clear that this is a semantic constraint
that the program must abide by and that the compiler must check.

However, simply doing `s/is/must be/g' here wouldn't be quite right either,
because at this point `FUNCNAME' doesn't refer to anything yet.
It's only later one, when you introduce some syntactic construct
by saying that it must have the form `... FUNCNAME ...',
that `FUNCNAME' ceases to be a dangling reference.

So, one option would be to list all the constraints (using "must be")
immediately after each syntactic construct, rather than grouping them
into a separate section as you have done here.  The drawback of this
option is that there is a lot of duplication.  The advantage is that
all the semantic constraints on each construct are described in the
one place.

Another option would be to keep the naming conventions section
(renamed as syntax conventions), using "is", and to add some extra
wording at the end explaining that whenever one of these names
is used in the description of a syntactic construct, then for any
term matching that description, the sub-term corresponding to that
name must satisfy the constraints specified for that name.
However, finding nice wording for this is tricky.

One more point: I think it would be a good idea to include
a pointer to the "Aditi updates" section in the "Goals" section
of the syntax chapter.  That is, the list of possible goal forms
should include something along the following lines

 | 	aditi_insert(...):
 | 	aditi_update(...):
 | 	aditi_bulk_insert(...):
 | 	aditi_bulk_update(...):
 | 	aditi_delete(...):
 | 		These goal forms are used for the Aditi database interface.
 | 		See the "Aditi update" section for further details.

just before the catch-all `CALL' goal form.
(Of course all this documentation should be inside `ifset aditi' in the
Texinfo source.)

-- 
Fergus Henderson <fjh at cs.mu.oz.au>  |  "I have always known that the pursuit
WWW: <http://www.cs.mu.oz.au/~fjh>  |  of excellence is a lethal habit"
PGP: finger fjh at 128.250.37.3        |     -- the last words of T. S. Garp.
--------------------------------------------------------------------------
mercury-developers mailing list
Post messages to:       mercury-developers at cs.mu.oz.au
Administrative Queries: owner-mercury-developers at cs.mu.oz.au
Subscriptions:          mercury-developers-request at cs.mu.oz.au
--------------------------------------------------------------------------