From 767dbb1af30500cc0ad44d6bd0e0e179a1191ec6 Mon Sep 17 00:00:00 2001 From: Andy Wingo Date: Tue, 12 Oct 2010 13:01:10 +0200 Subject: [PATCH] remove gds docs, telling users instead to use geiser and paredit * doc/ref/scheme-using.texi (Using Guile in Emacs): Remove GDS docs, as we don't have GDS any more. Instead of surveying the field, be opinionated and tell users what to use: Geiser and Paredit. --- doc/ref/scheme-using.texi | 763 +++----------------------------------- 1 file changed, 46 insertions(+), 717 deletions(-) diff --git a/doc/ref/scheme-using.texi b/doc/ref/scheme-using.texi index 810ee1574..4e666d70a 100644 --- a/doc/ref/scheme-using.texi +++ b/doc/ref/scheme-using.texi @@ -567,735 +567,64 @@ Finally, as a word to the wise: hackers close their REPL prompts with @node Using Guile in Emacs @section Using Guile in Emacs -@cindex GDS @cindex Emacs -There are several options for working on Guile Scheme code in Emacs. -The simplest are to use Emacs's standard @code{scheme-mode} for -editing code, and to run the interpreter when you need it by typing -``guile'' at the prompt of a @code{*shell*} buffer, but there are -Emacs libraries available which add various bells and whistles to -this. The following diagram shows these libraries and how they relate -to each other, with the arrows indicating ``builds on'' or -``extends''. For example, the Quack library builds on cmuscheme, -which in turn builds on the standard scheme mode. +Any text editor can edit Scheme, but some are better than others. Emacs +is the best, of course, and not just because it is a fine text editor. +Emacs has good support for Scheme out of the box, with sensible +indentation rules, parenthesis-matching, syntax highlighting, and even a +set of keybindings for structural editing, allowing navigation, +cut-and-paste, and transposition operations that work on balanced +S-expressions. -@iftex -@center @image{scheme,5in} -@end iftex -@ifnottex -@example -@verbatiminclude scheme.txt -@end example -@end ifnottex +As good as it is, though, two things will vastly improve your experience +with Emacs and Guile. -@dfn{scheme}, written by Bill Rozas and Dave Love, is Emacs's standard -mode for Scheme code files. It provides Scheme-sensitive syntax -highlighting, parenthesis matching, indentation and so on. +@cindex Paredit +The first is Taylor Campbell's +@uref{http://www.emacswiki.org/emacs/ParEdit, Paredit}. You should not +code in any dialect of Lisp without Paredit. (They say that +unopinionated writing is boring---hence this tone---but it's the +truth, regardless.) Paredit is the bee's knees. -@dfn{cmuscheme}, written by Olin Shivers, provides a comint-based Scheme -interaction buffer, so that you can run an interpreter more directly -than with the @code{*shell*} buffer approach by typing @kbd{M-x -run-scheme}. It also extends @code{scheme-mode} so that there are key -presses for sending selected bits of code from a Scheme buffer to this -interpreter. This means that when you are writing some code and want to -check what an expression evaluates to, you can easily select that code -and send it to the interpreter for evaluation, then switch to the -interpreter to see what the result is. cmuscheme is included in the -standard Emacs distribution. +@cindex Geiser +The second is José Antonio Ortega Ruiz's +@uref{http://www.nongnu.org/geiser/, Geiser}. Geiser complements Emacs' +@code{scheme-mode} with tight integration to running Guile processes via +a @code{comint-mode} REPL buffer. -@dfn{Quack}, written by Neil Van Dyke, adds a number of incremental -improvements to the scheme/cmuscheme combination: convenient menu -entries for looking up Scheme-related references (such as the SRFIs); -enhanced indentation rules that are customized for particular Scheme -interpreters, including Guile; an enhanced version of the -@code{run-scheme} command that knows the names of the common Scheme -interpreters and remembers which one you used last time; and so on. -Quack is available from @uref{http://www.neilvandyke.org/quack}. +Of course there are keybindings to switch to the REPL, and a good REPL +environment, but Geiser goes beyond that, providing: -@dfn{GDS}, written by Neil Jerram, also builds on the scheme/cmuscheme -combination, but with a change to the way that Scheme code fragments -are sent to the interpreter for evaluation. cmuscheme and Quack send -code fragments to the interpreter's standard input, on the assumption -that the interpreter is expecting to read Scheme expressions there, -and then monitor the interpreter's standard output to infer what the -result of the evaluation is. GDS doesn't use standard input and -output like this. Instead, it sets up a socket connection between the -Scheme interpreter and Emacs, and sends and receives messages using a -simple protocol through this socket. The messages include requests to -evaluate Scheme code, and responses conveying the results of an -evaluation, thus providing similar function to cmuscheme or Quack. -They also include requests for stack exploration and debugging, which -go beyond what cmuscheme or Quack can do. The price of this extra -power, however, is that GDS is Guile-specific. GDS requires the -Scheme interpreter to run some GDS-specific library code; currently -this code is written as a Guile module and uses features that are -specific to Guile. GDS is now included in the Guile distribution; for -previous Guile releases (1.8.4 and earlier) it can be obtained as part -of the @code{guile-debugging} package from -@uref{http://www.ossau.uklinux.net/guile}. - -Finally, @dfn{xscheme} is similar to cmuscheme --- in that it starts up -a Scheme interaction process and sends commands to that process's -standard input --- and to GDS --- in that it has support beyond -cmuscheme or Quack for exploring the Scheme stack when an error has -occurred --- but is implemented specifically for MIT/GNU Scheme. Hence -it isn't really relevant to Guile work in Emacs, except as a reference -for useful features that could be implemented in one of the other -libraries mentioned here. - -In summary, the best current choice for working on Guile code in Emacs -is either Quack or GDS, depending on which of these libraries' features -you find most important. For more information on Quack, please see the -website referenced above. GDS is documented further in the rest of this -section. - -@menu -* GDS Introduction:: -* GDS Architecture:: -* GDS Getting Started:: -* Working with GDS in Scheme Buffers:: -* Displaying the Scheme Stack:: -* Continuing Execution:: -* Associating Buffers with Clients:: -* An Example GDS Session:: -@end menu - - -@node GDS Introduction -@subsection GDS Introduction - -GDS aims to allow you to work on Guile Scheme code in the same kind of -way that Emacs allows you to work on Emacs Lisp code: providing easy -access to help, evaluating arbitrary fragments of code, a nice debugging -interface, and so on. The thinking behind the GDS library is that you -will usually be doing one of two things. - -@enumerate +@itemize @bullet @item -Writing or editing code. The code will be in a normal Emacs Scheme mode -buffer, and GDS extends Scheme mode to add keystrokes and menu items for -the things that are likely to be useful to you when working on code: - -@itemize +Form evaluation in the context of the current file's module. @item -completing the identifier at point, with respect to the set of variable -names that are known to the associated Guile process +Macro expansion. @item -accessing Guile's built in ``help'' and ``apropos'' commands +File/module loading and/or compilation. @item -evaluating fragments of code to check what they do, with the results -popping up in a temporary Emacs window. +Namespace-aware identifier completion (including local bindings, names +visible in the current module, and module names). +@item +Autodoc: the echo area shows information about the signature of the +procedure/macro around point automatically. +@item +Jump to definition of identifier at point. +@item +Access to documentation (including docstrings when the implementation +provides it). +@item +Listings of identifiers exported by a given module. +@item +Listings of callers/callees of procedures. +@item +Rudimentary support for debugging and error navigation. +@item +Support for multiple, simultaneous REPLs. @end itemize -@item -Debugging a Guile Scheme program. When your program hits an error or -stops at a trap, GDS shows you the relevant code and the Scheme stack, -and makes it easy to - -@itemize -@item -look at the values of local variables -@item -see what is happening at all levels of the Scheme stack -@item -continue execution, either normally or step by step. -@end itemize - -The presentation makes it very easy to move up and down the stack, -showing whenever possible the source code for each frame in another -Emacs buffer. It also provides convenient keystrokes for telling Guile -what to do next; for example, you can select a stack frame and tell -Guile to run until that frame completes, at which point GDS will display -the frame's return value. -@end enumerate - -GDS can provide these facilities for any number of Guile Scheme programs -(which we often refer to as ``clients'') at once, and these programs can -be started either independently of GDS, including outside Emacs, or -specifically @emph{by} GDS. - -Communication between each Guile client program and GDS uses a TCP -socket, which means that it is orthogonal to any other interfaces that -the client program has. In particular GDS does not interfere with a -program's standard input and output. - - -@node GDS Architecture -@subsection GDS Architecture - -In order to understand the following documentation fully it will help to -have a picture in mind of how GDS works, so we briefly describe that -here. GDS consists of three components. - -@itemize -@item -The GDS @dfn{interface} code is written in Emacs Lisp and runs inside -Emacs. This code, consisting of the installed files @file{gds.el} and -@file{gds-server.el}, is responsible for displaying information from -Guile in Emacs windows, and for responding to Emacs commands and -keystrokes by sending instructions back to the Guile program being -worked on. - -@item -The GDS @dfn{server} code is written in Scheme and runs as an Emacs -inferior process. It acts as a multiplexer between the (possibly -multiple) Guile programs being debugged and the interface code running -in Emacs. The server code is the installed file -@file{gds-server.scm}. - -@item -The GDS @dfn{client} code is written in Scheme (installed file -@file{gds-client.scm}), and must be loaded as a module by each Guile -program that wants to use GDS in any way. -@end itemize - -@noindent -The following diagram shows how these components are connected to each -other. - -@iftex -@center @image{gds,5in} -@end iftex -@ifnottex -@example -@verbatiminclude gds.txt -@end example -@end ifnottex - -@cindex TCP, use of -The data exchanged between client and server components, and between -server and interface, is a sequence of sexps (parenthesised expressions) -that are designed so as to be directly readable by both Scheme and Emacs -Lisp. The use of a TCP connection means that the server and Emacs -interface can theoretically be on a different computer from the client -programs, but in practice there are currently two problems with -this. Firstly the GDS API doesn't provide any way of specifying a -non-local server to connect to, and secondly there is no security or -authentication mechanism in the GDS protocol. These are issues that -should be addressed in the future. - - -@node GDS Getting Started -@subsection Getting Started with GDS - -To enable the use of GDS in your own Emacs sessions, simply add - -@lisp -(require 'gds) -@end lisp - -@noindent -somewhere in your @file{.emacs} file. This will cause Emacs to load the -GDS Emacs Lisp code when starting up, and to start the inferior GDS -server process so that it is ready and waiting for any Guile programs -that want to use GDS. - -(If GDS's Scheme code is not installed in one of the locations in -Guile's load path, you may find that the server process fails to start. -When this happens you will see an error message from Emacs: - -@lisp -error in process filter: Wrong type argument: listp, Backtrace: -@end lisp - -@noindent -and the @code{gds-debug} buffer will contain a Scheme backtrace ending -with the message: - -@lisp -no code for module (ice-9 gds-server) -@end lisp - -@noindent -The solution for this is to customize the Emacs variable -@code{gds-scheme-directory} so that it specifies where the GDS Scheme -code is installed. Then either restart Emacs or type @kbd{M-x -gds-run-debug-server} to try starting the GDS server process again.) - -For evaluations, help and completion from Scheme code buffers that you -are working on, this is all you need. The first time you do any of -these things, GDS will automatically start a new Guile client program as -an Emacs subprocess. This Guile program does nothing but wait for and -act on instructions from GDS, and we refer to it as a @dfn{utility} -Guile client. Over time this utility client will accumulate the code -that you ask it to evaluate, and you can also tell it to load complete -files or modules by sending it @code{load} or @code{use-modules} -expressions. - -When you want to use GDS to work on an independent Guile -application, you need to add something to that application's Scheme code -to cause it to connect to and interact with GDS at the right times. The -following subsections describe the ways of doing this. - -@subsubsection Invoking GDS when an Exception Occurs - -One option is to use GDS to catch and display any exceptions that -are thrown by the application's code. If you already have a -@code{lazy-catch} or @code{with-throw-handler} around the area of code -that you want to monitor, you just need to add the following to the -handler code: - -@lisp -(gds-debug-trap (throw->trap-context key args)) -@end lisp - -@noindent -where @code{key} and @code{args} are the first and rest arguments that -Guile passes to the handler. (In other words, they assume the handler -signature @code{(lambda (key . args) @dots{})}.) With Guile 1.8 or -later, you can also do this with a @code{catch}, by adding this same -code to the catch's pre-unwind handler. - -If you don't already have any of these, insert a whole -@code{with-throw-handler} expression (or @code{lazy-catch} if your Guile -is pre-1.8) around the code of interest like this: - -@lisp -(with-throw-handler #t - (lambda () - ;; Protected code here. - ) - (lambda (key . args) - (gds-debug-trap (throw->trap-context key args)))) -@end lisp - -Either way, you will need to use the @code{(ice-9 gds-client)} and -@code{(ice-9 debugging traps)} modules. - -Two special cases of this are the lazy-catch that the Guile REPL code -uses to catch exceptions in user code, and the lazy-catch inside the -@code{stack-catch} utility procedure that is provided by the -@code{(ice-9 stack-catch)} module. Both of these use a handler called -@code{lazy-handler-dispatch} (defined in @file{boot-9.scm}), which you -can hook into such that it calls GDS to display the stack when an -exception occurs. To do this, use the @code{on-lazy-handler-dispatch} -procedure as follows. - -@lisp -(use-modules (ice-9 gds-client) - (ice-9 debugging traps)) -(on-lazy-handler-dispatch gds-debug-trap) -@end lisp - -@noindent -After this the program will use GDS to display the stack whenever it -hits an exception that is protected by a @code{lazy-catch} using -@code{lazy-handler-dispatch}. - -@subsubsection Accepting GDS Instructions at Any Time - -In addition to setting an exception handler as described above, a -Guile program can in principle set itself up to accept new -instructions from GDS at any time, not just when it has stopped at an -exception. This would allow the GDS user to evaluate code in the -context of the running program, without having to wait for the program -to stop first. - -@lisp -(use-modules (ice-9 gds-client)) -(gds-accept-input #t) -@end lisp - -@code{gds-accept-input} causes the calling program to loop processing -instructions from GDS, until GDS sends the @code{continue} instruction. -This blocks the thread that calls it, however, so it will normally be -more practical for the program to set up a dedicated GDS thread and call -@code{gds-accept-input} from that thread. - -For @code{select}-driven applications, an alternative approach would be -for the GDS client code to provide an API which allowed the application -to - -@itemize -@item -discover the file descriptors (or Scheme ports) that are used for -receiving instruction from the GDS front end, so that it could include -these in its @code{select} call - -@item -call the GDS instruction handler when @code{select} indicated data -available for reading on those descriptors/ports. -@end itemize - -@noindent -This approach is not yet implemented, though. - -@subsubsection Utility Guile Implementation - -The ``utility'' Guile client mentioned above is a simple combination -of the mechanisms that we have just described. In fact the code for -the utility Guile client is essentially just this: - -@lisp -(use-modules (ice-9 gds-client)) -(named-module-use! '(guile-user) '(ice-9 session)) -(gds-accept-input #f)) -@end lisp - -The @code{named-module-use!} line ensures that the client can process -@code{help} and @code{apropos} expressions, to implement lookups in -Guile's online help. The @code{#f} parameter to -@code{gds-accept-input} means that the @code{continue} instruction -will not cause the instruction loop to exit, which makes sense here -because the utility client has nothing to do except to process GDS -instructions. - -The utility client does not use @code{on-lazy-handler-dispatch} at its -top level, because it has its own mechanism for catching and reporting -exceptions in the code that it is asked to evaluate. This mechanism -summarizes the exception and gives the user a button they can click to -see the full stack, so the end result is very similar to what -@code{on-lazy-handler-dispatch} provides. Deep inside -@code{gds-accept-input}, in the part that handles evaluating -expressions from Emacs, the GDS client code uses -@code{throw->trap-context} and @code{gds-debug-trap} to implement -this. - - -@node Working with GDS in Scheme Buffers -@subsection Working with GDS in Scheme Buffers - -The following subsections describe the facilities and key sequences that -GDS provides for working on code in @code{scheme-mode} buffers. - -@menu -* Access to Guile Help and Completion:: -* Evaluating Scheme Code:: -@end menu - - -@node Access to Guile Help and Completion -@subsubsection Access to Guile Help and Completion - -The following keystrokes provide fast and convenient access to Guile's -built in help, and to completion with respect to the set of defined and -accessible symbols. - -@table @kbd -@item C-h g -@findex gds-help-symbol -Get Guile help for a particular symbol, with the same results as if -you had typed @code{(help SYMBOL)} into the Guile REPL -(@code{gds-help-symbol}). The symbol to query defaults to the word at -or before the cursor but can also be entered or edited in the -minibuffer. The available help is popped up in a temporary Emacs -window. - -@item C-h G -@findex gds-apropos -List all accessible Guile symbols matching a given regular expression, -with the same results as if you had typed @code{(apropos REGEXP)} into -the Guile REPL (@code{gds-apropos}). The regexp to query defaults to -the word at or before the cursor but can also be entered or edited in -the minibuffer. The list of matching symbols is popped up in a -temporary Emacs window. - -@item M-@key{TAB} -@findex gds-complete-symbol -Try to complete the symbol at the cursor by matching it against the -set of all defined and accessible bindings in the associated Guile -process (@code{gds-complete-symbol}). If there are any extra -characters that can be definitively added to the symbol at point, they -are inserted. Otherwise, if there are any completions available, they -are popped up in a temporary Emacs window, where one of them can be -selected using either @kbd{@key{RET}} or the mouse. -@end table - - -@node Evaluating Scheme Code -@subsubsection Evaluating Scheme Code - -The following keystrokes and commands provide various ways of sending -code to a Guile client process for evaluation. - -@table @kbd -@item M-C-x -@findex gds-eval-defun -Evaluate the ``top level defun'' that the cursor is in, in other words -the smallest balanced expression which includes the cursor and whose -opening parenthesis is in column 0 (@code{gds-eval-defun}). - -@item C-x C-e -@findex gds-eval-last-sexp -Evaluate the expression that ends just before the cursor -(@code{gds-eval-last-sexp}). This is designed so that it is easy to -evaluate an expression that you have just finished typing. - -@item C-c C-e -@findex gds-eval-expression -Read a Scheme expression using the minibuffer, and evaluate that -expression (@code{gds-eval-expression}). - -@item C-c C-r -@findex gds-eval-region -Evaluate the Scheme code in the marked region of the current buffer -(@code{gds-eval-region}). Note that GDS does not check whether the -region contains a balanced expression, or try to expand the region so -that it does; it uses the region exactly as it is. -@end table - -If you type @kbd{C-u} before one of these commands, GDS will immediately -pop up a Scheme stack buffer, showing the requested evaluation, so that -you can single step through it. The Scheme stack display, and the -options for continuing through the code, are described in the next two -sections. - - -@node Displaying the Scheme Stack -@subsection Displaying the Scheme Stack - -When you specify @code{gds-debug-trap} as the behaviour for a trap and -the Guile program concerned hits that trap, GDS displays the stack and -the relevant Scheme source code in Emacs, allowing you to explore the -state of the program and then decide what to do next. The same -applies if the program calls @code{(on-lazy-handler-dispatch -gds-debug-trap)} and then throws an exception that passes through -@code{lazy-handler-dispatch}, except that in this case you can only -explore; it isn't possible to continue normal execution after an -exception. - -The following commands are available in the stack buffer for exploring -the state of the program. - -@table @asis -@item @kbd{u}, @kbd{C-p}, @kbd{@key{up}} -@findex gds-up -Select the stack frame one up from the currently selected frame -(@code{gds-up}). GDS displays stack frames with the innermost at the -top, so moving ``up'' means selecting a more ``inner'' frame. - -@item @kbd{d}, @kbd{C-n}, @kbd{@key{down}} -@findex gds-down -Select the stack frame one down from the currently selected frame -(@code{gds-down}). GDS displays stack frames with the innermost at the -top, so moving ``down'' means selecting a more ``outer'' frame. - -@item @kbd{@key{RET}} -@findex gds-select-stack-frame -Select the stack frame at point (@code{gds-select-stack-frame}). This -is useful after clicking somewhere in the stack trace with the mouse. -@end table - -Selecting a frame means that GDS will display the source code -corresponding to that frame in the adjacent window, and that -subsequent frame-sensitive commands, such as @code{gds-evaluate} (see -below) and @code{gds-step-over} (@pxref{Continuing Execution}), will -refer to that frame. - -@table @kbd -@item e -@findex gds-evaluate -Evaluate a variable or expression in the local environment of the -selected stack frame (@code{gds-evaluate}). The result is displayed in -the echo area. - -@item I -@findex gds-frame-info -Show summary information about the selected stack frame -(@code{gds-frame-info}). This includes what type of frame it is, the -associated expression, and the frame's source location, if any. - -@item A -@findex gds-frame-args -For an application frame, display the frame's arguments -(@code{gds-frame-args}). - -@item S -@findex gds-proc-source -For an application frame, show the Scheme source code of the procedure -being called (@code{gds-proc-source}). The source code (where -available) is displayed in the echo area. -@end table - -@kbd{S} (@code{gds-proc-source}) is useful when the procedure being -called was created by an anonymous @code{(lambda @dots{})} expression. -Such procedures appear in the stack trace as @code{}, which doesn't give you much clue as to what will happen -next. @kbd{S} will show you the procedure's code, which is usually -enough for you to identify it. - - -@node Continuing Execution -@subsection Continuing Execution - -If it makes sense to continue execution from the stack which is being -displayed, GDS provides the following further commands in the stack -buffer. - -@table @asis -@item @kbd{g}, @kbd{c}, @kbd{q} -@findex gds-go -Tell the program to continue running (@code{gds-go}). It may of course -stop again if it hits another trap, or another occurrence of the same -trap. - -The multiple keystrokes reflect that you can think of this as ``going'', -``continuing'' or ``quitting'' (in the sense of quitting the GDS -display). - -@item @kbd{@key{SPC}} -@findex gds-step-file -Tell the program to do a single-step to the next entry or exit of a -frame whose code comes from the same source file as the selected stack -frame (@code{gds-step-file}). - -In other words, you can hit @kbd{@key{SPC}} repeatedly to step through -the code in a given file, automatically stepping @emph{over} any -evaluations or procedure calls that use code from other files (or from -no file). - -If the selected stack frame has no source, the effect of this command is -the same as that of @kbd{i}, described next. - -@item @kbd{i} -@findex gds-step-into -Tell the debugged program to do a single-step to the next frame entry or -exit of any kind (@code{gds-step-into}). @kbd{i} therefore steps -through code at the most detailed level possible. - -@item @kbd{o} -@findex gds-step-over -Tell the debugged program to continue running until the selected stack -frame completes, and then to display its result (@code{gds-step-over}). -Note that the program may stop before then if it hits another trap; in -this case the trap telling it to stop when the marked frame completes -remains in place and so will still fire at the appropriate point. -@end table - - -@node Associating Buffers with Clients -@subsection Associating Buffers with Clients - -The first time that you use one of GDS's evaluation, help or completion -commands from a given Scheme mode buffer, GDS will ask which Guile -client program you want to use for the operation, or if you want to -start up a new ``utility'' client. After that GDS considers the buffer -to be ``associated'' with the selected client, and so sends all further -requests to that client, but you can override this by explicitly -associating the buffer with a different client, or by removing the -default association. - -@table @kbd -@item M-x gds-associate-buffer -Associate (or re-associate) the current buffer with a particular Guile -client program. The available clients are listed, and you can also -choose to start up a new ``utility'' client for this buffer to associate -with. - -@item M-x gds-dissociate-buffer -Dissociate the current buffer from its client, if any. This means that -the next time you use an evaluation, help or completion command, GDS -will ask you again which client to send the request to. -@end table - -When a buffer is associated with a client program, the buffer's modeline -shows whether the client is currently able to accept instruction from -GDS. This is done by adding one of the following suffixes to the -``Scheme'' major mode indicator: - -@table @asis -@item :ready -The client program (or one of its threads, if multithreaded) is -currently ready to accept instruction from GDS. In other words, if you -send it a help or evaluation request, you should see the result pretty -much immediately. - -@item :running -The client program is not currently able to accept instruction from -GDS. This means that it (or all of its threads, if multithreaded) is -busy, or waiting for input other than from GDS. - -@item :debug -The client program (or one of its threads, if multithreaded) is stopped -in ``debugging mode'' with GDS displaying the stack for a trap or -exception. It is waiting for instruction from GDS on what to do next. -@end table - - -@node An Example GDS Session -@subsection An Example GDS Session - -Create a file, @file{testgds.scm} say, for experimenting with GDS and -Scheme code, and type this into it: - -@lisp -(use-modules (ice-9 debugging traps) - (ice-9 gds-client) - (ice-9 debugging example-fns)) -(install-trap (make - #:behaviour gds-debug-trap - #:procedure fact1)) -@end lisp - -@noindent -Now select all of this code and type @kbd{C-c C-r} to send the selected -region to Guile for evaluation. GDS will ask you which Guile process to -use; unless you know that you already have another Guile application -running and connected to GDS, choose the ``Start a new Guile'' option, -which starts one of the ``utility'' processes described in @ref{GDS -Getting Started}. - -The results of the evaluation pop up in a window like this: - -@lisp -(use-modules (ice-9 debugging traps)\n @dots{} - -;;; Evaluating subexpression 1 in current module (guile-user) - @result{} no (or unspecified) value - -;;; Evaluating subexpression 2 in current module (guile-user) - @result{} no (or unspecified) value - ---:** *Guile Evaluation* (Scheme:ready)--All------------ -@end lisp - -@noindent -this tells you that the evaluation was successful but that the return -values were unspecified. Its effect was to load a module of example -functions and set a trap on one of these functions, @code{fact1}, that -calculates the factorial of its argument. - -If you now call @code{fact1}, you can see the trap and GDS's stack -display in action. To do this add - -@lisp -(fact1 4) -@end lisp - -@noindent -to your @file{testgds.scm} buffer and type @kbd{C-x C-e} (which -evaluates the expression that the cursor is just after the end of). -The result should be that a GDS stack window like the following -appears: - -@lisp -Calling procedure: -=> s [fact1 4] - s [primitive-eval (fact1 4)] - - ---:** PID 28729 (Guile-Debug)--All------------ -@end lisp - -This stack tells you that Guile is about to call the @code{fact1} -procedure, with argument 4, and you can step through this call in -detail by pressing @kbd{i} once and then @kbd{@key{SPC}} -(@pxref{Continuing Execution}). - -(@kbd{i} is needed as the first keystroke rather than @kbd{@key{SPC}}, -because the aim here is to step through code in the @code{(ice-9 -debugging example-fns)} module, whose source file is -@file{@dots{}/ice-9/debugging/example-fns.scm}, but the initial -@code{(fact1 4)} call comes from the Guile session, whose ``source -file'' Guile presents as @file{standard input}. If the user starts by -pressing @kbd{@key{SPC}} instead of @kbd{i}, the effect is that the -program runs until it hits the first recursive call @code{(fact1 (- n -1))}, where it stops because of the trap on @code{fact1} firing again. -At this point, the source file @emph{is} -@file{@dots{}/ice-9/debugging/example-fns.scm}, because the recursive -@code{(fact1 (- n 1))} call comes from code in that file, so further -pressing of @kbd{@key{SPC}} successfully single-steps through this -file.) +See Geiser's web page at @uref{http://www.nongnu.org/geiser/}, for more +information. @c Local Variables: