@c -*-texinfo-*-
@c This is part of the GNU Guile Reference Manual.
@c Copyright (C)  1996, 1997, 2000, 2001, 2002, 2003, 2004
@c   Free Software Foundation, Inc.
@c See the file guile.texi for copying conditions.

@page
@node Readline Support
@section Readline Support

@c FIXME::martin: Review me!

@cindex readline
@cindex command line history
Guile comes with an interface module to the readline library.  This
makes interactive use much more convenient, because of the command-line
editing features of readline.  Using @code{(ice-9 readline)}, you can
navigate through the current input line with the cursor keys, retrieve
older command lines from the input history and even search through the
history entries.

@menu
* Loading Readline Support::    How to load readline support into Guile.
* Readline Options::            How to modify readline's behaviour.
@end menu


@node Loading Readline Support
@subsection Loading Readline Support

The module is not loaded by default and so has to be loaded and
activated explicitly.  This is done with two simple lines of code:

@findex activate-readline
@lisp
(use-modules (ice-9 readline))
(activate-readline)
@end lisp

@c FIXME::martin: Review me!

The first line will load the necessary code, and the second will
activate readline's features for the REPL.  If you plan to use this
module often, you should save these to lines to your @file{.guile}
personal startup file.

You will notice that the REPL's behaviour changes a bit when you have
loaded the readline module.  For example, when you press Enter before
typing in the closing parentheses of a list, you will see the
@dfn{continuation} prompt, three dots: @code{...}  This gives you a nice
visual feedback when trying to match parentheses.  To make this even
easier, @dfn{bouncing parentheses} are implemented.  That means that
when you type in a closing parentheses, the cursor will jump to the
corresponding opening parenthesis for a short time, making it trivial to make
them match.

Once the readline module is activated, all lines entered interactively
will be stored in a history and can be recalled later using the
cursor-up and -down keys.  Readline also understands the Emacs keys for
navigating through the command line and history.

When you quit your Guile session by evaluating @code{(quit)} or pressing
Ctrl-D, the history will be saved to the file @file{.guile_history} and
read in when you start Guile for the next time.  Thus you can start a
new Guile session and still have the (probably long-winded) definition
expressions available.


@node Readline Options
@subsection Readline Options

@c FIXME::martin: Review me!

@cindex readline options
The readline interface module can be configured in several ways to
better suit the user's needs.  Configuration is done via the readline
module's options interface, in a similar way to the evaluator and
debugging options (@pxref{User level options interfaces}.)

@findex readline-options
@findex readline-enable
@findex readline-disable
@findex readline-set!
Here is the list of readline options generated by typing
@code{(readline-options 'full)} in Guile.  You can also see the
default values.

@smalllisp
bounce-parens   500   Time (ms) to show matching opening parenthesis (0 = off).
history-length  200   History length.
history-file    yes   Use history file.
@end smalllisp

The history length specifies how many input lines will be remembered.
If the history contains that many lines and additional lines are
entered, the oldest lines will be lost.  You can switch on/off the
usage of the history file using the following call.

@lisp
(readline-disable 'history)
@end lisp

The readline options interface can only be used @emph{after} loading
the readline module, because it is defined in that module.


@page
@node Value History
@section Value History

@c FIXME::martin: Review me!

@cindex value history
Another module which makes command line usage more convenient is
@code{(ice-9 history)}.  This module will change the REPL so that each
value which is evaluated and printed will be remembered under a name
constructed from the dollar character (@code{$}) and the number of the
evaluated expression.

Consider an example session.

@example
guile> (use-modules (ice-9 history))
guile> 1
$1 = 1
guile> (+ $1 $1)
$2 = 2
guile> (* $2 $2)
$3 = 4
@end example

After loading the value history module @code{(ice-9 history)}, one
(trivial) expression is evaluated.  The result is stored into the
variable @code{$1}.  This fact is indicated by the output @code{$1 = },
which is also caused by @code{(ice-9 history)}.  In the next line, this
variable is used two times, to produce the value @code{$2}, which in
turn is used in the calculation for @code{$3}.


@c Local Variables:
@c TeX-master: "guile.texi"
@c End: