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

Last change on this file since 37558 was 37558, checked in by wasamasa, 15 months ago

Revert spam

File size: 7.0 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.
11
12=== Author
13
14Vasilij Schneidermann
15
16=== Repository
17
18[[https://github.com/wasamasa/breadline]]
19
20=== Current state of the bindings
21
22* Basic interface for reading input and managing history
23* Completion interface
24* Customization of aspects crucial for Scheme programming
25
26=== Requirements
27
28You'll need to have a not too old version of GNU Readline
29installed. This egg has been tested with version 7, but version 6
30should work as well.  In case the auto-detected flags don't work for
31you, make sure to set {{READLINE_CFLAGS}} and {{READLINE_LDLIBS}}
32before installation.
33
34=== API
35
36==== History
37
38<procedure>(history-length)</procedure>
39
40Returns the current history length.
41
42<parameter>(history-file)</parameter>
43<parameter>(history-file PATH)</parameter>
44
45Specifies the location of the history file for {{make-readline-port}}.
46Defaults to {{#f}} which means to neither read nor write out the
47history.  {{PATH}} may be relative to the current working directory.
48
49<procedure>(add-history! ITEM)</procedure>
50
51Adds {{ITEM}} to the current history.
52
53<procedure>(read-history! FILE)</procedure>
54
55Reads in history items from {{FILE}} and adds them to the current
56history.
57
58<procedure>(write-history! FILE)</procedure>
59
60Writes out current history items to {{FILE}}.
61
62<procedure>(stifle-history! MAX)</procedure>
63
64Configure the current history to hold at most {{MAX}} items.
65
66<procedure>(unstifle-history!)</procedure>
67
68Undo any history stifling.  Returns the previously set maximum amount
69of history items as set by {{stifle-history!}}.  If the history was
70not stifled before, the value is negative.
71
72==== Completion
73
74<procedure>(completer-set! PROC)</procedure>
75
76Set the completion handler to {{PROC}}.  {{PROC}} is called repeatedly
77to collect completions with a fixnum state argument and a string
78prefix.  A state argument of zero means that the completion procedure
79may initialize its data, it is incremented for every subsequent call.
80The completion procedure must either return a completion matching the
81given string prefix or {{#f}} to signal that no further completions
82follow.  It is up to the completion procedure to keep track of what
83completions have been offered and whether any further completions are
84vailable.
85
86<procedure>(completer-word-break-characters-set STRING)</procedure>
87
88Sets the word-breaking characters for completion to {{STRING}}.  The
89default value of {{\t\n\"\\'`@$><=;|&{(}} is suitable for Bash's
90completion.
91
92==== Text Manipulation
93
94<procedure>(insert-text STRING)</procedure>
95
96Insert {{STRING}} into the line at the current cursor position.
97Returns the number of characters inserted.
98
99<procedure>(delete-text START END)</procedure>
100
101Delete the text between {{START}} and {{END}} in the current line.
102Returns the number of characters deleted.
103
104<procedure>(stuff-char CHAR)</procedure>
105
106Insert {{CHAR}} into the Readline input stream. It will be "read"
107before Readline attempts to read characters from the terminal. Up to
108512 characters may be pushed back. Returns {{1}} if the character was
109successfully inserted; {{0}} otherwise.
110
111<procedure>(redisplay)</procedure>
112
113Change what's displayed on the screen to reflect the current contents
114of Readline's buffer.
115
116==== Event hooks
117
118<procedure>(event-hook-set! PROCEDURE)</procedure>
119
120Registers a hook that will be called periodically when Readline is
121waiting for terminal input. By default, this will be called at most
122ten times a second if there is no keyboard input. The argument should
123be a thunk. Its return value is ignored.
124
125Only one event hook may be registered at a time. A
126previously-registered hook may be disabled by passing {{#f}}.
127
128<procedure>(pre-input-hook-set! PROCEDURE)</procedure>
129
130Registers a hook that will be called every time the first input prompt
131has been printed, just before {{readline}} starts reading input
132characters. The argument should be a thunk. Its return value is
133ignored.
134
135Only one pre-input hook may be registered at a time. A
136previously-registered hook may be disabled by passing {{#f}}.
137
138==== Customization
139
140<procedure>(variable-bind! VARIABLE VALUE)</procedure>
141
142Sets a GNU Readline variable to a value.  Both {{VARIABLE}} and
143{{VALUE}} must be strings.
144
145<procedure>(variable-value VARIABLE)</procedure>
146
147Retrieves the current value of the given GNU Readline variable.
148{{VARIABLE}} must be a string.
149
150<procedure>(basic-quote-characters-set STRING)</procedure>
151
152Sets the quoting characters to {{STRING}}, the default value being
153{{"'}}.  This setting is used for paren blinking to determine strings.
154
155<procedure>(paren-blink-timeout-set MICROSECS)</procedure>
156
157Sets the timeout for paren blinking in microseconds, the default value
158being 500000 microseconds.  Note that typing a closing paren will not
159blink the opening paren unless {{blink-matching-paren}} has been set.
160
161==== Line editing
162
163<procedure>(readline PROMPT)</procedure>
164
165Read in a line of user input after printing {{PROMPT}}.  Returns the
166user input or {{#f}} if input has been terminated with {{C-d}}.
167
168<procedure>(make-readline-port [PROMPT])</procedure>
169
170Returns an input port using GNU Readline for line editing and history
171management.  {{PROMPT}} may be a string or a thunk returning a string
172and defaults to {{(repl-prompt)}}.
173
174=== Examples
175
176<enscript highlight="scheme">
177(import breadline)
178
179(let loop ()
180  (let ((input (readline "> ")))
181    (if input
182        (begin
183          ;; processing code goes here
184          (print input)
185          (add-history! input)
186          (loop))
187        (newline))))
188</enscript>
189
190Further examples for usage in {{csi}} and writing your own completer
191can be found
192[[https://github.com/wasamasa/readline/tree/master/examples|in the repository]].
193
194=== License
195
196 Copyright 2016 Vasilij Schneidermann
197 
198 This program is free software: you can redistribute it and/or modify
199 it under the terms of the GNU General Public License as published by
200 the Free Software Foundation, either version 3 of the License, or (at
201 your option) any later version.
202 
203 This program is distributed in the hope that it will be useful, but
204 WITHOUT ANY WARRANTY; without even the implied warranty of
205 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
206 General Public License for more details.
207 
208 A full copy of the GPL license can be found at
209 <http://www.gnu.org/licenses/>.
210
211=== Version history
212
213==== 0.6
214
215* Change build script to use Scheme when possible
216* Improve examples
217
218==== 0.5
219
220* Improve pkg-config check
221
222==== 0.4
223
224* Use custom build script trying to use pkg-config, then falling back to {{CFLAGS}} and {{LDFLAGS}}
225
226==== 0.3
227
228* Support thunks for make-readline-port and its prompt (thanks Macro Maggi!)
229* Expose history-length procedure (thanks Macro Maggi!)
230
231==== 0.2
232
233* Link explicitly against ncurses (thanks Marco Maggi!)
234* Expose event and pre-input hooks and text modification functions (thanks Evhan!)
235
236==== 0.1
237
238* Initial release
Note: See TracBrowser for help on using the repository browser.