Commit | Line | Data |
---|---|---|
a0e07ba4 NJ |
1 | @page |
2 | @node Readline Support | |
3 | @chapter Readline Support | |
4 | ||
5 | @c FIXME::martin: Review me! | |
6 | ||
7 | @cindex readline | |
8 | @cindex command line history | |
9 | Guile comes with an interface module to the readline library. This | |
10 | makes interactive use much more convenient, because of the command-line | |
11 | editing features of readline. Using @code{(ice-9 readline)}, you can | |
12 | navigate through the current input line with the cursor keys, retrieve | |
13 | older command lines from the input history and even search through the | |
14 | history entries. | |
15 | ||
16 | @menu | |
17 | * Loading Readline Support:: How to load readline support into Guile. | |
18 | * Readline Options:: How to modify readline's behaviour. | |
19 | @end menu | |
20 | ||
21 | ||
22 | @node Loading Readline Support | |
23 | @section Loading Readline Support | |
24 | ||
25 | The module is not loaded by default and so has to be loaded and | |
26 | activated explicitly. This is done with two simple lines of code: | |
27 | ||
4b83d327 | 28 | @findex activate-readline |
a0e07ba4 NJ |
29 | @lisp |
30 | (use-modules (ice-9 readline)) | |
31 | (activate-readline) | |
32 | @end lisp | |
33 | ||
34 | @c FIXME::martin: Review me! | |
35 | ||
36 | The first line will load the necessary code, and the second will | |
37 | activate readline's features for the REPL. If you plan to use this | |
38 | module often, you should save these to lines to your @file{.guile} | |
39 | personal startup file. | |
40 | ||
41 | You will notice that the REPL's behaviour changes a bit when you have | |
85a9b4ed | 42 | loaded the readline module. For example, when you press Enter before |
a0e07ba4 NJ |
43 | typing in the closing parentheses of a list, you will see the |
44 | @dfn{continuation} prompt, three dots: @code{...} This gives you a nice | |
45 | visual feedback when trying to match parentheses. To make this even | |
46 | easier, @dfn{bouncing parentheses} are implemented. That means that | |
47 | when you type in a closing parentheses, the cursor will jump to the | |
85a9b4ed | 48 | corresponding opening parenthesis for a short time, making it trivial to make |
a0e07ba4 NJ |
49 | them match. |
50 | ||
51 | Once the readline module is activated, all lines entered interactively | |
52 | will be stored in a history and can be recalled later using the | |
53 | cursor-up and -down keys. Readline also understands the Emacs keys for | |
54 | navigating through the command line and history. | |
55 | ||
56 | When you quit your Guile session by evaluating @code{(quit)} or pressing | |
57 | Ctrl-D, the history will be saved to the file @file{.guile_history} and | |
58 | read in when you start Guile for the next time. Thus you can start a | |
59 | new Guile session and still have the (probably long-winded) definition | |
60 | expressions available. | |
61 | ||
62 | ||
63 | @node Readline Options | |
64 | @section Readline Options | |
65 | ||
66 | @c FIXME::martin: Review me! | |
67 | ||
68 | @cindex readline options | |
69 | The readline interface module can be configured in several ways to | |
70 | better suit the user's needs. Configuration is done via the readline | |
71 | module's options interface, in a similar way to the evaluator and | |
c936bede | 72 | debugging options (@pxref{User level options interfaces}.) |
a0e07ba4 | 73 | |
4b83d327 KR |
74 | @findex readline-options |
75 | @findex readline-enable | |
76 | @findex readline-disable | |
77 | @findex readline-set! | |
a0e07ba4 NJ |
78 | Here is the list of readline options generated by typing |
79 | @code{(readline-options 'full)} in Guile. You can also see the | |
80 | default values. | |
81 | ||
82 | @smalllisp | |
83 | bounce-parens 500 Time (ms) to show matching opening parenthesis (0 = off). | |
84 | history-length 200 History length. | |
85 | history-file yes Use history file. | |
86 | @end smalllisp | |
87 | ||
88 | The history length specifies how many input lines will be remembered. | |
89 | If the history contains that many lines and additional lines are | |
90 | entered, the oldest lines will be lost. You can switch on/off the | |
91 | usage of the history file using the following call. | |
92 | ||
93 | @lisp | |
94 | (readline-disable 'history) | |
95 | @end lisp | |
96 | ||
97 | The readline options interface can only be used @emph{after} loading | |
98 | the readline module, because it is defined in that module. | |
99 | ||
100 | ||
101 | @page | |
102 | @node Value History | |
103 | @chapter Value History | |
104 | ||
105 | @c FIXME::martin: Review me! | |
106 | ||
107 | @cindex value history | |
108 | Another module which makes command line usage more convenient is | |
109 | @code{(ice-9 history)}. This module will change the REPL so that each | |
110 | value which is evaluated and printed will be remembered under a name | |
111 | constructed from the dollar character (@code{$}) and the number of the | |
112 | evaluated expression. | |
113 | ||
114 | Consider an example session. | |
115 | ||
116 | @example | |
117 | guile> (use-modules (ice-9 history)) | |
118 | guile> 1 | |
119 | $1 = 1 | |
120 | guile> (+ $1 $1) | |
121 | $2 = 2 | |
122 | guile> (* $2 $2) | |
123 | $3 = 4 | |
124 | @end example | |
125 | ||
126 | After loading the value history module @code{(ice-9 history)}, one | |
127 | (trivial) expression is evaluated. The result is stored into the | |
128 | variable @code{$1}. This fact is indicated by the output @code{$1 = }, | |
129 | which is also caused by @code{(ice-9 history)}. In the next line, this | |
130 | variable is used two times, to produce the value @code{$2}, which in | |
131 | turn is used in the calculation for @code{$3}. | |
132 | ||
133 | ||
134 | @c Local Variables: | |
135 | @c TeX-master: "guile.texi" | |
136 | @c End: |