You are looking at historical revision 19930 of this page. It may differ significantly from its current revision.


A binding for the GNU readline library.


<procedure>(gnu-readline PROMPT)</procedure>

Reads a line using the GNU readline() function and returns a string. PROMPT should also be a string.

<procedure> (gnu-readline-clear-history)</procedure>

Clears the history buffer.

<procedure> (gnu-readline-read-history FILENAME)</procedure>

Reads the history buffer from the file FILENAME (or ~/.history if FILENAME is #f). Returns 0 on success.

<procedure> (gnu-readline-write-history FILENAME)</procedure>

Writes 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.

<procedure> (gnu-readline-append-history FILENAME)</procedure>

Appends only the new entries to FILENAME.

<procedure> (gnu-readline-new-lines)</procedure>

Returns the number of new entries (input lines from this session).

<procedure> (gnu-readline-truncate-history FILENAME NUMLINES)</procedure>

Truncates the history file FILENAME (or ~/.history if FILENAME is #f) to NUMLINES lines. Returns 0 on success.

<procedure> (gnu-history-install-file-manager FILENAME [NUMLINES])</procedure>

If you also want to make the command history span sessions, add the following:

(gnu-history-install-file-manager (string-append (or (getenv "HOME") ".") "/.csi.history"))

By 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.

<procedure> (make-gnu-readline-port [PROMPT] [PROMPT2])</procedure>

Returns 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.

<procedure> (gnu-readline-set-bounce-ms TIME)</procedure>

Changes the time that the cursor spends bouncing on the matching parenthesis - the default 500ms. To turn bouncing off completely, set to zero.

<procedure> (gnu-readline-parse-and-bind CONFIG)</procedure>

Passes string CONFIG straight to the readline library for parsing (see the readline manual page for details). This extension supports static linking.


% csi -quiet
#;1> (use readline)
#;2> (current-input-port (make-gnu-readline-port))

To get csi to keep a history use the following (in your ~/.csirc file):

(use readline regex)
(current-input-port (make-gnu-readline-port))
(gnu-history-install-file-manager (string-append (or (getenv "HOME") ".") "/.csi.history"))

NB: you must create the .csi.history file, readline will not create it:

% touch ~/.csi.history

To set readline to behave somewhat like vi:

(gnu-readline-parse-and-bind "set editing-mode vi")

Installation problems

This 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.

Mac OS X

10.6 (Snow Leopard)

10.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:

export CSC_OPTIONS="-I/opt/local/include -L/opt/local/lib"

...before the chicken-install. If this doesn't work, try an additional

export LIBRARY_PATH=/opt/local/lib


Mac OS X versions prior to 10.5 (Leopard) ship with an older readline, causing the following error when you install this egg:

/usr/bin/ld: Undefined symbols:

To fix this, install a copy of GNU readline in /usr/local/lib or, if you're using MacPorts, symlink it:

ln -s /opt/local/lib/libreadline.dylib /usr/local/lib

DO NOT modify the readline link in /usr/lib.

Debian GNU/Linux and derivatives (such as Ubuntu)

In the case of Debian, you should probably install the package libreadline-dev, which is not installed by default.

About this egg


Tony Garnock-Jones

Version history

fixed buggy fixes made by felix (thanks to ewfalor)
fixed buggy setup script (thanks to ewfalor)
Ported to Chicken 4
Fixed an old typo that could conceivably cause errors [elf]
Fixed build process for real this time (ensuring tests for lib availability actually do set, etc.) [elf]
Fixed build process [elf]
Added backtraces to control-c breaks [elf]
Fixed history so that multiple sessions dont clobber each other. [elf]
Added proper signal handling [elf]
Added support for static linking [felix]
Ignores duplicate history entries [Thanks to Toby Butzon]
Empty lines are not added to history [Thanks to Dan Muresan]
Added parenthesis bouncing, a new auto-complete [Heath Johns]
Export *completion-entry-function* to support autocomplete [Alejandro Forero Cuervo]
prompt argument to make-gnu-readline-port is optional [felix]
Replaced use of (end-of-file) with #!eof
Checks more possible libraries to link with at build time [Thanks to Peter Bex]
Adapted to new setup scheme.
More features, changed license to GPL, links with either libtermcap or libncurses.
Initial release


Copyright (c) 2002 Tony Garnock-Jones
Copyright (c) 2006 Heath Johns (paren bouncing and auto-completion code)

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA