[m-dev.] Stream2000

[Fergus Henderson]

On 21-Nov-2000, Peter Ross <peter.ross at miscrit.be> wrote:
> :- typeclass stream__line(S) <= stream__input(S) where [

I think there should be a comment immediately above that giving a
brief summary of what the `stream__line' type class is for.

> :- implementation.
> 
> 	% XXX needed so that we can build the library version.
> :- import_module (impure), lowlevel.
>
> :- import_module mutvar.
> :- import_module int, string.

It took me a long time to figure out what you meant by that XXX
comment.  So I suggest you elaborate, saying exactly what is needed
and explaining in more detail what you mean by "building the library
version"  (The library version of what?  And what's the library version
anyway?).

> %-----------------------------------------------------------------------------%
> % Copyright (C) 2000 The University of Melbourne.
> % This file may only be copied under the terms of the GNU Library General
> % Public License - see the file COPYING.LIB
> %-----------------------------------------------------------------------------%
> %
> % File: impure.m.
> % Main author: petdr
> % Stability: exceptionally low.
> %
> % An impure interface for describing streams.

It would be a good idea for the documentation here
to include a pointer to lowlevel.m, and vice versa.

> % An instance of the pure interface is then easily obtained, as shown by
> % the following instance declarations.
> %
> % :- instance stream__input(impure(your_type)) where [
> %	(stream__read_char(S, R) --> impure__read_char(S, R))
> % ].
> % :- instance stream__output(impure(your_type)) where [
> %	(stream__write_char(S, C) --> impure__write_char(S, C))
> % ].

Instance declarations of that form, where the type in question
has more than one type constructor, are forbidden by the Mercury
language reference manual.  (The two type constructors involved
here are impure/1 and your_type/0).

Is there some reason why you don't just use a generic instance
declaration of the form

	:- instance stream__input(impure(T)) <= lowlevel(T) where [
		stream__read_char(S, R) --> impure__read_char(S, R)
	].
?

(Did we already cover this issue?)

> % File: lowlevel.m.
...
> % This file provides throwing exceptions, grabbing error messages and
> % results packaged into ok/error/eof.

s/results packaged/packaging results/

> :- typeclass lowlevel(S) where [
> 		% Did an error occur processing the stream?
> 		% This predicate must also clear the error status of a
> 		% stream after reporting the error.
> 		% The bool indicates whether the predicate succeded.
> 	pred get_error(S::in, string::out, bool::out,
> 			io__state::di, io__state::uo) is det
> ].

s/succeded/succeeded/

Instead of
 		% The bool indicates whether the predicate succeded.
I would suggest
 		% The bool indicates whether there was an error.
		% If the bool is yes, then the string returned
		% holds the error message.

> :- typeclass lowlevel__input(S) <= lowlevel(S) where [
> 		% Read one character from the stream described by S.
> 		% The bool indicates whether the predicate succeded.
> 	pred read_char(S::in, char::out, bool::out,
> 			io__state::di, io__state::uo) is det,

s/succeded/succeeded/

Also I suggest
	s/Read one/Attempt to read one/
	s/predicate succeeded/character was successfully read/

> 		% Have we reached the eof for S?
> 		% The bool indicates whether the predicate succeded.

I suggest

 		% The bool will be yes iff S is at the eof.

Also it might help to spell out the first occurence of eof
as end-of-file.

> :- typeclass output(S) <= lowlevel(S) where [
> 		% Read one character from the current stream.
> 		% The bool indicates whether the predicate succeded.
> 	pred write_char(S::in, char::in, bool::out,

s/Read one/Write one/

Also I suggest
	s/Write one/Attempt to write one/
	s/predicate succeeded/character was successfully written/

It might be a good idea to document that for some stream types,
failures to send the character to its final destination may not be
reported at this point, but may instead be reported later; such
failures may be indicated on subsequent output operations, or when the
stream is closed.

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