cvs diff: better doc for higher-order stuff

[Fergus Henderson]

compiler/typecheck.m:
doc/reference_manual.texi:
	Improve the error messages and documentation about trying to
	taking the address of builtins and trying to curry higher-order terms.
	This change is in response to email from Bart Demoen where Bart
	described how he had been confused by the previous error message
	and lack of documentation.

Index: typecheck.m
===================================================================
RCS file: /home/staff/zs/imp/mercury/compiler/typecheck.m,v
retrieving revision 1.198
diff -u -r1.198 typecheck.m
--- typecheck.m	1997/04/21 09:16:08	1.198
+++ typecheck.m	1997/04/22 02:22:09
@@ -3513,7 +3513,25 @@
 		io__write_string(
 			"  If you're trying to invoke a higher-order\n"),
 		prog_out__write_context(Context),
-		io__write_string("  predicate, use `call', not `apply'.\n")
+		io__write_string("  predicate, use `call', not `apply'.\n"),
+		prog_out__write_context(Context),
+		io__write_string(
+			"  If you're trying to curry a higher-order\n"),
+		prog_out__write_context(Context),
+		io__write_string(
+			"  function, use a forwarding function:\n"),
+		prog_out__write_context(Context),
+		io__write_string(
+			"  e.g. instead of `NewFunc = apply(OldFunc, X)'\n"),
+		prog_out__write_context(Context),
+		io__write_string(
+			"  use `NewFunc = my_apply(OldFunc, X)'\n"),
+		prog_out__write_context(Context),
+		io__write_string(
+		"  where `my_apply' is defined with the appropriate arity,\n"),
+		prog_out__write_context(Context),
+		io__write_string(
+			"  e.g. `my_apply(Func, X, Y) :- apply(Func, X, Y).'\n")
 	;
 		[]
 	).
@@ -3589,7 +3607,16 @@
 		"  If you are trying to invoke a higher-order\n"),
 				prog_out__write_context(Context),
 				io__write_string(
-		"  function, you should use `apply', not `call'.\n")
+		"  function, you should use `apply', not `call'.\n"),
+				prog_out__write_context(Context),
+				io__write_string(
+		"  If you're trying to curry a higher-order predicate,\n"),
+				prog_out__write_context(Context),
+				io__write_string(
+		"  see the ""Creating higher-order terms"" section of the\n"),
+				prog_out__write_context(Context),
+				io__write_string(
+		"  Mercury Language Reference Manual.\n")
 			;
 			    []
 			)
Index: reference_manual.texi
===================================================================
RCS file: /home/staff/zs/imp/mercury/doc/reference_manual.texi,v
retrieving revision 1.49
diff -u -r1.49 reference_manual.texi
--- reference_manual.texi	1997/01/27 07:46:37	1.49
+++ reference_manual.texi	1997/04/22 02:43:55
@@ -1917,6 +1917,8 @@
 
 @node Creating higher-order terms
 @section Creating higher-order terms
+ at c NB. This section is pointed to by an error message in compiler/typecheck.m,
+ at c so if you change the section name, you need to update that error message.
 
 To create a higher-order predicate or function term, you can use
 a lambda expression, or, if the predicate or function has only one
@@ -1996,6 +1998,50 @@
 binds @samp{Double} to a higher-order function term of type
 @samp{func(list(int)) = list(int)}.
 
+Note that when constructing a higher-order term, you cannot just use
+the name of a builtin language construct such as @samp{=}, @samp{\=},
+ at samp{call}, or @samp{apply}, and nor can such constructs be curried.  
+Instead, you must either use an explicit lambda expression,
+or you must write a forwarding predicate or function.
+For example, instead of
+
+ at example
+list__filter([1,2,3], \=(2), List)
+ at end example
+
+ at noindent
+you must write either
+
+ at example
+list__filter([1,2,3], (pred(X::in) is semidet :- X \= 2), List)
+ at end example
+
+ at noindent
+or
+
+ at example
+list__filter([1,2,3], not_equal(2), List)
+ at end example
+
+ at noindent
+where you have defined @samp{not_equal} using
+
+ at example
+:- pred not_equal(T::in, T::in) is semidet.
+not_equal(X, Y) :- X \= Y.
+ at end example
+
+Another case when this arises is when want to curry a higher-order
+term.  Suppose, for example, that you have a higher-order predicate
+term @samp{OldPred} of type @samp{pred(int, char, float)}, and you want
+to construct a new higher-order predicate term @samp{NewPred} of type
+ at samp{pred(char, float)} from @samp{OldPred} by supplying a value for
+for just the first argument.  The solution is the same: use
+an explicit lambda expression or a forwarding predicate.
+In either case, the body of the lambda expression or the forwarding
+predicate must contain a higher-order call with all the arguments
+supplied.
+
 @node Calling higher-order terms
 @section Calling higher-order terms
 
@@ -2073,9 +2119,9 @@
 @end example
 
 @noindent
-where @samp{call(Pred, X)} is a call to the standard library predicate
- at samp{call/2} which invokes the higher-order predicate term @samp{Pred}
-with argument @samp{X}, and where @samp{list__member/2} is the standard
+where @samp{call(Pred, X)} invokes the higher-order predicate term
+ at samp{Pred} with argument @samp{X},
+and where @samp{list__member/2} is the standard
 library predicate for list membership.  In other words,
 @samp{solutions(Pred, List)} finds all the values of @samp{X}
 for which @samp{call(Pred, X)} is true, collects these solutions
@@ -2103,6 +2149,10 @@
 @example
 L = [[1,2,3],[1,3,2],[2,1,3],[2,3,1],[3,1,2],[3,2,1]].
 @end example
+
+See also @samp{unsorted_solutions/2} and @samp{solutions_set/2}, which
+are defined in the standard library module @samp{std_util} and documented
+in the Mercury Library Reference Manual.
 
 @node Higher-order modes
 @section Higher-order modes

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