[m-dev.] for review: add operators to reference manual

[David Glen JEFFERY]

On 25-Aug-2000, Fergus Henderson <fjh at cs.mu.OZ.AU> wrote:
> This change is a definite improvement on the current status quo.
> However, it could be improved still further:
> 
> 	- the "Terms:" section should contain a forward reference
> 	  to the "Operators:" section
> 
> 	- the "Operators:" section should explain what the specifiers
> 	  (e.g. "fx", "xfy", "fxy") mean, and what the numbers in the
> 	  "Priority" column mean.
> 
> 	- for the operators which `library/ops.m' documents as `NYI'
> 	  (`import_*', `export_*', and `use_*'), I think it would be
> 	  better not to document them here.  Currently they are not
> 	  used at all, and they're not likely we could even just comment
> 	  out those lines in library/ops.m.

I have have done those three things (and David's suggestion that
the operators be sorted on priority).

----------------------------------------------------------------------------
  
Estimated hours taken: 2
  
Add the list of valid operators to the reference manual.

doc/reference_manual.texi:
        Add a table of valid operators.
library/ops.m:
        Add a note indicating that reference_manual.texi needs to be kept
        in sync with the operator table.
  
----------------------------------------------------------------------------

Index: doc/reference_manual.texi
===================================================================
RCS file: /home/staff/zs/imp/mercury/doc/reference_manual.texi,v
retrieving revision 1.187
diff -u -t -r1.187 reference_manual.texi
--- doc/reference_manual.texi	2000/09/18 11:52:09	1.187
+++ doc/reference_manual.texi	2000/09/19 03:53:09
@@ -151,6 +151,7 @@
 * Syntax Overview::
 * Tokens::
 * Terms::
+* Builtin Operators::
 * Items::
 * Declarations::
 * Facts::
@@ -308,7 +309,8 @@
 Syntactically, terms in Mercury are exactly the same as in ISO Prolog,
 except that as extensions we permit higher-order terms and the
 introduction of infix operators by the use of grave accents (backquotes),
-as described below.
+as described below,
+and we support an extended set of builtin operators. @xref{Builtin Operators}.
 However, the meaning of some terms in Mercury is different to that
 in Prolog.  @xref{Data-terms}.
 
@@ -342,8 +344,7 @@
 
 A higher-order term is a ``closure'' term, which can be any term 
 other than a name or an operator term, followed without
-any intervening whitespace by an open parenthesis (i.e. an open_ct token),
-a sequence of argument terms separated by commas, and a close
+any intervening whitespace by an open parenthesis (i.e. an open_ct token), a sequence of argument terms separated by commas, and a close
 parenthesis.  A higher-order term is equivalent to a simple compound term
 whose functor is the empty name, and whose arguments are the 
 closure term followed by the argument terms of the higher-order term.
@@ -353,6 +354,136 @@
 term; for example, @code{(Term^FieldName)(Arg1, Arg2)}
 is a higher-order term, and so it gets parsed as
 if it were @code{''((Term^FieldName), Arg1, Arg2)}.
