doc/ref/repl-modules.texi

   1 @page
   2 @node Readline Support
   3 @chapter Readline Support
   4
   5 @c FIXME::martin: Review me!
   6
   7 @cindex readline
   8 @cindex command line history
   9 Guile comes with an interface module to the readline library.  This
  10 makes interactive use much more convenient, because of the command-line
  11 editing features of readline.  Using @code{(ice-9 readline)}, you can
  12 navigate through the current input line with the cursor keys, retrieve
  13 older command lines from the input history and even search through the
  14 history entries.
  15
  16 @menu
  17 * Loading Readline Support::    How to load readline support into Guile.
  18 * Readline Options::            How to modify readline's behaviour.
  19 @end menu
  20
  21
  22 @node Loading Readline Support
  23 @section Loading Readline Support
  24
  25 The module is not loaded by default and so has to be loaded and
  26 activated explicitly.  This is done with two simple lines of code:
  27
  28 @lisp
  29 (use-modules (ice-9 readline))
  30 (activate-readline)
  31 @end lisp
  32
  33 @c FIXME::martin: Review me!
  34
  35 The first line will load the necessary code, and the second will
  36 activate readline's features for the REPL.  If you plan to use this
  37 module often, you should save these to lines to your @file{.guile}
  38 personal startup file.
  39
  40 You will notice that the REPL's behaviour changes a bit when you have
  41 loaded the readline module.  For example, when you press Enter before
  42 typing in the closing parentheses of a list, you will see the
  43 @dfn{continuation} prompt, three dots: @code{...}  This gives you a nice
  44 visual feedback when trying to match parentheses.  To make this even
  45 easier, @dfn{bouncing parentheses} are implemented.  That means that
  46 when you type in a closing parentheses, the cursor will jump to the
  47 corresponding opening parenthesis for a short time, making it trivial to make
  48 them match.
  49
  50 Once the readline module is activated, all lines entered interactively
  51 will be stored in a history and can be recalled later using the
  52 cursor-up and -down keys.  Readline also understands the Emacs keys for
  53 navigating through the command line and history.
  54
  55 When you quit your Guile session by evaluating @code{(quit)} or pressing
  56 Ctrl-D, the history will be saved to the file @file{.guile_history} and
  57 read in when you start Guile for the next time.  Thus you can start a
  58 new Guile session and still have the (probably long-winded) definition
  59 expressions available.
  60
  61
  62 @node Readline Options
  63 @section Readline Options
  64
  65 @c FIXME::martin: Review me!
  66
  67 @cindex readline options
  68 The readline interface module can be configured in several ways to
  69 better suit the user's needs.  Configuration is done via the readline
  70 module's options interface, in a similar way to the evaluator and
  71 debugging options (@pxref{General option interface}.)
  72
  73 Here is the list of readline options generated by typing
  74 @code{(readline-options 'full)} in Guile.  You can also see the
  75 default values.
  76
  77 @smalllisp
  78 bounce-parens   500   Time (ms) to show matching opening parenthesis (0 = off).
  79 history-length  200   History length.
  80 history-file    yes   Use history file.
  81 @end smalllisp
  82
  83 The history length specifies how many input lines will be remembered.
  84 If the history contains that many lines and additional lines are
  85 entered, the oldest lines will be lost.  You can switch on/off the
  86 usage of the history file using the following call.
  87
  88 @lisp
  89 (readline-disable 'history)
  90 @end lisp
  91
  92 The readline options interface can only be used @emph{after} loading
  93 the readline module, because it is defined in that module.
  94
  95
  96 @page
  97 @node Value History
  98 @chapter Value History
  99
 100 @c FIXME::martin: Review me!
 101
 102 @cindex value history
 103 Another module which makes command line usage more convenient is
 104 @code{(ice-9 history)}.  This module will change the REPL so that each
 105 value which is evaluated and printed will be remembered under a name
 106 constructed from the dollar character (@code{$}) and the number of the
 107 evaluated expression.
 108
 109 Consider an example session.
 110
 111 @example
 112 guile> (use-modules (ice-9 history))
 113 guile> 1
 114 $1 = 1
 115 guile> (+ $1 $1)
 116 $2 = 2
 117 guile> (* $2 $2)
 118 $3 = 4
 119 @end example
 120
 121 After loading the value history module @code{(ice-9 history)}, one
 122 (trivial) expression is evaluated.  The result is stored into the
 123 variable @code{$1}.  This fact is indicated by the output @code{$1 = },
 124 which is also caused by @code{(ice-9 history)}.  In the next line, this
 125 variable is used two times, to produce the value @code{$2}, which in
 126 turn is used in the calculation for @code{$3}.
 127
 128
 129 @c Local Variables:
 130 @c TeX-master: "guile.texi"
 131 @c End: