[m-dev.] logging proposal

[Ian MacLarty]

On Mon, Mar 06, 2006 at 11:41:59AM +1100, Julien Fischer wrote:
> 
> On Sun, 5 Mar 2006, Ian MacLarty wrote:
> 
> > On 2 Mar 2006, at 05:54, Ralph Becket wrote:
> >
> > > Mark Brown, Thursday,  2 March 2006:
> > >> but I think I prefer the list syntax.
> > >
> > > Seconded.
> >
> > I'm happy with the list syntax.  I'm not sure when I'll get time to
> > implement this though :-)
> >
> > I was thinking of implementing it in the following way:
> >
> 
> I suggest that you first of all write the reference manual entry for
> this feature and *then* we can discuss how to implement it.

Index: doc/reference_manual.texi
===================================================================
RCS file: /home/mercury1/repository/mercury/doc/reference_manual.texi,v
retrieving revision 1.345
diff -u -r1.345 reference_manual.texi
--- doc/reference_manual.texi	8 Mar 2006 02:25:38 -0000	1.345
+++ doc/reference_manual.texi	11 Mar 2006 14:29:07 -0000
@@ -642,55 +642,6 @@
 
+
+ at item @code{debug @var{Vars} @var{Goal}}
+A goal used only for the purposes of debugging.
+ at var{Vars} is a list containing exactly two variables of the
+type io.state.  
+ at var{Goal} is a deterministic goal that may perform I/O using the
+io.state variables in @var{Vars}.
+When debug goals are disabled they are equivalent to the goal @samp{true}.
+When debug goals are enabled they are equivalent to the impure goal
+ at code{impure make_io_state(IO0), Goal, impure consume_io_state(IO)}
+where IO0 and IO are the names of the variables given in @var{Vars} and
+ at code{make_io_state/1} constructs a fake @code{io.state} variable and 
+ at code{comsume_io_state/1} destroys the fake io.state, with the exception that
+the impurity need not be propogated to the predicate the debug goal
+appears in.
+
 @end table
 
 @node State variables
@@ -8819,6 +8833,50 @@
 		impure Ys = map(ImpureFunc, Ys).
 @end example
 
+ at node Debug goals
+ at section Debug goals
+
+Sometimes it is useful for a program to have side effects only for the purposes
+of debugging.
+For example you may wish to observe the state of an executing
+program by printing out the values of certain variables at different points
+of execution.  
+In these cases it is unnessecarily restrictive to either thread
+an I/O state through all of your program
+(the program may be non-determinstic),
+or to use the impurity system to achive the desired side effects
+(since then the impurity must be propogated to all ancestors of the
+predicate(s) containing the impure debugging goals,
+even when the program is not being debugged).
+
+The Mercury language therefore supports a special type of goal called a 
+ at emph{debug goal} (@pxref{Goals}).
+Each debug goal has access to its own pair of io.state variables.
+
+For example:
+
+ at example
+	:- pred perform_computation(float::in, float::out) is det.
+
+	perform_computation(Input, Output) :-
+		do_complex_calculation(Input, Ouput),
+		debug [!IO] (
+			io.format("input = %.8f, output = %.8f\n",
+				[f(Input), f(Output)], !IO)
+		).
+ at end example
+
+Mercury compiler implemetations are required to support a boolean switch
+which allows the user to enable or disable debug goals at compile time.
+Debug goals only produce side effects if the compiler option to enable them is
+given at compilation time.
+If debug goals are disabled then they are equivalent
+to the empty conjunction.
+
+Debug goals must pass type and mode checking regardless of whether they are
+enabled or not.
+For the purposes of mode checking the debug goals are 
+treated as impure.
+
 @node Pragmas
 @chapter Pragmas
 
--------------------------------------------------------------------------
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
--------------------------------------------------------------------------