diff options
Diffstat (limited to 'doc/ref/scheme-using.texi')
-rw-r--r-- | doc/ref/scheme-using.texi | 411 |
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: |