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

Last change on this file since 24755 was 24755, checked in by svnwiki, 10 years ago

Anonymous wiki edit for IP [67.86.66.31]: clarify how to get readline support

File size: 6.5 KB
Line 
1[[tags: egg]]
2[[toc:]]
3
4== readline
5
6A binding for the GNU readline library.
7
8== Interface
9
10<procedure>(gnu-readline PROMPT)</procedure>
11
12Reads a line using the GNU readline() function and returns a string. PROMPT should also be a string.
13
14
15<procedure> (gnu-readline-clear-history)</procedure>
16
17Clears the history buffer.
18
19
20<procedure> (gnu-readline-read-history FILENAME)</procedure>
21
22Reads the history buffer from the file FILENAME (or ~/.history if FILENAME is #f). Returns 0 on success.
23
24<procedure> (gnu-readline-write-history FILENAME)</procedure>
25
26Writes the history buffer to the file FILENAME (or ~/.history if FILENAME is #f). Returns 0 on success.  Do not use unless you want to clobber simultaneous sessions.
27
28
29<procedure> (gnu-readline-append-history FILENAME)</procedure>
30
31Appends only the new entries to FILENAME.
32
33
34<procedure> (gnu-readline-new-lines)</procedure>
35
36Returns the number of new entries (input lines from this session).
37
38
39<procedure> (gnu-readline-truncate-history FILENAME NUMLINES)</procedure>
40
41Truncates the history file FILENAME (or ~/.history if FILENAME is #f) to NUMLINES lines. Returns 0 on success.
42
43<procedure> (gnu-history-install-file-manager FILENAME [NUMLINES])</procedure>
44
45If you also want to make the command history span sessions, add the following:
46
47{{(gnu-history-install-file-manager (string-append (or (get-environment-variable "HOME") ".") "/.csi.history"))}}
48
49By 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 gnu-history-install-file-manager. If #f is passed in, no history-file-pruning will take place.
50
51
52<procedure> (make-gnu-readline-port [PROMPT] [PROMPT2])</procedure>
53
54Returns 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.
55
56
57<procedure> (gnu-readline-set-bounce-ms TIME)</procedure>
58
59Changes the time that the cursor spends bouncing on the matching parenthesis - the default 500ms. To turn bouncing off completely, set to zero.
60
61<procedure> (gnu-readline-parse-and-bind CONFIG)</procedure>
62
63Passes string CONFIG straight to the readline library for parsing (see the readline manual page for details).
64
65
66This extension supports static linking.
67
68== Examples
69
70 % csi -quiet
71 #;1> (use readline)
72 #;2> (current-input-port (make-gnu-readline-port))
73 #;3>
74
75To get csi to use readline by default, and to keep a history, use the following (in your ~/.csirc file):
76
77 (use readline irregex)
78 (current-input-port (make-gnu-readline-port))
79 (gnu-history-install-file-manager
80  (string-append (or (get-environment-variable "HOME") ".") "/.csi.history"))
81
82Note: you must create the {{.csi.history}} file, {{readline}} will not create it:
83
84 % touch ~/.csi.history
85
86To set readline to behave somewhat like vi:
87 (gnu-readline-parse-and-bind "set editing-mode vi")
88
89== Installation problems
90
91This 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.
92
93=== Mac OS X
94
95==== 10.6 (Snow Leopard)
96
9710.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:
98
99 export CSC_OPTIONS="-I/opt/local/include -L/opt/local/lib"
100
101...before the {{chicken-install}}. If this doesn't work, try an additional
102
103 export LIBRARY_PATH=/opt/local/lib
104
105
106==== Pre-10.6
107
108Mac OS X versions prior to 10.5 (Leopard) ship with an older {{readline}}, causing the following error when you install this egg:
109
110 /usr/bin/ld: Undefined symbols:
111 _history_truncate_file
112
113To fix this, install a copy of GNU readline in {{/usr/local/lib}} or, if you're using MacPorts, symlink it:
114
115 ln -s /opt/local/lib/libreadline.dylib /usr/local/lib
116
117DO NOT modify the readline link in {{/usr/lib}}.
118=== Debian GNU/Linux and derivatives (such as Ubuntu)
119
120In the case of Debian, you should probably install the package {{libreadline-dev}}, which is not installed by default.
121== About this egg
122
123=== Author
124
125Tony Garnock-Jones
126
127=== Version history
128
129; 1.993 : fixed buggy build bugs caused by repeated build "fixes" (Jim Ursetto)
130; 1.992 : fixed buggy fixes made by felix (thanks to ewfalor)
131; 1.991 : fixed buggy setup script (thanks to ewfalor)
132; 1.99 : Ported to Chicken 4
133; 1.97 : Fixed an old typo that could conceivably cause errors [elf]
134; 1.96 : Fixed build process for real this time (ensuring tests for lib availability actually do set, etc.) [elf]
135; 1.95 : Fixed build process [elf]
136; 1.94 : Added backtraces to control-c breaks [elf]
137; 1.93 : Fixed history so that multiple sessions dont clobber each other. [elf]
138; 1.92 : Added proper signal handling [elf]
139; 1.91 : Added support for static linking [felix]
140; 1.9 : Ignores duplicate history entries [Thanks to Toby Butzon]
141; 1.8 : Empty lines are not added to history [Thanks to Dan Muresan]
142; 1.7 : Added parenthesis bouncing, a new auto-complete [Heath Johns]
143; 1.6 : Export *completion-entry-function* to support autocomplete [Alejandro Forero Cuervo]
144; 1.5 : prompt argument to make-gnu-readline-port is optional [felix]
145; 1.4 : Replaced use of (end-of-file) with #!eof
146; 1.3 : Checks more possible libraries to link with at build time [Thanks to Peter Bex]
147; 1.2 : Adapted to new setup scheme.
148; 1.1 : More features, changed license to GPL, links with either libtermcap or libncurses.
149; 1.0 : Initial release
150
151=== License
152
153 Copyright (c) 2002 Tony Garnock-Jones
154 Copyright (c) 2006 Heath Johns (paren bouncing and auto-completion code)
155 
156 This program is free software; you can redistribute it and/or modify
157 it under the terms of the GNU General Public License as published by
158 the Free Software Foundation; either version 2 of the License, or
159 (at your option) any later version.
160 
161 This program is distributed in the hope that it will be useful,
162 but WITHOUT ANY WARRANTY; without even the implied warranty of
163 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
164 GNU General Public License for more details.
165 
166 You should have received a copy of the GNU General Public License
167 along with this program; if not, write to the Free Software
168 Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
169
Note: See TracBrowser for help on using the repository browser.