link capture
March 25, 2002; David A. Gamey
This file is in the public domain.
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 appropriate
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