Commit | Line | Data |
---|---|---|
2da09c3f MV |
1 | @c -*-texinfo-*- |
2 | @c This is part of the GNU Guile Reference Manual. | |
1233b383 | 3 | @c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2010, 2011 |
2da09c3f MV |
4 | @c Free Software Foundation, Inc. |
5 | @c See the file guile.texi for copying conditions. | |
6 | ||
a0e07ba4 | 7 | @node Readline Support |
3229f68b | 8 | @section Readline Support |
a0e07ba4 NJ |
9 | |
10 | @c FIXME::martin: Review me! | |
11 | ||
12 | @cindex readline | |
13 | @cindex command line history | |
2f60df3b KR |
14 | Guile comes with an interface module to the readline library |
15 | (@pxref{Top,,, readline, GNU Readline Library}). This | |
a0e07ba4 NJ |
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. | |
40296bab | 25 | * Readline Functions:: Programming with readline. |
a0e07ba4 NJ |
26 | @end menu |
27 | ||
28 | ||
29 | @node Loading Readline Support | |
3229f68b | 30 | @subsection Loading Readline Support |
a0e07ba4 NJ |
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 | |
85a9b4ed | 48 | loaded the readline module. For example, when you press Enter before |
a0e07ba4 NJ |
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 | |
85a9b4ed | 54 | corresponding opening parenthesis for a short time, making it trivial to make |
a0e07ba4 NJ |
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 | ||
2f60df3b | 62 | @cindex @file{.guile_history} |
a0e07ba4 NJ |
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 | ||
2f60df3b KR |
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 | |
a0e07ba4 NJ |
83 | |
84 | @node Readline Options | |
3229f68b | 85 | @subsection Readline Options |
a0e07ba4 | 86 | |
a0e07ba4 | 87 | @cindex readline options |
1233b383 AW |
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 | ||
a0e07ba4 | 102 | Here is the list of readline options generated by typing |
84898084 | 103 | @code{(readline-options 'help)} in Guile. You can also see the |
a0e07ba4 NJ |
104 | default values. |
105 | ||
106 | @smalllisp | |
84898084 AW |
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). | |
a0e07ba4 NJ |
111 | @end smalllisp |
112 | ||
a0e07ba4 NJ |
113 | The readline options interface can only be used @emph{after} loading |
114 | the readline module, because it is defined in that module. | |
115 | ||
40296bab KR |
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 | ||
a0e07ba4 | 251 | |
a0e07ba4 NJ |
252 | @c Local Variables: |
253 | @c TeX-master: "guile.texi" | |
254 | @c End: |