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