source: project/wiki/eggref/5/breadline @ 39455

Last change on this file since 39455 was 39455, checked in by Vasilij Schneidermann, 6 months ago

Mention macOS-specific workarounds

File size: 9.8 KB
Line 
1== breadline
2
3[[toc:]]
4
5=== Introduction
6
7This egg provides an incomplete set of bindings to the
8[[http://tiswww.case.edu/php/chet/readline/rltop.html|GNU Readline]]
9library, suitable for augmenting {{csi}} and writing a {{csi}}-like
10application with line editing support.  See
11[[https://depp.brause.cc/breadline/examples|the bundled examples]] for
12a {{.csirc}} providing Scheme completion.
13
14=== Author
15
16Vasilij Schneidermann
17
18=== Repository
19
20[[https://depp.brause.cc/breadline]]
21
22=== Current state of the bindings
23
24* Basic interface for reading input and managing history
25* Completion interface
26* Customization of aspects crucial for Scheme programming
27
28=== Requirements
29
30You'll need to have a not too old version of GNU Readline
31installed. This egg has been tested with version 7, but version 6
32should work as well.  In case the auto-detected flags don't work for
33you, make sure to set {{READLINE_CFLAGS}} and {{READLINE_LDLIBS}}
34before installation.  The following subsections show known workarounds
35for platforms where the default build script does not suffice:
36
37==== Ubuntu 18.04
38
39 export READLINE_CFLAGS=-I/usr/include/readline
40 export READLINE_LDLIBS=-lreadline
41 chicken-install breadline
42
43An alternative solution is to set up
44{{/usr/share/pkgconfig/readline.pc}} as described on
45[[https://www.marache.net/post/readline-pc.html|Simon
46Marache-Francisco's blog]]. Edit the file to contain the following,
47then run {{chicken-install breadline}}:
48
49 Name: Readline
50 Description: Gnu Readline library for command line editing
51 URL: http://tiswww.cwru.edu/php/chet/readline/rltop.html
52 Version: 7.0
53 Requires.private: tinfo
54 Libs: -lreadline
55 Cflags: -I/usr/include/readline
56
57==== macOS Homebrew
58
59Ensure that {{pkg-config}} and {{readline}} have been installed via
60Homebrew.
61
62Consider Homebrew's remarks after installing readline:
63
64 readline is keg-only, which means it was not symlinked into /usr/local,
65 because macOS provides BSD libedit.
66 
67 For compilers to find readline you may need to set:
68   export LDFLAGS="-L/usr/local/opt/readline/lib"
69   export CPPFLAGS="-I/usr/local/opt/readline/include"
70 
71 For pkg-config to find readline you may need to set:
72   export PKG_CONFIG_PATH="/usr/local/opt/readline/lib/pkgconfig"
73
74Therefore export all of these, then run {{chicken-install breadline}}.
75
76In case it still doesn't work and {{pkg-config --libs readline}}
77fails, this may be the fault of an incorrect {{readline.pc}} file,
78see [[https://github.com/Homebrew/homebrew-core/issues/38972|Homebrew's issue tracker]]
79and update.
80
81==== mingw-msys2
82
83Assuming a 64bit installation, the egg can be installed as follows:
84
85 pacman -S pkg-config mingw-w64-x86_64-readline
86 export READLINE_CFLAGS=$(pkg-config --cflags readline)
87 export READLINE_LDLIBS=$(pkg-config --libs readline)
88 chicken-install breadline
89
90=== API
91
92==== History
93
94<procedure>(history-length)</procedure>
95
96Returns the current history length.
97
98<parameter>(history-file)</parameter>
99<parameter>(history-file PATH)</parameter>
100
101Specifies the location of the history file for {{make-readline-port}}.
102Defaults to {{#f}} which means to neither read nor write out the
103history.  {{PATH}} may be relative to the current working directory.
104
105<procedure>(add-history! ITEM)</procedure>
106
107Adds {{ITEM}} to the current history.
108
109<procedure>(read-history! FILE)</procedure>
110
111Reads in history items from {{FILE}} and adds them to the current
112history.
113
114<procedure>(write-history! FILE)</procedure>
115
116Writes out current history items to {{FILE}}.
117
118<procedure>(stifle-history! MAX)</procedure>
119
120Configure the current history to hold at most {{MAX}} items.
121
122<procedure>(unstifle-history!)</procedure>
123
124Undo any history stifling.  Returns the previously set maximum amount
125of history items as set by {{stifle-history!}}.  If the history was
126not stifled before, the value is negative.
127
128==== Completion
129
130<procedure>(completer-set! PROC)</procedure>
131
132Set the completion handler to {{PROC}}.  {{PROC}} is called repeatedly
133to collect completions with a fixnum state argument and a string
134prefix.  A state argument of zero means that the completion procedure
135may initialize its data, it is incremented for every subsequent call.
136The completion procedure must either return a completion matching the
137given string prefix or {{#f}} to signal that no further completions
138follow.  It is up to the completion procedure to keep track of what
139completions have been offered and whether any further completions are
140vailable.
141
142<procedure>(completer-word-break-characters-set STRING)</procedure>
143
144Sets the word-breaking characters for completion to {{STRING}}.  The
145default value of {{\t\n\"\\'`@$><=;|&{(}} is suitable for Bash's
146completion.
147
148==== Text Manipulation
149
150<procedure>(insert-text STRING)</procedure>
151
152Insert {{STRING}} into the line at the current cursor position.
153Returns the number of characters inserted.
154
155<procedure>(delete-text START END)</procedure>
156
157Delete the text between {{START}} and {{END}} in the current line.
158Returns the number of characters deleted.
159
160<procedure>(stuff-char CHAR)</procedure>
161
162Insert {{CHAR}} into the Readline input stream. It will be "read"
163before Readline attempts to read characters from the terminal. Up to
164512 characters may be pushed back. Returns {{1}} if the character was
165successfully inserted; {{0}} otherwise.
166
167<procedure>(redisplay)</procedure>
168
169Change what's displayed on the screen to reflect the current contents
170of Readline's buffer.
171
172==== Event hooks
173
174<procedure>(event-hook-set! PROCEDURE)</procedure>
175
176Registers a hook that will be called periodically when Readline is
177waiting for terminal input. By default, this will be called at most
178ten times a second if there is no keyboard input. The argument should
179be a thunk. Its return value is ignored.
180
181Only one event hook may be registered at a time. A
182previously-registered hook may be disabled by passing {{#f}}.
183
184<procedure>(pre-input-hook-set! PROCEDURE)</procedure>
185
186Registers a hook that will be called every time the first input prompt
187has been printed, just before {{readline}} starts reading input
188characters. The argument should be a thunk. Its return value is
189ignored.
190
191Only one pre-input hook may be registered at a time. A
192previously-registered hook may be disabled by passing {{#f}}.
193
194==== Customization
195
196<procedure>(variable-bind! VARIABLE VALUE)</procedure>
197
198Sets a GNU Readline variable to a value.  Both {{VARIABLE}} and
199{{VALUE}} must be strings.
200
201<procedure>(variable-value VARIABLE)</procedure>
202
203Retrieves the current value of the given GNU Readline variable.
204{{VARIABLE}} must be a string.
205
206<procedure>(basic-quote-characters-set STRING)</procedure>
207
208Sets the quoting characters to {{STRING}}, the default value being
209{{"'}}.  This setting is used for paren blinking to determine strings.
210
211<procedure>(paren-blink-timeout-set MICROSECS)</procedure>
212
213Sets the timeout for paren blinking in microseconds, the default value
214being 500000 microseconds.  Note that typing a closing paren will not
215blink the opening paren unless {{blink-matching-paren}} has been set.
216
217==== Line editing
218
219<procedure>(readline PROMPT)</procedure>
220
221Read in a line of user input after printing {{PROMPT}}.  Returns the
222user input or {{#f}} if input has been terminated with {{C-d}}.
223
224<procedure>(make-readline-port [PROMPT])</procedure>
225
226Returns an input port using GNU Readline for line editing and history
227management.  {{PROMPT}} may be a string or a thunk returning a string
228and defaults to {{(repl-prompt)}}.
229
230==== Cleanup
231
232<procedure>(cleanup-after-signal!)</procedure>
233<procedure>(reset-after-signal!)</procedure>
234
235Procedures to call in sequence after receiving a signal in a signal
236handler to ensure a clean terminal and readline state.
237
238<procedure>(reset-terminal! [TERMINAL-NAME])</procedure>
239
240Procedure to call after program exit to ensure a clean terminal state.
241The optional argument {{TERMINAL-NAME}} defaults to the value of the
242{{TERM}} environment variable.
243
244=== Examples
245
246<enscript highlight="scheme">
247(import (chicken process signal))
248(import breadline)
249
250(set-signal-handler! signal/int
251                     (lambda _
252                       (cleanup-after-signal!)
253                       (reset-after-signal!)))
254(on-exit reset-terminal!)
255
256(let loop ()
257  (let ((input (readline "> ")))
258    (if input
259        (begin
260          ;; processing code goes here
261          (print input)
262          (add-history! input)
263          (loop))
264        (newline))))
265</enscript>
266
267Further examples for usage in {{csi}} and writing your own completer
268can be found [[https://depp.brause.cc/breadline/examples|in the
269repository]].
270
271=== License
272
273 Copyright 2016 Vasilij Schneidermann
274 
275 This program is free software: you can redistribute it and/or modify
276 it under the terms of the GNU General Public License as published by
277 the Free Software Foundation, either version 3 of the License, or (at
278 your option) any later version.
279 
280 This program is distributed in the hope that it will be useful, but
281 WITHOUT ANY WARRANTY; without even the implied warranty of
282 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
283 General Public License for more details.
284 
285 A full copy of the GPL license can be found at
286 <http://www.gnu.org/licenses/>.
287
288=== Version history
289
290==== 0.8
291
292* Expose cleanup procedures for signal and exit handlers
293* Make use of these procedures in examples
294
295==== 0.7
296
297* Quote user-provided environment variables in Windows build script
298* Add build instructions for Ubuntu 18.04 and mingw-msys2
299
300==== 0.6
301
302* Change build script to use Scheme when possible
303* Improve examples
304
305==== 0.5
306
307* Improve pkg-config check
308
309==== 0.4
310
311* Use custom build script trying to use pkg-config, then falling back to {{CFLAGS}} and {{LDFLAGS}}
312
313==== 0.3
314
315* Support thunks for make-readline-port and its prompt (thanks Macro Maggi!)
316* Expose history-length procedure (thanks Macro Maggi!)
317
318==== 0.2
319
320* Link explicitly against ncurses (thanks Marco Maggi!)
321* Expose event and pre-input hooks and text modification functions (thanks Evhan!)
322
323==== 0.1
324
325* Initial release
Note: See TracBrowser for help on using the repository browser.