-@c -*-texinfo-*-
-@c This is part of the GNU Guile Reference Manual.
-@c Copyright (C) 2006, 2010
-@c Free Software Foundation, Inc.
-@c See the file guile.texi for copying conditions.
-
-@node Using Guile Interactively
-@section Using Guile Interactively
-
-When you start up Guile by typing just @code{guile}, without a
-@code{-c} argument or the name of a script to execute, you get an
-interactive interpreter where you can enter Scheme expressions, and
-Guile will evaluate them and print the results for you. Here are some
-simple examples.
-
-@lisp
-scheme@@(guile-user)> (+ 3 4 5)
-$1 = 12
-scheme@@(guile-user)> (display "Hello world!\n")
-Hello world!
-scheme@@(guile-user)> (values 'a 'b)
-$2 = a
-$3 = b
-@end lisp
-
-@noindent
-This mode of use is called a @dfn{REPL}, which is short for
-``Read-Eval-Print Loop'', because the Guile interpreter first reads the
-expression that you have typed, then evaluates it, and then prints the
-result.
-
-The prompt shows you what language and module you are in. In this case, the
-current language is @code{scheme}, and the current module is
-@code{(guile-user)}. @xref{Other Languages}, for more information on Guile's
-support for languages other than Scheme.
-
-@menu
-* Readline::
-* Value History::
-* REPL Commands::
-* Error Handling::
-* Interactive Debugging::
-@end menu
-
-
-@node Readline
-@subsection Readline
-
-To make it easier for you to repeat and vary previously entered
-expressions, or to edit the expression that you're typing in, Guile
-can use the GNU Readline library. This is not enabled by default
-because of licensing reasons, but all you need to activate Readline is
-the following pair of lines.
-
-@lisp
-scheme@@(guile-user)> (use-modules (ice-9 readline))
-scheme@@(guile-user)> (activate-readline)
-@end lisp
-
-It's a good idea to put these two lines (without the ``scheme@@(guile-user)>''
-prompts) in your @file{.guile} file. Guile reads this file when it
-starts up interactively, so anything in this file has the same effect
-as if you type it in by hand at the ``scheme@@(guile-user)>'' prompt.
-
-
-@node Value History
-@subsection Value History
-
-Just as Readline helps you to reuse a previous input line, @dfn{value
-history} allows you to use the @emph{result} of a previous evaluation
-in a new expression. When value history is enabled, each evaluation
-result is automatically assigned to the next in the sequence of
-variables @code{$1}, @code{$2}, @dots{}, and you can then use these
-variables in subsequent expressions.
-
-@lisp
-scheme@@(guile-user)> (iota 10)
-$1 = (0 1 2 3 4 5 6 7 8 9)
-scheme@@(guile-user)> (apply * (cdr $1))
-$2 = 362880
-scheme@@(guile-user)> (sqrt $2)
-$3 = 602.3952191045344
-scheme@@(guile-user)> (cons $2 $1)
-$4 = (362880 0 1 2 3 4 5 6 7 8 9)
-@end lisp
-
-Value history is enabled by default, because Guile's REPL imports the
-@code{(ice-9 history)} module. Value history may be turned off or on within the
-repl, using the options interface:
-
-@lisp
-scheme@@(guile-user)> ,option value-history #f
-scheme@@(guile-user)> 'foo
-foo
-scheme@@(guile-user)> ,option value-history #t
-scheme@@(guile-user)> 'bar
-$5 = bar
-@end lisp
-
-Note that previously recorded values are still accessible, even if value history
-is off. In rare cases, these references to past computations can cause Guile to
-use too much memory. One may clear these values, possibly enabling garbage
-collection, via the @code{clear-value-history!} procedure, described below.
-
-The programmatic interface to value history is in a module:
-
-@lisp
-(use-modules (ice-9 history))
-@end lisp
-
-@deffn {Scheme Procedure} value-history-enabled?
-Return true iff value history is enabled.
-@end deffn
-
-@deffn {Scheme Procedure} enable-value-history!
-Turn on value history, if it was off.
-@end deffn
-
-@deffn {Scheme Procedure} disable-value-history!
-Turn off value history, if it was on.
-@end deffn
-
-@deffn {Scheme Procedure} clear-value-history!
-Clear the value history. If the stored values are not captured by some other
-data structure or closure, they may then be reclaimed by the garbage collector.
-@end deffn
-
-
-@node REPL Commands
-@subsection REPL Commands
-
-@cindex commands
-The REPL exists to read expressions, evaluate them, and then print their
-results. But sometimes one wants to tell the REPL to evaluate an
-expression in a different way, or to do something else altogether. A
-user can affect the way the REPL works with a @dfn{REPL command}.
-
-The previous section had an example of a command, in the form of
-@code{,option}.
-
-@lisp
-scheme@@(guile-user)> ,option value-history #t
-@end lisp
-
-@noindent
-Commands are distinguished from expressions by their initial comma
-(@samp{,}). Since a comma cannot begin an expression in most languages,
-it is an effective indicator to the REPL that the following text forms a
-command, not an expression.
-
-REPL commands are convenient because they are always there. Even if the
-current module doesn't have a binding for @code{pretty-print}, one can
-always @code{,pretty-print}.
-
-The following sections document the various commands, grouped together
-by functionality. Many of the commands have abbreviations; see the
-online help (@code{,help}) for more information.
-
-@menu
-* Help Commands::
-* Module Commands::
-* Language Commands::
-* Compile Commands::
-* Profile Commands::
-* Debug Commands::
-* Inspect Commands::
-* System Commands::
-@end menu
-
-@node Help Commands
-@subsubsection Help Commands
-
-When Guile starts interactively, it notifies the user that help can be
-had by typing @samp{,help}. Indeed, @code{help} is a command, and a
-particularly useful one, as it allows the user to discover the rest of
-the commands.
-
-@deffn {REPL Command} help [@samp{all} | group | @samp{[-c]} command]
-Show help.
-
-With one argument, tries to look up the argument as a group name, giving
-help on that group if successful. Otherwise tries to look up the
-argument as a command, giving help on the command.
-
-If there is a command whose name is also a group name, use the @samp{-c
-@var{command}} form to give help on the command instead of the group.
-
-Without any argument, a list of help commands and command groups
-are displayed.
-@end deffn
-
-@deffn {REPL Command} show [topic]
-Gives information about Guile.
-
-With one argument, tries to show a particular piece of information;
-currently supported topics are `warranty' (or `w'), `copying' (or `c'),
-and `version' (or `v').
-
-Without any argument, a list of topics is displayed.
-@end deffn
-
-@deffn {REPL Command} apropos regexp
-Find bindings/modules/packages.
-@end deffn
-
-@deffn {REPL Command} describe obj
-Show description/documentation.
-@end deffn
-
-@node Module Commands
-@subsubsection Module Commands
-
-@deffn {REPL Command} module [module]
-Change modules / Show current module.
-@end deffn
-
-@deffn {REPL Command} import [module ...]
-Import modules / List those imported.
-@end deffn
-
-@deffn {REPL Command} load file
-Load a file in the current module.
-@end deffn
-
-@deffn {REPL Command} binding
-List current bindings.
-@end deffn
-
-@node Language Commands
-@subsubsection Language Commands
-
-@deffn {REPL Command} language language
-Change languages.
-@end deffn
-
-@node Compile Commands
-@subsubsection Compile Commands
-
-@deffn {REPL Command} compile exp
-Generate compiled code.
-@end deffn
-
-@deffn {REPL Command} compile-file file
-Compile a file.
-@end deffn
-
-@deffn {REPL Command} disassemble exp
-Disassemble a compiled procedure.
-@end deffn
-
-@deffn {REPL Command} disassemble-file file
-Disassemble a file.
-@end deffn
-
-@node Profile Commands
-@subsubsection Profile Commands
-
-@deffn {REPL Command} time exp
-Time execution.
-@end deffn
-
-@deffn {REPL Command} profile exp
-Profile execution.
-@end deffn
-
-@deffn {REPL Command} trace exp
-Trace execution.
-@end deffn
-
-@node Debug Commands
-@subsubsection Debug Commands
-
-These debugging commands are only available within a recursive REPL;
-they do not work at the top level.
-
-@deffn {REPL Command} backtrace [count] [#:width w] [#:full? f]
-Print a backtrace.
-
-Print a backtrace of all stack frames, or innermost @var{COUNT} frames.
-If @var{count} is negative, the last @var{count} frames will be shown.
-@end deffn
-
-@deffn {REPL Command} up [count]
-Select a calling stack frame.
-
-Select and print stack frames that called this one.
-An argument says how many frames up to go.
-@end deffn
-
-@deffn {REPL Command} down [count]
-Select a called stack frame.
-
-Select and print stack frames called by this one.
-An argument says how many frames down to go.
-@end deffn
-
-@deffn {REPL Command} frame [idx]
-Show a frame.
-
-Show the selected frame. With an argument, select a frame by index,
-then show it.
-@end deffn
-
-@deffn {REPL Command} procedure
-Print the procedure for the selected frame.
-@end deffn
-
-@deffn {REPL Command} locals
-Show local variables.
-
-Show locally-bound variables in the selected frame.
-@end deffn
-
-@c FIXME: whenever we regain support for stepping, here are the docs..
-
-@c The commands in this subsection all apply only when the stack is
-@c @dfn{continuable} --- in other words when it makes sense for the program
-@c that the stack comes from to continue running. Usually this means that
-@c the program stopped because of a trap or a breakpoint.
-
-@c @deffn {Debugger Command} step [n]
-@c Tell the debugged program to do @var{n} more steps from its current
-@c position. One @dfn{step} means executing until the next frame entry or
-@c exit of any kind. @var{n} defaults to 1.
-@c @end deffn
-
-@c @deffn {Debugger Command} next [n]
-@c Tell the debugged program to do @var{n} more steps from its current
-@c position, but only counting frame entries and exits where the
-@c corresponding source code comes from the same file as the current stack
-@c frame. (See @ref{Step Traps} for the details of how this works.) If
-@c the current stack frame has no source code, the effect of this command
-@c is the same as of @code{step}. @var{n} defaults to 1.
-@c @end deffn
-
-@c @deffn {Debugger Command} finish
-@c Tell the program being debugged to continue running until the completion
-@c of the current stack frame, and at that time to print the result and
-@c reenter the command line debugger.
-@c @end deffn
-
-@c @deffn {Debugger Command} continue
-@c Tell the program being debugged to continue running. (In fact this is
-@c the same as the @code{quit} command, because it exits the debugger
-@c command loop and so allows whatever code it was that invoked the
-@c debugger to continue.)
-@c @end deffn
-
-@c The @code{evaluate} command is most useful for querying the value of a
-@c variable, either global or local, in the environment of the selected
-@c stack frame, but it can be used more generally to evaluate any
-@c expression.
-
-@c @deffn {Debugger Command} evaluate expression
-@c Evaluate an expression in the environment of the selected stack frame.
-@c The expression must appear on the same line as the command, however it
-@c may be continued over multiple lines.
-@c @end deffn
-
-@node Inspect Commands
-@subsubsection Inspect Commands
-
-@deffn {REPL Command} inspect EXP
-Inspect the result(s) of evaluating @var{exp}.
-@end deffn
-
-@deffn {REPL Command} pretty-print EXP
-Pretty-print the result(s) of evaluating @var{exp}.
-@end deffn
-
-@node System Commands
-@subsubsection System Commands
-
-@deffn {REPL Command} gc
-Garbage collection.
-@end deffn
-
-@deffn {REPL Command} statistics
-Display statistics.
-@end deffn
-
-@deffn {REPL Command} option [key value]
-List/show/set options.
-@end deffn
-
-@deffn {REPL Command} quit
-Quit this session.
-@end deffn
-
-
-@node Error Handling
-@subsection Error Handling
-
-When code being evaluated from the REPL hits an error, Guile enters a
-new prompt, allowing you to inspect the context of the error.
-
-@lisp
-scheme@@(guile-user)> (map string-append '("a" "b") '("c" #\d))
-ERROR: In procedure string-append:
-ERROR: Wrong type (expecting string): #\d
-Entering a new prompt. Type `,bt' for a backtrace or `,q' to continue.
-scheme@@(guile-user) [1]>
-@end lisp
-
-The new prompt runs inside the old one, in the dynamic context of the
-error. It is a recursive REPL, augmented with a reified representation
-of the stack, ready for debugging.
-
-@code{,backtrace} (abbreviated @code{,bt}) displays the Scheme call
-stack at the point where the error occurred:
-
-@lisp
-scheme@@(guile-user) [1]> ,bt
- 1 (map #<procedure string-append _> ("a" "b") ("c" #\d))
- 0 (string-append "b" #\d)
-@end lisp
-
-In the above example, the backtrace doesn't have much source
-information, as @code{map} and @code{string-append} are both
-primitives. But in the general case, the space on the left of the
-backtrace indicates the line and column in which a given procedure calls
-another.
-
-You can exit a recursive REPL in the same way that you exit any REPL:
-via @samp{(quit)}, @samp{,quit} (abbreviated @samp{,q}), or
-@kbd{C-d}, among other options.
-
-
-@node Interactive Debugging
-@subsection Interactive Debugging
-
-A recursive debugging REPL exposes a number of other meta-commands that
-inspect the state of the computation at the time of the error. These
-commands allow you to
-
-@itemize @bullet
-@item
-display the Scheme call stack at the point where the error occurred;
-
-@item
-move up and down the call stack, to see in detail the expression being
-evaluated, or the procedure being applied, in each @dfn{frame}; and
-
-@item
-examine the values of variables and expressions in the context of each
-frame.
-@end itemize
-
-@noindent
-@xref{Debug Commands}, for documentation of the individual
-commands. This section aims to give more of a walkthrough of a typical
-debugging session.
-
-First, we're going to need a good error. Let's try to macroexpand the
-expression @code{(unquote foo)}, outside of a @code{quasiquote} form,
-and see how the macroexpander reports this error.
-
-@lisp
-scheme@@(guile-user)> (macroexpand '(unquote foo))
-ERROR: In procedure macroexpand:
-ERROR: unquote: expression not valid outside of quasiquote in (unquote foo)
-Entering a new prompt. Type `,bt' for a backtrace or `,q' to continue.
-scheme@@(guile-user) [1]>
-@end lisp
-
-The @code{backtrace} command, which can also be invoked as @code{bt},
-displays the call stack (aka backtrace) at the point where the debugger
-was entered:
-
-@lisp
-scheme@@(guile-user) [1]> ,bt
-In ice-9/psyntax.scm:
- 1130:21 3 (chi-top (unquote foo) () ((top)) e (eval) (hygiene #))
- 1071:30 2 (syntax-type (unquote foo) () ((top)) #f #f (# #) #f)
- 1368:28 1 (chi-macro #<procedure de9360 at ice-9/psyntax.scm...> ...)
-In unknown file:
- 0 (scm-error syntax-error macroexpand "~a: ~a in ~a" # #f)
-@end lisp
-
-A call stack consists of a sequence of stack @dfn{frames}, with each
-frame describing one procedure which is waiting to do something with the
-values returned by another. Here we see that there are four frames on
-the stack.
-
-Note that @code{macroexpand} is not on the stack -- it must have made a
-tail call to @code{chi-top}, as indeed we would find if we searched
-@code{ice-9/psyntax.scm} for its definition.
-
-When you enter the debugger, the innermost frame is selected, which
-means that the commands for getting information about the ``current''
-frame, or for evaluating expressions in the context of the current
-frame, will do so by default with respect to the innermost frame. To
-select a different frame, so that these operations will apply to it
-instead, use the @code{up}, @code{down} and @code{frame} commands like
-this:
-
-@lisp
-scheme@@(guile-user) [1]> ,up
-In ice-9/psyntax.scm:
- 1368:28 1 (chi-macro #<procedure de9360 at ice-9/psyntax.scm...> ...)
-scheme@@(guile-user) [1]> ,frame 3
-In ice-9/psyntax.scm:
- 1130:21 3 (chi-top (unquote foo) () ((top)) e (eval) (hygiene #))
-scheme@@(guile-user) [1]> ,down
-In ice-9/psyntax.scm:
- 1071:30 2 (syntax-type (unquote foo) () ((top)) #f #f (# #) #f)
-@end lisp
-
-Perhaps we're interested in what's going on in frame 2, so we take a
-look at its local variables:
-
-@lisp
-scheme@@(guile-user) [1]> ,locals
- Local variables:
- $1 = e = (unquote foo)
- $2 = r = ()
- $3 = w = ((top))
- $4 = s = #f
- $5 = rib = #f
- $6 = mod = (hygiene guile-user)
- $7 = for-car? = #f
- $8 = first = unquote
- $9 = ftype = macro
- $10 = fval = #<procedure de9360 at ice-9/psyntax.scm:2817:2 (x)>
- $11 = fe = unquote
- $12 = fw = ((top))
- $13 = fs = #f
- $14 = fmod = (hygiene guile-user)
-@end lisp
-
-All of the values are accessible by their value-history names
-(@code{$@var{n}}):
-
-@lisp
-scheme@@(guile-user) [1]> $10
-$15 = #<procedure de9360 at ice-9/psyntax.scm:2817:2 (x)>
-@end lisp
-
-We can even invoke the procedure at the REPL directly:
-
-@lisp
-scheme@@(guile-user) [1]> ($10 'not-going-to-work)
-ERROR: In procedure macroexpand:
-ERROR: source expression failed to match any pattern in not-going-to-work
-Entering a new prompt. Type `,bt' for a backtrace or `,q' to continue.
-@end lisp
-
-Well at this point we've caused an error within an error. Let's just
-quit back to the top level:
-
-@lisp
-scheme@@(guile-user) [2]> ,q
-scheme@@(guile-user) [1]> ,q
-scheme@@(guile-user)>
-@end lisp
-
-Finally, as a word to the wise: hackers close their REPL prompts with
-@kbd{C-d}.
-
-
-@node Using Guile in Emacs
-@section Using Guile in Emacs
-
-@cindex GDS
-@cindex Emacs
-There are several options for working on Guile Scheme code in Emacs.
-The simplest are to use Emacs's standard @code{scheme-mode} for
-editing code, and to run the interpreter when you need it by typing
-``guile'' at the prompt of a @code{*shell*} buffer, but there are
-Emacs libraries available which add various bells and whistles to
-this. The following diagram shows these libraries and how they relate
-to each other, with the arrows indicating ``builds on'' or
-``extends''. For example, the Quack library builds on cmuscheme,
-which in turn builds on the standard scheme mode.
-
-@iftex
-@center @image{scheme,5in}
-@end iftex
-@ifnottex
-@example
-@verbatiminclude scheme.txt
-@end example
-@end ifnottex
-
-@dfn{scheme}, written by Bill Rozas and Dave Love, is Emacs's standard
-mode for Scheme code files. It provides Scheme-sensitive syntax
-highlighting, parenthesis matching, indentation and so on.
-
-@dfn{cmuscheme}, written by Olin Shivers, provides a comint-based Scheme
-interaction buffer, so that you can run an interpreter more directly
-than with the @code{*shell*} buffer approach by typing @kbd{M-x
-run-scheme}. It also extends @code{scheme-mode} so that there are key
-presses for sending selected bits of code from a Scheme buffer to this
-interpreter. This means that when you are writing some code and want to
-check what an expression evaluates to, you can easily select that code
-and send it to the interpreter for evaluation, then switch to the
-interpreter to see what the result is. cmuscheme is included in the
-standard Emacs distribution.
-
-@dfn{Quack}, written by Neil Van Dyke, adds a number of incremental
-improvements to the scheme/cmuscheme combination: convenient menu
-entries for looking up Scheme-related references (such as the SRFIs);
-enhanced indentation rules that are customized for particular Scheme
-interpreters, including Guile; an enhanced version of the
-@code{run-scheme} command that knows the names of the common Scheme
-interpreters and remembers which one you used last time; and so on.
-Quack is available from @uref{http://www.neilvandyke.org/quack}.
-
-@dfn{GDS}, written by Neil Jerram, also builds on the scheme/cmuscheme
-combination, but with a change to the way that Scheme code fragments
-are sent to the interpreter for evaluation. cmuscheme and Quack send
-code fragments to the interpreter's standard input, on the assumption
-that the interpreter is expecting to read Scheme expressions there,
-and then monitor the interpreter's standard output to infer what the
-result of the evaluation is. GDS doesn't use standard input and
-output like this. Instead, it sets up a socket connection between the
-Scheme interpreter and Emacs, and sends and receives messages using a
-simple protocol through this socket. The messages include requests to
-evaluate Scheme code, and responses conveying the results of an
-evaluation, thus providing similar function to cmuscheme or Quack.
-They also include requests for stack exploration and debugging, which
-go beyond what cmuscheme or Quack can do. The price of this extra
-power, however, is that GDS is Guile-specific. GDS requires the
-Scheme interpreter to run some GDS-specific library code; currently
-this code is written as a Guile module and uses features that are
-specific to Guile. GDS is now included in the Guile distribution; for
-previous Guile releases (1.8.4 and earlier) it can be obtained as part
-of the @code{guile-debugging} package from
-@uref{http://www.ossau.uklinux.net/guile}.
-
-Finally, @dfn{xscheme} is similar to cmuscheme --- in that it starts up
-a Scheme interaction process and sends commands to that process's
-standard input --- and to GDS --- in that it has support beyond
-cmuscheme or Quack for exploring the Scheme stack when an error has
-occurred --- but is implemented specifically for MIT/GNU Scheme. Hence
-it isn't really relevant to Guile work in Emacs, except as a reference
-for useful features that could be implemented in one of the other
-libraries mentioned here.
-
-In summary, the best current choice for working on Guile code in Emacs
-is either Quack or GDS, depending on which of these libraries' features
-you find most important. For more information on Quack, please see the
-website referenced above. GDS is documented further in the rest of this
-section.
-
-@menu
-* GDS Introduction::
-* GDS Architecture::
-* GDS Getting Started::
-* Working with GDS in Scheme Buffers::
-* Displaying the Scheme Stack::
-* Continuing Execution::
-* Associating Buffers with Clients::
-* An Example GDS Session::
-@end menu
-
-
-@node GDS Introduction
-@subsection GDS Introduction
-
-GDS aims to allow you to work on Guile Scheme code in the same kind of
-way that Emacs allows you to work on Emacs Lisp code: providing easy
-access to help, evaluating arbitrary fragments of code, a nice debugging
-interface, and so on. The thinking behind the GDS library is that you
-will usually be doing one of two things.
-
-@enumerate
-@item
-Writing or editing code. The code will be in a normal Emacs Scheme mode
-buffer, and GDS extends Scheme mode to add keystrokes and menu items for
-the things that are likely to be useful to you when working on code:
-
-@itemize
-@item
-completing the identifier at point, with respect to the set of variable
-names that are known to the associated Guile process
-@item
-accessing Guile's built in ``help'' and ``apropos'' commands
-@item
-evaluating fragments of code to check what they do, with the results
-popping up in a temporary Emacs window.
-@end itemize
-
-@item
-Debugging a Guile Scheme program. When your program hits an error or
-stops at a trap, GDS shows you the relevant code and the Scheme stack,
-and makes it easy to
-
-@itemize
-@item
-look at the values of local variables
-@item
-see what is happening at all levels of the Scheme stack
-@item
-continue execution, either normally or step by step.
-@end itemize
-
-The presentation makes it very easy to move up and down the stack,
-showing whenever possible the source code for each frame in another
-Emacs buffer. It also provides convenient keystrokes for telling Guile
-what to do next; for example, you can select a stack frame and tell
-Guile to run until that frame completes, at which point GDS will display
-the frame's return value.
-@end enumerate
-
-GDS can provide these facilities for any number of Guile Scheme programs
-(which we often refer to as ``clients'') at once, and these programs can
-be started either independently of GDS, including outside Emacs, or
-specifically @emph{by} GDS.
-
-Communication between each Guile client program and GDS uses a TCP
-socket, which means that it is orthogonal to any other interfaces that
-the client program has. In particular GDS does not interfere with a
-program's standard input and output.
-
-
-@node GDS Architecture
-@subsection GDS Architecture
-
-In order to understand the following documentation fully it will help to
-have a picture in mind of how GDS works, so we briefly describe that
-here. GDS consists of three components.
-
-@itemize
-@item
-The GDS @dfn{interface} code is written in Emacs Lisp and runs inside
-Emacs. This code, consisting of the installed files @file{gds.el} and
-@file{gds-server.el}, is responsible for displaying information from
-Guile in Emacs windows, and for responding to Emacs commands and
-keystrokes by sending instructions back to the Guile program being
-worked on.
-
-@item
-The GDS @dfn{server} code is written in Scheme and runs as an Emacs
-inferior process. It acts as a multiplexer between the (possibly
-multiple) Guile programs being debugged and the interface code running
-in Emacs. The server code is the installed file
-@file{gds-server.scm}.
-
-@item
-The GDS @dfn{client} code is written in Scheme (installed file
-@file{gds-client.scm}), and must be loaded as a module by each Guile
-program that wants to use GDS in any way.
-@end itemize
-
-@noindent
-The following diagram shows how these components are connected to each
-other.
-
-@iftex
-@center @image{gds,5in}
-@end iftex
-@ifnottex
-@example
-@verbatiminclude gds.txt
-@end example
-@end ifnottex
-
-@cindex TCP, use of
-The data exchanged between client and server components, and between
-server and interface, is a sequence of sexps (parenthesised expressions)
-that are designed so as to be directly readable by both Scheme and Emacs
-Lisp. The use of a TCP connection means that the server and Emacs
-interface can theoretically be on a different computer from the client
-programs, but in practice there are currently two problems with
-this. Firstly the GDS API doesn't provide any way of specifying a
-non-local server to connect to, and secondly there is no security or
-authentication mechanism in the GDS protocol. These are issues that
-should be addressed in the future.
-
-
-@node GDS Getting Started
-@subsection Getting Started with GDS
-
-To enable the use of GDS in your own Emacs sessions, simply add
-
-@lisp
-(require 'gds)
-@end lisp
-
-@noindent
-somewhere in your @file{.emacs} file. This will cause Emacs to load the
-GDS Emacs Lisp code when starting up, and to start the inferior GDS
-server process so that it is ready and waiting for any Guile programs
-that want to use GDS.
-
-(If GDS's Scheme code is not installed in one of the locations in
-Guile's load path, you may find that the server process fails to start.
-When this happens you will see an error message from Emacs:
-
-@lisp
-error in process filter: Wrong type argument: listp, Backtrace:
-@end lisp
-
-@noindent
-and the @code{gds-debug} buffer will contain a Scheme backtrace ending
-with the message:
-
-@lisp
-no code for module (ice-9 gds-server)
-@end lisp
-
-@noindent
-The solution for this is to customize the Emacs variable
-@code{gds-scheme-directory} so that it specifies where the GDS Scheme
-code is installed. Then either restart Emacs or type @kbd{M-x
-gds-run-debug-server} to try starting the GDS server process again.)
-
-For evaluations, help and completion from Scheme code buffers that you
-are working on, this is all you need. The first time you do any of
-these things, GDS will automatically start a new Guile client program as
-an Emacs subprocess. This Guile program does nothing but wait for and
-act on instructions from GDS, and we refer to it as a @dfn{utility}
-Guile client. Over time this utility client will accumulate the code
-that you ask it to evaluate, and you can also tell it to load complete
-files or modules by sending it @code{load} or @code{use-modules}
-expressions.
-
-When you want to use GDS to work on an independent Guile
-application, you need to add something to that application's Scheme code
-to cause it to connect to and interact with GDS at the right times. The
-following subsections describe the ways of doing this.
-
-@subsubsection Invoking GDS when an Exception Occurs
-
-One option is to use GDS to catch and display any exceptions that
-are thrown by the application's code. If you already have a
-@code{lazy-catch} or @code{with-throw-handler} around the area of code
-that you want to monitor, you just need to add the following to the
-handler code:
-
-@lisp
-(gds-debug-trap (throw->trap-context key args))
-@end lisp
-
-@noindent
-where @code{key} and @code{args} are the first and rest arguments that
-Guile passes to the handler. (In other words, they assume the handler
-signature @code{(lambda (key . args) @dots{})}.) With Guile 1.8 or
-later, you can also do this with a @code{catch}, by adding this same
-code to the catch's pre-unwind handler.
-
-If you don't already have any of these, insert a whole
-@code{with-throw-handler} expression (or @code{lazy-catch} if your Guile
-is pre-1.8) around the code of interest like this:
-
-@lisp
-(with-throw-handler #t
- (lambda ()
- ;; Protected code here.
- )
- (lambda (key . args)
- (gds-debug-trap (throw->trap-context key args))))
-@end lisp
-
-Either way, you will need to use the @code{(ice-9 gds-client)} and
-@code{(ice-9 debugging traps)} modules.
-
-Two special cases of this are the lazy-catch that the Guile REPL code
-uses to catch exceptions in user code, and the lazy-catch inside the
-@code{stack-catch} utility procedure that is provided by the
-@code{(ice-9 stack-catch)} module. Both of these use a handler called
-@code{lazy-handler-dispatch} (defined in @file{boot-9.scm}), which you
-can hook into such that it calls GDS to display the stack when an
-exception occurs. To do this, use the @code{on-lazy-handler-dispatch}
-procedure as follows.
-
-@lisp
-(use-modules (ice-9 gds-client)
- (ice-9 debugging traps))
-(on-lazy-handler-dispatch gds-debug-trap)
-@end lisp
-
-@noindent
-After this the program will use GDS to display the stack whenever it
-hits an exception that is protected by a @code{lazy-catch} using
-@code{lazy-handler-dispatch}.
-
-@subsubsection Accepting GDS Instructions at Any Time
-
-In addition to setting an exception handler as described above, a
-Guile program can in principle set itself up to accept new
-instructions from GDS at any time, not just when it has stopped at an
-exception. This would allow the GDS user to evaluate code in the
-context of the running program, without having to wait for the program
-to stop first.
-
-@lisp
-(use-modules (ice-9 gds-client))
-(gds-accept-input #t)
-@end lisp
-
-@code{gds-accept-input} causes the calling program to loop processing
-instructions from GDS, until GDS sends the @code{continue} instruction.
-This blocks the thread that calls it, however, so it will normally be
-more practical for the program to set up a dedicated GDS thread and call
-@code{gds-accept-input} from that thread.
-
-For @code{select}-driven applications, an alternative approach would be
-for the GDS client code to provide an API which allowed the application
-to
-
-@itemize
-@item
-discover the file descriptors (or Scheme ports) that are used for
-receiving instruction from the GDS front end, so that it could include
-these in its @code{select} call
-
-@item
-call the GDS instruction handler when @code{select} indicated data
-available for reading on those descriptors/ports.
-@end itemize
-
-@noindent
-This approach is not yet implemented, though.
-
-@subsubsection Utility Guile Implementation
-
-The ``utility'' Guile client mentioned above is a simple combination
-of the mechanisms that we have just described. In fact the code for
-the utility Guile client is essentially just this:
-
-@lisp
-(use-modules (ice-9 gds-client))
-(named-module-use! '(guile-user) '(ice-9 session))
-(gds-accept-input #f))
-@end lisp
-
-The @code{named-module-use!} line ensures that the client can process
-@code{help} and @code{apropos} expressions, to implement lookups in
-Guile's online help. The @code{#f} parameter to
-@code{gds-accept-input} means that the @code{continue} instruction
-will not cause the instruction loop to exit, which makes sense here
-because the utility client has nothing to do except to process GDS
-instructions.
-
-The utility client does not use @code{on-lazy-handler-dispatch} at its
-top level, because it has its own mechanism for catching and reporting
-exceptions in the code that it is asked to evaluate. This mechanism
-summarizes the exception and gives the user a button they can click to
-see the full stack, so the end result is very similar to what
-@code{on-lazy-handler-dispatch} provides. Deep inside
-@code{gds-accept-input}, in the part that handles evaluating
-expressions from Emacs, the GDS client code uses
-@code{throw->trap-context} and @code{gds-debug-trap} to implement
-this.
-
-
-@node Working with GDS in Scheme Buffers
-@subsection Working with GDS in Scheme Buffers
-
-The following subsections describe the facilities and key sequences that
-GDS provides for working on code in @code{scheme-mode} buffers.
-
-@menu
-* Access to Guile Help and Completion::
-* Evaluating Scheme Code::
-@end menu
-
-
-@node Access to Guile Help and Completion
-@subsubsection Access to Guile Help and Completion
-
-The following keystrokes provide fast and convenient access to Guile's
-built in help, and to completion with respect to the set of defined and
-accessible symbols.
-
-@table @kbd
-@item C-h g
-@findex gds-help-symbol
-Get Guile help for a particular symbol, with the same results as if
-you had typed @code{(help SYMBOL)} into the Guile REPL
-(@code{gds-help-symbol}). The symbol to query defaults to the word at
-or before the cursor but can also be entered or edited in the
-minibuffer. The available help is popped up in a temporary Emacs
-window.
-
-@item C-h G
-@findex gds-apropos
-List all accessible Guile symbols matching a given regular expression,
-with the same results as if you had typed @code{(apropos REGEXP)} into
-the Guile REPL (@code{gds-apropos}). The regexp to query defaults to
-the word at or before the cursor but can also be entered or edited in
-the minibuffer. The list of matching symbols is popped up in a
-temporary Emacs window.
-
-@item M-@key{TAB}
-@findex gds-complete-symbol
-Try to complete the symbol at the cursor by matching it against the
-set of all defined and accessible bindings in the associated Guile
-process (@code{gds-complete-symbol}). If there are any extra
-characters that can be definitively added to the symbol at point, they
-are inserted. Otherwise, if there are any completions available, they
-are popped up in a temporary Emacs window, where one of them can be
-selected using either @kbd{@key{RET}} or the mouse.
-@end table
-
-
-@node Evaluating Scheme Code
-@subsubsection Evaluating Scheme Code
-
-The following keystrokes and commands provide various ways of sending
-code to a Guile client process for evaluation.
-
-@table @kbd
-@item M-C-x
-@findex gds-eval-defun
-Evaluate the ``top level defun'' that the cursor is in, in other words
-the smallest balanced expression which includes the cursor and whose
-opening parenthesis is in column 0 (@code{gds-eval-defun}).
-
-@item C-x C-e
-@findex gds-eval-last-sexp
-Evaluate the expression that ends just before the cursor
-(@code{gds-eval-last-sexp}). This is designed so that it is easy to
-evaluate an expression that you have just finished typing.
-
-@item C-c C-e
-@findex gds-eval-expression
-Read a Scheme expression using the minibuffer, and evaluate that
-expression (@code{gds-eval-expression}).
-
-@item C-c C-r
-@findex gds-eval-region
-Evaluate the Scheme code in the marked region of the current buffer
-(@code{gds-eval-region}). Note that GDS does not check whether the
-region contains a balanced expression, or try to expand the region so
-that it does; it uses the region exactly as it is.
-@end table
-
-If you type @kbd{C-u} before one of these commands, GDS will
-immediately pop up a Scheme stack buffer, showing the requested
-evaluation, so that you can single step through it. (This is achieved
-by setting a @code{<source-trap>} trap at the start of the requested
-evaluation; see @ref{Source Traps} for more on how those work.) The
-Scheme stack display, and the options for continuing through the code,
-are described in the next two sections.
-
-
-@node Displaying the Scheme Stack
-@subsection Displaying the Scheme Stack
-
-When you specify @code{gds-debug-trap} as the behaviour for a trap and
-the Guile program concerned hits that trap, GDS displays the stack and
-the relevant Scheme source code in Emacs, allowing you to explore the
-state of the program and then decide what to do next. The same
-applies if the program calls @code{(on-lazy-handler-dispatch
-gds-debug-trap)} and then throws an exception that passes through
-@code{lazy-handler-dispatch}, except that in this case you can only
-explore; it isn't possible to continue normal execution after an
-exception.
-
-The following commands are available in the stack buffer for exploring
-the state of the program.
-
-@table @asis
-@item @kbd{u}, @kbd{C-p}, @kbd{@key{up}}
-@findex gds-up
-Select the stack frame one up from the currently selected frame
-(@code{gds-up}). GDS displays stack frames with the innermost at the
-top, so moving ``up'' means selecting a more ``inner'' frame.
-
-@item @kbd{d}, @kbd{C-n}, @kbd{@key{down}}
-@findex gds-down
-Select the stack frame one down from the currently selected frame
-(@code{gds-down}). GDS displays stack frames with the innermost at the
-top, so moving ``down'' means selecting a more ``outer'' frame.
-
-@item @kbd{@key{RET}}
-@findex gds-select-stack-frame
-Select the stack frame at point (@code{gds-select-stack-frame}). This
-is useful after clicking somewhere in the stack trace with the mouse.
-@end table
-
-Selecting a frame means that GDS will display the source code
-corresponding to that frame in the adjacent window, and that
-subsequent frame-sensitive commands, such as @code{gds-evaluate} (see
-below) and @code{gds-step-over} (@pxref{Continuing Execution}), will
-refer to that frame.
-
-@table @kbd
-@item e
-@findex gds-evaluate
-Evaluate a variable or expression in the local environment of the
-selected stack frame (@code{gds-evaluate}). The result is displayed in
-the echo area.
-
-@item I
-@findex gds-frame-info
-Show summary information about the selected stack frame
-(@code{gds-frame-info}). This includes what type of frame it is, the
-associated expression, and the frame's source location, if any.
-
-@item A
-@findex gds-frame-args
-For an application frame, display the frame's arguments
-(@code{gds-frame-args}).
-
-@item S
-@findex gds-proc-source
-For an application frame, show the Scheme source code of the procedure
-being called (@code{gds-proc-source}). The source code (where
-available) is displayed in the echo area.
-@end table
-
-@kbd{S} (@code{gds-proc-source}) is useful when the procedure being
-called was created by an anonymous @code{(lambda @dots{})} expression.
-Such procedures appear in the stack trace as @code{<procedure #f
-(@dots{})>}, which doesn't give you much clue as to what will happen
-next. @kbd{S} will show you the procedure's code, which is usually
-enough for you to identify it.
-
-
-@node Continuing Execution
-@subsection Continuing Execution
-
-If it makes sense to continue execution from the stack which is being
-displayed, GDS provides the following further commands in the stack
-buffer.
-
-@table @asis
-@item @kbd{g}, @kbd{c}, @kbd{q}
-@findex gds-go
-Tell the program to continue running (@code{gds-go}). It may of course
-stop again if it hits another trap, or another occurrence of the same
-trap.
-
-The multiple keystrokes reflect that you can think of this as ``going'',
-``continuing'' or ``quitting'' (in the sense of quitting the GDS
-display).
-
-@item @kbd{@key{SPC}}
-@findex gds-step-file
-Tell the program to do a single-step to the next entry or exit of a
-frame whose code comes from the same source file as the selected stack
-frame (@code{gds-step-file}).
-
-In other words, you can hit @kbd{@key{SPC}} repeatedly to step through
-the code in a given file, automatically stepping @emph{over} any
-evaluations or procedure calls that use code from other files (or from
-no file).
-
-If the selected stack frame has no source, the effect of this command is
-the same as that of @kbd{i}, described next.
-
-@item @kbd{i}
-@findex gds-step-into
-Tell the debugged program to do a single-step to the next frame entry or
-exit of any kind (@code{gds-step-into}). @kbd{i} therefore steps
-through code at the most detailed level possible.
-
-@item @kbd{o}
-@findex gds-step-over
-Tell the debugged program to continue running until the selected stack
-frame completes, and then to display its result (@code{gds-step-over}).
-Note that the program may stop before then if it hits another trap; in
-this case the trap telling it to stop when the marked frame completes
-remains in place and so will still fire at the appropriate point.
-@end table
-
-
-@node Associating Buffers with Clients
-@subsection Associating Buffers with Clients
-
-The first time that you use one of GDS's evaluation, help or completion
-commands from a given Scheme mode buffer, GDS will ask which Guile
-client program you want to use for the operation, or if you want to
-start up a new ``utility'' client. After that GDS considers the buffer
-to be ``associated'' with the selected client, and so sends all further
-requests to that client, but you can override this by explicitly
-associating the buffer with a different client, or by removing the
-default association.
-
-@table @kbd
-@item M-x gds-associate-buffer
-Associate (or re-associate) the current buffer with a particular Guile
-client program. The available clients are listed, and you can also
-choose to start up a new ``utility'' client for this buffer to associate
-with.
-
-@item M-x gds-dissociate-buffer
-Dissociate the current buffer from its client, if any. This means that
-the next time you use an evaluation, help or completion command, GDS
-will ask you again which client to send the request to.
-@end table
-
-When a buffer is associated with a client program, the buffer's modeline
-shows whether the client is currently able to accept instruction from
-GDS. This is done by adding one of the following suffixes to the
-``Scheme'' major mode indicator:
-
-@table @asis
-@item :ready
-The client program (or one of its threads, if multithreaded) is
-currently ready to accept instruction from GDS. In other words, if you
-send it a help or evaluation request, you should see the result pretty
-much immediately.
-
-@item :running
-The client program is not currently able to accept instruction from
-GDS. This means that it (or all of its threads, if multithreaded) is
-busy, or waiting for input other than from GDS.
-
-@item :debug
-The client program (or one of its threads, if multithreaded) is stopped
-in ``debugging mode'' with GDS displaying the stack for a trap or
-exception. It is waiting for instruction from GDS on what to do next.
-@end table
-
-
-@node An Example GDS Session
-@subsection An Example GDS Session
-
-Create a file, @file{testgds.scm} say, for experimenting with GDS and
-Scheme code, and type this into it:
-
-@lisp
-(use-modules (ice-9 debugging traps)
- (ice-9 gds-client)
- (ice-9 debugging example-fns))
-(install-trap (make <procedure-trap>
- #:behaviour gds-debug-trap
- #:procedure fact1))
-@end lisp
-
-@noindent
-Now select all of this code and type @kbd{C-c C-r} to send the selected
-region to Guile for evaluation. GDS will ask you which Guile process to
-use; unless you know that you already have another Guile application
-running and connected to GDS, choose the ``Start a new Guile'' option,
-which starts one of the ``utility'' processes described in @ref{GDS
-Getting Started}.
-
-The results of the evaluation pop up in a window like this:
-
-@lisp
-(use-modules (ice-9 debugging traps)\n @dots{}
-
-;;; Evaluating subexpression 1 in current module (guile-user)
- @result{} no (or unspecified) value
-
-;;; Evaluating subexpression 2 in current module (guile-user)
- @result{} no (or unspecified) value
-
---:** *Guile Evaluation* (Scheme:ready)--All------------
-@end lisp
-
-@noindent
-this tells you that the evaluation was successful but that the return
-values were unspecified. Its effect was to load a module of example
-functions and set a trap on one of these functions, @code{fact1}, that
-calculates the factorial of its argument.
-
-If you now call @code{fact1}, you can see the trap and GDS's stack
-display in action. To do this add
-
-@lisp
-(fact1 4)
-@end lisp
-
-@noindent
-to your @file{testgds.scm} buffer and type @kbd{C-x C-e} (which
-evaluates the expression that the cursor is just after the end of).
-The result should be that a GDS stack window like the following
-appears:
-
-@lisp
-Calling procedure:
-=> s [fact1 4]
- s [primitive-eval (fact1 4)]
-
-
---:** PID 28729 (Guile-Debug)--All------------
-@end lisp
-
-This stack tells you that Guile is about to call the @code{fact1}
-procedure, with argument 4, and you can step through this call in
-detail by pressing @kbd{i} once and then @kbd{@key{SPC}}
-(@pxref{Continuing Execution}).
-
-(@kbd{i} is needed as the first keystroke rather than @kbd{@key{SPC}},
-because the aim here is to step through code in the @code{(ice-9
-debugging example-fns)} module, whose source file is
-@file{@dots{}/ice-9/debugging/example-fns.scm}, but the initial
-@code{(fact1 4)} call comes from the Guile session, whose ``source
-file'' Guile presents as @file{standard input}. If the user starts by
-pressing @kbd{@key{SPC}} instead of @kbd{i}, the effect is that the
-program runs until it hits the first recursive call @code{(fact1 (- n
-1))}, where it stops because of the trap on @code{fact1} firing again.
-At this point, the source file @emph{is}
-@file{@dots{}/ice-9/debugging/example-fns.scm}, because the recursive
-@code{(fact1 (- n 1))} call comes from code in that file, so further
-pressing of @kbd{@key{SPC}} successfully single-steps through this
-file.)
-
-
-@c Local Variables:
-@c TeX-master: "guile.texi"
-@c End:
+@c -*-texinfo-*-
+@c This is part of the GNU Guile Reference Manual.
+@c Copyright (C) 2006, 2010, 2011, 2012, 2013
+@c Free Software Foundation, Inc.
+@c See the file guile.texi for copying conditions.
+
+@node Using Guile Interactively
+@section Using Guile Interactively
+
+When you start up Guile by typing just @code{guile}, without a
+@code{-c} argument or the name of a script to execute, you get an
+interactive interpreter where you can enter Scheme expressions, and
+Guile will evaluate them and print the results for you. Here are some
+simple examples.
+
+@lisp
+scheme@@(guile-user)> (+ 3 4 5)
+$1 = 12
+scheme@@(guile-user)> (display "Hello world!\n")
+Hello world!
+scheme@@(guile-user)> (values 'a 'b)
+$2 = a
+$3 = b
+@end lisp
+
+@noindent
+This mode of use is called a @dfn{REPL}, which is short for
+``Read-Eval-Print Loop'', because the Guile interpreter first reads the
+expression that you have typed, then evaluates it, and then prints the
+result.
+
+The prompt shows you what language and module you are in. In this case, the
+current language is @code{scheme}, and the current module is
+@code{(guile-user)}. @xref{Other Languages}, for more information on Guile's
+support for languages other than Scheme.
+
+@menu
+* Init File::
+* Readline::
+* Value History::
+* REPL Commands::
+* Error Handling::
+* Interactive Debugging::
+@end menu
+
+
+@node Init File
+@subsection The Init File, @file{~/.guile}
+
+@cindex .guile
+When run interactively, Guile will load a local initialization file from
+@file{~/.guile}. This file should contain Scheme expressions for
+evaluation.
+
+This facility lets the user customize their interactive Guile
+environment, pulling in extra modules or parameterizing the REPL
+implementation.
+
+To run Guile without loading the init file, use the @code{-q}
+command-line option.
+
+
+@node Readline
+@subsection Readline
+
+To make it easier for you to repeat and vary previously entered
+expressions, or to edit the expression that you're typing in, Guile
+can use the GNU Readline library. This is not enabled by default
+because of licensing reasons, but all you need to activate Readline is
+the following pair of lines.
+
+@lisp
+scheme@@(guile-user)> (use-modules (ice-9 readline))
+scheme@@(guile-user)> (activate-readline)
+@end lisp
+
+It's a good idea to put these two lines (without the
+@code{scheme@@(guile-user)>} prompts) in your @file{.guile} file.
+@xref{Init File}, for more on @file{.guile}.
+
+
+@node Value History
+@subsection Value History
+
+Just as Readline helps you to reuse a previous input line, @dfn{value
+history} allows you to use the @emph{result} of a previous evaluation in
+a new expression. When value history is enabled, each evaluation result
+is automatically assigned to the next in the sequence of variables
+@code{$1}, @code{$2}, @dots{}. You can then use these variables in
+subsequent expressions.
+
+@lisp
+scheme@@(guile-user)> (iota 10)
+$1 = (0 1 2 3 4 5 6 7 8 9)
+scheme@@(guile-user)> (apply * (cdr $1))
+$2 = 362880
+scheme@@(guile-user)> (sqrt $2)
+$3 = 602.3952191045344
+scheme@@(guile-user)> (cons $2 $1)
+$4 = (362880 0 1 2 3 4 5 6 7 8 9)
+@end lisp
+
+Value history is enabled by default, because Guile's REPL imports the
+@code{(ice-9 history)} module. Value history may be turned off or on within the
+repl, using the options interface:
+
+@lisp
+scheme@@(guile-user)> ,option value-history #f
+scheme@@(guile-user)> 'foo
+foo
+scheme@@(guile-user)> ,option value-history #t
+scheme@@(guile-user)> 'bar
+$5 = bar
+@end lisp
+
+Note that previously recorded values are still accessible, even if value history
+is off. In rare cases, these references to past computations can cause Guile to
+use too much memory. One may clear these values, possibly enabling garbage
+collection, via the @code{clear-value-history!} procedure, described below.
+
+The programmatic interface to value history is in a module:
+
+@lisp
+(use-modules (ice-9 history))
+@end lisp
+
+@deffn {Scheme Procedure} value-history-enabled?
+Return true if value history is enabled, or false otherwise.
+@end deffn
+
+@deffn {Scheme Procedure} enable-value-history!
+Turn on value history, if it was off.
+@end deffn
+
+@deffn {Scheme Procedure} disable-value-history!
+Turn off value history, if it was on.
+@end deffn
+
+@deffn {Scheme Procedure} clear-value-history!
+Clear the value history. If the stored values are not captured by some other
+data structure or closure, they may then be reclaimed by the garbage collector.
+@end deffn
+
+
+@node REPL Commands
+@subsection REPL Commands
+
+@cindex commands
+The REPL exists to read expressions, evaluate them, and then print their
+results. But sometimes one wants to tell the REPL to evaluate an
+expression in a different way, or to do something else altogether. A
+user can affect the way the REPL works with a @dfn{REPL command}.
+
+The previous section had an example of a command, in the form of
+@code{,option}.
+
+@lisp
+scheme@@(guile-user)> ,option value-history #t
+@end lisp
+
+@noindent
+Commands are distinguished from expressions by their initial comma
+(@samp{,}). Since a comma cannot begin an expression in most languages,
+it is an effective indicator to the REPL that the following text forms a
+command, not an expression.
+
+REPL commands are convenient because they are always there. Even if the
+current module doesn't have a binding for @code{pretty-print}, one can
+always @code{,pretty-print}.
+
+The following sections document the various commands, grouped together
+by functionality. Many of the commands have abbreviations; see the
+online help (@code{,help}) for more information.
+
+@menu
+* Help Commands::
+* Module Commands::
+* Language Commands::
+* Compile Commands::
+* Profile Commands::
+* Debug Commands::
+* Inspect Commands::
+* System Commands::
+@end menu
+
+@node Help Commands
+@subsubsection Help Commands
+
+When Guile starts interactively, it notifies the user that help can be
+had by typing @samp{,help}. Indeed, @code{help} is a command, and a
+particularly useful one, as it allows the user to discover the rest of
+the commands.
+
+@deffn {REPL Command} help [@code{all} | group | @code{[-c]} command]
+Show help.
+
+With one argument, tries to look up the argument as a group name, giving
+help on that group if successful. Otherwise tries to look up the
+argument as a command, giving help on the command.
+
+If there is a command whose name is also a group name, use the @samp{-c
+@var{command}} form to give help on the command instead of the group.
+
+Without any argument, a list of help commands and command groups
+are displayed.
+@end deffn
+
+@deffn {REPL Command} show [topic]
+Gives information about Guile.
+
+With one argument, tries to show a particular piece of information;
+currently supported topics are `warranty' (or `w'), `copying' (or `c'),
+and `version' (or `v').
+
+Without any argument, a list of topics is displayed.
+@end deffn
+
+@deffn {REPL Command} apropos regexp
+Find bindings/modules/packages.
+@end deffn
+
+@deffn {REPL Command} describe obj
+Show description/documentation.
+@end deffn
+
+@node Module Commands
+@subsubsection Module Commands
+
+@deffn {REPL Command} module [module]
+Change modules / Show current module.
+@end deffn
+
+@deffn {REPL Command} import module @dots{}
+Import modules / List those imported.
+@end deffn
+
+@deffn {REPL Command} load file
+Load a file in the current module.
+@end deffn
+
+@deffn {REPL Command} reload [module]
+Reload the given module, or the current module if none was given.
+@end deffn
+
+@deffn {REPL Command} binding
+List current bindings.
+@end deffn
+
+@deffn {REPL Command} in module expression
+@deffnx {REPL Command} in module command arg @dots{}
+Evaluate an expression, or alternatively, execute another meta-command
+in the context of a module. For example, @samp{,in (foo bar) ,binding}
+will show the bindings in the module @code{(foo bar)}.
+@end deffn
+
+@node Language Commands
+@subsubsection Language Commands
+
+@deffn {REPL Command} language language
+Change languages.
+@end deffn
+
+@node Compile Commands
+@subsubsection Compile Commands
+
+@deffn {REPL Command} compile exp
+Generate compiled code.
+@end deffn
+
+@deffn {REPL Command} compile-file file
+Compile a file.
+@end deffn
+
+@deffn {REPL Command} expand exp
+Expand any macros in a form.
+@end deffn
+
+@deffn {REPL Command} optimize exp
+Run the optimizer on a piece of code and print the result.
+@end deffn
+
+@deffn {REPL Command} disassemble exp
+Disassemble a compiled procedure.
+@end deffn
+
+@deffn {REPL Command} disassemble-file file
+Disassemble a file.
+@end deffn
+
+@node Profile Commands
+@subsubsection Profile Commands
+
+@deffn {REPL Command} time exp
+Time execution.
+@end deffn
+
+@deffn {REPL Command} profile exp
+Profile execution.
+@end deffn
+
+@deffn {REPL Command} trace exp [#:width w] [#:max-indent i]
+Trace execution.
+
+By default, the trace will limit its width to the width of your
+terminal, or @var{width} if specified. Nested procedure invocations
+will be printed farther to the right, though if the width of the
+indentation passes the @var{max-indent}, the indentation is abbreviated.
+@end deffn
+
+@node Debug Commands
+@subsubsection Debug Commands
+
+These debugging commands are only available within a recursive REPL;
+they do not work at the top level.
+
+@deffn {REPL Command} backtrace [count] [#:width w] [#:full? f]
+Print a backtrace.
+
+Print a backtrace of all stack frames, or innermost @var{count} frames.
+If @var{count} is negative, the last @var{count} frames will be shown.
+@end deffn
+
+@deffn {REPL Command} up [count]
+Select a calling stack frame.
+
+Select and print stack frames that called this one.
+An argument says how many frames up to go.
+@end deffn
+
+@deffn {REPL Command} down [count]
+Select a called stack frame.
+
+Select and print stack frames called by this one.
+An argument says how many frames down to go.
+@end deffn
+
+@deffn {REPL Command} frame [idx]
+Show a frame.
+
+Show the selected frame. With an argument, select a frame by index,
+then show it.
+@end deffn
+
+@deffn {REPL Command} procedure
+Print the procedure for the selected frame.
+@end deffn
+
+@deffn {REPL Command} locals
+Show local variables.
+
+Show locally-bound variables in the selected frame.
+@end deffn
+
+@deffn {REPL Command} error-message
+@deffnx {REPL Command} error
+Show error message.
+
+Display the message associated with the error that started the current
+debugging REPL.
+@end deffn
+
+@deffn {REPL Command} registers
+Show the VM registers associated with the current frame.
+
+@xref{Stack Layout}, for more information on VM stack frames.
+@end deffn
+
+@deffn {REPL Command} width [cols]
+Sets the number of display columns in the output of @code{,backtrace}
+and @code{,locals} to @var{cols}. If @var{cols} is not given, the width
+of the terminal is used.
+@end deffn
+
+The next 3 commands work at any REPL.
+
+@deffn {REPL Command} break proc
+Set a breakpoint at @var{proc}.
+@end deffn
+
+@deffn {REPL Command} break-at-source file line
+Set a breakpoint at the given source location.
+@end deffn
+
+@deffn {REPL Command} tracepoint proc
+Set a tracepoint on the given procedure. This will cause all calls to
+the procedure to print out a tracing message. @xref{Tracing Traps}, for
+more information.
+@end deffn
+
+The rest of the commands in this subsection all apply only when the
+stack is @dfn{continuable} --- in other words when it makes sense for
+the program that the stack comes from to continue running. Usually this
+means that the program stopped because of a trap or a breakpoint.
+
+@deffn {REPL Command} step
+Tell the debugged program to step to the next source location.
+@end deffn
+
+@deffn {REPL Command} next
+Tell the debugged program to step to the next source location in the
+same frame. (See @ref{Traps} for the details of how this works.)
+@end deffn
+
+@deffn {REPL Command} finish
+Tell the program being debugged to continue running until the completion
+of the current stack frame, and at that time to print the result and
+reenter the REPL.
+@end deffn
+
+
+@node Inspect Commands
+@subsubsection Inspect Commands
+
+@deffn {REPL Command} inspect exp
+Inspect the result(s) of evaluating @var{exp}.
+@end deffn
+
+@deffn {REPL Command} pretty-print exp
+Pretty-print the result(s) of evaluating @var{exp}.
+@end deffn
+
+@node System Commands
+@subsubsection System Commands
+
+@deffn {REPL Command} gc
+Garbage collection.
+@end deffn
+
+@deffn {REPL Command} statistics
+Display statistics.
+@end deffn
+
+@deffn {REPL Command} option [name] [exp]
+With no arguments, lists all options. With one argument, shows the
+current value of the @var{name} option. With two arguments, sets the
+@var{name} option to the result of evaluating the Scheme expression
+@var{exp}.
+@end deffn
+
+@deffn {REPL Command} quit
+Quit this session.
+@end deffn
+
+Current REPL options include:
+
+@table @code
+@item compile-options
+The options used when compiling expressions entered at the REPL.
+@xref{Compilation}, for more on compilation options.
+@item interp
+Whether to interpret or compile expressions given at the REPL, if such a
+choice is available. Off by default (indicating compilation).
+@item prompt
+A customized REPL prompt. @code{#f} by default, indicating the default
+prompt.
+@item print
+A procedure of two arguments used to print the result of evaluating each
+expression. The arguments are the current REPL and the value to print.
+By default, @code{#f}, to use the default procedure.
+@item value-history
+Whether value history is on or not. @xref{Value History}.
+@item on-error
+What to do when an error happens. By default, @code{debug}, meaning to
+enter the debugger. Other values include @code{backtrace}, to show a
+backtrace without entering the debugger, or @code{report}, to simply
+show a short error printout.
+@end table
+
+Default values for REPL options may be set using
+@code{repl-default-option-set!} from @code{(system repl common)}:
+
+@deffn {Scheme Procedure} repl-default-option-set! key value
+Set the default value of a REPL option. This function is particularly
+useful in a user's init file. @xref{Init File}.
+@end deffn
+
+
+@node Error Handling
+@subsection Error Handling
+
+When code being evaluated from the REPL hits an error, Guile enters a
+new prompt, allowing you to inspect the context of the error.
+
+@lisp
+scheme@@(guile-user)> (map string-append '("a" "b") '("c" #\d))
+ERROR: In procedure string-append:
+ERROR: Wrong type (expecting string): #\d
+Entering a new prompt. Type `,bt' for a backtrace or `,q' to continue.
+scheme@@(guile-user) [1]>
+@end lisp
+
+The new prompt runs inside the old one, in the dynamic context of the
+error. It is a recursive REPL, augmented with a reified representation
+of the stack, ready for debugging.
+
+@code{,backtrace} (abbreviated @code{,bt}) displays the Scheme call
+stack at the point where the error occurred:
+
+@lisp
+scheme@@(guile-user) [1]> ,bt
+ 1 (map #<procedure string-append _> ("a" "b") ("c" #\d))
+ 0 (string-append "b" #\d)
+@end lisp
+
+In the above example, the backtrace doesn't have much source
+information, as @code{map} and @code{string-append} are both
+primitives. But in the general case, the space on the left of the
+backtrace indicates the line and column in which a given procedure calls
+another.
+
+You can exit a recursive REPL in the same way that you exit any REPL:
+via @samp{(quit)}, @samp{,quit} (abbreviated @samp{,q}), or
+@kbd{C-d}, among other options.
+
+
+@node Interactive Debugging
+@subsection Interactive Debugging
+
+A recursive debugging REPL exposes a number of other meta-commands that
+inspect the state of the computation at the time of the error. These
+commands allow you to
+
+@itemize @bullet
+@item
+display the Scheme call stack at the point where the error occurred;
+
+@item
+move up and down the call stack, to see in detail the expression being
+evaluated, or the procedure being applied, in each @dfn{frame}; and
+
+@item
+examine the values of variables and expressions in the context of each
+frame.
+@end itemize
+
+@noindent
+@xref{Debug Commands}, for documentation of the individual
+commands. This section aims to give more of a walkthrough of a typical
+debugging session.
+
+First, we're going to need a good error. Let's try to macroexpand the
+expression @code{(unquote foo)}, outside of a @code{quasiquote} form,
+and see how the macroexpander reports this error.
+
+@lisp
+scheme@@(guile-user)> (macroexpand '(unquote foo))
+ERROR: In procedure macroexpand:
+ERROR: unquote: expression not valid outside of quasiquote in (unquote foo)
+Entering a new prompt. Type `,bt' for a backtrace or `,q' to continue.
+scheme@@(guile-user) [1]>
+@end lisp
+
+The @code{backtrace} command, which can also be invoked as @code{bt},
+displays the call stack (aka backtrace) at the point where the debugger
+was entered:
+
+@lisp
+scheme@@(guile-user) [1]> ,bt
+In ice-9/psyntax.scm:
+ 1130:21 3 (chi-top (unquote foo) () ((top)) e (eval) (hygiene #))
+ 1071:30 2 (syntax-type (unquote foo) () ((top)) #f #f (# #) #f)
+ 1368:28 1 (chi-macro #<procedure de9360 at ice-9/psyntax.scm...> ...)
+In unknown file:
+ 0 (scm-error syntax-error macroexpand "~a: ~a in ~a" # #f)
+@end lisp
+
+A call stack consists of a sequence of stack @dfn{frames}, with each
+frame describing one procedure which is waiting to do something with the
+values returned by another. Here we see that there are four frames on
+the stack.
+
+Note that @code{macroexpand} is not on the stack -- it must have made a
+tail call to @code{chi-top}, as indeed we would find if we searched
+@code{ice-9/psyntax.scm} for its definition.
+
+When you enter the debugger, the innermost frame is selected, which
+means that the commands for getting information about the ``current''
+frame, or for evaluating expressions in the context of the current
+frame, will do so by default with respect to the innermost frame. To
+select a different frame, so that these operations will apply to it
+instead, use the @code{up}, @code{down} and @code{frame} commands like
+this:
+
+@lisp
+scheme@@(guile-user) [1]> ,up
+In ice-9/psyntax.scm:
+ 1368:28 1 (chi-macro #<procedure de9360 at ice-9/psyntax.scm...> ...)
+scheme@@(guile-user) [1]> ,frame 3
+In ice-9/psyntax.scm:
+ 1130:21 3 (chi-top (unquote foo) () ((top)) e (eval) (hygiene #))
+scheme@@(guile-user) [1]> ,down
+In ice-9/psyntax.scm:
+ 1071:30 2 (syntax-type (unquote foo) () ((top)) #f #f (# #) #f)
+@end lisp
+
+Perhaps we're interested in what's going on in frame 2, so we take a
+look at its local variables:
+
+@lisp
+scheme@@(guile-user) [1]> ,locals
+ Local variables:
+ $1 = e = (unquote foo)
+ $2 = r = ()
+ $3 = w = ((top))
+ $4 = s = #f
+ $5 = rib = #f
+ $6 = mod = (hygiene guile-user)
+ $7 = for-car? = #f
+ $8 = first = unquote
+ $9 = ftype = macro
+ $10 = fval = #<procedure de9360 at ice-9/psyntax.scm:2817:2 (x)>
+ $11 = fe = unquote
+ $12 = fw = ((top))
+ $13 = fs = #f
+ $14 = fmod = (hygiene guile-user)
+@end lisp
+
+All of the values are accessible by their value-history names
+(@code{$@var{n}}):
+
+@lisp
+scheme@@(guile-user) [1]> $10
+$15 = #<procedure de9360 at ice-9/psyntax.scm:2817:2 (x)>
+@end lisp
+
+We can even invoke the procedure at the REPL directly:
+
+@lisp
+scheme@@(guile-user) [1]> ($10 'not-going-to-work)
+ERROR: In procedure macroexpand:
+ERROR: source expression failed to match any pattern in not-going-to-work
+Entering a new prompt. Type `,bt' for a backtrace or `,q' to continue.
+@end lisp
+
+Well at this point we've caused an error within an error. Let's just
+quit back to the top level:
+
+@lisp
+scheme@@(guile-user) [2]> ,q
+scheme@@(guile-user) [1]> ,q
+scheme@@(guile-user)>
+@end lisp
+
+Finally, as a word to the wise: hackers close their REPL prompts with
+@kbd{C-d}.
+
+
+@node Using Guile in Emacs
+@section Using Guile in Emacs
+
+@cindex Emacs
+Any text editor can edit Scheme, but some are better than others. Emacs
+is the best, of course, and not just because it is a fine text editor.
+Emacs has good support for Scheme out of the box, with sensible
+indentation rules, parenthesis-matching, syntax highlighting, and even a
+set of keybindings for structural editing, allowing navigation,
+cut-and-paste, and transposition operations that work on balanced
+S-expressions.
+
+As good as it is, though, two things will vastly improve your experience
+with Emacs and Guile.
+
+@cindex Paredit
+The first is Taylor Campbell's
+@uref{http://www.emacswiki.org/emacs/ParEdit, Paredit}. You should not
+code in any dialect of Lisp without Paredit. (They say that
+unopinionated writing is boring---hence this tone---but it's the
+truth, regardless.) Paredit is the bee's knees.
+
+@cindex Geiser
+The second is
+@iftex
+Jos@'e
+@end iftex
+@ifnottex
+José
+@end ifnottex
+Antonio Ortega Ruiz's
+@uref{http://www.nongnu.org/geiser/, Geiser}. Geiser complements Emacs'
+@code{scheme-mode} with tight integration to running Guile processes via
+a @code{comint-mode} REPL buffer.
+
+Of course there are keybindings to switch to the REPL, and a good REPL
+environment, but Geiser goes beyond that, providing:
+
+@itemize @bullet
+@item
+Form evaluation in the context of the current file's module.
+@item
+Macro expansion.
+@item
+File/module loading and/or compilation.
+@item
+Namespace-aware identifier completion (including local bindings, names
+visible in the current module, and module names).
+@item
+Autodoc: the echo area shows information about the signature of the
+procedure/macro around point automatically.
+@item
+Jump to definition of identifier at point.
+@item
+Access to documentation (including docstrings when the implementation
+provides it).
+@item
+Listings of identifiers exported by a given module.
+@item
+Listings of callers/callees of procedures.
+@item
+Rudimentary support for debugging and error navigation.
+@item
+Support for multiple, simultaneous REPLs.
+@end itemize
+
+See Geiser's web page at @uref{http://www.nongnu.org/geiser/}, for more
+information.
+
+
+@node Using Guile Tools
+@section Using Guile Tools
+
+@cindex guild
+@cindex guile-tools
+@cindex wizards
+Guile also comes with a growing number of command-line utilities: a
+compiler, a disassembler, some module inspectors, and in the future, a
+system to install Guile packages from the internet. These tools may be
+invoked using the @code{guild} program.
+
+@example
+$ guild compile -o foo.go foo.scm
+wrote `foo.go'
+@end example
+
+This program used to be called @code{guile-tools} up to
+Guile version 2.0.1, and for backward
+compatibility it still may be called as such. However we changed the
+name to @code{guild}, not only because it is pleasantly shorter and
+easier to read, but also because this tool will serve to bind Guile
+wizards together, by allowing hackers to share code with each other
+using a CPAN-like system.
+
+@xref{Compilation}, for more on @code{guild compile}.
+
+A complete list of guild scripts can be had by invoking @code{guild
+list}, or simply @code{guild}.
+
+
+@node Installing Site Packages
+@section Installing Site Packages
+
+@cindex site
+@cindex site path
+@cindex load path
+@findex %site-dir
+@findex %site-ccache-dir
+
+At some point, you will probably want to share your code with other
+people. To do so effectively, it is important to follow a set of common
+conventions, to make it easy for the user to install and use your
+package.
+
+The first thing to do is to install your Scheme files where Guile can
+find them. When Guile goes to find a Scheme file, it will search a
+@dfn{load path} to find the file: first in Guile's own path, then in
+paths for @dfn{site packages}. A site package is any Scheme code that
+is installed and not part of Guile itself. @xref{Load Paths}, for more
+on load paths.
+
+There are several site paths, for historical reasons, but the one that
+should generally be used can be obtained by invoking the
+@code{%site-dir} procedure. @xref{Build Config}. If Guile
+@value{EFFECTIVE-VERSION} is installed on your system in @code{/usr/},
+then @code{(%site-dir)} will be
+@code{/usr/share/guile/site/@value{EFFECTIVE-VERSION}}. Scheme files
+should be installed there.
+
+If you do not install compiled @code{.go} files, Guile will compile your
+modules and programs when they are first used, and cache them in the
+user's home directory. @xref{Compilation}, for more on
+auto-compilation. However, it is better to compile the files before
+they are installed, and to just copy the files to a place that Guile can
+find them.
+
+As with Scheme files, Guile searches a path to find compiled @code{.go}
+files, the @code{%load-compiled-path}. By default, this path has two
+entries: a path for Guile's files, and a path for site packages. You
+should install your @code{.go} files into the latter directory, whose
+value is returned by invoking the @code{%site-ccache-dir} procedure. As
+in the previous example, if Guile @value{EFFECTIVE-VERSION} is installed
+on your system in @code{/usr/}, then @code{(%site-ccache-dir)} site
+packages will be
+@code{/usr/lib/guile/@value{EFFECTIVE-VERSION}/site-ccache}.
+
+Note that a @code{.go} file will only be loaded in preference to a
+@code{.scm} file if it is newer. For that reason, you should install
+your Scheme files first, and your compiled files second. @code{Load
+Paths}, for more on the loading process.
+
+Finally, although this section is only about Scheme, sometimes you need
+to install C extensions too. Shared libraries should be installed in
+the @dfn{extensions dir}. This value can be had from the build config
+(@pxref{Build Config}). Again, if Guile @value{EFFECTIVE-VERSION} is
+installed on your system in @code{/usr/}, then the extensions dir will
+be @code{/usr/lib/guile/@value{EFFECTIVE-VERSION}/extensions}.
+
+
+@c Local Variables:
+@c TeX-master: "guile.texi"
+@c End:
HCoop / bpt / guile.git / blobdiff