[m-rev.] for review: improvements to library/io.m

[Fergus Henderson]

Probably the most contentions part here is the addition of `io__print_cc'.
But I think this is really worthwhile, since this predicate is just
as useful as `io__print', and should not be any harder to write.
Currently instead of

	:- use_module io.
	p -->
		io__print_cc(some_term).

you have to use

	:- use_module io.
	:- use_module deconstruct.
	p -->
		io__current_output_stream(OutStream),
		io__print(OutStream, some_term,
			deconstruct__include_details_cc).

which is much less convenient.

----------

Estimated hours taken: 2
Branches: main

Some minor improvments to library/io.m.

library/io.m:
	- Add io__print_cc/3 and io__write_cc/3.
	- Improve the documentation of io__print and io__write.
	- Delete the long-obsolete predicates io__{print,write,read}_anything
	  (they were declared `pragma obsolete' in 1997).
	- Avoid some code duplication in the implementations.

NEWS:
	Mention the removal of io__{print,write,read}_anything.
	(The changes to add `io__print_cc/3' and `io__write_cc/3'
	were already covered by the existing wording about adding
	new versions of `io__print' and `io__write'.)

Workspace: /home/ceres/fjh/mercury
Index: library/io.m
===================================================================
RCS file: /home/mercury1/repository/mercury/library/io.m,v
retrieving revision 1.246
diff -u -d -r1.246 io.m
--- library/io.m	4 Mar 2002 19:28:53 -0000	1.246
+++ library/io.m	7 Mar 2002 13:36:44 -0000
@@ -330,22 +330,39 @@
 :- mode io__print(in, in(include_details_cc), in, di, uo) is cc_multi.
 :- mode io__print(in, in, in, di, uo) is cc_multi.
 
-%		io__print/5 writes its third argument to the specified output
-%		stream in a format that is intended to be human readable. 
+:- pred io__print_cc(T, io__state, io__state).
+:- mode io__print_cc(in, di, uo) is cc_multi.
+
+%	io__print/3 writes its argument to the standard output stream.
+%	io__print/4 writes its second argument to the output stream
+%	specified in its first argument.
+%	In all cases, the argument to output can be of any type.
+%	It is output in a format that is intended to be human readable.
 %
-%		If the argument is just a single string or character, it
-%		will be printed out exactly as is (unquoted).
-%		If the argument is of type univ, then it will print out
-%		the value stored in the univ, but not the type.
-%		For higher-order types, or for types defined using the
-%		foreign language interface (pragma foreign_code), the text
-%		output will only describe the type that is being printed, not
-%		the value.
+%	If the argument is just a single string or character, it
+%	will be printed out exactly as is (unquoted).
+%	If the argument is of type univ, then it will print out
+%	the value stored in the univ, but not the type.
 %
-%		io__print/4 implicitly specifies `canonicalize' as the
-%		treatment of noncanonical types, while io__print/3 also
-%		implicitly specifies the current output stream as the stream
-%		for this I/O action.
+%	io__print/5 is the same as io__print/4 except that it allows
+%	the caller to specify how non-canonical types should be handled.
+%	io__print/3 and io__print/4 implicitly specify `canonicalize'
+%	as the method for handling non-canonical types.  This means
+%	that for higher-order types, or types with user-defined
+%	equality axioms, or types defined using the foreign language
+%	interface (i.e. c_pointer type or pragma foreign_type),
+%	the text output will only describe the type that is being
+%	printed, not the value.
+%
+%	io__print_cc/3 is the same as io__print/3 except that it
+%	specifies `include_details_cc' rather than `canonicalize'.
+%	This means that it will print the details of non-canonical
+%	types.  However, it has determinism `cc_multi'.
+%
+%	Note that even if `include_details_cc' is specified,
+%	some implementations may not be able to print all the details
+%	for higher-order types or types defined using the foreign
+%	language interface.
 
 :- pred io__write(T, io__state, io__state).
 :- mode io__write(in, di, uo) is det.
@@ -360,24 +377,33 @@
 :- mode io__write(in, in(include_details_cc), in, di, uo) is cc_multi.
 :- mode io__write(in, in, in, di, uo) is cc_multi.
 
-%		io__write/3 writes its argument to the current output stream.
-%		io__write/4 writes its argument to the specified output stream.
-%		The argument may be of any type.
-%		The argument is written in a format that is intended to
-%		be valid Mercury syntax whenever possible.
+:- pred io__write_cc(T, io__state, io__state).
+:- mode io__write_cc(in, di, uo) is cc_multi.
+
+%	io__write/3 writes its argument to the current output stream.
+%	io__write/4 writes its second argument to the output stream
+%	specified in its first argument.
+%	In all cases, the argument to output may be of any type.
+%	The argument is written in a format that is intended to
+%	be valid Mercury syntax whenever possible.
 %
-%		Strings and characters are always printed out in quotes,
-%		using backslash escapes if necessary.
-%		For higher-order types, or for types defined using the
-%		foreign language interface (pragma foreign_code), the text
-%		output will only describe the type that is being printed, not
-%		the value, and the result may not be parsable by `io__read'.
-%		For the types containing existential quantifiers,
-%		the type `type_desc' and closure types, the result may not be
-%		parsable by `io__read', either.  But in all other cases the
-%		format used is standard Mercury syntax, and if you do append a
-%		period and newline (".\n"), then the results can be read in
-%		again using `io__read'.
+%	Strings and characters are always printed out in quotes,
+%	using backslash escapes if necessary.
+%	For higher-order types, or for types defined using the
+%	foreign language interface (pragma foreign_code), the text
+%	output will only describe the type that is being printed, not
+%	the value, and the result may not be parsable by `io__read'.
+%	For the types containing existential quantifiers,
+%	the type `type_desc' and closure types, the result may not be
+%	parsable by `io__read', either.  But in all other cases the
+%	format used is standard Mercury syntax, and if you do append a
+%	period and newline (".\n"), then the results can be read in
+%	again using `io__read'.
+%
+%	io__write/5 is the same as io__write/4 except that it allows
+%	the caller to specify how non-canonical types should be handled.
+%	io__write_cc/3 is the same as io__write/3 except that it
+%	specifies `include_details_cc' rather than `canonicalize'.
 
 :- pred io__nl(io__state, io__state).
 :- mode io__nl(di, uo) is det.
@@ -1177,29 +1203,6 @@
 %-----------------------------------------------------------------------------%
 :- interface.
 
-% For backwards compatibility:
-
-:- pragma obsolete(io__read_anything/3).
-:- pred io__read_anything(io__read_result(T), io__state, io__state).
-:- mode io__read_anything(out, di, uo) is det.
-%		Same as io__read/3.
-
-:- pragma obsolete(io__read_anything/4).
-:- pred io__read_anything(io__output_stream, io__read_result(T),
-			io__state, io__state).
-:- mode io__read_anything(in, out, di, uo) is det.
-%		Same as io__read/4.
-
-:- pragma obsolete(io__write_anything/3).
-:- pred io__write_anything(T, io__state, io__state).
-:- mode io__write_anything(in, di, uo) is det.
-%		Same as io__write/3.
-
-:- pragma obsolete(io__write_anything/4).
-:- pred io__write_anything(io__output_stream, T, io__state, io__state).
-:- mode io__write_anything(in, in, di, uo) is det.
-%		Same as io__write/4.
-
 % For use by term_io.m:
 
 :- import_module ops.
@@ -2090,9 +2093,6 @@
 	io__binary_input_stream(Stream),
 	io__putback_byte(Stream, Char).
 
-io__read_anything(Result) -->
-	io__read(Result).
-
 io__read(Result) -->
 	term_io__read_term(ReadResult),
 	io__get_line_number(LineNumber),
@@ -2157,9 +2157,6 @@
 		Result = error(String, Int)
 	).
 
