summaryrefslogtreecommitdiffhomepage
path: root/doc
diff options
context:
space:
mode:
authorJose Antonio Ortega Ruiz <jao@gnu.org>2001-09-16 22:17:33 +0000
committerJose Antonio Ortega Ruiz <jao@gnu.org>2001-09-16 22:17:33 +0000
commite259b37f7316117d7c0f74b53373481c94c3cf02 (patch)
tree62831fc2403eff30c1f0c9f2496b77acf003dc88 /doc
parenta1effd7645557b44f58ff684c719424bcd4c3038 (diff)
downloadmdk-e259b37f7316117d7c0f74b53373481c94c3cf02.tar.gz
mdk-e259b37f7316117d7c0f74b53373481c94c3cf02.tar.bz2
partial doc update
Diffstat (limited to 'doc')
-rw-r--r--doc/.cvsignore1
-rw-r--r--doc/mdk.texi22
-rw-r--r--doc/mdk_ack.texi4
-rw-r--r--doc/mdk_copying.texi2
-rw-r--r--doc/mdk_gstart.texi148
-rw-r--r--doc/mdk_index.texi4
-rw-r--r--doc/mdk_install.texi2
-rw-r--r--doc/mdk_intro.texi4
8 files changed, 164 insertions, 23 deletions
diff --git a/doc/.cvsignore b/doc/.cvsignore
index 0128ab7..3c56128 100644
--- a/doc/.cvsignore
+++ b/doc/.cvsignore
@@ -15,6 +15,7 @@ mdk.info-1
mdk.info-2
mdk.info-3
mdk.info-4
+mdk.info-5
mdk.ky
mdk.log
mdk.pg
diff --git a/doc/mdk.texi b/doc/mdk.texi
index 6999267..58afc1d 100644
--- a/doc/mdk.texi
+++ b/doc/mdk.texi
@@ -102,6 +102,7 @@ helpful discussions, as well as actual code (@pxref{mixvm.el}).
@menu
* Introduction::
+* Acknowledgments::
* Installing MDK:: Installing GNU MDK from the source tarball.
* MIX and MIXAL tutorial:: Learn the innards of MIX and MIXAL.
* Getting started:: Basic usage of the @sc{mdk} tools.
@@ -111,7 +112,6 @@ helpful discussions, as well as actual code (@pxref{mixvm.el}).
* mixasm:: Invoking the MIXAL assembler.
* Problems:: Reporting bugs.
* Copying:: @sc{mdk} licensing terms.
-* Acknowledgments::
* Concept Index:: Index of concepts.
* Instructions and commands:: Index of MIXAL instructions and MIXVM commands.
@@ -132,6 +132,9 @@ helpful discussions, as well as actual code (@pxref{mixvm.el}).
+
+
+
@detailmenu
--- The Detailed Node Listing ---
@@ -187,6 +190,7 @@ Getting started
* Running the program:: Running and debugging your programs.
* Using mixguile:: Using the Scheme interpreter to run and
debug your programs.
+* Using Scheme in mixvm and gmixvm::
Running the program
@@ -196,9 +200,15 @@ Running the program
Using @code{mixguile}
-* The mixguile shell::
-* Additional functions::
-* Defining new functions::
+* The mixguile shell:: Using the Scheme MIX virtual machine.
+* Additional functions:: Scheme functions accessing the VM.
+* Defining new functions:: Defining your own Scheme functions.
+* Hook functions::
+
+Hook functions
+
+* Command hooks::
+* Break hooks::
@code{mixvm}, the MIX computer simulator
@@ -235,6 +245,7 @@ Copying
@end menu
@include mdk_intro.texi
+@include mdk_ack.texi
@include mdk_install.texi
@include mdk_tut.texi
@include mdk_gstart.texi
@@ -244,7 +255,6 @@ Copying
@include mdk_mixasm.texi
@include mdk_bugs.texi
@include mdk_copying.texi
-@include mdk_ack.texi
@include mdk_index.texi
@include mdk_findex.texi
@@ -252,4 +262,4 @@ Copying
@contents
@bye
-$Id: mdk.texi,v 1.13 2001/09/13 00:13:39 jao Exp $
+$Id: mdk.texi,v 1.14 2001/09/16 22:17:33 jao Exp $
diff --git a/doc/mdk_ack.texi b/doc/mdk_ack.texi
index 4145694..cba9251 100644
--- a/doc/mdk_ack.texi
+++ b/doc/mdk_ack.texi
@@ -4,9 +4,9 @@
@c Free Software Foundation, Inc.
@c See the file mdk.texi for copying conditions.
-@c $Id: mdk_ack.texi,v 1.2 2001/09/14 00:48:29 jao Exp $
+@c $Id: mdk_ack.texi,v 1.3 2001/09/16 22:17:33 jao Exp $
-@node Acknowledgments, Concept Index, Copying, Top
+@node Acknowledgments, Installing MDK, Introduction, Top
@comment node-name, next, previous, up
@unnumbered Acknowledgements
diff --git a/doc/mdk_copying.texi b/doc/mdk_copying.texi
index bfb6b34..bbcd225 100644
--- a/doc/mdk_copying.texi
+++ b/doc/mdk_copying.texi
@@ -1,4 +1,4 @@
-@node Copying, Acknowledgments, Problems, Top
+@node Copying, Concept Index, Problems, Top
@appendix Copying
@menu
diff --git a/doc/mdk_gstart.texi b/doc/mdk_gstart.texi
index 67758f5..14a88d9 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.8 2001/09/15 02:14:01 jao Exp $
+@c $Id: mdk_gstart.texi,v 1.9 2001/09/16 22:17:33 jao Exp $
@node Getting started, mixvm.el, MIX and MIXAL tutorial, Top
@chapter Getting started
@@ -22,6 +22,7 @@ assumed; for a compact reminder, see @ref{MIX and MIXAL tutorial}.
* Running the program:: Running and debugging your programs.
* Using mixguile:: Using the Scheme interpreter to run and
debug your programs.
+* Using Scheme in mixvm and gmixvm::
@end menu
@node Writing a source file, Compiling, Getting started, Getting started
@@ -484,7 +485,7 @@ of executed instructions) and @code{weval} (which evaluates
w-expressions on the fly). For a complete description of all available
MIX commands, @xref{mixvm}.
-@node Using mixguile, , Running the program, Getting started
+@node Using mixguile, Using Scheme in mixvm and gmixvm, Running the program, Getting started
@section Using @code{mixguile}
With @code{mixguile} you can run a MIX simulator embedded in a Guile
@@ -497,6 +498,7 @@ using this MIX emulator.
* The mixguile shell:: Using the Scheme MIX virtual machine.
* Additional functions:: Scheme functions accessing the VM.
* Defining new functions:: Defining your own Scheme functions.
+* Hook functions::
@end menu
@node The mixguile shell, Additional functions, Using mixguile, Using mixguile
@@ -620,7 +622,7 @@ list of these additional functions,
In the next section, we'll see a sample of using these functions to
extend @code{mixguile}'s functionality.
-@node Defining new functions, , Additional functions, Using mixguile
+@node Defining new functions, Hook functions, Additional functions, Using mixguile
@subsection Defining new functions
@cindex Scheme functions
@@ -720,12 +722,26 @@ 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
+@node Hook functions, , Defining new functions, Using mixguile
@subsection Hook functions
@cindex hook function
@cindex pre-hook
@cindex post-hook
+Hooks are functions called before or after a given event occurs. In
+@code{mixguile}, you can define command and break hooks, which are
+associated, respectively, with command execution and program
+interruption events. The following sections give you a tutorial on using
+hook functions within @code{mixguile}.
+
+@menu
+* Command hooks::
+* Break hooks::
+@end menu
+
+@node Command hooks, Break hooks, Hook functions, Hook functions
+@subsubsection Command hooks
+
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
@@ -787,11 +803,9 @@ 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:
+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
@@ -832,3 +846,119 @@ New contents: 100
guile>
@end example
+@cindex global hook
+
+You can add any number of hooks to a given command. They will be
+executed in the same order as they are registered. You can also define
+global post (pre) hooks, which will be called before (after) any
+@code{mixvm} command is executed. Global hook functions must admit two
+arguments, namely, a string naming the invoked command and a string list
+of its arguments, and they are installed using the Scheme functions
+@code{mix-add-global-pre-hook} and @code{mix-add-global-post-hook}. A
+simple example of global hook would be:
+
+@example
+guile> (define pre-hook
+ (lambda (cmd args)
+ (display cmd)
+ (display " invoked with arguments ")
+ (display args)
+ (newline)))
+guile> (mix-add-global-pre-hook pre-hook)
+ok
+guile> (mix-pmem 120 125)
+pmem invoked with arguments (120-125)
+0120: + 00 00 00 00 00 (0000000000)
+0121: + 00 00 00 00 00 (0000000000)
+0122: + 00 00 00 00 00 (0000000000)
+0123: + 00 00 00 00 00 (0000000000)
+0124: + 00 00 00 00 00 (0000000000)
+0125: + 00 00 00 00 00 (0000000000)
+guile>
+@end example
+
+Note that if you invoke @code{mixvm} commands within a global hook, its
+associated command hooks will be run. Thus, if you have installed both
+the @code{next} hooks described earlier and the global hook above,
+executing @code{mix-next} will yield the following result:
+
+@example
+guile> (mix-next 5)
+next invoked with arguments (5)
+slog invoked with arguments (off)
+MIXAL HELLO WORLD
+Stopped at line 7: MSG ALF "MIXAL"
+slog invoked with arguments (on)
+guile>
+@end example
+
+Adventurous readers may see the above global hook as the beginning of a
+command log utility or a macro recorder that saves your commands for
+replay.
+
+@node Break hooks, , Command hooks, Hook functions
+@subsubsection Break hooks
+
+@cindex break hook
+
+We have seen in the previous section how to associate hooks to command
+execution, but they are not the whole story. You can also associate hook
+functions to program interruption, that is, specify functions that
+should be called every time the execution of a MIX program is stopped
+due to the presence of a breakpoint, either explicit or
+conditional. Break hooks take as arguments the line number and memory
+address at which the break occurred. A simple hook that logs the line
+and address of the breakpoint could be defined as:
+
+@example
+(define break-hook
+ (lambda (line address)
+ (display "Breakpoint encountered at line ")
+ (display line)
+ (display " and address ")
+ (display address)
+ (newline)))
+@end example
+@noindent
+and installed for explicit and conditional breakpoints using
+
+@example
+(mix-add-break-hook break-hook)
+(mix-add-cond-break-hook break-hook)
+@end example
+@noindent
+after that, every time the virtual machine encounters a breakpoint,
+@code{break-code} shall be evaluated for you@footnote{You may have
+noticed that break hooks can be implemented in terms of command hooks
+associated to @code{mix-run} and @code{mix-next}. As a matter of fact,
+they @emph{are} implemented this way: take a look at the file
+@file{@emph{install_dir}/share/mdk/mix-vm-stat.scm} if you are curious.}.
+
+
+@node Using Scheme in mixvm and gmixvm, , Using mixguile, Getting started
+@section Using Scheme in @code{mixvm} and @code{gmixvm}
+@cindex @code{scmf}
+
+In the previous section (@pxref{Using mixguile}) we have seen how the
+Guile shell @code{mixguile} offers you the possibility of using Scheme
+to manipulate a MIx virtual machine and extend the set of commands
+offered by @code{mixvm} and @code{gmixvm}. This possibility is not
+limited to the @code{mixguile} shell. Actually, both @code{mixvm} and
+@code{gmixvm} incorporate an embedded Guile interpreter, and can
+evaluate Scheme expressions. To evaluate a single-line expression at the
+@code{mixvm} or @code{gmixvm} command prompt, simply write it and press
+return (the command parser will recognise it as a Scheme expression
+because it is parenthesized, and will pass it to the Guile
+interpreter). You can also load and evaluate a file, using the @code{scmf}
+command like this:
+
+@example
+MIX> scmf /path/to/file/file.scm
+@end example
+
+Therefore, you have at your disposal all the @code{mixguile} goodies
+described above (new functions, new command definitions, hooks...)
+inside @code{mixvm} and @code{gmixvm}. In other words, these programs
+are extensible using Scheme. See @ref{Using mixguile} for examples of
+how to do it.
+
diff --git a/doc/mdk_index.texi b/doc/mdk_index.texi
index 9c3a1db..5aaecc4 100644
--- a/doc/mdk_index.texi
+++ b/doc/mdk_index.texi
@@ -4,9 +4,9 @@
@c Free Software Foundation, Inc.
@c See the file mdk.texi for copying conditions.
-@c $Id: mdk_index.texi,v 1.4 2001/09/13 00:13:39 jao Exp $
+@c $Id: mdk_index.texi,v 1.5 2001/09/16 22:17:33 jao Exp $
-@node Concept Index, Instructions and commands, Acknowledgments, Top
+@node Concept Index, Instructions and commands, Copying, Top
@unnumbered Concept Index
@cindex tail recursion
diff --git a/doc/mdk_install.texi b/doc/mdk_install.texi
index a9aa9a8..2874d79 100644
--- a/doc/mdk_install.texi
+++ b/doc/mdk_install.texi
@@ -4,7 +4,7 @@
@c Free Software Foundation, Inc.
@c See the file mdk.texi for copying conditions.
-@node Installing MDK, MIX and MIXAL tutorial, Introduction, Top
+@node Installing MDK, MIX and MIXAL tutorial, Acknowledgments, Top
@comment node-name, next, previous, up
@chapter Installing @sc{mdk}
diff --git a/doc/mdk_intro.texi b/doc/mdk_intro.texi
index 5464980..c86ca18 100644
--- a/doc/mdk_intro.texi
+++ b/doc/mdk_intro.texi
@@ -4,9 +4,9 @@
@c Free Software Foundation, Inc.
@c See the file mdk.texi for copying conditions.
-@c $Id: mdk_intro.texi,v 1.4 2001/09/13 00:13:39 jao Exp $
+@c $Id: mdk_intro.texi,v 1.5 2001/09/16 22:17:33 jao Exp $
-@node Introduction, Installing MDK, Top, Top
+@node Introduction, Acknowledgments, Top, Top
@comment node-name, next, previous, up
@unnumbered Introduction
@cindex Introduction