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

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

Changes applied for Twobitsprite (216.240.30.23) through svnwiki:

fixed example for chicken 4

File size: 5.8 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)
11Reads a line using the GNU readline() function and returns a string. PROMPT should also be a string.
12 [procedure] (gnu-readline-clear-history)
13Clears the history buffer.
14 [procedure] (gnu-readline-read-history FILENAME)
15Reads the history buffer from the file FILENAME (or ~/.history if FILENAME is #f). Returns 0 on success.
16 [procedure] (gnu-readline-write-history FILENAME)
17Writes 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.
18 [procedure] (gnu-readline-append-history FILENAME)
19Appends only the new entries to FILENAME.
20 [procedure] (gnu-readline-new-lines)
21Returns the number of new entries (input lines from this session).
22 [procedure] (gnu-readline-truncate-history FILENAME NUMLINES)
23Truncates the history file FILENAME (or ~/.history if FILENAME is #f) to NUMLINES lines. Returns 0 on success.
24 [procedure] (gnu-history-install-file-manager FILENAME [NUMLINES])
25If you also want to make the command history span sessions, add the following:
26
27{{(gnu-history-install-file-manager (string-append (or (getenv "HOME") ".") "/.csi.history"))}}
28
29By 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.
30 [procedure] (make-gnu-readline-port [PROMPT] [PROMPT2])
31Returns 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.
32 [procedure] (gnu-readline-set-bounce-ms TIME)
33Changes the time that the cursor spends bouncing on the matching parenthesis - the default 500ms. To turn bouncing off completely, set to zero.
34 [procedure] (gnu-readline-parse-and-bind CONFIG)
35Passes string CONFIG straight to the readline library for parsing (see the readline manual page for details).
36This extension supports static linking.
37
38== Examples
39
40 % csi -quiet
41 #;1> (require 'readline)
42 #;2> (current-input-port (make-gnu-readline-port))
43 #;3>
44
45To get csi to keep a history use the following (in your ~/.csirc file):
46 (require 'readline 'regex)
47 (current-input-port (make-gnu-readline-port))
48 (gnu-history-install-file-manager (string-append (or (getenv "HOME") ".") "/.csi.history"))
49
50In Chicken version 4+ you will need to use (use readline) instead of (require 'readline)
51
52To set readline to behave somewhat like vi:
53 (gnu-readline-parse-and-bind "set editing-mode vi")
54
55== Installation problems
56
57This 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.
58
59=== MacOS X
60
61In particular, Mac OS X versions prior to 10.5 Leopard ship with {{/usr/lib/libreadline.dylib}} linked to an older libedit, causing the following error when you install this egg:
62
63 /usr/bin/ld: Undefined symbols:
64 _history_truncate_file
65
66To fix this, install a copy of GNU readline in {{/usr/local/lib}} or, if you're using MacPorts, symlink it:
67
68 ln -s /opt/local/lib/libreadline.dylib /usr/local/lib
69
70Do ''not'' modify the readline link in {{/usr/lib}}.
71
72MacOS X 10.5.2 again causes errors when building this egg.  Installing MacPorts and doing the symlink above fixes the problem.
73=== Debian GNU/Linux and derivatives (such as Ubuntu)
74
75In the case of Debian, you should probably install the package {{libreadline-dev}}, which is not installed by default.
76== About this egg
77
78=== Author
79
80Tony Garnock-Jones
81
82=== Version history
83
84; 1.99 : Ported to Chicken 4
85; 1.97 : Fixed an old typo that could conceivably cause errors [elf]
86; 1.96 : Fixed build process for real this time (ensuring tests for lib availability actually do set, etc.) [elf]
87; 1.95 : Fixed build process [elf]
88; 1.94 : Added backtraces to control-c breaks [elf]
89; 1.93 : Fixed history so that multiple sessions dont clobber each other. [elf]
90; 1.92 : Added proper signal handling [elf]
91; 1.91 : Added support for static linking [felix]
92; 1.9 : Ignores duplicate history entries [Thanks to Toby Butzon]
93; 1.8 : Empty lines are not added to history [Thanks to Dan Muresan]
94; 1.7 : Added parenthesis bouncing, a new auto-complete [Heath Johns]
95; 1.6 : Export *completion-entry-function* to support autocomplete [Alejandro Forero Cuervo]
96; 1.5 : prompt argument to make-gnu-readline-port is optional [felix]
97; 1.4 : Replaced use of (end-of-file) with #!eof
98; 1.3 : Checks more possible libraries to link with at build time [Thanks to Peter Bex]
99; 1.2 : Adapted to new setup scheme.
100; 1.1 : More features, changed license to GPL, links with either libtermcap or libncurses.
101; 1.0 : Initial release
102
103=== License
104
105 Copyright (c) 2002 Tony Garnock-Jones
106 Copyright (c) 2006 Heath Johns (paren bouncing and auto-completion code)
107 
108 This program is free software; you can redistribute it and/or modify
109 it under the terms of the GNU General Public License as published by
110 the Free Software Foundation; either version 2 of the License, or
111 (at your option) any later version.
112 
113 This program is distributed in the hope that it will be useful,
114 but WITHOUT ANY WARRANTY; without even the implied warranty of
115 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
116 GNU General Public License for more details.
117 
118 You should have received a copy of the GNU General Public License
119 along with this program; if not, write to the Free Software
120 Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
121
Note: See TracBrowser for help on using the repository browser.