Using Guile Interactively
=========================

When you start up Guile by typing just guile, without a -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.

     guile> (+ 3 4 5)
     12
     guile> (display "Hello world!\n")
     Hello world!
     guile> (values 'a 'b)
     a
     b

This mode of use is called a 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.

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.

     guile> (use-modules (ice-9 readline))
     guile> (activate-readline)

It's a good idea to put these two lines (without the ``guile>'' prompts) in your .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.

Value History
-------------

Just as Readline helps you to reuse a previous input line, value history allows you to use the 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 $1, $2, ..., and you can then use these variables in subsequent expressions.

     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)

To enable value history, type (use-modules (ice-9 history)) at the Guile prompt, or add this to your .guile file.  (It is not enabled by default, to avoid the possibility of conflicting with some other use you may have for the variables $1, $2, ..., and also because it prevents the stored evaluation results from being garbage collected, which some people may not want.)

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:

     (make-string (* 4 (+ 3 #\s)) #\space)
     -|
     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.

However, as the message above says, you can obtain more information about the context of the error by typing (backtrace) or (debug).

(backtrace) displays the Scheme call stack at the point where the error occurred:

     (backtrace)
     -|
     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.

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 (debug-enable 'backtrace) to your .guile.

(debug) takes you into Guile's interactive debugger, which provides commands that allow you to

  * display the Scheme call stack at the point where the error occurred (the backtrace command --- see Display Backtrace)

  * move up and down the call stack, to see in detail the expression being evaluated, or the procedure being applied, in each frame (the up, down, frame, position, info args and info frame commands --- see Frame Selection and Frame Information)

  * examine the values of variables and expressions in the context of each frame (the evaluate command --- see Frame Evaluation).

This is documented further in the following section.

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:

     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>

``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.

Display Backtrace
.................

The backtrace command, which can also be invoked as bt or where, displays the call stack (aka backtrace) at the point where the debugger was entered:

     debug> bt
     In standard input:
       36: 0* [make-string ...
       36: 1*  [* 4 ...
       36: 2*   [+ 3 #\s]

 -- Debugger Command: backtrace [count]
 -- Debugger Command: bt [count]
 -- Debugger Command: where [count]
     Print backtrace of all stack frames, or of the innermost COUNT frames.  With a negative argument, print the outermost -COUNT frames.  If the number of frames isn't explicitly given, the debug option depth determines the maximum number of frames printed.

The format of the displayed backtrace is the same as for the backtrace procedure.

Frame Selection
...............

A call stack consists of a sequence of stack 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 up, down and frame commands like this:

     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 ...

 -- Debugger Command: up [n]
     Move N frames up the stack.  For positive N, this advances toward the outermost frame, to higher frame numbers, to frames that have existed longer.  N defaults to one.

 -- Debugger Command: down [n]
     Move N frames down the stack.  For positive N, this advances toward the innermost frame, to lower frame numbers, to frames that were created more recently.  N defaults to one.

 -- 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.

Frame Information
.................

[to be completed]

 -- Debugger Command: info frame
     All about selected stack frame.

 -- Debugger Command: info args
     Argument variables of current stack frame.

 -- Debugger Command: position
     Display the position of the current expression.

Frame Evaluation
................

[to be completed]

 -- 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.

Single Stepping
...............

[to be completed]

 -- Debugger Command: step [n]
     Continue until entry to Nth next frame.

 -- Debugger Command: next [n]
     Continue until entry to Nth next frame in same file.

Run To Frame Exit
.................

[to be completed]

 -- Debugger Command: finish
     Continue until evaluation of the current frame is complete, and print the result obtained.

 -- Debugger Command: trace-finish
     Trace until evaluation of the current frame is complete.

Continue Execution
..................

[to be completed]

 -- Debugger Command: continue
     Continue program execution.

Leave Debugger
..............

[to be completed]

 -- Debugger Command: quit
     Exit the debugger.

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. (You can also, of course, run a Guile session in Emacs simply by typing ``guile'' in a *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.

 1. 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:

       * completing the identifier at point

       * accessing Guile's built in help

       * evaluating fragments of code to check what they do.

 2. 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

       * look at the values of local variables

       * see what is happening at all levels of the Scheme stack

       * continue execution, either normally or step by step.

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.