2 @c This is part of the GNU Guile Reference Manual.
3 @c Copyright (C) 2006, 2010
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
17 scheme@@(guile-user)> (+ 3 4 5)
19 scheme@@(guile-user)> (display "Hello world!\n")
21 scheme@@(guile-user)> (values 'a 'b)
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
32 The prompt shows you what language and module you are in. In this case, the
33 current language is @code{scheme}, and the current module is
34 @code{(guile-user)}. @xref{Other Languages}, for more information on Guile's
35 support for languages other than Scheme.
42 * Interactive Debugging::
49 To make it easier for you to repeat and vary previously entered
50 expressions, or to edit the expression that you're typing in, Guile
51 can use the GNU Readline library. This is not enabled by default
52 because of licensing reasons, but all you need to activate Readline is
53 the following pair of lines.
56 scheme@@(guile-user)> (use-modules (ice-9 readline))
57 scheme@@(guile-user)> (activate-readline)
60 It's a good idea to put these two lines (without the
61 @code{scheme@@(guile-user)>} prompts) in your @file{.guile} file. Guile
62 reads this file when it starts up interactively, so anything in this
63 file has the same effect as if you type it in by hand at the
64 @code{scheme@@(guile-user)>} prompt.
68 @subsection Value History
70 Just as Readline helps you to reuse a previous input line, @dfn{value
71 history} allows you to use the @emph{result} of a previous evaluation in
72 a new expression. When value history is enabled, each evaluation result
73 is automatically assigned to the next in the sequence of variables
74 @code{$1}, @code{$2}, @dots{}. You can then use these variables in
75 subsequent expressions.
78 scheme@@(guile-user)> (iota 10)
79 $1 = (0 1 2 3 4 5 6 7 8 9)
80 scheme@@(guile-user)> (apply * (cdr $1))
82 scheme@@(guile-user)> (sqrt $2)
83 $3 = 602.3952191045344
84 scheme@@(guile-user)> (cons $2 $1)
85 $4 = (362880 0 1 2 3 4 5 6 7 8 9)
88 Value history is enabled by default, because Guile's REPL imports the
89 @code{(ice-9 history)} module. Value history may be turned off or on within the
90 repl, using the options interface:
93 scheme@@(guile-user)> ,option value-history #f
94 scheme@@(guile-user)> 'foo
96 scheme@@(guile-user)> ,option value-history #t
97 scheme@@(guile-user)> 'bar
101 Note that previously recorded values are still accessible, even if value history
102 is off. In rare cases, these references to past computations can cause Guile to
103 use too much memory. One may clear these values, possibly enabling garbage
104 collection, via the @code{clear-value-history!} procedure, described below.
106 The programmatic interface to value history is in a module:
109 (use-modules (ice-9 history))
112 @deffn {Scheme Procedure} value-history-enabled?
113 Return true iff value history is enabled.
116 @deffn {Scheme Procedure} enable-value-history!
117 Turn on value history, if it was off.
120 @deffn {Scheme Procedure} disable-value-history!
121 Turn off value history, if it was on.
124 @deffn {Scheme Procedure} clear-value-history!
125 Clear the value history. If the stored values are not captured by some other
126 data structure or closure, they may then be reclaimed by the garbage collector.
131 @subsection REPL Commands
134 The REPL exists to read expressions, evaluate them, and then print their
135 results. But sometimes one wants to tell the REPL to evaluate an
136 expression in a different way, or to do something else altogether. A
137 user can affect the way the REPL works with a @dfn{REPL command}.
139 The previous section had an example of a command, in the form of
143 scheme@@(guile-user)> ,option value-history #t
147 Commands are distinguished from expressions by their initial comma
148 (@samp{,}). Since a comma cannot begin an expression in most languages,
149 it is an effective indicator to the REPL that the following text forms a
150 command, not an expression.
152 REPL commands are convenient because they are always there. Even if the
153 current module doesn't have a binding for @code{pretty-print}, one can
154 always @code{,pretty-print}.
156 The following sections document the various commands, grouped together
157 by functionality. Many of the commands have abbreviations; see the
158 online help (@code{,help}) for more information.
163 * Language Commands::
172 @subsubsection Help Commands
174 When Guile starts interactively, it notifies the user that help can be
175 had by typing @samp{,help}. Indeed, @code{help} is a command, and a
176 particularly useful one, as it allows the user to discover the rest of
179 @deffn {REPL Command} help [@code{all} | group | @code{[-c]} command]
182 With one argument, tries to look up the argument as a group name, giving
183 help on that group if successful. Otherwise tries to look up the
184 argument as a command, giving help on the command.
186 If there is a command whose name is also a group name, use the @samp{-c
187 @var{command}} form to give help on the command instead of the group.
189 Without any argument, a list of help commands and command groups
193 @deffn {REPL Command} show [topic]
194 Gives information about Guile.
196 With one argument, tries to show a particular piece of information;
197 currently supported topics are `warranty' (or `w'), `copying' (or `c'),
198 and `version' (or `v').
200 Without any argument, a list of topics is displayed.
203 @deffn {REPL Command} apropos regexp
204 Find bindings/modules/packages.
207 @deffn {REPL Command} describe obj
208 Show description/documentation.
211 @node Module Commands
212 @subsubsection Module Commands
214 @deffn {REPL Command} module [module]
215 Change modules / Show current module.
218 @deffn {REPL Command} import [module ...]
219 Import modules / List those imported.
222 @deffn {REPL Command} load file
223 Load a file in the current module.
226 @deffn {REPL Command} reload [module]
227 Reload the given module, or the current module if none was given.
230 @deffn {REPL Command} binding
231 List current bindings.
234 @deffn {REPL Command} in module expression
235 @deffnx {REPL Command} in module command [args ...]
236 Evaluate an expression, or alternatively, execute another meta-command
237 in the context of a module. For example, @samp{,in (foo bar) ,binding}
238 will show the bindings in the module @code{(foo bar)}.
241 @node Language Commands
242 @subsubsection Language Commands
244 @deffn {REPL Command} language language
248 @node Compile Commands
249 @subsubsection Compile Commands
251 @deffn {REPL Command} compile exp
252 Generate compiled code.
255 @deffn {REPL Command} compile-file file
259 @deffn {REPL Command} disassemble exp
260 Disassemble a compiled procedure.
263 @deffn {REPL Command} disassemble-file file
267 @node Profile Commands
268 @subsubsection Profile Commands
270 @deffn {REPL Command} time exp
274 @deffn {REPL Command} profile exp
278 @deffn {REPL Command} trace exp
283 @subsubsection Debug Commands
285 These debugging commands are only available within a recursive REPL;
286 they do not work at the top level.
288 @deffn {REPL Command} backtrace [count] [#:width w] [#:full? f]
291 Print a backtrace of all stack frames, or innermost @var{COUNT} frames.
292 If @var{count} is negative, the last @var{count} frames will be shown.
295 @deffn {REPL Command} up [count]
296 Select a calling stack frame.
298 Select and print stack frames that called this one.
299 An argument says how many frames up to go.
302 @deffn {REPL Command} down [count]
303 Select a called stack frame.
305 Select and print stack frames called by this one.
306 An argument says how many frames down to go.
309 @deffn {REPL Command} frame [idx]
312 Show the selected frame. With an argument, select a frame by index,
316 @deffn {REPL Command} procedure
317 Print the procedure for the selected frame.
320 @deffn {REPL Command} locals
321 Show local variables.
323 Show locally-bound variables in the selected frame.
326 @deffn {REPL Command} error-message
327 @deffnx {REPL Command} error
330 Display the message associated with the error that started the current
334 @deffn {REPL Command} registers
335 Show the VM registers associated with the current frame.
337 @xref{Stack Layout}, for more information on VM stack frames.
340 The next 3 commands work at any REPL.
342 @deffn {REPL Command} break proc
343 Set a breakpoint at @var{proc}.
346 @deffn {REPL Command} break-at-source file line
347 Set a breakpoint at the given source location.
350 @deffn {REPL Command} tracepoint proc
351 Set a tracepoint on the given procedure. This will cause all calls to
352 the procedure to print out a tracing message. @xref{Tracing Traps}, for
356 The rest of the commands in this subsection all apply only when the
357 stack is @dfn{continuable} --- in other words when it makes sense for
358 the program that the stack comes from to continue running. Usually this
359 means that the program stopped because of a trap or a breakpoint.
361 @deffn {REPL Command} step
362 Tell the debugged program to step to the next source location.
365 @deffn {REPL Command} next
366 Tell the debugged program to step to the next source location in the
367 same frame. (See @ref{Traps} for the details of how this works.)
370 @deffn {REPL Command} finish
371 Tell the program being debugged to continue running until the completion
372 of the current stack frame, and at that time to print the result and
377 @node Inspect Commands
378 @subsubsection Inspect Commands
380 @deffn {REPL Command} inspect EXP
381 Inspect the result(s) of evaluating @var{exp}.
384 @deffn {REPL Command} pretty-print EXP
385 Pretty-print the result(s) of evaluating @var{exp}.
388 @node System Commands
389 @subsubsection System Commands
391 @deffn {REPL Command} gc
395 @deffn {REPL Command} statistics
399 @deffn {REPL Command} option [key value]
400 List/show/set options.
403 @deffn {REPL Command} quit
409 @subsection Error Handling
411 When code being evaluated from the REPL hits an error, Guile enters a
412 new prompt, allowing you to inspect the context of the error.
415 scheme@@(guile-user)> (map string-append '("a" "b") '("c" #\d))
416 ERROR: In procedure string-append:
417 ERROR: Wrong type (expecting string): #\d
418 Entering a new prompt. Type `,bt' for a backtrace or `,q' to continue.
419 scheme@@(guile-user) [1]>
422 The new prompt runs inside the old one, in the dynamic context of the
423 error. It is a recursive REPL, augmented with a reified representation
424 of the stack, ready for debugging.
426 @code{,backtrace} (abbreviated @code{,bt}) displays the Scheme call
427 stack at the point where the error occurred:
430 scheme@@(guile-user) [1]> ,bt
431 1 (map #<procedure string-append _> ("a" "b") ("c" #\d))
432 0 (string-append "b" #\d)
435 In the above example, the backtrace doesn't have much source
436 information, as @code{map} and @code{string-append} are both
437 primitives. But in the general case, the space on the left of the
438 backtrace indicates the line and column in which a given procedure calls
441 You can exit a recursive REPL in the same way that you exit any REPL:
442 via @samp{(quit)}, @samp{,quit} (abbreviated @samp{,q}), or
443 @kbd{C-d}, among other options.
446 @node Interactive Debugging
447 @subsection Interactive Debugging
449 A recursive debugging REPL exposes a number of other meta-commands that
450 inspect the state of the computation at the time of the error. These
451 commands allow you to
455 display the Scheme call stack at the point where the error occurred;
458 move up and down the call stack, to see in detail the expression being
459 evaluated, or the procedure being applied, in each @dfn{frame}; and
462 examine the values of variables and expressions in the context of each
467 @xref{Debug Commands}, for documentation of the individual
468 commands. This section aims to give more of a walkthrough of a typical
471 First, we're going to need a good error. Let's try to macroexpand the
472 expression @code{(unquote foo)}, outside of a @code{quasiquote} form,
473 and see how the macroexpander reports this error.
476 scheme@@(guile-user)> (macroexpand '(unquote foo))
477 ERROR: In procedure macroexpand:
478 ERROR: unquote: expression not valid outside of quasiquote in (unquote foo)
479 Entering a new prompt. Type `,bt' for a backtrace or `,q' to continue.
480 scheme@@(guile-user) [1]>
483 The @code{backtrace} command, which can also be invoked as @code{bt},
484 displays the call stack (aka backtrace) at the point where the debugger
488 scheme@@(guile-user) [1]> ,bt
489 In ice-9/psyntax.scm:
490 1130:21 3 (chi-top (unquote foo) () ((top)) e (eval) (hygiene #))
491 1071:30 2 (syntax-type (unquote foo) () ((top)) #f #f (# #) #f)
492 1368:28 1 (chi-macro #<procedure de9360 at ice-9/psyntax.scm...> ...)
494 0 (scm-error syntax-error macroexpand "~a: ~a in ~a" # #f)
497 A call stack consists of a sequence of stack @dfn{frames}, with each
498 frame describing one procedure which is waiting to do something with the
499 values returned by another. Here we see that there are four frames on
502 Note that @code{macroexpand} is not on the stack -- it must have made a
503 tail call to @code{chi-top}, as indeed we would find if we searched
504 @code{ice-9/psyntax.scm} for its definition.
506 When you enter the debugger, the innermost frame is selected, which
507 means that the commands for getting information about the ``current''
508 frame, or for evaluating expressions in the context of the current
509 frame, will do so by default with respect to the innermost frame. To
510 select a different frame, so that these operations will apply to it
511 instead, use the @code{up}, @code{down} and @code{frame} commands like
515 scheme@@(guile-user) [1]> ,up
516 In ice-9/psyntax.scm:
517 1368:28 1 (chi-macro #<procedure de9360 at ice-9/psyntax.scm...> ...)
518 scheme@@(guile-user) [1]> ,frame 3
519 In ice-9/psyntax.scm:
520 1130:21 3 (chi-top (unquote foo) () ((top)) e (eval) (hygiene #))
521 scheme@@(guile-user) [1]> ,down
522 In ice-9/psyntax.scm:
523 1071:30 2 (syntax-type (unquote foo) () ((top)) #f #f (# #) #f)
526 Perhaps we're interested in what's going on in frame 2, so we take a
527 look at its local variables:
530 scheme@@(guile-user) [1]> ,locals
532 $1 = e = (unquote foo)
537 $6 = mod = (hygiene guile-user)
541 $10 = fval = #<procedure de9360 at ice-9/psyntax.scm:2817:2 (x)>
545 $14 = fmod = (hygiene guile-user)
548 All of the values are accessible by their value-history names
552 scheme@@(guile-user) [1]> $10
553 $15 = #<procedure de9360 at ice-9/psyntax.scm:2817:2 (x)>
556 We can even invoke the procedure at the REPL directly:
559 scheme@@(guile-user) [1]> ($10 'not-going-to-work)
560 ERROR: In procedure macroexpand:
561 ERROR: source expression failed to match any pattern in not-going-to-work
562 Entering a new prompt. Type `,bt' for a backtrace or `,q' to continue.
565 Well at this point we've caused an error within an error. Let's just
566 quit back to the top level:
569 scheme@@(guile-user) [2]> ,q
570 scheme@@(guile-user) [1]> ,q
571 scheme@@(guile-user)>
574 Finally, as a word to the wise: hackers close their REPL prompts with
578 @node Using Guile in Emacs
579 @section Using Guile in Emacs
582 Any text editor can edit Scheme, but some are better than others. Emacs
583 is the best, of course, and not just because it is a fine text editor.
584 Emacs has good support for Scheme out of the box, with sensible
585 indentation rules, parenthesis-matching, syntax highlighting, and even a
586 set of keybindings for structural editing, allowing navigation,
587 cut-and-paste, and transposition operations that work on balanced
590 As good as it is, though, two things will vastly improve your experience
591 with Emacs and Guile.
594 The first is Taylor Campbell's
595 @uref{http://www.emacswiki.org/emacs/ParEdit, Paredit}. You should not
596 code in any dialect of Lisp without Paredit. (They say that
597 unopinionated writing is boring---hence this tone---but it's the
598 truth, regardless.) Paredit is the bee's knees.
608 Antonio Ortega Ruiz's
609 @uref{http://www.nongnu.org/geiser/, Geiser}. Geiser complements Emacs'
610 @code{scheme-mode} with tight integration to running Guile processes via
611 a @code{comint-mode} REPL buffer.
613 Of course there are keybindings to switch to the REPL, and a good REPL
614 environment, but Geiser goes beyond that, providing:
618 Form evaluation in the context of the current file's module.
622 File/module loading and/or compilation.
624 Namespace-aware identifier completion (including local bindings, names
625 visible in the current module, and module names).
627 Autodoc: the echo area shows information about the signature of the
628 procedure/macro around point automatically.
630 Jump to definition of identifier at point.
632 Access to documentation (including docstrings when the implementation
635 Listings of identifiers exported by a given module.
637 Listings of callers/callees of procedures.
639 Rudimentary support for debugging and error navigation.
641 Support for multiple, simultaneous REPLs.
644 See Geiser's web page at @uref{http://www.nongnu.org/geiser/}, for more
649 @c TeX-master: "guile.texi"