+
+ at node Builtin Operators
+ at section Builtin Operators
+
+The following table lists all of Mercury's builtin operators. 
+Operators with a low ``Priority'' bind more tightly than those
+with a high ``Priority''. For example, given that @code{+} has priority
+500 and @code{*} has priority 400, the term @code{2 * X + Y} would parse
+as @code{(2 * X) + Y}.
+
+The ``Specifier'' field indicates what structure terms 
+constructed with an operator are allowed to take. 
+``f'' representes the operators and ``x'' and ``y'' represent arguments. 
+``x'' represents an argument whose priority must be 
+strictly lower that that of the operator.
+``y'' represents an argument whose priority is 
+lower or equal to that of the operator.
+
+ at multitable @columnfractions .25 .2 .2 .2
+
+ at item Operator @tab Category @tab Specifier @tab Priority
+
+ at item @code{^} @tab after @tab xfy @tab 99
+ at item @code{^} @tab before @tab fx @tab 100
+ at item @code{**} @tab after @tab xfy @tab 200
+ at item @code{-} @tab before @tab fx @tab 200
+ at item @code{\} @tab before @tab fx @tab 200
+ at item @code{*} @tab after @tab yfx @tab 400
+ at item @code{//} @tab after @tab yfx @tab 400
+ at item @code{/} @tab after @tab yfx @tab 400
+ at item @code{<<} @tab after @tab yfx @tab 400
+ at item @code{>>} @tab after @tab yfx @tab 400
+ at item @code{div} @tab after @tab yfx @tab 400
+ at item @code{mod} @tab after @tab xfx @tab 400
+ at item @code{rem} @tab after @tab xfx @tab 400
+ at item @code{++} @tab after @tab xfy @tab 500
+ at item @code{+} @tab after @tab yfx @tab 500
+ at item @code{+} @tab before @tab fx @tab 500
+ at item @code{--} @tab after @tab yfx @tab 500
+ at item @code{-} @tab after @tab yfx @tab 500
+ at item @code{/\} @tab after @tab yfx @tab 500
+ at item @code{\/} @tab after @tab yfx @tab 500
+ at item @code{aditi_bottom_up} @tab before @tab fx @tab 500
+ at item @code{aditi_top_down} @tab before @tab fx @tab 500
+ at item @code{.} @tab after @tab xfy @tab 600
+ at item @code{:} @tab after @tab yfx @tab 600
+ at item @code{:=} @tab after @tab xfx @tab 650
+ at item @code{=^} @tab after @tab xfx @tab 650
+ at item @code{<} @tab after @tab xfx @tab 700
+ at item @code{=..} @tab after @tab xfx @tab 700
+ at item @code{=:=} @tab after @tab xfx @tab 700
+ at item @code{=<} @tab after @tab xfx @tab 700
+ at item @code{==} @tab after @tab xfx @tab 700
+ at item @code{=\=} @tab after @tab xfx @tab 700
+ at item @code{=} @tab after @tab xfx @tab 700
+ at item @code{>=} @tab after @tab xfx @tab 700
+ at item @code{>} @tab after @tab xfx @tab 700
+ at item @code{@@<} @tab after @tab xfx @tab 700
+ at item @code{@@=<} @tab after @tab xfx @tab 700
+ at item @code{@@>=} @tab after @tab xfx @tab 700
+ at item @code{@@>} @tab after @tab xfx @tab 700
+ at item @code{\==} @tab after @tab xfx @tab 700
+ at item @code{\=} @tab after @tab xfx @tab 700
+ at item @code{~=} @tab after @tab xfx @tab 700
+ at item @code{is} @tab after @tab xfx @tab 701
+ at item @code{and} @tab after @tab xfy @tab 720
+ at item @code{or} @tab after @tab xfy @tab 740
+ at item @code{func} @tab before @tab fx @tab 800
+ at item @code{impure} @tab before @tab fy @tab 800
+ at item @code{pred} @tab before @tab fx @tab 800
+ at item @code{semipure} @tab before @tab fy @tab 800
+ at item @code{\+} @tab before @tab fy @tab 900
+ at item @code{not} @tab before @tab fy @tab 900
+ at item @code{when} @tab after @tab xfx @tab 900
+ at item @code{~} @tab before @tab fy @tab 900
+ at item @code{<=>} @tab after @tab xfy @tab 920
+ at item @code{<=} @tab after @tab xfy @tab 920
+ at item @code{=>} @tab after @tab xfy @tab 920
+ at item @code{all} @tab before @tab fxy @tab 950
+ at item @code{lambda} @tab before @tab fxy @tab 950
+ at item @code{some} @tab before @tab fxy @tab 950
+ at item @code{,} @tab after @tab xfy @tab 1000
+ at item @code{&} @tab after @tab xfy @tab 1025
+ at item @code{->} @tab after @tab xfy @tab 1050
+ at item @code{;} @tab after @tab xfy @tab 1100
+ at item @code{then} @tab after @tab xfx @tab 1150
+ at item @code{if} @tab before @tab fx @tab 1160
+ at item @code{else} @tab after @tab xfy @tab 1170
+ at item @code{::} @tab after @tab xfx @tab 1175
+ at item @code{==>} @tab after @tab xfx @tab 1175
+ at item @code{where} @tab after @tab xfx @tab 1175
+ at item @code{--->} @tab after @tab xfy @tab 1179
+ at item @code{type} @tab before @tab fx @tab 1180
+ at item @code{end_module} @tab before @tab fx @tab 1199
+ at c @item @code{export_adt} @tab before @tab fx @tab 1199
+ at c @item @code{export_cons} @tab before @tab fx @tab 1199
+ at c @item @code{export_module} @tab before @tab fx @tab 1199
+ at c @item @code{export_op} @tab before @tab fx @tab 1199
+ at c @item @code{export_pred} @tab before @tab fx @tab 1199
+ at c @item @code{export_sym} @tab before @tab fx @tab 1199
+ at c @item @code{export_type} @tab before @tab fx @tab 1199
+ at c @item @code{import_adt} @tab before @tab fx @tab 1199
+ at c @item @code{import_cons} @tab before @tab fx @tab 1199
+ at item @code{import_module} @tab before @tab fx @tab 1199
+ at c @item @code{import_op} @tab before @tab fx @tab 1199
+ at c @item @code{import_pred} @tab before @tab fx @tab 1199
+ at c @item @code{import_sym} @tab before @tab fx @tab 1199
+ at c @item @code{import_type} @tab before @tab fx @tab 1199
+ at item @code{include_module} @tab before @tab fx @tab 1199
+ at item @code{instance} @tab before @tab fx @tab 1199
+ at item @code{inst} @tab before @tab fx @tab 1199
+ at item @code{mode} @tab before @tab fx @tab 1199
+ at item @code{module} @tab before @tab fx @tab 1199
+ at item @code{pragma} @tab before @tab fx @tab 1199
+ at item @code{promise} @tab before @tab fx @tab 1199
+ at item @code{rule} @tab before @tab fx @tab 1199
+ at item @code{typeclass} @tab before @tab fx @tab 1199
+ at c @item @code{use_adt} @tab before @tab fx @tab 1199
+ at c @item @code{use_cons} @tab before @tab fx @tab 1199
+ at item @code{use_module} @tab before @tab fx @tab 1199
+ at c @item @code{use_op} @tab before @tab fx @tab 1199
+ at c @item @code{use_pred} @tab before @tab fx @tab 1199
+ at c @item @code{use_sym} @tab before @tab fx @tab 1199
+ at c @item @code{use_type} @tab before @tab fx @tab 1199
+ at item @code{-->} @tab after @tab xfx @tab 1200
+ at item @code{:-} @tab after @tab xfx @tab 1200
+ at item @code{:-} @tab before @tab fx @tab 1200
+ at item @code{?-} @tab before @tab fx @tab 1200
+
+ at end multitable
 
 @node Items
 @section Items
Index: library/ops.m
===================================================================
RCS file: /home/staff/zs/imp/mercury/library/ops.m,v
retrieving revision 1.31
diff -u -t -r1.31 ops.m
--- library/ops.m	2000/08/13 13:18:47	1.31
+++ library/ops.m	2000/08/25 05:28:49
@@ -116,8 +116,8 @@
 ops__lookup_op(_OpTable, Name) :-
         ops__op_table(Name, _, _, _).
 
-        % Changes here may require changes to compiler/mercury_to_mercury.m
-        % and doc/transition_guide.texi.
+        % Changes here may require changes to compiler/mercury_to_mercury.m,
+        % doc/transition_guide.texi and doc/reference_manual.texi.
 :- pred ops__op_table(string, ops__category, ops__specifier, ops__priority).
 :- mode ops__op_table(in, in, out, out) is semidet.
 :- mode ops__op_table(in, out, out, out) is nondet.

dgj
-- 
David Jeffery (dgj at cs.mu.oz.au) | If your thesis is utterly vacuous
PhD student,                    | Use first-order predicate calculus.
Dept. of Comp. Sci. & Soft. Eng.|     With sufficient formality
The University of Melbourne     |     The sheerist banality
Australia                       | Will be hailed by the critics: "Miraculous!"
                                |     -- Anon.
--------------------------------------------------------------------------
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
--------------------------------------------------------------------------