| 1 |
# Dissecting line-edit feature |
| 2 |
|
| 3 |
You can use line editing on gosh REPL if the terminal is capable. The |
| 4 |
feature is implemented entirely in Gauche itself, instead of relying on |
| 5 |
external libraries such as libreadline. This document describes the |
| 6 |
internals of the line editing feature for those who want to fix bugs |
| 7 |
or add new features. |
| 8 |
|
| 9 |
## Modules involved in the line editing feature |
| 10 |
|
| 11 |
There are number of modules involved in this feature. |
| 12 |
|
| 13 |
- `gauche.interactive.editable-reader` : This module is autoloaded |
| 14 |
when `gosh` is invoked in the interactive mode. First it tries to |
| 15 |
obtain a default console (`text.console`), and if it succeeds, create |
| 16 |
a line editor instance (`text.line-edit`) and returns several procedures |
| 17 |
to be called from `read-eval-print-loop`. If it can't get a default |
| 18 |
console (e.g. the terminal is not capable, or the stdios are connected |
| 19 |
to non-terminal device), then it returns false values and |
| 20 |
`read-eval-print-loop` falls back to a basic I/O without editing |
| 21 |
capability. |
| 22 |
This module also calls load/save edit history API in the appropriate |
| 23 |
time. |
| 24 |
|
| 25 |
- `text.console`: This module provides an abstract API to control consoles |
| 26 |
such as cursor placements. |
| 27 |
Currently it supports VT100-compatible console and Windows console. |
| 28 |
It used to be a standard to use termcap/terminfo to abstract the device |
| 29 |
difference, and curses for high-level console manipulations. However, |
| 30 |
the world has moved on. We no longer have wide variations of terminal |
| 31 |
controls, so that adding dependencies to those external libraries is |
| 32 |
overkill. Besides, Windows console requires totally different controls |
| 33 |
than the traditional Unix consoles. So we decided to roll our own. |
| 34 |
|
| 35 |
- `text.line-edit`: This module effectively implements a text editor. |
| 36 |
It uses `text.gap-buffer` for the buffer structure and `data.ring-buffer` |
| 37 |
for the kill ring. It uses `text.console` for drawing, so it is |
| 38 |
independent from the actual console device. It also supports |
| 39 |
unlimited undoing, and save/load histories. |
| 40 |
|
| 41 |
- `text.gap-buffer`: Implements a gap buffer, suitable for the back-end |
| 42 |
of text editor. |
| 43 |
|
| 44 |
## Startup sequence - what happens before you get `gosh$` prompt |
| 45 |
|
| 46 |
The main program of `gosh` calls `user#read-eval-print-loop` if no |
| 47 |
script file is given. If `-q` option is given to `gosh`, it is |
| 48 |
`gauche#read-eval-print-loop` (defined in `libeval.scm`), which only |
| 49 |
provides very basic REPL. However, if `-q` option isn't given, |
| 50 |
`gauche.interactive` is loaded first which shadows `read-eval-print-loop`, |
| 51 |
so that `gauche.interactive#read-eval-print-loop` is invoked instead. |
| 52 |
|
| 53 |
While loading `gauche.interactive`, `make-editable-reader` of |
| 54 |
`gauche.inetractive.editable-reader` is invoked. It tries to get |
| 55 |
a default console by `text.console#make-default-console`. If it can, |
| 56 |
it returns four values - A procedure to read an S-expr, to read a line, |
| 57 |
a thunk to skip trailing whitespaces, and `<line-edit-context>`. |
| 58 |
The returned readers are line-edit enabled. |
| 59 |
|
| 60 |
The first three procedures are passed to `gauche.interactive#make-repl-reader`, |
| 61 |
which returns a reader that (1) recognizes top-level REPL commands, |
| 62 |
and (2) consume trailing whitespaces after S-expression input. |
| 63 |
|
| 64 |
If line editing is not enabled (by `-fno-line-edit` option, or from |
| 65 |
an environment variable), or `make-editable-reader` can't obtain |
| 66 |
a default console, a repl reader is created with |
| 67 |
`(make-repl-reader read read-line consume-trailing-whitespaces)`. |
| 68 |
Thus, it recognizes the top level REPL commands, but does not use |
| 69 |
line editing. |
| 70 |
|
| 71 |
The `gauche.interactive#read-eval-print-loop` needs a _reader_, an |
| 72 |
_evaluator_, a _printer_, and a _prompter_. _Reader_ and _prompter_ |
| 73 |
are constructed as follows. |
| 74 |
|
| 75 |
. If line editing is enabled: |
| 76 |
- _Prompter_ actually does nothing, since the line editor needs to know |
| 77 |
the columns used by the prompt. |
| 78 |
- _Reader_ invokes `text.line-edit#read-line/edit`, which set the console |
| 79 |
to 'rare' mode, query the screen size and the current cursor location, |
| 80 |
show the prompt, and goes into editor mode. |
| 81 |
. If line editing is disabled: |
| 82 |
- _Prompter_ displays the prompt. |
| 83 |
- _Reader_ reads from the current input port, and handles the top-level |
| 84 |
REPL command and trailing whitespaces if needed. |
| 85 |
|
| 86 |
### The editor - `read-line/edit` |
| 87 |
|
| 88 |
An instance of `<line-edit-context>` maintains the state of line editing. |
| 89 |
It is coupled with an instance of `<console>`; while line editing is on, |
| 90 |
all console I/O should be done through `<line-edit-context>`, or the |
| 91 |
state it keeps and the actual content displayed on terminal become |
| 92 |
out of sync. |
| 93 |
|
| 94 |
Line editing is on when you call `read-line/edit` with an a line-edit |
| 95 |
context. It changes the console mode to monitor keystrokes, then |
| 96 |
interacts with the user until they "commit" the input, then changes |
| 97 |
the console mode back to the original mode and returns the text |
| 98 |
the user committed. |
| 99 |
|
| 100 |
The context has a table to map keystrokes to edit commands. A new |
| 101 |
context gets a copy of the default map. You can modify the map of |
| 102 |
a context without affecting other contexts. |
| 103 |
|
| 104 |
### Defining edit commands |
| 105 |
|
| 106 |
An edit command is a procedure that takes three arguments, |
| 107 |
a context, a gap-buffer, and a keystroke object. It may change |
| 108 |
the content of the buffer, and must return one of the following |
| 109 |
objects. In general, edit commands shouldn't directly change the |
| 110 |
state of the context. |
| 111 |
|
| 112 |
- 'visible : the command changed something visible so we need to |
| 113 |
redisplay, but we don't need to save the change in |
| 114 |
the actual buffer. The selection is cleared. |
| 115 |
- 'unchanged : no change visually and internally; we break |
| 116 |
undo sequence and reset last yank, but not clear |
| 117 |
selection. |
| 118 |
This occurs, for example, backward-char at the |
| 119 |
beginning of the input. |
| 120 |
- 'nop : totally ignore the key input. |
| 121 |
- 'redraw : we won't change the state of the editor, but |
| 122 |
we reobtain the cursor position before redrawing |
| 123 |
the buffer content. This is necessary when the command |
| 124 |
wrote something on the screen and we don't want to clobber |
| 125 |
it. |
| 126 |
- 'moved : the command only moved cursor pos. requires redisplay, |
| 127 |
but we keep selection. |
| 128 |
- #<eof> : end of input - either input port is closed, or |
| 129 |
the user typed EOT char when the buffer is empty. |
| 130 |
- 'commit : record the current buffer to the history, and |
| 131 |
returns it. |
| 132 |
- 'undone : the command undid the change. we record the fact, |
| 133 |
for the consecutive undo behaves differently than |
| 134 |
other commands. |
| 135 |
- <edit-directive> : the command changed the buffer contents, |
| 136 |
and the return value is an edit directive to undo the |
| 137 |
change. |
| 138 |
- (yanked <edit-directive>) : this is only returned by yank and yank-pop |
| 139 |
command. |
| 140 |
|
| 141 |
...(more to come)... |