2 @c This is part of the GNU Guile Reference Manual.
4 @c Free Software Foundation, Inc.
5 @c See the file guile.texi for copying conditions.
7 @node Using Guile Interactively
8 @section Using Guile Interactively
10 When you start up Guile by typing just @code{guile}, without a
11 @code{-c} argument or the name of a script to execute, you get an
12 interactive interpreter where you can enter Scheme expressions, and
13 Guile will evaluate them and print the results for you. Here are some
19 guile> (display "Hello world!\n")
27 This mode of use is called a @dfn{REPL}, which is short for
28 ``Read-Eval-Print Loop'', because the Guile interpreter first reads the
29 expression that you have typed, then evaluates it, and then prints the
36 * Interactive Debugger:: Using the interactive debugger.
43 To make it easier for you to repeat and vary previously entered
44 expressions, or to edit the expression that you're typing in, Guile
45 can use the GNU Readline library. This is not enabled by default
46 because of licensing reasons, but all you need to activate Readline is
47 the following pair of lines.
50 guile> (use-modules (ice-9 readline))
51 guile> (activate-readline)
54 It's a good idea to put these two lines (without the ``guile>''
55 prompts) in your @file{.guile} file. Guile reads this file when it
56 starts up interactively, so anything in this file has the same effect
57 as if you type it in by hand at the ``guile>'' prompt.
61 @subsection Value History
63 Just as Readline helps you to reuse a previous input line, @dfn{value
64 history} allows you to use the @emph{result} of a previous evaluation
65 in a new expression. When value history is enabled, each evaluation
66 result is automatically assigned to the next in the sequence of
67 variables @code{$1}, @code{$2}, @dots{}, and you can then use these
68 variables in subsequent expressions.
72 $1 = (0 1 2 3 4 5 6 7 8 9)
73 guile> (apply * (cdr $1))
76 $3 = 602.3952191045344
78 $4 = (362880 0 1 2 3 4 5 6 7 8 9)
81 To enable value history, type @code{(use-modules (ice-9 history))} at
82 the Guile prompt, or add this to your @file{.guile} file. (It is not
83 enabled by default, to avoid the possibility of conflicting with some
84 other use you may have for the variables @code{$1}, @code{$2},
85 @dots{}, and also because it prevents the stored evaluation results
86 from being garbage collected, which some people may not want.)
90 @subsection Error Handling
92 When code being evaluated from the REPL hits an error, Guile remembers
93 the execution context where the error occurred and can give you three
94 levels of information about what the error was and exactly where it
97 By default, Guile displays only the first level, which is the most
98 immediate information about where and why the error occurred, for
102 (make-string (* 4 (+ 3 #\s)) #\space)
104 standard input:2:19: In procedure + in expression (+ 3 #\s):
105 standard input:2:19: Wrong type argument: #\s
106 ABORT: (wrong-type-arg)
108 Type "(backtrace)" to get more information
109 or "(debug)" to enter the debugger.
113 However, as the message above says, you can obtain more information
114 about the context of the error by typing @code{(backtrace)} or
117 @code{(backtrace)} displays the Scheme call stack at the point where the
125 2: 0* [make-string ...
129 Type "(debug-enable 'backtrace)" if you would like a backtrace
130 automatically if an error occurs in the future.
134 In a more complex scenario than this one, this can be extremely useful
135 for understanding where and why the error occurred. You can make Guile
136 show the backtrace automatically by adding @code{(debug-enable
137 'backtrace)} to your @file{.guile}.
139 @code{(debug)} takes you into Guile's interactive debugger, which
140 provides commands that allow you to
144 display the Scheme call stack at the point where the error occurred
145 (the @code{backtrace} command --- see @ref{Display Backtrace})
148 move up and down the call stack, to see in detail the expression being
149 evaluated, or the procedure being applied, in each @dfn{frame} (the
150 @code{up}, @code{down}, @code{frame}, @code{position}, @code{info args}
151 and @code{info frame} commands --- see @ref{Frame Selection} and
152 @ref{Frame Information})
155 examine the values of variables and expressions in the context of each
156 frame (the @code{evaluate} command --- see @ref{Frame Evaluation}).
160 The interactive debugger is documented further in the following section.
163 @node Interactive Debugger
164 @subsection Using the Interactive Debugger
166 Guile's interactive debugger is a command line application that
167 accepts commands from you for examining the stack and, if stopped at a
168 trap, for continuing program execution in various ways. Unlike in the
169 normal Guile REPL, commands are typed mostly without parentheses.
171 When you first enter the debugger, it introduces itself with a message
175 This is the Guile debugger -- for help, type `help'.
176 There are 3 frames on the stack.
178 Frame 2 at standard input:36:19
184 ``debug>'' is the debugger's prompt, and a reminder that you are not in
185 the normal Guile REPL. In case you find yourself in the debugger by
186 mistake, the @code{quit} command will return you to the REPL.
188 @deffn {Debugger Command} quit
192 The other available commands are described in the following subsections.
195 * Display Backtrace:: backtrace.
196 * Frame Selection:: up, down, frame.
197 * Frame Information:: info args, info frame, position.
198 * Frame Evaluation:: evaluate.
199 * Stepping and Continuing:: step, next, (trace-)finish, continue.
203 @node Display Backtrace
204 @subsubsection Display Backtrace
206 The @code{backtrace} command, which can also be invoked as @code{bt} or
207 @code{where}, displays the call stack (aka backtrace) at the point where
208 the debugger was entered:
213 36: 0* [make-string ...
218 @deffn {Debugger Command} backtrace [count]
219 @deffnx {Debugger Command} bt [count]
220 @deffnx {Debugger Command} where [count]
221 Print backtrace of all stack frames, or of the innermost @var{count}
222 frames. With a negative argument, print the outermost -@var{count}
223 frames. If the number of frames isn't explicitly given, the debug
224 option @code{depth} determines the maximum number of frames printed.
227 The format of the displayed backtrace is the same as for the
228 @code{display-backtrace} procedure (@pxref{Examining the Stack}).
231 @node Frame Selection
232 @subsubsection Frame Selection
234 A call stack consists of a sequence of stack @dfn{frames}, with each
235 frame describing one level of the nested evaluations and applications
236 that the program was executing when it hit a breakpoint or an error.
237 Frames are numbered such that frame 0 is the outermost --- i.e. the
238 operation on the call stack that began least recently --- and frame N-1
239 the innermost (where N is the total number of frames on the stack).
241 When you enter the debugger, the innermost frame is selected, which
242 means that the commands for getting information about the ``current''
243 frame, or for evaluating expressions in the context of the current
244 frame, will do so by default with respect to the innermost frame. To
245 select a different frame, so that these operations will apply to it
246 instead, use the @code{up}, @code{down} and @code{frame} commands like
251 Frame 1 at standard input:36:14
254 Frame 0 at standard input:36:1
257 Frame 1 at standard input:36:14
261 @deffn {Debugger Command} up [n]
262 Move @var{n} frames up the stack. For positive @var{n}, this
263 advances toward the outermost frame, to lower frame numbers, to
264 frames that have existed longer. @var{n} defaults to one.
267 @deffn {Debugger Command} down [n]
268 Move @var{n} frames down the stack. For positive @var{n}, this
269 advances toward the innermost frame, to higher frame numbers, to frames
270 that were created more recently. @var{n} defaults to one.
273 @deffn {Debugger Command} frame [n]
274 Select and print a stack frame. With no argument, print the selected
275 stack frame. (See also ``info frame''.) An argument specifies the
276 frame to select; it must be a stack-frame number.
280 @node Frame Information
281 @subsubsection Frame Information
283 The following commands return detailed information about the currently
286 @deffn {Debugger Command} {info frame}
287 Display a verbose description of the selected frame. The information
288 that this command provides is equivalent to what can be deduced from the
289 one line summary for the frame that appears in a backtrace, but is
290 presented and explained more clearly.
293 @deffn {Debugger Command} {info args}
294 Display the argument variables of the current stack frame. Arguments
295 can also be seen in the backtrace, but are presented more clearly by
299 @deffn {Debugger Command} position
300 Display the name of the source file that the current expression comes
301 from, and the line and column number of the expression's opening
302 parenthesis within that file. This information is only available when
303 the @code{positions} read option is enabled (@pxref{Reader options}).
307 @node Frame Evaluation
308 @subsubsection Frame Evaluation
310 The @code{evaluate} command is most useful for querying the value of a
311 variable, either global or local, in the environment of the selected
312 stack frame, but it can be used more generally to evaluate any
315 @deffn {Debugger Command} evaluate expression
316 Evaluate an expression in the environment of the selected stack frame.
317 The expression must appear on the same line as the command, however it
318 may be continued over multiple lines.
322 @node Stepping and Continuing
323 @subsubsection Single Stepping and Continuing Execution
325 The commands in this subsection all apply only when the stack is
326 @dfn{continuable} --- in other words when it makes sense for the program
327 that the stack comes from to continue running. Usually this means that
328 the program stopped because of a trap or a breakpoint.
330 @deffn {Debugger Command} step [n]
331 Tell the debugged program to do @var{n} more steps from its current
332 position. One @dfn{step} means executing until the next frame entry or
333 exit of any kind. @var{n} defaults to 1.
336 @deffn {Debugger Command} next [n]
337 Tell the debugged program to do @var{n} more steps from its current
338 position, but only counting frame entries and exits where the
339 corresponding source code comes from the same file as the current stack
340 frame. (See @ref{Step Traps} for the details of how this works.) If
341 the current stack frame has no source code, the effect of this command
342 is the same as of @code{step}. @var{n} defaults to 1.
345 @deffn {Debugger Command} finish
346 Tell the program being debugged to continue running until the completion
347 of the current stack frame, and at that time to print the result and
348 reenter the command line debugger.
351 @deffn {Debugger Command} continue
352 Tell the program being debugged to continue running. (In fact this is
353 the same as the @code{quit} command, because it exits the debugger
354 command loop and so allows whatever code it was that invoked the
355 debugger to continue.)
359 @node Using Guile in Emacs
360 @section Using Guile in Emacs
364 There are several options for working on Guile Scheme code in Emacs.
365 The simplest are to use Emacs's standard @code{scheme-mode} for
366 editing code, and to run the interpreter when you need it by typing
367 ``guile'' at the prompt of a @code{*shell*} buffer, but there are
368 Emacs libraries available which add various bells and whistles to
369 this. The following diagram shows these libraries and how they relate
370 to each other, with the arrows indicating ``builds on'' or
371 ``extends''. For example, the Quack library builds on cmuscheme,
372 which in turn builds on the standard scheme mode.
375 @center @image{scheme,5in}
379 @verbatiminclude scheme.txt
383 @dfn{scheme}, written by Bill Rozas and Dave Love, is Emacs's standard
384 mode for Scheme code files. It provides Scheme-sensitive syntax
385 highlighting, parenthesis matching, indentation and so on.
387 @dfn{cmuscheme}, written by Olin Shivers, provides a comint-based Scheme
388 interaction buffer, so that you can run an interpreter more directly
389 than with the @code{*shell*} buffer approach by typing @kbd{M-x
390 run-scheme}. It also extends @code{scheme-mode} so that there are key
391 presses for sending selected bits of code from a Scheme buffer to this
392 interpreter. This means that when you are writing some code and want to
393 check what an expression evaluates to, you can easily select that code
394 and send it to the interpreter for evaluation, then switch to the
395 interpreter to see what the result is. cmuscheme is included in the
396 standard Emacs distribution.
398 @dfn{Quack}, written by Neil Van Dyke, adds a number of incremental
399 improvements to the scheme/cmuscheme combination: convenient menu
400 entries for looking up Scheme-related references (such as the SRFIs);
401 enhanced indentation rules that are customized for particular Scheme
402 interpreters, including Guile; an enhanced version of the
403 @code{run-scheme} command that knows the names of the common Scheme
404 interpreters and remembers which one you used last time; and so on.
405 Quack is available from @uref{http://www.neilvandyke.org/quack}.
407 @dfn{GDS}, written by Neil Jerram, also builds on the scheme/cmuscheme
408 combination, but with a change to the way that Scheme code fragments
409 are sent to the interpreter for evaluation. cmuscheme and Quack send
410 code fragments to the interpreter's standard input, on the assumption
411 that the interpreter is expecting to read Scheme expressions there,
412 and then monitor the interpreter's standard output to infer what the
413 result of the evaluation is. GDS doesn't use standard input and
414 output like this. Instead, it sets up a socket connection between the
415 Scheme interpreter and Emacs, and sends and receives messages using a
416 simple protocol through this socket. The messages include requests to
417 evaluate Scheme code, and responses conveying the results of an
418 evaluation, thus providing similar function to cmuscheme or Quack.
419 They also include requests for stack exploration and debugging, which
420 go beyond what cmuscheme or Quack can do. The price of this extra
421 power, however, is that GDS is Guile-specific. GDS requires the
422 Scheme interpreter to run some GDS-specific library code; currently
423 this code is written as a Guile module and uses features that are
424 specific to Guile. GDS is now included in the Guile distribution; for
425 previous Guile releases (1.8.4 and earlier) it can be obtained as part
426 of the @code{guile-debugging} package from
427 @uref{http://www.ossau.uklinux.net/guile}.
429 Finally, @dfn{xscheme} is similar to cmuscheme --- in that it starts up
430 a Scheme interaction process and sends commands to that process's
431 standard input --- and to GDS --- in that it has support beyond
432 cmuscheme or Quack for exploring the Scheme stack when an error has
433 occurred --- but is implemented specifically for MIT/GNU Scheme. Hence
434 it isn't really relevant to Guile work in Emacs, except as a reference
435 for useful features that could be implemented in one of the other
436 libraries mentioned here.
438 In summary, the best current choice for working on Guile code in Emacs
439 is either Quack or GDS, depending on which of these libraries' features
440 you find most important. For more information on Quack, please see the
441 website referenced above. GDS is documented further in the rest of this
447 * GDS Getting Started::
448 * Working with GDS in Scheme Buffers::
449 * Displaying the Scheme Stack::
450 * Continuing Execution::
451 * Associating Buffers with Clients::
452 * An Example GDS Session::
456 @node GDS Introduction
457 @subsection GDS Introduction
459 GDS aims to allow you to work on Guile Scheme code in the same kind of
460 way that Emacs allows you to work on Emacs Lisp code: providing easy
461 access to help, evaluating arbitrary fragments of code, a nice debugging
462 interface, and so on. The thinking behind the GDS library is that you
463 will usually be doing one of two things.
467 Writing or editing code. The code will be in a normal Emacs Scheme mode
468 buffer, and GDS extends Scheme mode to add keystrokes and menu items for
469 the things that are likely to be useful to you when working on code:
473 completing the identifier at point, with respect to the set of variable
474 names that are known to the associated Guile process
476 accessing Guile's built in ``help'' and ``apropos'' commands
478 evaluating fragments of code to check what they do, with the results
479 popping up in a temporary Emacs window.
483 Debugging a Guile Scheme program. When your program hits an error or
484 stops at a trap, GDS shows you the relevant code and the Scheme stack,
489 look at the values of local variables
491 see what is happening at all levels of the Scheme stack
493 continue execution, either normally or step by step.
496 The presentation makes it very easy to move up and down the stack,
497 showing whenever possible the source code for each frame in another
498 Emacs buffer. It also provides convenient keystrokes for telling Guile
499 what to do next; for example, you can select a stack frame and tell
500 Guile to run until that frame completes, at which point GDS will display
501 the frame's return value.
504 GDS can provide these facilities for any number of Guile Scheme programs
505 (which we often refer to as ``clients'') at once, and these programs can
506 be started either independently of GDS, including outside Emacs, or
507 specifically @emph{by} GDS.
509 Communication between each Guile client program and GDS uses a TCP
510 socket, which means that it is orthogonal to any other interfaces that
511 the client program has. In particular GDS does not interfere with a
512 program's standard input and output.
515 @node GDS Architecture
516 @subsection GDS Architecture
518 In order to understand the following documentation fully it will help to
519 have a picture in mind of how GDS works, so we briefly describe that
520 here. GDS consists of three components.
524 The GDS @dfn{interface} code is written in Emacs Lisp and runs inside
525 Emacs. This code, consisting of the installed files @file{gds.el} and
526 @file{gds-server.el}, is responsible for displaying information from
527 Guile in Emacs windows, and for responding to Emacs commands and
528 keystrokes by sending instructions back to the Guile program being
532 The GDS @dfn{server} code is written in Scheme and runs as an Emacs
533 inferior process. It acts as a multiplexer between the (possibly
534 multiple) Guile programs being debugged and the interface code running
535 in Emacs. The server code is the installed file
536 @file{gds-server.scm}.
539 The GDS @dfn{client} code is written in Scheme (installed file
540 @file{gds-client.scm}), and must be loaded as a module by each Guile
541 program that wants to use GDS in any way.
545 The following diagram shows how these components are connected to each
549 @center @image{gds,5in}
553 @verbatiminclude gds.txt
558 The data exchanged between client and server components, and between
559 server and interface, is a sequence of sexps (parenthesised expressions)
560 that are designed so as to be directly readable by both Scheme and Emacs
561 Lisp. The use of a TCP connection means that the server and Emacs
562 interface can theoretically be on a different computer from the client
563 programs, but in practice there are currently two problems with
564 this. Firstly the GDS API doesn't provide any way of specifying a
565 non-local server to connect to, and secondly there is no security or
566 authentication mechanism in the GDS protocol. These are issues that
567 should be addressed in the future.
570 @node GDS Getting Started
571 @subsection Getting Started with GDS
573 To enable the use of GDS in your own Emacs sessions, simply add
580 somewhere in your @file{.emacs} file. This will cause Emacs to load the
581 GDS Emacs Lisp code when starting up, and to start the inferior GDS
582 server process so that it is ready and waiting for any Guile programs
583 that want to use GDS.
585 (If GDS's Scheme code is not installed in one of the locations in
586 Guile's load path, you may find that the server process fails to start.
587 When this happens you will see an error message from Emacs:
590 error in process filter: Wrong type argument: listp, Backtrace:
594 and the @code{gds-debug} buffer will contain a Scheme backtrace ending
598 no code for module (ice-9 gds-server)
602 The solution for this is to customize the Emacs variable
603 @code{gds-scheme-directory} so that it specifies where the GDS Scheme
604 code is installed. Then either restart Emacs or type @kbd{M-x
605 gds-run-debug-server} to try starting the GDS server process again.)
607 For evaluations, help and completion from Scheme code buffers that you
608 are working on, this is all you need. The first time you do any of
609 these things, GDS will automatically start a new Guile client program as
610 an Emacs subprocess. This Guile program does nothing but wait for and
611 act on instructions from GDS, and we refer to it as a @dfn{utility}
612 Guile client. Over time this utility client will accumulate the code
613 that you ask it to evaluate, and you can also tell it to load complete
614 files or modules by sending it @code{load} or @code{use-modules}
617 When you want to use GDS to work on an independent Guile
618 application, you need to add something to that application's Scheme code
619 to cause it to connect to and interact with GDS at the right times. The
620 following subsections describe the ways of doing this.
622 @subsubsection Invoking GDS when an Exception Occurs
624 One option is to use GDS to catch and display any exceptions that
625 are thrown by the application's code. If you already have a
626 @code{lazy-catch} or @code{with-throw-handler} around the area of code
627 that you want to monitor, you just need to add the following to the
631 (gds-debug-trap (throw->trap-context key args))
635 where @code{key} and @code{args} are the first and rest arguments that
636 Guile passes to the handler. (In other words, they assume the handler
637 signature @code{(lambda (key . args) @dots{})}.) With Guile 1.8 or
638 later, you can also do this with a @code{catch}, by adding this same
639 code to the catch's pre-unwind handler.
641 If you don't already have any of these, insert a whole
642 @code{with-throw-handler} expression (or @code{lazy-catch} if your Guile
643 is pre-1.8) around the code of interest like this:
646 (with-throw-handler #t
648 ;; Protected code here.
651 (gds-debug-trap (throw->trap-context key args))))
654 Either way, you will need to use the @code{(ice-9 gds-client)} and
655 @code{(ice-9 debugging traps)} modules.
657 Two special cases of this are the lazy-catch that the Guile REPL code
658 uses to catch exceptions in user code, and the lazy-catch inside the
659 @code{stack-catch} utility procedure that is provided by the
660 @code{(ice-9 stack-catch)} module. Both of these use a handler called
661 @code{lazy-handler-dispatch} (defined in @file{boot-9.scm}), which you
662 can hook into such that it calls GDS to display the stack when an
663 exception occurs. To do this, use the @code{on-lazy-handler-dispatch}
664 procedure as follows.
667 (use-modules (ice-9 gds-client)
668 (ice-9 debugging traps))
669 (on-lazy-handler-dispatch gds-debug-trap)
673 After this the program will use GDS to display the stack whenever it
674 hits an exception that is protected by a @code{lazy-catch} using
675 @code{lazy-handler-dispatch}.
677 @subsubsection Accepting GDS Instructions at Any Time
679 In addition to setting an exception handler as described above, a
680 Guile program can in principle set itself up to accept new
681 instructions from GDS at any time, not just when it has stopped at an
682 exception. This would allow the GDS user to evaluate code in the
683 context of the running program, without having to wait for the program
687 (use-modules (ice-9 gds-client))
688 (gds-accept-input #t)
691 @code{gds-accept-input} causes the calling program to loop processing
692 instructions from GDS, until GDS sends the @code{continue} instruction.
693 This blocks the thread that calls it, however, so it will normally be
694 more practical for the program to set up a dedicated GDS thread and call
695 @code{gds-accept-input} from that thread.
697 For @code{select}-driven applications, an alternative approach would be
698 for the GDS client code to provide an API which allowed the application
703 discover the file descriptors (or Scheme ports) that are used for
704 receiving instruction from the GDS front end, so that it could include
705 these in its @code{select} call
708 call the GDS instruction handler when @code{select} indicated data
709 available for reading on those descriptors/ports.
713 This approach is not yet implemented, though.
715 @subsubsection Utility Guile Implementation
717 The ``utility'' Guile client mentioned above is a simple combination
718 of the mechanisms that we have just described. In fact the code for
719 the utility Guile client is essentially just this:
722 (use-modules (ice-9 gds-client))
723 (named-module-use! '(guile-user) '(ice-9 session))
724 (gds-accept-input #f))
727 The @code{named-module-use!} line ensures that the client can process
728 @code{help} and @code{apropos} expressions, to implement lookups in
729 Guile's online help. The @code{#f} parameter to
730 @code{gds-accept-input} means that the @code{continue} instruction
731 will not cause the instruction loop to exit, which makes sense here
732 because the utility client has nothing to do except to process GDS
735 The utility client does not use @code{on-lazy-handler-dispatch} at its
736 top level, because it has its own mechanism for catching and reporting
737 exceptions in the code that it is asked to evaluate. This mechanism
738 summarizes the exception and gives the user a button they can click to
739 see the full stack, so the end result is very similar to what
740 @code{on-lazy-handler-dispatch} provides. Deep inside
741 @code{gds-accept-input}, in the part that handles evaluating
742 expressions from Emacs, the GDS client code uses
743 @code{throw->trap-context} and @code{gds-debug-trap} to implement
747 @node Working with GDS in Scheme Buffers
748 @subsection Working with GDS in Scheme Buffers
750 The following subsections describe the facilities and key sequences that
751 GDS provides for working on code in @code{scheme-mode} buffers.
754 * Access to Guile Help and Completion::
755 * Evaluating Scheme Code::
759 @node Access to Guile Help and Completion
760 @subsubsection Access to Guile Help and Completion
762 The following keystrokes provide fast and convenient access to Guile's
763 built in help, and to completion with respect to the set of defined and
768 @findex gds-help-symbol
769 Get Guile help for a particular symbol, with the same results as if
770 you had typed @code{(help SYMBOL)} into the Guile REPL
771 (@code{gds-help-symbol}). The symbol to query defaults to the word at
772 or before the cursor but can also be entered or edited in the
773 minibuffer. The available help is popped up in a temporary Emacs
778 List all accessible Guile symbols matching a given regular expression,
779 with the same results as if you had typed @code{(apropos REGEXP)} into
780 the Guile REPL (@code{gds-apropos}). The regexp to query defaults to
781 the word at or before the cursor but can also be entered or edited in
782 the minibuffer. The list of matching symbols is popped up in a
783 temporary Emacs window.
786 @findex gds-complete-symbol
787 Try to complete the symbol at the cursor by matching it against the
788 set of all defined and accessible bindings in the associated Guile
789 process (@code{gds-complete-symbol}). If there are any extra
790 characters that can be definitively added to the symbol at point, they
791 are inserted. Otherwise, if there are any completions available, they
792 are popped up in a temporary Emacs window, where one of them can be
793 selected using either @kbd{@key{RET}} or the mouse.
797 @node Evaluating Scheme Code
798 @subsubsection Evaluating Scheme Code
800 The following keystrokes and commands provide various ways of sending
801 code to a Guile client process for evaluation.
805 @findex gds-eval-defun
806 Evaluate the ``top level defun'' that the cursor is in, in other words
807 the smallest balanced expression which includes the cursor and whose
808 opening parenthesis is in column 0 (@code{gds-eval-defun}).
811 @findex gds-eval-last-sexp
812 Evaluate the expression that ends just before the cursor
813 (@code{gds-eval-last-sexp}). This is designed so that it is easy to
814 evaluate an expression that you have just finished typing.
817 @findex gds-eval-expression
818 Read a Scheme expression using the minibuffer, and evaluate that
819 expression (@code{gds-eval-expression}).
822 @findex gds-eval-region
823 Evaluate the Scheme code in the marked region of the current buffer
824 (@code{gds-eval-region}). Note that GDS does not check whether the
825 region contains a balanced expression, or try to expand the region so
826 that it does; it uses the region exactly as it is.
829 If you type @kbd{C-u} before one of these commands, GDS will
830 immediately pop up a Scheme stack buffer, showing the requested
831 evaluation, so that you can single step through it. (This is achieved
832 by setting a @code{<source-trap>} trap at the start of the requested
833 evaluation; see @ref{Source Traps} for more on how those work.) The
834 Scheme stack display, and the options for continuing through the code,
835 are described in the next two sections.
838 @node Displaying the Scheme Stack
839 @subsection Displaying the Scheme Stack
841 When you specify @code{gds-debug-trap} as the behaviour for a trap and
842 the Guile program concerned hits that trap, GDS displays the stack and
843 the relevant Scheme source code in Emacs, allowing you to explore the
844 state of the program and then decide what to do next. The same
845 applies if the program calls @code{(on-lazy-handler-dispatch
846 gds-debug-trap)} and then throws an exception that passes through
847 @code{lazy-handler-dispatch}, except that in this case you can only
848 explore; it isn't possible to continue normal execution after an
851 The following commands are available in the stack buffer for exploring
852 the state of the program.
855 @item @kbd{u}, @kbd{C-p}, @kbd{@key{up}}
857 Select the stack frame one up from the currently selected frame
858 (@code{gds-up}). GDS displays stack frames with the innermost at the
859 top, so moving ``up'' means selecting a more ``inner'' frame.
861 @item @kbd{d}, @kbd{C-n}, @kbd{@key{down}}
863 Select the stack frame one down from the currently selected frame
864 (@code{gds-down}). GDS displays stack frames with the innermost at the
865 top, so moving ``down'' means selecting a more ``outer'' frame.
867 @item @kbd{@key{RET}}
868 @findex gds-select-stack-frame
869 Select the stack frame at point (@code{gds-select-stack-frame}). This
870 is useful after clicking somewhere in the stack trace with the mouse.
873 Selecting a frame means that GDS will display the source code
874 corresponding to that frame in the adjacent window, and that
875 subsequent frame-sensitive commands, such as @code{gds-evaluate} (see
876 below) and @code{gds-step-over} (@pxref{Continuing Execution}), will
882 Evaluate a variable or expression in the local environment of the
883 selected stack frame (@code{gds-evaluate}). The result is displayed in
887 @findex gds-frame-info
888 Show summary information about the selected stack frame
889 (@code{gds-frame-info}). This includes what type of frame it is, the
890 associated expression, and the frame's source location, if any.
893 @findex gds-frame-args
894 For an application frame, display the frame's arguments
895 (@code{gds-frame-args}).
898 @findex gds-proc-source
899 For an application frame, show the Scheme source code of the procedure
900 being called (@code{gds-proc-source}). The source code (where
901 available) is displayed in the echo area.
904 @kbd{S} (@code{gds-proc-source}) is useful when the procedure being
905 called was created by an anonymous @code{(lambda @dots{})} expression.
906 Such procedures appear in the stack trace as @code{<procedure #f
907 (@dots{})>}, which doesn't give you much clue as to what will happen
908 next. @kbd{S} will show you the procedure's code, which is usually
909 enough for you to identify it.
912 @node Continuing Execution
913 @subsection Continuing Execution
915 If it makes sense to continue execution from the stack which is being
916 displayed, GDS provides the following further commands in the stack
920 @item @kbd{g}, @kbd{c}, @kbd{q}
922 Tell the program to continue running (@code{gds-go}). It may of course
923 stop again if it hits another trap, or another occurrence of the same
926 The multiple keystrokes reflect that you can think of this as ``going'',
927 ``continuing'' or ``quitting'' (in the sense of quitting the GDS
930 @item @kbd{@key{SPC}}
931 @findex gds-step-file
932 Tell the program to do a single-step to the next entry or exit of a
933 frame whose code comes from the same source file as the selected stack
934 frame (@code{gds-step-file}).
936 In other words, you can hit @kbd{@key{SPC}} repeatedly to step through
937 the code in a given file, automatically stepping @emph{over} any
938 evaluations or procedure calls that use code from other files (or from
941 If the selected stack frame has no source, the effect of this command is
942 the same as that of @kbd{i}, described next.
945 @findex gds-step-into
946 Tell the debugged program to do a single-step to the next frame entry or
947 exit of any kind (@code{gds-step-into}). @kbd{i} therefore steps
948 through code at the most detailed level possible.
951 @findex gds-step-over
952 Tell the debugged program to continue running until the selected stack
953 frame completes, and then to display its result (@code{gds-step-over}).
954 Note that the program may stop before then if it hits another trap; in
955 this case the trap telling it to stop when the marked frame completes
956 remains in place and so will still fire at the appropriate point.
960 @node Associating Buffers with Clients
961 @subsection Associating Buffers with Clients
963 The first time that you use one of GDS's evaluation, help or completion
964 commands from a given Scheme mode buffer, GDS will ask which Guile
965 client program you want to use for the operation, or if you want to
966 start up a new ``utility'' client. After that GDS considers the buffer
967 to be ``associated'' with the selected client, and so sends all further
968 requests to that client, but you can override this by explicitly
969 associating the buffer with a different client, or by removing the
973 @item M-x gds-associate-buffer
974 Associate (or re-associate) the current buffer with a particular Guile
975 client program. The available clients are listed, and you can also
976 choose to start up a new ``utility'' client for this buffer to associate
979 @item M-x gds-dissociate-buffer
980 Dissociate the current buffer from its client, if any. This means that
981 the next time you use an evaluation, help or completion command, GDS
982 will ask you again which client to send the request to.
985 When a buffer is associated with a client program, the buffer's modeline
986 shows whether the client is currently able to accept instruction from
987 GDS. This is done by adding one of the following suffixes to the
988 ``Scheme'' major mode indicator:
992 The client program (or one of its threads, if multithreaded) is
993 currently ready to accept instruction from GDS. In other words, if you
994 send it a help or evaluation request, you should see the result pretty
998 The client program is not currently able to accept instruction from
999 GDS. This means that it (or all of its threads, if multithreaded) is
1000 busy, or waiting for input other than from GDS.
1003 The client program (or one of its threads, if multithreaded) is stopped
1004 in ``debugging mode'' with GDS displaying the stack for a trap or
1005 exception. It is waiting for instruction from GDS on what to do next.
1009 @node An Example GDS Session
1010 @subsection An Example GDS Session
1012 Create a file, @file{testgds.scm} say, for experimenting with GDS and
1013 Scheme code, and type this into it:
1016 (use-modules (ice-9 debugging traps)
1018 (ice-9 debugging example-fns))
1019 (install-trap (make <procedure-trap>
1020 #:behaviour gds-debug-trap
1025 Now select all of this code and type @kbd{C-c C-r} to send the selected
1026 region to Guile for evaluation. GDS will ask you which Guile process to
1027 use; unless you know that you already have another Guile application
1028 running and connected to GDS, choose the ``Start a new Guile'' option,
1029 which starts one of the ``utility'' processes described in @ref{GDS
1032 The results of the evaluation pop up in a window like this:
1035 (use-modules (ice-9 debugging traps)\n @dots{}
1037 ;;; Evaluating subexpression 1 in current module (guile-user)
1038 @result{} no (or unspecified) value
1040 ;;; Evaluating subexpression 2 in current module (guile-user)
1041 @result{} no (or unspecified) value
1043 --:** *Guile Evaluation* (Scheme:ready)--All------------
1047 this tells you that the evaluation was successful but that the return
1048 values were unspecified. Its effect was to load a module of example
1049 functions and set a trap on one of these functions, @code{fact1}, that
1050 calculates the factorial of its argument.
1052 If you now call @code{fact1}, you can see the trap and GDS's stack
1053 display in action. To do this add
1060 to your @file{testgds.scm} buffer and type @kbd{C-x C-e} (which
1061 evaluates the expression that the cursor is just after the end of).
1062 The result should be that a GDS stack window like the following
1068 s [primitive-eval (fact1 4)]
1071 --:** PID 28729 (Guile-Debug)--All------------
1074 This stack tells you that Guile is about to call the @code{fact1}
1075 procedure, with argument 4, and you can step through this call in
1076 detail by pressing @kbd{i} once and then @kbd{@key{SPC}}
1077 (@pxref{Continuing Execution}).
1079 (@kbd{i} is needed as the first keystroke rather than @kbd{@key{SPC}},
1080 because the aim here is to step through code in the @code{(ice-9
1081 debugging example-fns)} module, whose source file is
1082 @file{@dots{}/ice-9/debugging/example-fns.scm}, but the initial
1083 @code{(fact1 4)} call comes from the Guile session, whose ``source
1084 file'' Guile presents as @file{standard input}. If the user starts by
1085 pressing @kbd{@key{SPC}} instead of @kbd{i}, the effect is that the
1086 program runs until it hits the first recursive call @code{(fact1 (- n
1087 1))}, where it stops because of the trap on @code{fact1} firing again.
1088 At this point, the source file @emph{is}
1089 @file{@dots{}/ice-9/debugging/example-fns.scm}, because the recursive
1090 @code{(fact1 (- n 1))} call comes from code in that file, so further
1091 pressing of @kbd{@key{SPC}} successfully single-steps through this
1096 @c TeX-master: "guile.texi"