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.
388 @dfn{scheme}, written by Bill Rozas and Dave Love, is Emacs's standard
389 mode for Scheme code files. It provides Scheme-sensitive syntax
390 highlighting, parenthesis matching, indentation and so on.
392 @dfn{cmuscheme}, written by Olin Shivers, provides a comint-based Scheme
393 interaction buffer, so that you can run an interpreter more directly
394 than with the @code{*shell*} buffer approach by typing @kbd{M-x
395 run-scheme}. It also extends @code{scheme-mode} so that there are key
396 presses for sending selected bits of code from a Scheme buffer to this
397 interpreter. This means that when you are writing some code and want to
398 check what an expression evaluates to, you can easily select that code
399 and send it to the interpreter for evaluation, then switch to the
400 interpreter to see what the result is. cmuscheme is included in the
401 standard Emacs distribution.
403 @dfn{Quack}, written by Neil Van Dyke, adds a number of incremental
404 improvements to the scheme/cmuscheme combination: convenient menu
405 entries for looking up Scheme-related references (such as the SRFIs);
406 enhanced indentation rules that are customized for particular Scheme
407 interpreters, including Guile; an enhanced version of the
408 @code{run-scheme} command that knows the names of the common Scheme
409 interpreters and remembers which one you used last time; and so on.
410 Quack is available from @uref{http://www.neilvandyke.org/quack}.
412 @dfn{GDS}, written by Neil Jerram, also builds on the scheme/cmuscheme
413 combination, but with a change to the way that Scheme code fragments
414 are sent to the interpreter for evaluation. cmuscheme and Quack send
415 code fragments to the interpreter's standard input, on the assumption
416 that the interpreter is expecting to read Scheme expressions there,
417 and then monitor the interpreter's standard output to infer what the
418 result of the evaluation is. GDS doesn't use standard input and
419 output like this. Instead, it sets up a socket connection between the
420 Scheme interpreter and Emacs, and sends and receives messages using a
421 simple protocol through this socket. The messages include requests to
422 evaluate Scheme code, and responses conveying the results of an
423 evaluation, thus providing similar function to cmuscheme or Quack.
424 They also include requests for stack exploration and debugging, which
425 go beyond what cmuscheme or Quack can do. The price of this extra
426 power, however, is that GDS is Guile-specific. GDS requires the
427 Scheme interpreter to run some GDS-specific library code; currently
428 this code is written as a Guile module and uses features that are
429 specific to Guile. GDS is now included in the Guile distribution; for
430 previous Guile releases (1.8.4 and earlier) it can be obtained as part
431 of the @code{guile-debugging} package from
432 @uref{http://www.ossau.uklinux.net/guile}.
434 Finally, @dfn{xscheme} is similar to cmuscheme --- in that it starts up
435 a Scheme interaction process and sends commands to that process's
436 standard input --- and to GDS --- in that it has support beyond
437 cmuscheme or Quack for exploring the Scheme stack when an error has
438 occurred --- but is implemented specifically for MIT/GNU Scheme. Hence
439 it isn't really relevant to Guile work in Emacs, except as a reference
440 for useful features that could be implemented in one of the other
441 libraries mentioned here.
443 In summary, the best current choice for working on Guile code in Emacs
444 is either Quack or GDS, depending on which of these libraries' features
445 you find most important. For more information on Quack, please see the
446 website referenced above. GDS is documented further in the rest of this
452 * GDS Getting Started::
453 * Working with GDS in Scheme Buffers::
454 * Displaying the Scheme Stack::
455 * Continuing Execution::
456 * Associating Buffers with Clients::
457 * An Example GDS Session::
461 @node GDS Introduction
462 @subsection GDS Introduction
464 GDS aims to allow you to work on Guile Scheme code in the same kind of
465 way that Emacs allows you to work on Emacs Lisp code: providing easy
466 access to help, evaluating arbitrary fragments of code, a nice debugging
467 interface, and so on. The thinking behind the GDS library is that you
468 will usually be doing one of two things.
472 Writing or editing code. The code will be in a normal Emacs Scheme mode
473 buffer, and GDS extends Scheme mode to add keystrokes and menu items for
474 the things that are likely to be useful to you when working on code:
478 completing the identifier at point, with respect to the set of variable
479 names that are known to the associated Guile process
481 accessing Guile's built in ``help'' and ``apropos'' commands
483 evaluating fragments of code to check what they do, with the results
484 popping up in a temporary Emacs window.
488 Debugging a Guile Scheme program. When your program hits an error or
489 stops at a trap, GDS shows you the relevant code and the Scheme stack,
494 look at the values of local variables
496 see what is happening at all levels of the Scheme stack
498 continue execution, either normally or step by step.
501 The presentation makes it very easy to move up and down the stack,
502 showing whenever possible the source code for each frame in another
503 Emacs buffer. It also provides convenient keystrokes for telling Guile
504 what to do next; for example, you can select a stack frame and tell
505 Guile to run until that frame completes, at which point GDS will display
506 the frame's return value.
509 GDS can provide these facilities for any number of Guile Scheme programs
510 (which we often refer to as ``clients'') at once, and these programs can
511 be started either independently of GDS, including outside Emacs, or
512 specifically @emph{by} GDS.
514 Communication between each Guile client program and GDS uses a TCP
515 socket, which means that it is orthogonal to any other interfaces that
516 the client program has. In particular GDS does not interfere with a
517 program's standard input and output.
520 @node GDS Architecture
521 @subsection GDS Architecture
523 In order to understand the following documentation fully it will help to
524 have a picture in mind of how GDS works, so we briefly describe that
525 here. GDS consists of three components.
529 The GDS @dfn{interface} code is written in Emacs Lisp and runs inside
530 Emacs. This code, consisting of the installed files @file{gds.el} and
531 @file{gds-server.el}, is responsible for displaying information from
532 Guile in Emacs windows, and for responding to Emacs commands and
533 keystrokes by sending instructions back to the Guile program being
537 The GDS @dfn{server} code is written in Scheme and runs as an Emacs
538 inferior process. It acts as a multiplexer between the (possibly
539 multiple) Guile programs being debugged and the interface code running
540 in Emacs. The server code is the installed file
541 @file{gds-server.scm}.
544 The GDS @dfn{client} code is written in Scheme (installed file
545 @file{gds-client.scm}), and must be loaded as a module by each Guile
546 program that wants to use GDS in any way.
550 The following diagram shows how these components are connected to each
559 | +------------+ |-_ +-------------------+
560 +----------------+ -_TCP | Emacs |
562 -_+------------+ | +---------------+ |
563 _| GDS Server |-----| GDS Interface | |
564 +----------------+ _- +------------+ | +---------------+ |
565 | Program #2 | _- +-------------------+
574 The data exchanged between client and server components, and between
575 server and interface, is a sequence of sexps (parenthesised expressions)
576 that are designed so as to be directly readable by both Scheme and Emacs
577 Lisp. The use of a TCP connection means that the server and Emacs
578 interface can theoretically be on a different computer from the client
579 programs, but in practice there are currently two problems with
580 this. Firstly the GDS API doesn't provide any way of specifying a
581 non-local server to connect to, and secondly there is no security or
582 authentication mechanism in the GDS protocol. These are issues that
583 should be addressed in the future.
586 @node GDS Getting Started
587 @subsection Getting Started with GDS
589 To enable the use of GDS in your own Emacs sessions, simply add
596 somewhere in your @file{.emacs} file. This will cause Emacs to load the
597 GDS Emacs Lisp code when starting up, and to start the inferior GDS
598 server process so that it is ready and waiting for any Guile programs
599 that want to use GDS.
601 (If GDS's Scheme code is not installed in one of the locations in
602 Guile's load path, you may find that the server process fails to start.
603 When this happens you will see an error message from Emacs:
606 error in process filter: Wrong type argument: listp, Backtrace:
610 and the @code{gds-debug} buffer will contain a Scheme backtrace ending
614 no code for module (ice-9 gds-server)
618 The solution for this is to customize the Emacs variable
619 @code{gds-scheme-directory} so that it specifies where the GDS Scheme
620 code is installed. Then either restart Emacs or type @kbd{M-x
621 gds-run-debug-server} to try starting the GDS server process again.)
623 For evaluations, help and completion from Scheme code buffers that you
624 are working on, this is all you need. The first time you do any of
625 these things, GDS will automatically start a new Guile client program as
626 an Emacs subprocess. This Guile program does nothing but wait for and
627 act on instructions from GDS, and we refer to it as a @dfn{utility}
628 Guile client. Over time this utility client will accumulate the code
629 that you ask it to evaluate, and you can also tell it to load complete
630 files or modules by sending it @code{load} or @code{use-modules}
633 When you want to use GDS to work on an independent Guile
634 application, you need to add something to that application's Scheme code
635 to cause it to connect to and interact with GDS at the right times. The
636 following subsections describe the ways of doing this.
638 @subsubsection Invoking GDS when an Exception Occurs
640 One option is to use GDS to catch and display any exceptions that
641 are thrown by the application's code. If you already have a
642 @code{lazy-catch} or @code{with-throw-handler} around the area of code
643 that you want to monitor, you just need to add the following to the
647 (gds-debug-trap (throw->trap-context key args))
651 where @code{key} and @code{args} are the first and rest arguments that
652 Guile passes to the handler. (In other words, they assume the handler
653 signature @code{(lambda (key . args) @dots{})}.) With Guile 1.8 or
654 later, you can also do this with a @code{catch}, by adding this same
655 code to the catch's pre-unwind handler.
657 If you don't already have any of these, insert a whole
658 @code{with-throw-handler} expression (or @code{lazy-catch} if your Guile
659 is pre-1.8) around the code of interest like this:
662 (with-throw-handler #t
664 ;; Protected code here.
667 (gds-debug-trap (throw->trap-context key args))))
670 Either way, you will need to use the @code{(ice-9 gds-client)} and
671 @code{(ice-9 debugging traps)} modules.
673 Two special cases of this are the lazy-catch that the Guile REPL code
674 uses to catch exceptions in user code, and the lazy-catch inside the
675 @code{stack-catch} utility procedure that is provided by the
676 @code{(ice-9 stack-catch)} module. Both of these use a handler called
677 @code{lazy-handler-dispatch} (defined in @file{boot-9.scm}), which you
678 can hook into such that it calls GDS to display the stack when an
679 exception occurs. To do this, use the @code{on-lazy-handler-dispatch}
680 procedure as follows.
683 (use-modules (ice-9 gds-client)
684 (ice-9 debugging traps))
685 (on-lazy-handler-dispatch gds-debug-trap)
689 After this the program will use GDS to display the stack whenever it
690 hits an exception that is protected by a @code{lazy-catch} using
691 @code{lazy-handler-dispatch}.
693 @subsubsection Accepting GDS Instructions at Any Time
695 In addition to setting an exception handler as described above, a
696 Guile program can in principle set itself up to accept new
697 instructions from GDS at any time, not just when it has stopped at an
698 exception. This would allow the GDS user to evaluate code in the
699 context of the running program, without having to wait for the program
703 (use-modules (ice-9 gds-client))
704 (gds-accept-input #t)
707 @code{gds-accept-input} causes the calling program to loop processing
708 instructions from GDS, until GDS sends the @code{continue} instruction.
709 This blocks the thread that calls it, however, so it will normally be
710 more practical for the program to set up a dedicated GDS thread and call
711 @code{gds-accept-input} from that thread.
713 For @code{select}-driven applications, an alternative approach would be
714 for the GDS client code to provide an API which allowed the application
719 discover the file descriptors (or Scheme ports) that are used for
720 receiving instruction from the GDS front end, so that it could include
721 these in its @code{select} call
724 call the GDS instruction handler when @code{select} indicated data
725 available for reading on those descriptors/ports.
729 This approach is not yet implemented, though.
731 @subsubsection Utility Guile Implementation
733 The ``utility'' Guile client mentioned above is a simple combination
734 of the mechanisms that we have just described. In fact the code for
735 the utility Guile client is essentially just this:
738 (use-modules (ice-9 gds-client))
739 (named-module-use! '(guile-user) '(ice-9 session))
740 (gds-accept-input #f))
743 The @code{named-module-use!} line ensures that the client can process
744 @code{help} and @code{apropos} expressions, to implement lookups in
745 Guile's online help. The @code{#f} parameter to
746 @code{gds-accept-input} means that the @code{continue} instruction
747 will not cause the instruction loop to exit, which makes sense here
748 because the utility client has nothing to do except to process GDS
751 The utility client does not use @code{on-lazy-handler-dispatch} at its
752 top level, because it has its own mechanism for catching and reporting
753 exceptions in the code that it is asked to evaluate. This mechanism
754 summarizes the exception and gives the user a button they can click to
755 see the full stack, so the end result is very similar to what
756 @code{on-lazy-handler-dispatch} provides. Deep inside
757 @code{gds-accept-input}, in the part that handles evaluating
758 expressions from Emacs, the GDS client code uses
759 @code{throw->trap-context} and @code{gds-debug-trap} to implement
763 @node Working with GDS in Scheme Buffers
764 @subsection Working with GDS in Scheme Buffers
766 The following subsections describe the facilities and key sequences that
767 GDS provides for working on code in @code{scheme-mode} buffers.
770 * Access to Guile Help and Completion::
771 * Evaluating Scheme Code::
775 @node Access to Guile Help and Completion
776 @subsubsection Access to Guile Help and Completion
778 The following keystrokes provide fast and convenient access to Guile's
779 built in help, and to completion with respect to the set of defined and
784 @findex gds-help-symbol
785 Get Guile help for a particular symbol, with the same results as if
786 you had typed @code{(help SYMBOL)} into the Guile REPL
787 (@code{gds-help-symbol}). The symbol to query defaults to the word at
788 or before the cursor but can also be entered or edited in the
789 minibuffer. The available help is popped up in a temporary Emacs
794 List all accessible Guile symbols matching a given regular expression,
795 with the same results as if you had typed @code{(apropos REGEXP)} into
796 the Guile REPL (@code{gds-apropos}). The regexp to query defaults to
797 the word at or before the cursor but can also be entered or edited in
798 the minibuffer. The list of matching symbols is popped up in a
799 temporary Emacs window.
802 @findex gds-complete-symbol
803 Try to complete the symbol at the cursor by matching it against the
804 set of all defined and accessible bindings in the associated Guile
805 process (@code{gds-complete-symbol}). If there are any extra
806 characters that can be definitively added to the symbol at point, they
807 are inserted. Otherwise, if there are any completions available, they
808 are popped up in a temporary Emacs window, where one of them can be
809 selected using either @kbd{@key{RET}} or the mouse.
813 @node Evaluating Scheme Code
814 @subsubsection Evaluating Scheme Code
816 The following keystrokes and commands provide various ways of sending
817 code to a Guile client process for evaluation.
821 @findex gds-eval-defun
822 Evaluate the ``top level defun'' that the cursor is in, in other words
823 the smallest balanced expression which includes the cursor and whose
824 opening parenthesis is in column 0 (@code{gds-eval-defun}).
827 @findex gds-eval-last-sexp
828 Evaluate the expression that ends just before the cursor
829 (@code{gds-eval-last-sexp}). This is designed so that it is easy to
830 evaluate an expression that you have just finished typing.
833 @findex gds-eval-expression
834 Read a Scheme expression using the minibuffer, and evaluate that
835 expression (@code{gds-eval-expression}).
838 @findex gds-eval-region
839 Evaluate the Scheme code in the marked region of the current buffer
840 (@code{gds-eval-region}). Note that GDS does not check whether the
841 region contains a balanced expression, or try to expand the region so
842 that it does; it uses the region exactly as it is.
845 If you type @kbd{C-u} before one of these commands, GDS will
846 immediately pop up a Scheme stack buffer, showing the requested
847 evaluation, so that you can single step through it. (This is achieved
848 by setting a @code{<source-trap>} trap at the start of the requested
849 evaluation; see @ref{Source Traps} for more on how those work.) The
850 Scheme stack display, and the options for continuing through the code,
851 are described in the next two sections.
854 @node Displaying the Scheme Stack
855 @subsection Displaying the Scheme Stack
857 When you specify @code{gds-debug-trap} as the behaviour for a trap and
858 the Guile program concerned hits that trap, GDS displays the stack and
859 the relevant Scheme source code in Emacs, allowing you to explore the
860 state of the program and then decide what to do next. The same
861 applies if the program calls @code{(on-lazy-handler-dispatch
862 gds-debug-trap)} and then throws an exception that passes through
863 @code{lazy-handler-dispatch}, except that in this case you can only
864 explore; it isn't possible to continue normal execution after an
867 The following commands are available in the stack buffer for exploring
868 the state of the program.
871 @item @kbd{u}, @kbd{C-p}, @kbd{@key{up}}
873 Select the stack frame one up from the currently selected frame
874 (@code{gds-up}). GDS displays stack frames with the innermost at the
875 top, so moving ``up'' means selecting a more ``inner'' frame.
877 @item @kbd{d}, @kbd{C-n}, @kbd{@key{down}}
879 Select the stack frame one down from the currently selected frame
880 (@code{gds-down}). GDS displays stack frames with the innermost at the
881 top, so moving ``down'' means selecting a more ``outer'' frame.
883 @item @kbd{@key{RET}}
884 @findex gds-select-stack-frame
885 Select the stack frame at point (@code{gds-select-stack-frame}). This
886 is useful after clicking somewhere in the stack trace with the mouse.
889 Selecting a frame means that GDS will display the source code
890 corresponding to that frame in the adjacent window, and that
891 subsequent frame-sensitive commands, such as @code{gds-evaluate} (see
892 below) and @code{gds-step-over} (@pxref{Continuing Execution}), will
898 Evaluate a variable or expression in the local environment of the
899 selected stack frame (@code{gds-evaluate}). The result is displayed in
903 @findex gds-frame-info
904 Show summary information about the selected stack frame
905 (@code{gds-frame-info}). This includes what type of frame it is, the
906 associated expression, and the frame's source location, if any.
909 @findex gds-frame-args
910 For an application frame, display the frame's arguments
911 (@code{gds-frame-args}).
914 @findex gds-proc-source
915 For an application frame, show the Scheme source code of the procedure
916 being called (@code{gds-proc-source}). The source code (where
917 available) is displayed in the echo area.
920 @kbd{S} (@code{gds-proc-source}) is useful when the procedure being
921 called was created by an anonymous @code{(lambda @dots{})} expression.
922 Such procedures appear in the stack trace as @code{<procedure #f
923 (@dots{})>}, which doesn't give you much clue as to what will happen
924 next. @kbd{S} will show you the procedure's code, which is usually
925 enough for you to identify it.
928 @node Continuing Execution
929 @subsection Continuing Execution
931 If it makes sense to continue execution from the stack which is being
932 displayed, GDS provides the following further commands in the stack
936 @item @kbd{g}, @kbd{c}, @kbd{q}
938 Tell the program to continue running (@code{gds-go}). It may of course
939 stop again if it hits another trap, or another occurrence of the same
942 The multiple keystrokes reflect that you can think of this as ``going'',
943 ``continuing'' or ``quitting'' (in the sense of quitting the GDS
946 @item @kbd{@key{SPC}}
947 @findex gds-step-file
948 Tell the program to do a single-step to the next entry or exit of a
949 frame whose code comes from the same source file as the selected stack
950 frame (@code{gds-step-file}).
952 In other words, you can hit @kbd{@key{SPC}} repeatedly to step through
953 the code in a given file, automatically stepping @emph{over} any
954 evaluations or procedure calls that use code from other files (or from
957 If the selected stack frame has no source, the effect of this command is
958 the same as that of @kbd{i}, described next.
961 @findex gds-step-into
962 Tell the debugged program to do a single-step to the next frame entry or
963 exit of any kind (@code{gds-step-into}). @kbd{i} therefore steps
964 through code at the most detailed level possible.
967 @findex gds-step-over
968 Tell the debugged program to continue running until the selected stack
969 frame completes, and then to display its result (@code{gds-step-over}).
970 Note that the program may stop before then if it hits another trap; in
971 this case the trap telling it to stop when the marked frame completes
972 remains in place and so will still fire at the appropriate point.
976 @node Associating Buffers with Clients
977 @subsection Associating Buffers with Clients
979 The first time that you use one of GDS's evaluation, help or completion
980 commands from a given Scheme mode buffer, GDS will ask which Guile
981 client program you want to use for the operation, or if you want to
982 start up a new ``utility'' client. After that GDS considers the buffer
983 to be ``associated'' with the selected client, and so sends all further
984 requests to that client, but you can override this by explicitly
985 associating the buffer with a different client, or by removing the
989 @item M-x gds-associate-buffer
990 Associate (or re-associate) the current buffer with a particular Guile
991 client program. The available clients are listed, and you can also
992 choose to start up a new ``utility'' client for this buffer to associate
995 @item M-x gds-dissociate-buffer
996 Dissociate the current buffer from its client, if any. This means that
997 the next time you use an evaluation, help or completion command, GDS
998 will ask you again which client to send the request to.
1001 When a buffer is associated with a client program, the buffer's modeline
1002 shows whether the client is currently able to accept instruction from
1003 GDS. This is done by adding one of the following suffixes to the
1004 ``Scheme'' major mode indicator:
1008 The client program (or one of its threads, if multithreaded) is
1009 currently ready to accept instruction from GDS. In other words, if you
1010 send it a help or evaluation request, you should see the result pretty
1014 The client program is not currently able to accept instruction from
1015 GDS. This means that it (or all of its threads, if multithreaded) is
1016 busy, or waiting for input other than from GDS.
1019 The client program (or one of its threads, if multithreaded) is stopped
1020 in ``debugging mode'' with GDS displaying the stack for a trap or
1021 exception. It is waiting for instruction from GDS on what to do next.
1025 @node An Example GDS Session
1026 @subsection An Example GDS Session
1028 Create a file, @file{testgds.scm} say, for experimenting with GDS and
1029 Scheme code, and type this into it:
1032 (use-modules (ice-9 debugging traps)
1034 (ice-9 debugging example-fns))
1035 (install-trap (make <procedure-trap>
1036 #:behaviour gds-debug-trap
1041 Now select all of this code and type @kbd{C-c C-r} to send the selected
1042 region to Guile for evaluation. GDS will ask you which Guile process to
1043 use; unless you know that you already have another Guile application
1044 running and connected to GDS, choose the ``Start a new Guile'' option,
1045 which starts one of the ``utility'' processes described in @ref{GDS
1048 The results of the evaluation pop up in a window like this:
1051 (use-modules (ice-9 debugging traps)\n @dots{}
1053 ;;; Evaluating subexpression 1 in current module (guile-user)
1054 @result{} no (or unspecified) value
1056 ;;; Evaluating subexpression 2 in current module (guile-user)
1057 @result{} no (or unspecified) value
1059 --:** *Guile Evaluation* (Scheme:ready)--All------------
1063 this tells you that the evaluation was successful but that the return
1064 values were unspecified. Its effect was to load a module of example
1065 functions and set a trap on one of these functions, @code{fact1}, that
1066 calculates the factorial of its argument.
1068 If you now call @code{fact1}, you can see the trap and GDS's stack
1069 display in action. To do this add
1076 to your @file{testgds.scm} buffer and type @kbd{C-x C-e} (which
1077 evaluates the expression that the cursor is just after the end of).
1078 The result should be that a GDS stack window like the following
1084 s [primitive-eval (fact1 4)]
1087 --:** PID 28729 (Guile-Debug)--All------------
1090 This stack tells you that Guile is about to call the @code{fact1}
1091 procedure, with argument 4, and you can step through this call in
1092 detail by pressing @kbd{i} once and then @kbd{@key{SPC}}
1093 (@pxref{Continuing Execution}).
1095 (@kbd{i} is needed as the first keystroke rather than @kbd{@key{SPC}},
1096 because the aim here is to step through code in the @code{(ice-9
1097 debugging example-fns)} module, whose source file is
1098 @file{@dots{}/ice-9/debugging/example-fns.scm}, but the initial
1099 @code{(fact1 4)} call comes from the Guile session, whose ``source
1100 file'' Guile presents as @file{standard input}. If the user starts by
1101 pressing @kbd{@key{SPC}} instead of @kbd{i}, the effect is that the
1102 program runs until it hits the first recursive call @code{(fact1 (- n
1103 1))}, where it stops because of the trap on @code{fact1} firing again.
1104 At this point, the source file @emph{is}
1105 @file{@dots{}/ice-9/debugging/example-fns.scm}, because the recursive
1106 @code{(fact1 (- n 1))} call comes from code in that file, so further
1107 pressing of @kbd{@key{SPC}} successfully single-steps through this
1112 @c TeX-master: "guile.texi"