summaryrefslogtreecommitdiff
path: root/doc/ref/scheme-using.texi
diff options
context:
space:
mode:
authorNeil Jerram <neil@ossau.uklinux.net>2006-08-01 21:33:17 +0000
committerNeil Jerram <neil@ossau.uklinux.net>2006-08-01 21:33:17 +0000
commit46f7666d7f9d07484a44f438f9b51c0a29b8a0c4 (patch)
treebd529c1c334d4b4ac3627dac89ba2b6a84b3f0cd /doc/ref/scheme-using.texi
parentb49123789ffd7b61d87ed62333605b5051fe63f7 (diff)
downloadguile-46f7666d7f9d07484a44f438f9b51c0a29b8a0c4.tar.gz
* scheme-debugging.texi (Debug Last Error, Interactive Debugger):
Moved/merged to scheme-using.texi, as REPL features. (Examples): New. (Intro to Breakpoints): New introductory text here. Removed all subnodes except for Breakpoints Overview. * scheme-using.texi: New. * guile.texi (Programming in Scheme): Include new scheme-using.texi file. * Makefile.am (guile_TEXINFOS): Include new scheme-using.texi file.
Diffstat (limited to 'doc/ref/scheme-using.texi')
-rw-r--r--doc/ref/scheme-using.texi411
1 files changed, 411 insertions, 0 deletions
diff --git a/doc/ref/scheme-using.texi b/doc/ref/scheme-using.texi
new file mode 100644
index 000000000..b596ce50a
--- /dev/null
+++ b/doc/ref/scheme-using.texi
@@ -0,0 +1,411 @@
+@c -*-texinfo-*-
+@c This is part of the GNU Guile Reference Manual.
+@c Copyright (C) 2006
+@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
+guile> (+ 3 4 5)
+12
+guile> (display "Hello world!\n")
+Hello world!
+guile> (values 'a 'b)
+a
+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.
+
+@menu
+* Readline::
+* Value Historyx::
+* Error Handling::
+* Interactive Debugger:: Using the interactive debugger.
+@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
+guile> (use-modules (ice-9 readline))
+guile> (activate-readline)
+@end lisp
+
+It's a good idea to put these two lines (without the ``guile>''
+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 ``guile>'' prompt.
+
+
+@node Value Historyx
+@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
+guile> (iota 10)
+$1 = (0 1 2 3 4 5 6 7 8 9)
+guile> (apply * (cdr $1))
+$2 = 362880
+guile> (sqrt $2)
+$3 = 602.3952191045344
+guile> (cons $2 $1)
+$4 = (362880 0 1 2 3 4 5 6 7 8 9)
+@end lisp
+
+To enable value history, type @code{(use-modules (ice-9 history))} at
+the Guile prompt, or add this to your @file{.guile} file. (It is not
+enabled by default, to avoid the possibility of conflicting with some
+other use you may have for the variables @code{$1}, @code{$2},
+@dots{}, and also because it prevents the stored evaluation results
+from being garbage collected, which some people may not want.)
+
+
+@node Error Handling
+@subsection Error Handling
+
+When code being evaluated from the REPL hits an error, Guile remembers
+the execution context where the error occurred and can give you three
+levels of information about what the error was and exactly where it
+occurred.
+
+By default, Guile then displays only the first level, which is the most
+immediate information about where and why the error occurred, for
+example:
+
+@lisp
+(make-string (* 4 (+ 3 #\s)) #\space)
+@print{}
+standard input:2:19: In procedure + in expression (+ 3 #\s):
+standard input:2:19: Wrong type argument: #\s
+ABORT: (wrong-type-arg)
+
+Type "(backtrace)" to get more information or "(debug)" to enter the debugger.
+@end lisp
+
+@noindent
+However, as the message above says, you can obtain more information
+about the context of the error by typing @code{(backtrace)} or
+@code{(debug)}.
+
+@code{(backtrace)} displays the Scheme call stack at the point where the
+error occurred:
+
+@lisp
+(backtrace)
+@print{}
+Backtrace:
+In standard input:
+ 2: 0* [make-string ...
+ 2: 1* [* 4 ...
+ 2: 2* [+ 3 #\s]
+
+Type "(debug-enable 'backtrace)" if you would like a backtrace
+automatically if an error occurs in the future.
+@end lisp
+
+@noindent
+In a more complex scenario than this one, this can be extremely useful
+for understanding where and why the error occurred. You can make Guile
+show the backtrace automatically by adding @code{(debug-enable
+'backtrace)} to your @file{.guile}.
+
+@code{(debug)} takes you into Guile's interactive debugger, which
+provides commands that allow you to
+
+@itemize @bullet
+@item
+display the Scheme call stack at the point where the error occurred
+(the @code{backtrace} command --- see @ref{Display Backtrace})
+
+@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} (the
+@code{up}, @code{down}, @code{frame}, @code{position}, @code{info args}
+and @code{info frame} commands --- see @ref{Frame Selection} and
+@ref{Frame Information})
+
+@item
+examine the values of variables and expressions in the context of each
+frame (the @code{evaluate} command --- see @ref{Frame Evaluation}).
+@end itemize
+
+@noindent
+This is documented further in the following section.
+
+
+@node Interactive Debugger
+@subsection Using the Interactive Debugger
+
+Guile's interactive debugger is a command line application that accepts
+commands from you for examining the stack and, if at a breakpoint, for
+continuing program execution in various ways. Unlike in the normal
+Guile REPL, commands are typed mostly without parentheses.
+
+When you first enter the debugger, it introduces itself with a message
+like this:
+
+@lisp
+This is the Guile debugger -- for help, type `help'.
+There are 3 frames on the stack.
+
+Frame 2 at standard input:36:19
+ [+ 3 #\s]
+debug>
+@end lisp
+
+@noindent
+``debug>'' is the debugger's prompt, and a reminder that you are not in
+the normal Guile REPL. The available commands are described in the
+following subsections.
+
+@menu
+* Display Backtrace:: backtrace.
+* Frame Selection:: up, down, frame.
+* Frame Information:: info args, info frame, position.
+* Frame Evaluation:: evaluate.
+* Single Stepping:: step, next.
+* Run To Frame Exit:: finish, trace-finish.
+* Continue Execution:: continue.
+* Leave Debugger:: quit.
+@end menu
+
+
+@node Display Backtrace
+@subsubsection Display Backtrace
+
+The @code{backtrace} command, which can also be invoked as @code{bt} or
+@code{where}, displays the call stack (aka backtrace) at the point where
+the debugger was entered:
+
+@lisp
+debug> bt
+In standard input:
+ 36: 0* [make-string ...
+ 36: 1* [* 4 ...
+ 36: 2* [+ 3 #\s]
+@end lisp
+
+@deffn {Debugger Command} backtrace [count]
+@deffnx {Debugger Command} bt [count]
+@deffnx {Debugger Command} where [count]
+Print backtrace of all stack frames, or of the innermost @var{count}
+frames. With a negative argument, print the outermost -@var{count}
+frames. If the number of frames isn't explicitly given, the debug
+option @code{depth} determines the maximum number of frames printed.
+@end deffn
+
+The format of the displayed backtrace is the same as for the
+@code{backtrace} procedure.
+
+
+@node Frame Selection
+@subsubsection Frame Selection
+
+A call stack consists of a sequence of stack @dfn{frames}, with each
+frame describing one level of the nested evaluations and applications
+that the program was executing when it hit a breakpoint or an error.
+Frames are numbered such that frame 0 is the outermost --- i.e. the
+operation on the call stack that began least recently --- and frame N-1
+the innermost (where N is the total number of frames on the stack).
+
+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
+debug> up
+Frame 1 at standard input:36:14
+ [* 4 ...
+debug> frame 0
+Frame 0 at standard input:36:1
+ [make-string ...
+debug> down
+Frame 1 at standard input:36:14
+ [* 4 ...
+@end lisp
+
+@deffn {Debugger Command} up [n]
+Move @var{n} frames up the stack. For positive @var{n}, this
+advances toward the outermost frame, to higher frame numbers, to
+frames that have existed longer. @var{n} defaults to one.
+@end deffn
+
+@deffn {Debugger Command} down [n]
+Move @var{n} frames down the stack. For positive @var{n}, this
+advances toward the innermost frame, to lower frame numbers, to frames
+that were created more recently. @var{n} defaults to one.
+@end deffn
+
+@deffn {Debugger Command} frame [n]
+Select and print a stack frame. With no argument, print the selected
+stack frame. (See also ``info frame''.) An argument specifies the
+frame to select; it must be a stack-frame number.
+@end deffn
+
+
+@node Frame Information
+@subsubsection Frame Information
+
+[to be completed]
+
+@deffn {Debugger Command} {info frame}
+All about selected stack frame.
+@end deffn
+
+@deffn {Debugger Command} {info args}
+Argument variables of current stack frame.
+@end deffn
+
+@deffn {Debugger Command} position
+Display the position of the current expression.
+@end deffn
+
+
+@node Frame Evaluation
+@subsubsection Frame Evaluation
+
+[to be completed]
+
+@deffn {Debugger Command} evaluate expression
+Evaluate an expression.
+The expression must appear on the same line as the command,
+however it may be continued over multiple lines.
+@end deffn
+
+
+@node Single Stepping
+@subsubsection Single Stepping
+
+[to be completed]
+
+@deffn {Debugger Command} step [n]
+Continue until entry to @var{n}th next frame.
+@end deffn
+
+@deffn {Debugger Command} next [n]
+Continue until entry to @var{n}th next frame in same file.
+@end deffn
+
+
+@node Run To Frame Exit
+@subsubsection Run To Frame Exit
+
+[to be completed]
+
+@deffn {Debugger Command} finish
+Continue until evaluation of the current frame is complete, and
+print the result obtained.
+@end deffn
+
+@deffn {Debugger Command} trace-finish
+Trace until evaluation of the current frame is complete.
+@end deffn
+
+
+@node Continue Execution
+@subsubsection Continue Execution
+
+[to be completed]
+
+@deffn {Debugger Command} continue
+Continue program execution.
+@end deffn
+
+
+@node Leave Debugger
+@subsubsection Leave Debugger
+
+[to be completed]
+
+@deffn {Debugger Command} quit
+Exit the debugger.
+@end deffn
+
+
+@node Using Guile in Emacs
+@section Using Guile in Emacs
+
+The Guile distribution includes a rich environment for working on Guile
+Scheme code within Emacs. The idea of this environment is 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.@footnote{You can also, of course, run a Guile session in Emacs
+simply by typing ``guile'' in a @code{*shell*} buffer. The environment
+described here provides a much better integration than that, though.}
+
+The thinking behind this environment 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 the Guile/Emacs environment 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
+@item
+accessing Guile's built in help
+@item
+evaluating fragments of code to check what they do.
+@end itemize
+
+@item
+Debugging a Guile Scheme program. When your program hits an error or
+a breakpoint, the Guile/Emacs environment 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
+@end enumerate
+
+Combinations of these work well too. You can evaluate a fragment of
+code (in a Scheme buffer) that contains a breakpoint, then use the
+debugging interface to step through the code at the breakpoint. You
+can also run a program until it hits a breakpoint, then examine,
+modify and reevaluate some of the relevant code, and then tell the
+program to continue running.
+
+
+@c Local Variables:
+@c TeX-master: "guile.texi"
+@c End: