Summary

############################################################################

	File:     capture.icn

	Subject:  Procedures to echo output to a second file

	Author:   David A. Gamey

	Date:     August 14, 1996

############################################################################

   This file is in the public domain.

############################################################################

       Version:  1.0

############################################################################

  Capture is initially called by the user with one argument, the open file 
  to contain the echoed output. Then it places itself and several shadow 
  procedures between all calls to write, writes & stop.  The user never
  need call capture again.

  Subsequently, during calls to write, writes, and stop, the approprate 
  shadow procedure gains control and calls capture internally.  Capture 
  then constructs a list of only those elements that direct output to 
  &output and calls the original builtin function via the saved name.  
  Upon return the shadow routine calls the the original builtin function 
  with the full list.   

  A series of uncaptured output functions have been added to allow output
  to be directed only to &output.  These are handy for placing progress 
  messages and other comforting information on the screen.
  
  Example:

     otherfile := open(...,"w")

     capfile :=  capture(open(filename,"w"))

     write("Hello there.",var1,var2," - this should be echoed",
        otherfile,"This should appear once in the other file only")

     uncaptured_writes("This will appear once only.")

     every i := 1 to 10000 do
        if ( i % 100 ) = 0 then

           uncaptured_writes("Progress is ",i,"\r")

     close(capfile)
     close(otherfile)

############################################################################

  Notes: 

  1.    stop must be handled specially in its shadow function
  2.    capture is not designed to be turned off
  3.    This may be most useful in systems other than Unix 
        (i.e. that don't have a "tee" command)
  4.    Display has not been captured because
        a) display is usually a debugging aid, and capture was 
           originally intended to capture screen output to a file
           where a record or audit trail might be required
        b) the display output would be 'down a level' showing the 
           locals at the display_capture_ level, although the depth
           argument could easily be incremented to adjust for this
        c) write, writes, and stop handle arguments the same way
  5.    An alternative to having two calls would be to have capture
        call the desired procedure with : 
           push(&output,x) ; return p!(y ||| x )
        While this would remove the complexity with stop it would
        probably be slower

############################################################################

  History:

  10Jun94  -  D.Gamey  -  added uncaptured i/o routines
  05Oct94  -  D.Gamey  -  temporarily suspend tracing
  20Oct94  -  D.Gamey  -  fix no output for f(&null)
                       -  eliminated global variable and select procedure
  
############################################################################

This file is part of the (main) package.

capture(p, x)

stop_capture_(x)

uncaptured_stop(x)

uncaptured_write(x)

subtitle Support procedures to provide uncaptured output

uncaptured_writes(x)

write_capture_(x)

writes_capture_(x)