source: project/wiki/eggref/4/readline @ 32667

Last change on this file since 32667 was 32667, checked in by Alexej Magura, 4 years ago

Updated the toplevel commands; added v4.1.1 to version history.

File size: 12.0 KB
Line 
1[[tags: egg]]
2[[toc:]]
3
4== Readline
5
6An interface to the GNU readline library
7
8== Interface
9
10=== Toplevel Commands
11==== ,!!
12Evaluates the previous command.
13
14This command is never added to the history list, sorry: it broke the Matrix.
15
16
17(j/k It caused an infinite loop when entered twice in a row, so I just made it so that the previous command can never be {{,!!}}).
18
19==== ,h-clear
20Clears the current session's history list.
21
22==== ,h-save
23Enable/disable saving session history on exit
24
25It is enabled by default.
26
27==== ,h-rec
28Enable/disable recording history for the current session
29
30It's enabled by default.
31
32==== ,h-load
33Read file contents into the history list for the current session.
34
35Currently, there might be a bug (I haven't checked) where the file's name has an extra space added to it unless you enter it on a separate line:
36 ,h-load
37 ~/.csi_hist
38
39==== ,vi-mode
40Sets the current editing mode to Vi.
41
42The equivalent function call would be:
43 (readline#parse-and-bind "set editing-mode vi")
44
45==== ,emacs-mode
46Sets the current editing mode to Emacs
47
48=== Variables
49==== version
50<type>string</type>
51The current version string.
52
53==== session
54<type>kvlist</type>
55A Key-value list of settings that affect how some of the egg's functions behave for the current session.
56
57===== load-history-file
58<type>boolean</type>
59Used by {{install-history-file}}.  Set to {{#t}} by default; when set to {{#f}}, the history file will '''NOT''' be loaded at start-up.
60
61===== save-history-on-exit
62<type>boolean</type>
63Used by {{install-history-file}}.  Set to {{#t}} by default; when set to {{#f}}, the current session's history will '''NOT''' be saved to the history file on exit.
64
65===== record-history
66<type>boolean</type>
67Used by {{,rl-rec}}.  Set to {{#t}} by default; when set to {{#f}} it disables recording history for the current session.
68
69===== verify-history-expansions
70<type>boolean</type>
71Settings this to true makes {{,rl-!!}} wait for you to press enter instead of inserting {{EOL}} automatically.
72
73=== Functions
74==== use-legacy-bindings
75<procedure>(use-legacy-bindings)</procedure>
76
77Exports symbols aliasing the v1.993 API to the current API.
78
79Use this function only if you have legacy code that uses the older API.
80
81
82Returns {{(void)}} on success; will cause an error on fail.
83
84 Example:
85
86 (readline#use-legacy-bindings)
87 (current-input-port (make-gnu-readline-port))
88
89==== readline
90<procedure>(readline prompt1 [prompt2] )</procedure>
91
92Reads a line using the GNU readline() function and returns a string.
93
94
95Both arguments must be strings; {{prompt2}} is optional.
96
97==== %signal-cleanup
98<procedure>(%signal-cleanup)</procedure>
99
100Sets the state of the underlying readline environment to a clean slate.
101
102'''NOTE''' Calls {{free()}}; so using this more than once consecutively may result in undefined behavior, as in a segfault.
103
104==== clear-history
105<procedure>(clear-history)</procedure>
106
107Clears the history buffer.
108
109==== read-history
110<procedure>(read-history [file])</procedure>
111
112Reads contents of the provided file into the history buffer.
113
114When called without file-name, reads from ~/.history.  Returns 0 on success, or errno on fail.
115
116==== write-history
117<procedure>(write-history [file])</procedure>
118
119Writes the history buffer to {{file}} or ~/.history when no {{file}} is provided.
120
121
122Returns {{0}} on success; {{errno}} on fail.
123
124
125'''USE AT YOUR OWN RISK!'''
126
127Using this may clobber simultaneous sessions.
128
129==== append-history
130<procedure>(append-history [file])</procedure>
131
132Appends history buffer from the ''current'' session to {{file}}.
133
134
135Returns {{0}} on success; {{errno}} on fail.
136
137==== history-newlines
138<procedure>(history-newlines)</procedure>
139
140Returns the number of entries from the ''current'' session.
141
142==== truncate-history
143<procedure>(truncate-history [file] [n])</procedure>
144
145Truncates provided history {{file}} to a maximum of {{n}} lines.
146
147Returns {{0}} on win; {{errno}} on fail.
148
149==== install-history-file
150<procedure>(install-history-file [homedir] [filename] [nlines])</procedure>
151
152If you also want to make the command history span sessions, add the following to your {{~/.csirc}}:
153
154{{(install-history-file)}}
155
156By default this will save 1000 lines of history between sessions (it will prune the history file to 1000 lines at startup). For a different history size, pass the desired number of lines as the (optional) second argument to history-install-file-manager. If {{#f}} or no second argument is passed in, no history-file-pruning will take place.
157
158'''NOTE''' Do not use this in conjunction with {{rlwrap}}.  The maintainer did so and experience some very weird behavior from {{csi}}.
159
160==== make-readline-port
161<procedure>(make-readline-port [prompt] [prompt2])</procedure>
162
163Returns an input-port that uses the GNU readline facility. If PROMPT is not given, the value returned by (repl-prompt) is used for generating the current prompt (see the Chicken manual for more details about repl-prompt). PROMPT2 is used when there are still unclosed parenthesis; if not given, an appropriate default is generated.
164
165==== set-bounce-ms
166<procedure>(set-bounce-ms ms)</procedure>
167
168Changes the time that the cursor spends bouncing on the matching parenthesis - the default 500ms. To turn bouncing off completely, set it to {{0}}.
169
170==== parse-and-bind
171<procedure>(parse-and-bind string)</procedure>
172
173Passes {{string}} straight to the readline library for parsing (see the readline manual page for details).
174
175==== history-list
176<procedure>(history-list)</procedure>
177Returns the history list as a newline separated list.
178
179==== history-position
180<procedure>(history-position [pos])</procedure>
181Returns the current ''offset'' within the history list.
182
183Passing ''pos'' sets the current ''offset''.
184
185==== add-history
186<procedure>(%history-add% string)</procedure>
187Adds ''string'' to the history list.
188
189'''NOTE'''
190
191This function exists primarily for testing purposes.
192
193Returns {{void}}
194
195
196==== remove-history
197<procedure>(%remove-history% offset)</procedure>
198Removes and '''frees''' the specified history entry and its associated memory.
199
200==== eval-last-history-line
201<procedure>(eval-last-history-line [script])</procedure>
202The function behind {{,rl-!!}}.
203
204This function is '''not''' added to the history unless ''script'' is true.
205DO '''NOT''' pass ''script'' as true, unless you know what you are doing: it makes it possible to accidentally cause an infinite loop if the previous command was also {{eval-last-history-line #t}}!!
206
207'''NOTE'''
208
209The line does not have to be from the current session.
210Also, I don't know what happens when there isn't said line, but I reckon it'd cause a segfault; I'll see about fixing that in the 3.1 release.
211
212== Building
213
214This extension supports static linking.
215
216=== Examples
217
218 % csi -quiet
219 #;1> (use readline)
220 #;2> (current-input-port (make-readline-port))
221 #;3>
222
223To get csi to use readline by default, and to keep a history, use the following (in your ~/.csirc file):
224
225 (use readline)
226 (current-input-port (make-readline-port))
227 (install-history-file #f "/.csi.history")
228
229To set readline to behave somewhat like vi:
230 (parse-and-bind "set editing-mode vi")
231
232== Installation problems
233
234This extension requires GNU readline.  You will receive errors if you don't have the C header files for your readline installation or if you use some versions of the BSD readline alternative, libedit.
235
236=== Mac OS X
237
238==== 10.8/10.9 (Snow Leopard/Mavericks)
239Using bash...
240
241 brew install readline
242 readline_version=$(brew list readline --versions)
243 readline_version=${readline_version##* }
244 export CSC_OPTIONS="-I/usr/local/Cellar/readline/$readline_version/include -L/usr/local/Cellar/readline/$readline_version/lib -Wl,-flat_namespace,-undefined,suppress"
245 unset readline_version
246 brew reinstall chicken
247 chicken-install readline
248
249==== 10.6 (Snow Leopard)
250
25110.6 ships with a much older version of readline than this egg expects.  Fortunately, recent versions of {{readline}} in MacPorts work.  {{readline @6.0.000_2+darwin}} is confirmed to work with 10.6.2.  First install the {{readline}} package from MacPorts and then do this:
252
253 export CSC_OPTIONS="-I/opt/local/include -L/opt/local/lib"
254
255...before the {{chicken-install}}. If this doesn't work, try an additional
256
257 export LIBRARY_PATH=/opt/local/lib
258
259
260==== Pre-10.6
261
262Mac OS X versions prior to 10.5 (Leopard) ship with an older {{readline}}, causing the following error when you install this egg:
263
264 /usr/bin/ld: Undefined symbols:
265 _history_truncate_file
266
267To fix this, install a copy of GNU readline in {{/usr/local/lib}} or, if you're using MacPorts, symlink it:
268
269 ln -s /opt/local/lib/libreadline.dylib /usr/local/lib
270
271DO NOT modify the readline link in {{/usr/lib}}.
272=== Debian GNU/Linux and derivatives (such as Ubuntu)
273
274In the case of Debian, you should probably install the package {{libreadline-dev}}, which is not installed by default.
275== About this egg
276
277=== Author
278
279Tony Garnock-Jones
280
281Maintained by Alexej Magura
282
283=== Version history
284; 4.1.1 : Slight changes to the toplevel commands interface.
285; 4.1.0 : Necessary updates in light of the changes in Chicken v4.10 as compared to Chicken v4.9.
286; 4.0.0 : Version bump due to v3.0b2 being considered newer than v3.1.1.
287; 3.1.1 : Removes `regex` as a dependency (patch).
288; 3.1 : Removes `current-history-line' and renames all of the history related functions.
289; 3.0 : Removes a lot of the stuff introduced by 2.0; adds toplevel-commands for convience.
290; 3.0b2 : Fixed memleaks in history-list function and str_unquotd
291; 3.0b1 : Made a few tweaks to the API to keep it in sync with the documentation I've written.
292; 3.0b : Lots of API additions and a few changes; more efficient memory usage; removed libbsd as an optional depend
293; 2.4 : Fixed setup file and version string.
294; 2.3 : Reverted back to v1.993 setup file due to that fixes a bug with automated builds; added checks for libbsd
295; 2.2 : Fixed more bugs with the detection of unclosed expressions
296; 2.1 : Fixed a bug with legacy support where the aliases pointed to uninterned symbols.
297; 2.0 : Fixed a bug with the unclosed-exp-prompt, where {{"<NEWLINE>}} did not count as an unclosed expression.  Added more history functions and other cool stuff  (see soon-to-appear changelog for details)
298; 1.993 : fixed buggy build bugs caused by repeated build "fixes" (Jim Ursetto)
299; 1.992 : fixed buggy fixes made by felix (thanks to ewfalor)
300; 1.991 : fixed buggy setup script (thanks to ewfalor)
301; 1.99 : Ported to Chicken 4
302; 1.97 : Fixed an old typo that could conceivably cause errors [elf]
303; 1.96 : Fixed build process for real this time (ensuring tests for lib availability actually do set, etc.) [elf]
304; 1.95 : Fixed build process [elf]
305; 1.94 : Added backtraces to control-c breaks [elf]
306; 1.93 : Fixed history so that multiple sessions dont clobber each other. [elf]
307; 1.92 : Added proper signal handling [elf]
308; 1.91 : Added support for static linking [felix]
309; 1.9 : Ignores duplicate history entries [Thanks to Toby Butzon]
310; 1.8 : Empty lines are not added to history [Thanks to Dan Muresan]
311; 1.7 : Added parenthesis bouncing, a new auto-complete [Heath Johns]
312; 1.6 : Export *completion-entry-function* to support autocomplete [Alejandro Forero Cuervo]
313; 1.5 : prompt argument to make-gnu-readline-port is optional [felix]
314; 1.4 : Replaced use of (end-of-file) with #!eof
315; 1.3 : Checks more possible libraries to link with at build time [Thanks to Peter Bex]
316; 1.2 : Adapted to new setup scheme.
317; 1.1 : More features, changed license to GPL, links with either libtermcap or libncurses.
318; 1.0 : Initial release
319
320=== License
321
322 Copyright (c) 2002 Tony Garnock-Jones
323 Copyright (c) 2006 Heath Johns (paren bouncing and auto-completion code)
324
325 This program is free software; you can redistribute it and/or modify
326 it under the terms of the GNU General Public License as published by
327 the Free Software Foundation; either version 2 of the License, or
328 (at your option) any later version.
329
330 This program is distributed in the hope that it will be useful,
331 but WITHOUT ANY WARRANTY; without even the implied warranty of
332 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
333 GNU General Public License for more details.
334
335 You should have received a copy of the GNU General Public License
336 along with this program; if not, write to the Free Software
337 Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
Note: See TracBrowser for help on using the repository browser.