2 @c This is part of the GNU Guile Reference Manual.
3 @c Copyright (C) 2006, 2010, 2011, 2012, 2013
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.
43 * Interactive Debugging::
48 @subsection The Init File, @file{~/.guile}
51 When run interactively, Guile will load a local initialization file from
52 @file{~/.guile}. This file should contain Scheme expressions for
55 This facility lets the user customize their interactive Guile
56 environment, pulling in extra modules or parameterizing the REPL
59 To run Guile without loading the init file, use the @code{-q}
66 To make it easier for you to repeat and vary previously entered
67 expressions, or to edit the expression that you're typing in, Guile
68 can use the GNU Readline library. This is not enabled by default
69 because of licensing reasons, but all you need to activate Readline is
70 the following pair of lines.
73 scheme@@(guile-user)> (use-modules (ice-9 readline))
74 scheme@@(guile-user)> (activate-readline)
77 It's a good idea to put these two lines (without the
78 @code{scheme@@(guile-user)>} prompts) in your @file{.guile} file.
79 @xref{Init File}, for more on @file{.guile}.
83 @subsection Value History
85 Just as Readline helps you to reuse a previous input line, @dfn{value
86 history} allows you to use the @emph{result} of a previous evaluation in
87 a new expression. When value history is enabled, each evaluation result
88 is automatically assigned to the next in the sequence of variables
89 @code{$1}, @code{$2}, @dots{}. You can then use these variables in
90 subsequent expressions.
93 scheme@@(guile-user)> (iota 10)
94 $1 = (0 1 2 3 4 5 6 7 8 9)
95 scheme@@(guile-user)> (apply * (cdr $1))
97 scheme@@(guile-user)> (sqrt $2)
98 $3 = 602.3952191045344
99 scheme@@(guile-user)> (cons $2 $1)
100 $4 = (362880 0 1 2 3 4 5 6 7 8 9)
103 Value history is enabled by default, because Guile's REPL imports the
104 @code{(ice-9 history)} module. Value history may be turned off or on within the
105 repl, using the options interface:
108 scheme@@(guile-user)> ,option value-history #f
109 scheme@@(guile-user)> 'foo
111 scheme@@(guile-user)> ,option value-history #t
112 scheme@@(guile-user)> 'bar
116 Note that previously recorded values are still accessible, even if value history
117 is off. In rare cases, these references to past computations can cause Guile to
118 use too much memory. One may clear these values, possibly enabling garbage
119 collection, via the @code{clear-value-history!} procedure, described below.
121 The programmatic interface to value history is in a module:
124 (use-modules (ice-9 history))
127 @deffn {Scheme Procedure} value-history-enabled?
128 Return true if value history is enabled, or false otherwise.
131 @deffn {Scheme Procedure} enable-value-history!
132 Turn on value history, if it was off.
135 @deffn {Scheme Procedure} disable-value-history!
136 Turn off value history, if it was on.
139 @deffn {Scheme Procedure} clear-value-history!
140 Clear the value history. If the stored values are not captured by some other
141 data structure or closure, they may then be reclaimed by the garbage collector.
146 @subsection REPL Commands
149 The REPL exists to read expressions, evaluate them, and then print their
150 results. But sometimes one wants to tell the REPL to evaluate an
151 expression in a different way, or to do something else altogether. A
152 user can affect the way the REPL works with a @dfn{REPL command}.
154 The previous section had an example of a command, in the form of
158 scheme@@(guile-user)> ,option value-history #t
162 Commands are distinguished from expressions by their initial comma
163 (@samp{,}). Since a comma cannot begin an expression in most languages,
164 it is an effective indicator to the REPL that the following text forms a
165 command, not an expression.
167 REPL commands are convenient because they are always there. Even if the
168 current module doesn't have a binding for @code{pretty-print}, one can
169 always @code{,pretty-print}.
171 The following sections document the various commands, grouped together
172 by functionality. Many of the commands have abbreviations; see the
173 online help (@code{,help}) for more information.
178 * Language Commands::
187 @subsubsection Help Commands
189 When Guile starts interactively, it notifies the user that help can be
190 had by typing @samp{,help}. Indeed, @code{help} is a command, and a
191 particularly useful one, as it allows the user to discover the rest of
194 @deffn {REPL Command} help [@code{all} | group | @code{[-c]} command]
197 With one argument, tries to look up the argument as a group name, giving
198 help on that group if successful. Otherwise tries to look up the
199 argument as a command, giving help on the command.
201 If there is a command whose name is also a group name, use the @samp{-c
202 @var{command}} form to give help on the command instead of the group.
204 Without any argument, a list of help commands and command groups
208 @deffn {REPL Command} show [topic]
209 Gives information about Guile.
211 With one argument, tries to show a particular piece of information;
212 currently supported topics are `warranty' (or `w'), `copying' (or `c'),
213 and `version' (or `v').
215 Without any argument, a list of topics is displayed.
218 @deffn {REPL Command} apropos regexp
219 Find bindings/modules/packages.
222 @deffn {REPL Command} describe obj
223 Show description/documentation.
226 @node Module Commands
227 @subsubsection Module Commands
229 @deffn {REPL Command} module [module]
230 Change modules / Show current module.
233 @deffn {REPL Command} import module @dots{}
234 Import modules / List those imported.
237 @deffn {REPL Command} load file
238 Load a file in the current module.
241 @deffn {REPL Command} reload [module]
242 Reload the given module, or the current module if none was given.
245 @deffn {REPL Command} binding
246 List current bindings.
249 @deffn {REPL Command} in module expression
250 @deffnx {REPL Command} in module command arg @dots{}
251 Evaluate an expression, or alternatively, execute another meta-command
252 in the context of a module. For example, @samp{,in (foo bar) ,binding}
253 will show the bindings in the module @code{(foo bar)}.
256 @node Language Commands
257 @subsubsection Language Commands
259 @deffn {REPL Command} language language
263 @node Compile Commands
264 @subsubsection Compile Commands
266 @deffn {REPL Command} compile exp
267 Generate compiled code.
270 @deffn {REPL Command} compile-file file
274 @deffn {REPL Command} expand exp
275 Expand any macros in a form.
278 @deffn {REPL Command} optimize exp
279 Run the optimizer on a piece of code and print the result.
282 @deffn {REPL Command} disassemble exp
283 Disassemble a compiled procedure.
286 @deffn {REPL Command} disassemble-file file
290 @node Profile Commands
291 @subsubsection Profile Commands
293 @deffn {REPL Command} time exp
297 @deffn {REPL Command} profile exp
301 @deffn {REPL Command} trace exp [#:width w] [#:max-indent i]
304 By default, the trace will limit its width to the width of your
305 terminal, or @var{width} if specified. Nested procedure invocations
306 will be printed farther to the right, though if the width of the
307 indentation passes the @var{max-indent}, the indentation is abbreviated.
311 @subsubsection Debug Commands
313 These debugging commands are only available within a recursive REPL;
314 they do not work at the top level.
316 @deffn {REPL Command} backtrace [count] [#:width w] [#:full? f]
319 Print a backtrace of all stack frames, or innermost @var{count} frames.
320 If @var{count} is negative, the last @var{count} frames will be shown.
323 @deffn {REPL Command} up [count]
324 Select a calling stack frame.
326 Select and print stack frames that called this one.
327 An argument says how many frames up to go.
330 @deffn {REPL Command} down [count]
331 Select a called stack frame.
333 Select and print stack frames called by this one.
334 An argument says how many frames down to go.
337 @deffn {REPL Command} frame [idx]
340 Show the selected frame. With an argument, select a frame by index,
344 @deffn {REPL Command} procedure
345 Print the procedure for the selected frame.
348 @deffn {REPL Command} locals
349 Show local variables.
351 Show locally-bound variables in the selected frame.
354 @deffn {REPL Command} error-message
355 @deffnx {REPL Command} error
358 Display the message associated with the error that started the current
362 @deffn {REPL Command} registers
363 Show the VM registers associated with the current frame.
365 @xref{Stack Layout}, for more information on VM stack frames.
368 @deffn {REPL Command} width [cols]
369 Sets the number of display columns in the output of @code{,backtrace}
370 and @code{,locals} to @var{cols}. If @var{cols} is not given, the width
371 of the terminal is used.
374 The next 3 commands work at any REPL.
376 @deffn {REPL Command} break proc
377 Set a breakpoint at @var{proc}.
380 @deffn {REPL Command} break-at-source file line
381 Set a breakpoint at the given source location.
384 @deffn {REPL Command} tracepoint proc
385 Set a tracepoint on the given procedure. This will cause all calls to
386 the procedure to print out a tracing message. @xref{Tracing Traps}, for
390 The rest of the commands in this subsection all apply only when the
391 stack is @dfn{continuable} --- in other words when it makes sense for
392 the program that the stack comes from to continue running. Usually this
393 means that the program stopped because of a trap or a breakpoint.
395 @deffn {REPL Command} step
396 Tell the debugged program to step to the next source location.
399 @deffn {REPL Command} next
400 Tell the debugged program to step to the next source location in the
401 same frame. (See @ref{Traps} for the details of how this works.)
404 @deffn {REPL Command} finish
405 Tell the program being debugged to continue running until the completion
406 of the current stack frame, and at that time to print the result and
411 @node Inspect Commands
412 @subsubsection Inspect Commands
414 @deffn {REPL Command} inspect exp
415 Inspect the result(s) of evaluating @var{exp}.
418 @deffn {REPL Command} pretty-print exp
419 Pretty-print the result(s) of evaluating @var{exp}.
422 @node System Commands
423 @subsubsection System Commands
425 @deffn {REPL Command} gc
429 @deffn {REPL Command} statistics
433 @deffn {REPL Command} option [name] [exp]
434 With no arguments, lists all options. With one argument, shows the
435 current value of the @var{name} option. With two arguments, sets the
436 @var{name} option to the result of evaluating the Scheme expression
440 @deffn {REPL Command} quit
444 Current REPL options include:
447 @item compile-options
448 The options used when compiling expressions entered at the REPL.
449 @xref{Compilation}, for more on compilation options.
451 Whether to interpret or compile expressions given at the REPL, if such a
452 choice is available. Off by default (indicating compilation).
454 A customized REPL prompt. @code{#f} by default, indicating the default
457 A procedure of two arguments used to print the result of evaluating each
458 expression. The arguments are the current REPL and the value to print.
459 By default, @code{#f}, to use the default procedure.
461 Whether value history is on or not. @xref{Value History}.
463 What to do when an error happens. By default, @code{debug}, meaning to
464 enter the debugger. Other values include @code{backtrace}, to show a
465 backtrace without entering the debugger, or @code{report}, to simply
466 show a short error printout.
469 Default values for REPL options may be set using
470 @code{repl-default-option-set!} from @code{(system repl common)}:
472 @deffn {Scheme Procedure} repl-default-option-set! key value
473 Set the default value of a REPL option. This function is particularly
474 useful in a user's init file. @xref{Init File}.
479 @subsection Error Handling
481 When code being evaluated from the REPL hits an error, Guile enters a
482 new prompt, allowing you to inspect the context of the error.
485 scheme@@(guile-user)> (map string-append '("a" "b") '("c" #\d))
486 ERROR: In procedure string-append:
487 ERROR: Wrong type (expecting string): #\d
488 Entering a new prompt. Type `,bt' for a backtrace or `,q' to continue.
489 scheme@@(guile-user) [1]>
492 The new prompt runs inside the old one, in the dynamic context of the
493 error. It is a recursive REPL, augmented with a reified representation
494 of the stack, ready for debugging.
496 @code{,backtrace} (abbreviated @code{,bt}) displays the Scheme call
497 stack at the point where the error occurred:
500 scheme@@(guile-user) [1]> ,bt
501 1 (map #<procedure string-append _> ("a" "b") ("c" #\d))
502 0 (string-append "b" #\d)
505 In the above example, the backtrace doesn't have much source
506 information, as @code{map} and @code{string-append} are both
507 primitives. But in the general case, the space on the left of the
508 backtrace indicates the line and column in which a given procedure calls
511 You can exit a recursive REPL in the same way that you exit any REPL:
512 via @samp{(quit)}, @samp{,quit} (abbreviated @samp{,q}), or
513 @kbd{C-d}, among other options.
516 @node Interactive Debugging
517 @subsection Interactive Debugging
519 A recursive debugging REPL exposes a number of other meta-commands that
520 inspect the state of the computation at the time of the error. These
521 commands allow you to
525 display the Scheme call stack at the point where the error occurred;
528 move up and down the call stack, to see in detail the expression being
529 evaluated, or the procedure being applied, in each @dfn{frame}; and
532 examine the values of variables and expressions in the context of each
537 @xref{Debug Commands}, for documentation of the individual
538 commands. This section aims to give more of a walkthrough of a typical
541 First, we're going to need a good error. Let's try to macroexpand the
542 expression @code{(unquote foo)}, outside of a @code{quasiquote} form,
543 and see how the macroexpander reports this error.
546 scheme@@(guile-user)> (macroexpand '(unquote foo))
547 ERROR: In procedure macroexpand:
548 ERROR: unquote: expression not valid outside of quasiquote in (unquote foo)
549 Entering a new prompt. Type `,bt' for a backtrace or `,q' to continue.
550 scheme@@(guile-user) [1]>
553 The @code{backtrace} command, which can also be invoked as @code{bt},
554 displays the call stack (aka backtrace) at the point where the debugger
558 scheme@@(guile-user) [1]> ,bt
559 In ice-9/psyntax.scm:
560 1130:21 3 (chi-top (unquote foo) () ((top)) e (eval) (hygiene #))
561 1071:30 2 (syntax-type (unquote foo) () ((top)) #f #f (# #) #f)
562 1368:28 1 (chi-macro #<procedure de9360 at ice-9/psyntax.scm...> ...)
564 0 (scm-error syntax-error macroexpand "~a: ~a in ~a" # #f)
567 A call stack consists of a sequence of stack @dfn{frames}, with each
568 frame describing one procedure which is waiting to do something with the
569 values returned by another. Here we see that there are four frames on
572 Note that @code{macroexpand} is not on the stack -- it must have made a
573 tail call to @code{chi-top}, as indeed we would find if we searched
574 @code{ice-9/psyntax.scm} for its definition.
576 When you enter the debugger, the innermost frame is selected, which
577 means that the commands for getting information about the ``current''
578 frame, or for evaluating expressions in the context of the current
579 frame, will do so by default with respect to the innermost frame. To
580 select a different frame, so that these operations will apply to it
581 instead, use the @code{up}, @code{down} and @code{frame} commands like
585 scheme@@(guile-user) [1]> ,up
586 In ice-9/psyntax.scm:
587 1368:28 1 (chi-macro #<procedure de9360 at ice-9/psyntax.scm...> ...)
588 scheme@@(guile-user) [1]> ,frame 3
589 In ice-9/psyntax.scm:
590 1130:21 3 (chi-top (unquote foo) () ((top)) e (eval) (hygiene #))
591 scheme@@(guile-user) [1]> ,down
592 In ice-9/psyntax.scm:
593 1071:30 2 (syntax-type (unquote foo) () ((top)) #f #f (# #) #f)
596 Perhaps we're interested in what's going on in frame 2, so we take a
597 look at its local variables:
600 scheme@@(guile-user) [1]> ,locals
602 $1 = e = (unquote foo)
607 $6 = mod = (hygiene guile-user)
611 $10 = fval = #<procedure de9360 at ice-9/psyntax.scm:2817:2 (x)>
615 $14 = fmod = (hygiene guile-user)
618 All of the values are accessible by their value-history names
622 scheme@@(guile-user) [1]> $10
623 $15 = #<procedure de9360 at ice-9/psyntax.scm:2817:2 (x)>
626 We can even invoke the procedure at the REPL directly:
629 scheme@@(guile-user) [1]> ($10 'not-going-to-work)
630 ERROR: In procedure macroexpand:
631 ERROR: source expression failed to match any pattern in not-going-to-work
632 Entering a new prompt. Type `,bt' for a backtrace or `,q' to continue.
635 Well at this point we've caused an error within an error. Let's just
636 quit back to the top level:
639 scheme@@(guile-user) [2]> ,q
640 scheme@@(guile-user) [1]> ,q
641 scheme@@(guile-user)>
644 Finally, as a word to the wise: hackers close their REPL prompts with
648 @node Using Guile in Emacs
649 @section Using Guile in Emacs
652 Any text editor can edit Scheme, but some are better than others. Emacs
653 is the best, of course, and not just because it is a fine text editor.
654 Emacs has good support for Scheme out of the box, with sensible
655 indentation rules, parenthesis-matching, syntax highlighting, and even a
656 set of keybindings for structural editing, allowing navigation,
657 cut-and-paste, and transposition operations that work on balanced
660 As good as it is, though, two things will vastly improve your experience
661 with Emacs and Guile.
664 The first is Taylor Campbell's
665 @uref{http://www.emacswiki.org/emacs/ParEdit, Paredit}. You should not
666 code in any dialect of Lisp without Paredit. (They say that
667 unopinionated writing is boring---hence this tone---but it's the
668 truth, regardless.) Paredit is the bee's knees.
678 Antonio Ortega Ruiz's
679 @uref{http://www.nongnu.org/geiser/, Geiser}. Geiser complements Emacs'
680 @code{scheme-mode} with tight integration to running Guile processes via
681 a @code{comint-mode} REPL buffer.
683 Of course there are keybindings to switch to the REPL, and a good REPL
684 environment, but Geiser goes beyond that, providing:
688 Form evaluation in the context of the current file's module.
692 File/module loading and/or compilation.
694 Namespace-aware identifier completion (including local bindings, names
695 visible in the current module, and module names).
697 Autodoc: the echo area shows information about the signature of the
698 procedure/macro around point automatically.
700 Jump to definition of identifier at point.
702 Access to documentation (including docstrings when the implementation
705 Listings of identifiers exported by a given module.
707 Listings of callers/callees of procedures.
709 Rudimentary support for debugging and error navigation.
711 Support for multiple, simultaneous REPLs.
714 See Geiser's web page at @uref{http://www.nongnu.org/geiser/}, for more
718 @node Using Guile Tools
719 @section Using Guile Tools
724 Guile also comes with a growing number of command-line utilities: a
725 compiler, a disassembler, some module inspectors, and in the future, a
726 system to install Guile packages from the internet. These tools may be
727 invoked using the @code{guild} program.
730 $ guild compile -o foo.go foo.scm
734 This program used to be called @code{guile-tools} up to
735 Guile version 2.0.1, and for backward
736 compatibility it still may be called as such. However we changed the
737 name to @code{guild}, not only because it is pleasantly shorter and
738 easier to read, but also because this tool will serve to bind Guile
739 wizards together, by allowing hackers to share code with each other
740 using a CPAN-like system.
742 @xref{Compilation}, for more on @code{guild compile}.
744 A complete list of guild scripts can be had by invoking @code{guild
745 list}, or simply @code{guild}.
748 @node Installing Site Packages
749 @section Installing Site Packages
755 @findex %site-ccache-dir
757 At some point, you will probably want to share your code with other
758 people. To do so effectively, it is important to follow a set of common
759 conventions, to make it easy for the user to install and use your
762 The first thing to do is to install your Scheme files where Guile can
763 find them. When Guile goes to find a Scheme file, it will search a
764 @dfn{load path} to find the file: first in Guile's own path, then in
765 paths for @dfn{site packages}. A site package is any Scheme code that
766 is installed and not part of Guile itself. @xref{Load Paths}, for more
769 There are several site paths, for historical reasons, but the one that
770 should generally be used can be obtained by invoking the
771 @code{%site-dir} procedure. @xref{Build Config}. If Guile
772 @value{EFFECTIVE-VERSION} is installed on your system in @code{/usr/},
773 then @code{(%site-dir)} will be
774 @code{/usr/share/guile/site/@value{EFFECTIVE-VERSION}}. Scheme files
775 should be installed there.
777 If you do not install compiled @code{.go} files, Guile will compile your
778 modules and programs when they are first used, and cache them in the
779 user's home directory. @xref{Compilation}, for more on
780 auto-compilation. However, it is better to compile the files before
781 they are installed, and to just copy the files to a place that Guile can
784 As with Scheme files, Guile searches a path to find compiled @code{.go}
785 files, the @code{%load-compiled-path}. By default, this path has two
786 entries: a path for Guile's files, and a path for site packages. You
787 should install your @code{.go} files into the latter directory, whose
788 value is returned by invoking the @code{%site-ccache-dir} procedure. As
789 in the previous example, if Guile @value{EFFECTIVE-VERSION} is installed
790 on your system in @code{/usr/}, then @code{(%site-ccache-dir)} site
792 @code{/usr/lib/guile/@value{EFFECTIVE-VERSION}/site-ccache}.
794 Note that a @code{.go} file will only be loaded in preference to a
795 @code{.scm} file if it is newer. For that reason, you should install
796 your Scheme files first, and your compiled files second. @code{Load
797 Paths}, for more on the loading process.
799 Finally, although this section is only about Scheme, sometimes you need
800 to install C extensions too. Shared libraries should be installed in
801 the @dfn{extensions dir}. This value can be had from the build config
802 (@pxref{Build Config}). Again, if Guile @value{EFFECTIVE-VERSION} is
803 installed on your system in @code{/usr/}, then the extensions dir will
804 be @code{/usr/lib/guile/@value{EFFECTIVE-VERSION}/extensions}.
808 @c TeX-master: "guile.texi"