Commit | Line | Data |
---|---|---|
2da09c3f MV |
1 | @c -*-texinfo-*- |
2 | @c This is part of the GNU Guile Reference Manual. | |
ca290a89 | 3 | @c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2010 |
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 NJ |
86 | |
87 | @c FIXME::martin: Review me! | |
88 | ||
89 | @cindex readline options | |
90 | The readline interface module can be configured in several ways to | |
91 | better suit the user's needs. Configuration is done via the readline | |
92 | module's options interface, in a similar way to the evaluator and | |
40296bab | 93 | debugging options (@pxref{Runtime Options}). |
a0e07ba4 | 94 | |
4b83d327 KR |
95 | @findex readline-options |
96 | @findex readline-enable | |
97 | @findex readline-disable | |
98 | @findex readline-set! | |
a0e07ba4 | 99 | Here is the list of readline options generated by typing |
84898084 | 100 | @code{(readline-options 'help)} in Guile. You can also see the |
a0e07ba4 NJ |
101 | default values. |
102 | ||
103 | @smalllisp | |
84898084 AW |
104 | history-file yes Use history file. |
105 | history-length 200 History length. | |
106 | bounce-parens 500 Time (ms) to show matching opening parenthesis | |
107 | (0 = off). | |
a0e07ba4 NJ |
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 | ||
40296bab KR |
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 | ||
a0e07ba4 | 257 | |
a0e07ba4 NJ |
258 | @c Local Variables: |
259 | @c TeX-master: "guile.texi" | |
260 | @c End: |