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

readline

Bindings for the GNU readline library.

Requirements

API

Functions

use-legacy-bindings

[procedure] (use-legacy-bindings)

Exports symbols aliasing the v1.993 API to the current API.

Use this function only if you have legacy code that uses the older API.

Returns (void) on success; will cause an error on fail.

Example:

(readline#use-legacy-bindings)
(current-input-port (make-gnu-readline-port))

readline

[procedure] (readline prompt1 [prompt2])

Reads a line using the GNU readline() function and returns a string.

Both arguments must be strings; prompt2 is optional.

%signal-cleanup

[procedure] (%signal-cleanup)

Sets the state of the underlying readline environment to a clean slate.

NOTE Calls free(); so using this more than once consecutively may cause problems, such as a segfault.

clear-history

[procedure] (clear-history)

Clears the history buffer.

read-history

[procedure] (read-history [file])

Reads contents of the provided file into the history buffer.

When called without file-name, reads from ~/.history. Returns 0 on success, or errno on fail.

write-history

[procedure] (write-history [file])

Writes the history buffer to file or ~/.history when no file is provided.

Returns 0 on success; errno on fail.

USE AT YOUR OWN RISK!

Using this may clobber simultaneous sessions.

append-history

[procedure] (append-history [file])

Appends history buffer from the current session to file.

Returns 0 on success; errno on fail.

history-newlines

[procedure] (history-newlines)

Returns the number of entries from the current session.

truncate-history

[procedure] (truncate-history [file] [n])

Truncates provided history file to a maximum of n lines.

Returns 0 on win; errno on fail.

install-history-file

[procedure] (install-file-manager [homedir] [filename] [nlines])

If you also want to make the command history span sessions, add the following to your ~/.csirc:

(install-history-file)

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 history-install-file-manager. If #f or no second argument is passed in, no history-file-pruning will take place.

NOTE Do not use this in conjunction with rlwrap. The maintainer did so and experience some very weird behavior from csi.

make-readline-port

[procedure] (make-readline-port [prompt] [prompt2])

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.

set-bounce-ms

[procedure] (set-bounce-ms ms)

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

parse-and-bind

[procedure] (parse-and-bind string)

Passes string straight to the readline library for parsing (see the readline manual page for details).

history-stifle

[procedure] (history-stifle [max])

Limit the current history file/session (might be either or: this detail has not been tested) remembering only the last max entries.

Call without args to unstifle the current history file/session.

history-stifled

[procedure] (history-stifled)

Returns true or false depending on whether the current history file/session is being stifled.

[procedure] (history-search string direction)

Search the history for string in direction starting at the current history position.

Direction should be either -1 for backwards, or >= 0 for forwards.

history-search-backward

[procedure] (history-search-backward string)

Search the history for string starting at the current history position and progressing backwards.

history-search-forward

[procedure] (history-search-forward string)

Search the history for string starting at the current history position and progressing forwards.

history-search-backward-starts-with

[procedure] (history-search-backward-starts-with string)

Search the history backwards for string starting at the current history position. The search is anchored: matching lines must being with string.

history-search-forward-starts-with

[procedure] (history-search-forward-starts-with string)

Search the history forwards for string starting at the current history position. The search is anchored: matching lines must being with string.

history-search-from-position

[procedure] (history-search-from-position string direction position)

Search the history in direction for string starting at the absolute index position.

history-list

[procedure] (history-list)

Returns the history list as a newline separated list.

history-list-length

[procedure] (history-list-length)

Returns the current length of the history list.

history-list-max-entries

[procedure] (history-list-max-entries)

Returns the maximum number of supported history entries.

It is the maintainer's opinion that 0, as a return value, means unlimited.

history-list-size

[procedure] (history-list-size)

Returns the sizeof all of the lines in the history list's entries.

history-position

[procedure] (history-position [pos])

Returns the current offset within the history list.

Passing pos sets the current offset.

history-use-timestamps

[procedure] (history-write-timestamps yes-no)

If passed #t, timestamps are written to the history file, so they can be preserved between sessions. Timestamps are disabled by default.

history-get-entry

[procedure] (history-get-entry index [time])

Returns the history entry at position index starting from history_base. Pass time as #t to have said entry's timestamp included in the return value.

history-current-entry

[procedure] (history-current-entry [time])

Returns the current history entry as determined by the current history position; the return value is a string.

history-previous-entry

[procedure] (history-previous-entry [time])

Returns the previous history entry as determined by the current history position; returns a string.

history-next-entry

[procedure] (history-next-entry [time])

Returns the next history entry as determined by the current history position; returns a string.

Building

This extension supports static linking.

Examples

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

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

(use readline irregex)
(current-input-port (make-readline-port))
(history-install-file-manager
 (string-append (or (get-environment-variable "HOME") ".") "/.csi.history"))

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

% touch ~/.csi.history

To set readline to behave somewhat like vi:

(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.8/10.9 (Snow Leopard/Mavericks)

Using bash...

brew install readline
readline_version=$(brew list readline --versions)
readline_version=${readline_version##* }
export CSC_OPTIONS="-I/usr/local/Cellar/readline/$readline_version/include -L/usr/local/Cellar/readline/$readline_version/lib"
unset readline_version
brew reinstall chicken
chicken-install readline

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

Pre-10.6

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:
_history_truncate_file

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

Author

Tony Garnock-Jones

Maintained by Alexej Magura

Version history
3.0b2
Fixed memleaks in history-list function and str_unquotd
3.0b1
Made a few tweaks to the API to keep it in sync with the documentation I've written.
3.0b
Lots of API additions and a few changes; more efficient memory usage; removed libbsd as an optional depend
2.4
Fixed setup file and version string.
2.3
Reverted back to v1.993 setup file due to that fixes a bug with automated builds; added checks for libbsd
2.2
Fixed more bugs with the detection of unclosed expressions
2.1
Fixed a bug with legacy support where the aliases pointed to uninterned symbols.
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)
1.993
fixed buggy build bugs caused by repeated build "fixes" (Jim Ursetto)
1.992
fixed buggy fixes made by felix (thanks to ewfalor)
1.991
fixed buggy setup script (thanks to ewfalor)
1.99
Ported to Chicken 4
1.97
Fixed an old typo that could conceivably cause errors [elf]
1.96
Fixed build process for real this time (ensuring tests for lib availability actually do set, etc.) [elf]
1.95
Fixed build process [elf]
1.94
Added backtraces to control-c breaks [elf]
1.93
Fixed history so that multiple sessions dont clobber each other. [elf]
1.92
Added proper signal handling [elf]
1.91
Added support for static linking [felix]
1.9
Ignores duplicate history entries [Thanks to Toby Butzon]
1.8
Empty lines are not added to history [Thanks to Dan Muresan]
1.7
Added parenthesis bouncing, a new auto-complete [Heath Johns]
1.6
Export *completion-entry-function* to support autocomplete [Alejandro Forero Cuervo]
1.5
prompt argument to make-gnu-readline-port is optional [felix]
1.4
Replaced use of (end-of-file) with #!eof
1.3
Checks more possible libraries to link with at build time [Thanks to Peter Bex]
1.2
Adapted to new setup scheme.
1.1
More features, changed license to GPL, links with either libtermcap or libncurses.
1.0
Initial release

License

 
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
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
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