[m-dev.] Stream2000

[Peter Ross]

On Wed, Nov 22, 2000 at 12:41:41AM +1100, Fergus Henderson wrote:
> 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?).
> 
Will do, this is an artifact from the fact that I have been using this
code as a library in the quicksilver webserver.


> > %-----------------------------------------------------------------------------%
> > % 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?)
> 
No we didn't, I thought I had used those instance declarations as is for
the tcp.m module that I have been writing, but on closer examination I
didn't.  I have deleted the comment.

It is not possible to use a generic instance.  As there is no generic
way to determine the stream name, unless we add a new method to the
impure base type class, but I prefer that sort of meta information to
reside in a Mercury type, not in the C type that we are likely to be
using at this level.

Index: impure.m
===================================================================
RCS file: /cvsroot/quicksilver/webserver/stream/impure.m,v
retrieving revision 1.1
diff -u -r1.1 impure.m
--- impure.m	2000/11/20 17:40:40	1.1
+++ impure.m	2000/11/21 14:00:47
@@ -8,7 +8,8 @@
 % Main author: petdr
 % Stability: exceptionally low.
 %
-% An impure interface for describing streams.
+% An impure interface for describing streams, you may want to also look
+% at the pure lowlevel interface in lowlevel.m.
 %
 % This file provides a typeclass for people who want to map streams
 % to a foreign language binding while doing the minimum amount of work.  In
@@ -21,16 +22,6 @@
 % IO into Mercury di/uo.  That's all it does, but it's something you'll
 % have to do and get right every time you implement a stream, so we have
 % done it for you.
-%
-% 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))
-% ].
 %
 %-----------------------------------------------------------------------------%
 %-----------------------------------------------------------------------------%
Index: lowlevel.m
===================================================================
RCS file: /cvsroot/quicksilver/webserver/stream/lowlevel.m,v
retrieving revision 1.1
diff -u -r1.1 lowlevel.m
--- lowlevel.m	2000/11/21 10:23:20	1.1
+++ lowlevel.m	2000/11/21 14:00:47
@@ -17,7 +17,7 @@
 % defined interface.
 %
 % This file provides throwing exceptions, grabbing error messages and
-% results packaged into ok/error/eof.
+% packaging results into ok/error/eof.
 %
 %-----------------------------------------------------------------------------%
 %-----------------------------------------------------------------------------%
@@ -36,25 +36,29 @@
 		% 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.
+		% The bool indicates whether there was an error.  If the
+		% bool is yes, then the string returned holds the error
+		% message.
 	pred get_error(S::in, string::out, bool::out,
 			io__state::di, io__state::uo) is det
 ].
 
 :- typeclass lowlevel__input(S) <= lowlevel(S) where [
-		% Read one character from the stream described by S.
-		% The bool indicates whether the predicate succeded.
+		% Attempt to read one character from the stream
+		% described by S.  
+		% The bool indicates whether the character was
+		% successfully read.
 	pred read_char(S::in, char::out, bool::out,
 			io__state::di, io__state::uo) is det,
 
-		% Have we reached the eof for S?
-		% The bool indicates whether the predicate succeded.
+		% The bool will be yes iff S is at the end-of-file (eof).
 	pred is_eof(S::in, bool::out, io__state::di, io__state::uo) is det
 ].
 
 :- typeclass output(S) <= lowlevel(S) where [
-		% Read one character from the current stream.
-		% The bool indicates whether the predicate succeded.
+		% Attempt to write one character to the current stream.
+		% The bool indicates whether the character was
+		% successfully written.
 	pred write_char(S::in, char::in, bool::out,
 			io__state::di, io__state::uo) is det
 ].
Index: stream.m
===================================================================
RCS file: /cvsroot/quicksilver/webserver/stream/stream.m,v
retrieving revision 1.3
diff -u -r1.3 stream.m
--- stream.m	2000/11/21 10:23:20	1.3
+++ stream.m	2000/11/21 14:00:47
@@ -195,7 +195,9 @@
 
 :- implementation.
 
-	% XXX needed so that we can build the library version.
+	% These two imports are only so that when building a stand-alone
+	% stream library we include the following modules in the
+	% library.
 :- import_module (impure), lowlevel.
 
 :- import_module mutvar.

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