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