partial doc update

1 files changed, 115 insertions, 2 deletions

diff --git a/doc/mdk_gstart.texi b/doc/mdk_gstart.texi
index 9cdebf3..67758f5 100644
--- a/doc/mdk_gstart.texi
+++ b/doc/mdk_gstart.texi
@@ -4,7 +4,7 @@
 @c   Free Software Foundation, Inc.
 @c See the file mdk.texi for copying conditions.
 
-@c $Id: mdk_gstart.texi,v 1.7 2001/09/14 00:41:40 jao Exp $
+@c $Id: mdk_gstart.texi,v 1.8 2001/09/15 02:14:01 jao Exp $
 
 @node Getting started, mixvm.el, MIX and MIXAL tutorial, Top
 @chapter Getting started
@@ -614,7 +614,8 @@ guile>
 Other functions returning the contents of the virtual machine components
 are @code{mix-cmp} and @code{mix-over}, which eval to the value of the
 comparison flag and the overflow toggle respectively. For a complete
-list of these additional functions, see @xref{mixguile----}.
+list of these additional functions,
+@c see @xref{mixguile----}.
 
 In the next section, we'll see a sample of using these functions to
 extend @code{mixguile}'s functionality.
@@ -719,3 +720,115 @@ loads it before entering the REPL. Therefore, you can copy your
 definitions in that file, or load the @file{functions.scm} file in
 @file{mixguile.scm}.
 
+@node Hook functions
+@subsection Hook functions
+@cindex hook function
+@cindex pre-hook
+@cindex post-hook
+
+In the previous section, we have seen how to extend @code{mixguile}'s
+functionality through the use of user defined functions. Frequently,
+you'll write new functions that improve in some way the workings of a
+built-in @code{mixvm} command, following this pattern:
+
+@enumerate a
+@item
+Prepare the command execution
+@item
+Execute the desired command
+@item
+Perform post execution operations
+@end enumerate
+
+We call the functions executed in step (a) @dfn{pre-hook}s, and those of
+step @dfn{post-hook}s of the given command. @code{mixguile} lets you
+specify pre- and post-hooks for any @code{mixvm} command using the
+@code{mix-add-pre-hook} and  @code{mix-add-post-hook} functions, which
+take as arguments a symbol naming the command and a function to be
+executed before (resp. after) the command. In other words,
+@code{mixguile} will execute for you steps (a) and (c) above whenever
+you eval (b). The hook functions must take a single argument, which is a
+string list of the command's arguments. As an example, let us define the
+following hooks for the @code{next} command:
+
+@example
+(define next-pre-hook
+  (lambda (arglist)
+    (mix-slog #f)))
+
+(define next-post-hook
+  (lambda (arglist)
+    (display "Stopped at line ")
+    (display (mix-src-line-no))
+    (display ": ")
+    (display (mix-src-line))
+    (newline)
+    (mix-slog #t)))
+@end example
+@noindent
+In these functions, we are using the function @code{mix-slog} to turn
+off the informational messages produced by the virtual machine, since we
+are providing our own ones in the post hook function. To install these
+hooks, we would write:
+
+@example
+(mix-add-pre-hook 'next next-pre-hook)
+(mix-add-post-hook 'next next-post-hook)
+@end example
+@noindent
+Assuming we have put the above expressions in @code{mixguile}'s
+initialisation file, we would obtain the following results when
+evaluating @code{mix-next}: 
+
+@example
+guile> (mix-next)
+MIXAL HELLO WORLD                                                     
+Stopped at line 6:             HLT   
+guile> 
+@end example
+
+You can add any number of hooks to a given command. They will be
+executed in the same order as they are registered. As a second, more
+elaborated example, let's define hooks which print the address and
+contents of a cell being modified using @code{smem}. The hook functions
+could be something like this:
+
+@example
+(define smem-pre-hook
+  (lambda (arglist)
+    (if (eq? (length arglist) 2)
+        (begin
+          (display "Changing address ")
+          (display (car arglist))
+          (newline)
+          (display "Old contents: ")
+          (display (mix-cell (string->number (car arglist))))
+          (newline))
+        (error "Wrong arguments" arglist))))
+
+(define smem-post-hook
+  (lambda (arglist)
+    (if (eq? (length arglist) 2)
+        (begin
+          (display "New contents: ")
+          (display (mix-cell (string->number (car arglist))))
+          (newline)))))
+@end example
+@noindent
+and we can install them using
+
+@example
+(mix-add-pre-hook 'smem smem-pre-hook)
+(mix-add-post-hook 'smem smem-post-hook)
+@end example
+@noindent
+Aferwards, a sample execution of @code{mix-smem} would look like this:
+
+@example
+guile> (mix-smem 2000 100)
+Changing address 2000
+Old contents: 0
+New contents: 100
+guile>
+@end example
+