guile18/doc/ref/repl-modules.texi

   1 @c -*-texinfo-*-
   2 @c This is part of the GNU Guile Reference Manual.
   3 @c Copyright (C)  1996, 1997, 2000, 2001, 2002, 2003, 2004
   4 @c   Free Software Foundation, Inc.
   5 @c See the file guile.texi for copying conditions.
   6
   7 @page
   8 @node Readline Support
   9 @section Readline Support
  10
  11 @c FIXME::martin: Review me!
  12
  13 @cindex readline
  14 @cindex command line history
  15 Guile comes with an interface module to the readline library
  16 (@pxref{Top,,, readline, GNU Readline Library}).  This
  17 makes interactive use much more convenient, because of the command-line
  18 editing features of readline.  Using @code{(ice-9 readline)}, you can
  19 navigate through the current input line with the cursor keys, retrieve
  20 older command lines from the input history and even search through the
  21 history entries.
  22
  23 @menu
  24 * Loading Readline Support::    How to load readline support into Guile.
  25 * Readline Options::            How to modify readline's behaviour.
  26 * Readline Functions::          Programming with readline.
  27 @end menu
  28
  29
  30 @node Loading Readline Support
  31 @subsection Loading Readline Support
  32
  33 The module is not loaded by default and so has to be loaded and
  34 activated explicitly.  This is done with two simple lines of code:
  35
  36 @lisp
  37 (use-modules (ice-9 readline))
  38 (activate-readline)
  39 @end lisp
  40
  41 @c FIXME::martin: Review me!
  42
  43 The first line will load the necessary code, and the second will
  44 activate readline's features for the REPL.  If you plan to use this
  45 module often, you should save these to lines to your @file{.guile}
  46 personal startup file.
  47
  48 You will notice that the REPL's behaviour changes a bit when you have
  49 loaded the readline module.  For example, when you press Enter before
  50 typing in the closing parentheses of a list, you will see the
  51 @dfn{continuation} prompt, three dots: @code{...}  This gives you a nice
  52 visual feedback when trying to match parentheses.  To make this even
  53 easier, @dfn{bouncing parentheses} are implemented.  That means that
  54 when you type in a closing parentheses, the cursor will jump to the
  55 corresponding opening parenthesis for a short time, making it trivial to make
  56 them match.
  57
  58 Once the readline module is activated, all lines entered interactively
  59 will be stored in a history and can be recalled later using the
  60 cursor-up and -down keys.  Readline also understands the Emacs keys for
  61 navigating through the command line and history.
  62
  63 @cindex @file{.guile_history}
  64 When you quit your Guile session by evaluating @code{(quit)} or pressing
  65 Ctrl-D, the history will be saved to the file @file{.guile_history} and
  66 read in when you start Guile for the next time.  Thus you can start a
  67 new Guile session and still have the (probably long-winded) definition
  68 expressions available.
  69
  70 @cindex @env{GUILE_HISTORY}
  71 @cindex @file{.inputrc}
  72 You can specify a different history file by setting the environment
  73 variable @env{GUILE_HISTORY}.  And you can make Guile specific
  74 customizations to your @file{.inputrc} by testing for application
  75 @samp{Guile} (@pxref{Conditional Init Constructs,,, readline, GNU
  76 Readline Library}).  For instance to define a key inserting a matched
  77 pair of parentheses,
  78
  79 @example
  80 $if Guile
  81   "\C-o": "()\C-b"
  82 $endif
  83 @end example
  84
  85 @node Readline Options
  86 @subsection Readline Options
  87
  88 @c FIXME::martin: Review me!
  89
  90 @cindex readline options
  91 The readline interface module can be configured in several ways to
  92 better suit the user's needs.  Configuration is done via the readline
  93 module's options interface, in a similar way to the evaluator and
  94 debugging options (@pxref{Runtime Options}).
  95
  96 @findex readline-options
  97 @findex readline-enable
  98 @findex readline-disable
  99 @findex readline-set!
 100 Here is the list of readline options generated by typing
 101 @code{(readline-options 'full)} in Guile.  You can also see the
 102 default values.
 103
 104 @smalllisp
 105 bounce-parens   500   Time (ms) to show matching opening parenthesis (0 = off).
 106 history-length  200   History length.
 107 history-file    yes   Use history file.
 108 @end smalllisp
 109
 110 The history length specifies how many input lines will be remembered.
 111 If the history contains that many lines and additional lines are
 112 entered, the oldest lines will be lost.  You can switch on/off the
 113 usage of the history file using the following call.
 114
 115 @lisp
 116 (readline-disable 'history)
 117 @end lisp
 118
 119 The readline options interface can only be used @emph{after} loading
 120 the readline module, because it is defined in that module.
 121
 122 @node Readline Functions
 123 @subsection Readline Functions
 124
 125 The following functions are provided by
 126
 127 @example
 128 (use-modules (ice-9 readline))
 129 @end example
 130
 131 There are two ways to use readline from Scheme code, either make calls
 132 to @code{readline} directly to get line by line input, or use the
 133 readline port below with all the usual reading functions.
 134
 135 @defun readline [prompt]
 136 Read a line of input from the user and return it as a string (without
 137 a newline at the end).  @var{prompt} is the prompt to show, or the
 138 default is the string set in @code{set-readline-prompt!} below.
 139
 140 @example
 141 (readline "Type something: ") @result{} "hello"
 142 @end example
 143 @end defun
 144
 145 @defun set-readline-input-port! port
 146 @defunx set-readline-output-port! port
 147 Set the input and output port the readline function should read from
 148 and write to.  @var{port} must be a file port (@pxref{File Ports}),
 149 and should usually be a terminal.
 150
 151 The default is the @code{current-input-port} and
 152 @code{current-output-port} (@pxref{Default Ports}) when @code{(ice-9
 153 readline)} loads, which in an interactive user session means the Unix
 154 ``standard input'' and ``standard output''.
 155 @end defun
 156
 157 @subsubsection Readline Port
 158
 159 @defun readline-port
 160 Return a buffered input port (@pxref{Buffered Input}) which calls the
 161 @code{readline} function above to get input.  This port can be used
 162 with all the usual reading functions (@code{read}, @code{read-char},
 163 etc), and the user gets the interactive editing features of readline.
 164
 165 There's only a single readline port created.  @code{readline-port}
 166 creates it when first called, and on subsequent calls just returns
 167 what it previously made.
 168 @end defun
 169
 170 @defun activate-readline
 171 If the @code{current-input-port} is a terminal (@pxref{Terminals and
 172 Ptys,, @code{isatty?}}) then enable readline for all reading from
 173 @code{current-input-port} (@pxref{Default Ports}) and enable readline
 174 features in the interactive REPL (@pxref{The REPL}).
 175
 176 @example
 177 (activate-readline)
 178 (read-char)
 179 @end example
 180
 181 @code{activate-readline} enables readline on @code{current-input-port}
 182 simply by a @code{set-current-input-port} to the @code{readline-port}
 183 above.  An application can do that directly if the extra REPL features
 184 that @code{activate-readline} adds are not wanted.
 185 @end defun
 186
 187 @defun set-readline-prompt! prompt1 [prompt2]
 188 Set the prompt string to print when reading input.  This is used when
 189 reading through @code{readline-port}, and is also the default prompt
 190 for the @code{readline} function above.
 191
 192 @var{prompt1} is the initial prompt shown.  If a user might enter an
 193 expression across multiple lines, then @var{prompt2} is a different
 194 prompt to show further input required.  In the Guile REPL for instance
 195 this is an ellipsis (@samp{...}).
 196
 197 See @code{set-buffered-input-continuation?!} (@pxref{Buffered Input})
 198 for an application to indicate the boundaries of logical expressions
 199 (assuming of course an application has such a notion).
 200 @end defun
 201
 202 @subsubsection Completion
 203
 204 @defun with-readline-completion-function completer thunk
 205 Call @code{(@var{thunk})} with @var{completer} as the readline tab
 206 completion function to be used in any readline calls within that
 207 @var{thunk}.  @var{completer} can be @code{#f} for no completion.
 208
 209 @var{completer} will be called as @code{(@var{completer} text state)},
 210 as described in (@pxref{How Completing Works,,, readline, GNU Readline
 211 Library}).  @var{text} is a partial word to be completed, and each
 212 @var{completer} call should return a possible completion string or
 213 @code{#f} when no more.  @var{state} is @code{#f} for the first call
 214 asking about a new @var{text} then @code{#t} while getting further
 215 completions of that @var{text}.
 216
 217 Here's an example @var{completer} for user login names from the
 218 password file (@pxref{User Information}), much like readline's own
 219 @code{rl_username_completion_function},
 220
 221 @example
 222 (define (username-completer-function text state)
 223   (if (not state)
 224       (setpwent))  ;; new, go to start of database
 225   (let more ((pw (getpwent)))
 226     (if pw
 227         (if (string-prefix? text (passwd:name pw))
 228             (passwd:name pw)     ;; this name matches, return it
 229             (more (getpwent)))   ;; doesn't match, look at next
 230         (begin
 231           ;; end of database, close it and return #f
 232           (endpwent)
 233           #f))))
 234 @end example
 235 @end defun
 236
 237 @defun apropos-completion-function text state
 238 A completion function offering completions for Guile functions and
 239 variables (all @code{define}s).  This is the default completion
 240 function.
 241 @c
 242 @c  FIXME: Cross reference the ``apropos'' stuff when it's documented.
 243 @c
 244 @end defun
 245
 246 @defun filename-completion-function text state
 247 A completion function offering filename completions.  This is
 248 readline's @code{rl_filename_completion_function} (@pxref{Completion
 249 Functions,,, readline, GNU Readline Library}).
 250 @end defun
 251
 252 @defun make-completion-function string-list
 253 Return a completion function which offers completions from the
 254 possibilities in @var{string-list}.  Matching is case-sensitive.
 255 @end defun
 256
 257
 258 @page
 259 @node Value History
 260 @section Value History
 261
 262 @c FIXME::martin: Review me!
 263
 264 @cindex value history
 265 Another module which makes command line usage more convenient is
 266 @code{(ice-9 history)}.  This module will change the REPL so that each
 267 value which is evaluated and printed will be remembered under a name
 268 constructed from the dollar character (@code{$}) and the number of the
 269 evaluated expression.
 270
 271 Consider an example session.
 272
 273 @example
 274 guile> (use-modules (ice-9 history))
 275 guile> 1
 276 $1 = 1
 277 guile> (+ $1 $1)
 278 $2 = 2
 279 guile> (* $2 $2)
 280 $3 = 4
 281 @end example
 282
 283 After loading the value history module @code{(ice-9 history)}, one
 284 (trivial) expression is evaluated.  The result is stored into the
 285 variable @code{$1}.  This fact is indicated by the output @code{$1 = },
 286 which is also caused by @code{(ice-9 history)}.  In the next line, this
 287 variable is used two times, to produce the value @code{$2}, which in
 288 turn is used in the calculation for @code{$3}.
 289
 290
 291 @c Local Variables:
 292 @c TeX-master: "guile.texi"
 293 @c End: