summaryrefslogtreecommitdiffhomepage
diff options
context:
space:
mode:
authorJose Antonio Ortega Ruiz <jao@gnu.org>2001-09-15 02:14:01 +0000
committerJose Antonio Ortega Ruiz <jao@gnu.org>2001-09-15 02:14:01 +0000
commita211bda54bf57c1e2565f82ed7985f660593a64f (patch)
tree5c727411d50206227e4693d33750d47c5e60232f
parent1da0768f6973118f0286bebe5508462bb6a176cf (diff)
downloadmdk-a211bda54bf57c1e2565f82ed7985f660593a64f.tar.gz
mdk-a211bda54bf57c1e2565f82ed7985f660593a64f.tar.bz2
partial doc update
-rw-r--r--doc/mdk_gstart.texi117
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
+