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