Debian Codegraph @

doc/HOWTO-line-edit.adoc

raw
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)...