-io__read_anything(Stream, Result) -->
-	io__read(Stream, Result).
-
 io__read(Stream, Result) -->
 	io__set_input_stream(Stream, OrigStream),
 	io__read(Result),
@@ -2236,6 +2233,8 @@
 
 %-----------------------------------------------------------------------------%
 
+% various different versions of io__print
+
 :- pragma export(io__print(in, in(do_not_allow), in, di, uo),
 	"ML_io_print_dna_to_stream").
 :- pragma export(io__print(in, in(canonicalize), in, di, uo),
@@ -2260,6 +2259,9 @@
 io__print(Term) -->
 	io__do_print(canonicalize, Term).
 
+io__print_cc(Term) -->
+	io__do_print(include_details_cc, Term).
+
 :- pred io__do_print(deconstruct__noncanon_handling, T, io__state, io__state).
 :- mode io__do_print(in(do_not_allow), in, di, uo) is det.
 :- mode io__do_print(in(canonicalize), in, di, uo) is det.
@@ -2300,11 +2302,9 @@
 	)
 */
 
-io__write_anything(Anything) -->
-	io__write(Anything).
+%-----------------------------------------------------------------------------%
 
-io__write_anything(Stream, Anything) -->
-	io__write(Stream, Anything).
+% various different versions of io__write
 
 io__write(Stream, NonCanon, X) -->
 	io__set_output_stream(Stream, OrigStream),
