[m-rev.] clarify docs RE existential types vs mode-specific clauses

[Fergus Henderson]

Branches: main
Estimated hours taken: 0.75

Update the documentation to address SourceForge bug #512581.

doc/reference_manual.texi:
	Clarify the interaction between mode-specific clauses
	and existential types.

Workspace: /mnt/ceres/home/ceres/fjh/mercury
Index: doc/reference_manual.texi
===================================================================
RCS file: /home/mercury1/repository/mercury/doc/reference_manual.texi,v
retrieving revision 1.258
diff -u -d -r1.258 reference_manual.texi
--- doc/reference_manual.texi	2002/08/23 07:15:10	1.258
+++ doc/reference_manual.texi	2002/10/01 08:02:29
@@ -4706,6 +4706,12 @@
 a predicate or function which was explicitly declared to have an
 existentially quantified type.
 
+Note that an existentially typed procedure is not allowed to have
+different types for its existentially typed arguments in different clauses
+(even mode-specific clauses) or in different subgoals of a single clause;
+however, the same effect can be achieved in other ways
+(see @pxref{Some idioms using existentially quantified types}).
+
 For procedures involving calls to existentially-typed predicates or functions,
 the compiler's mode analysis must take account of the modes for type
 variables in all polymorphic calls.
@@ -5010,6 +5016,38 @@
 	; Name = "bar", Univ = 'new mkshowable'("blah")
 	),
 	Univ = mkshowable(Showable).
+ at end example
+
+The issue can also arise for mode-specific clauses
+(see @pxref{Different clauses for different modes}).
+For instance, the following example is illegal:
+
+ at example
+:- some [T] pred bad_example3(string, T).
+:-          mode bad_example3(in(bound("foo")), out) is det.
+:-          mode bad_example3(in(bound("bar")), out) is det.
+:- pragma promise_pure(bad_example3/2).
+bad_example3("foo"::in(bound("foo")), 42::out).
+bad_example3("bar"::in(bound("bar")), "blah"::out).
+	% type error (cannot unify `int' and `string')
+ at end example
+
+The solution is similar, although in this case an intermediate
+predicate is required:
+
+ at example
+:- some [T] pred good_example3(string, T).
+:-          mode good_example3(in(bound("foo")), out) is det.
+:-          mode good_example3(in(bound("bar")), out) is det.
+good_example3(Name, univ_value(Univ)) :-
+	good_example3_univ(Name, Univ).
+
+:- pred good_example3_univ(string, univ).
+:- mode good_example3_univ(in(bound("foo")), out) is det.
+:- mode good_example3_univ(in(bound("bar")), out) is det.
+:- pragma promise_pure(good_example3_univ/2).
+good_example3_univ("foo"::in(bound("foo")), univ(42)::out).
+good_example3_univ("bar"::in(bound("bar")), univ("blah")::out).
 @end example
 
 @node Semantics

-- 
Fergus Henderson <fjh at cs.mu.oz.au>  |  "I have always known that the pursuit
The University of Melbourne         |  of excellence is a lethal habit"
WWW: <http://www.cs.mu.oz.au/~fjh>  |     -- the last words of T. S. Garp.
--------------------------------------------------------------------------
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
--------------------------------------------------------------------------