@@ -2316,9 +2316,11 @@
 	io__do_write(canonicalize, X),
 	io__set_output_stream(OrigStream, _Stream).
 
-io__write(Term) -->
-	{ type_to_univ(Term, Univ) },
-	io__write_univ(Univ).
+io__write(X) -->
+	io__do_write(canonicalize, X).
+
+io__write_cc(X) -->
+	io__do_write(include_details_cc, X).
 
 :- pred io__do_write(deconstruct__noncanon_handling, T, io__state, io__state).
 :- mode io__do_write(in(do_not_allow), in, di, uo) is det.
@@ -2328,23 +2330,23 @@
 
 io__do_write(NonCanon, Term) -->
 	{ type_to_univ(Term, Univ) },
-	io__get_op_table(OpTable),
-	io__do_write_univ(NonCanon, Univ, ops__max_priority(OpTable) + 1).
+	io__do_write_univ(NonCanon, Univ).
+
+%-----------------------------------------------------------------------------%
+
+% various different versions of io__write_univ
 
 io__write_univ(Univ) -->
-	io__get_op_table(OpTable),
-	io__do_write_univ(canonicalize, Univ, ops__max_priority(OpTable) + 1).
+	io__do_write_univ(canonicalize, Univ).
 
 io__write_univ(Stream, Univ) -->
 	io__set_output_stream(Stream, OrigStream),
-	io__get_op_table(OpTable),
-	io__do_write_univ(canonicalize, Univ, ops__max_priority(OpTable) + 1),
+	io__do_write_univ(canonicalize, Univ),
 	io__set_output_stream(OrigStream, _Stream).
 
 io__write_univ(Stream, NonCanon, Univ) -->
 	io__set_output_stream(Stream, OrigStream),
-	io__get_op_table(OpTable),
-	io__do_write_univ(NonCanon, Univ, ops__max_priority(OpTable) + 1),
+	io__do_write_univ(NonCanon, Univ),
 	io__set_output_stream(OrigStream, _Stream).
 
 :- pred io__do_write_univ(deconstruct__noncanon_handling, univ,
Index: NEWS
===================================================================
RCS file: /home/mercury1/repository/mercury/NEWS,v
retrieving revision 1.247
diff -u -d -u -r1.247 NEWS
--- NEWS	6 Mar 2002 14:34:52 -0000	1.247
+++ NEWS	7 Mar 2002 13:47:30 -0000
@@ -173,7 +173,11 @@
 * We've removed the long obsolete `int__builtin_*' and
   `float__builtin_float_*' predicates, which were synonyms
   for the arithmetic functions dating from when Mercury didn't
-  have functions.
+  have functions. 
+  
+* We've removed the long obsolete predicates `io__read_anything',
+  `io__write_anything', and `io__print_anything', which were long ago
+  renamed as `io__read', `io__write', and `io__print' respectively.
 
 Changes to the extras distribution:
 

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