readline

Outdated egg!

This is an egg for CHICKEN 4, the unsupported old release. You're almost certainly looking for the CHICKEN 5 version of this egg, if it exists.

If it does not exist, there may be equivalent functionality provided by another egg; have a look at the egg index. Otherwise, please consider porting this egg to the current version of CHICKEN.

An interface to the GNU readline library

Interface

Variables

version

stringtype: The current version string.

session

kvlisttype: A Key-value list of settings that affect how some of the egg's functions behave for the current session.

load-history-file

booleantype: Used by install-history-file. Set to #t by default; when set to #f, the history file will NOT be loaded at start-up.

save-history-on-exit

booleantype: Used 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.

record-history

booleantype: Used by ,rl-rec. Set to #t by default; when set to #f it disables recording history for the current session.

verify-history-expansions

booleantype: Settings this to true makes ,rl-!! wait for you to press enter instead of inserting EOL automatically.

Functions

use-legacy-bindings

use-legacy-bindingsprocedure

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

readline prompt1 #!optional prompt2procedure

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

Both arguments must be strings; prompt2 is optional.

%signal-cleanup

%signal-cleanupprocedure

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

NOTE Calls free(); so using this more than once consecutively may result in undefined behavior, as in a segfault.

clear-history

clear-historyprocedure: Clears the history buffer.

read-history

read-history #!optional fileprocedure

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

write-history #!optional fileprocedure

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

append-history #!optional fileprocedure

Appends history buffer from the current session to file.

Returns 0 on success; errno on fail.

history-newlines

history-newlinesprocedure: Returns the number of entries from the current session.

truncate-history

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

Truncates provided history file to a maximum of n lines.

Returns 0 on win; errno on fail.

install-history-file

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

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

(make-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.

set-bounce-ms

set-bounce-ms msprocedure: 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

parse-and-bind stringprocedure: Passes string straight to the readline library for parsing (see the readline manual page for details).

history-list

history-listprocedure: Returns the history list as a newline separated list.

history-position

history-position #!optional posprocedure

Returns the current offset within the history list.

Passing pos sets the current offset.

add-history

%history-add% stringprocedure

Adds string to the history list.

NOTE

This function exists primarily for testing purposes.

Returns void

remove-history

%remove-history% offsetprocedure: Removes and frees the specified history entry and its associated memory.

eval-last-history-line

eval-last-history-line #!optional scriptprocedure

The function behind ,rl-!!.

This function is not added to the history unless script is true. DO 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!!

NOTE

The line does not have to be from the current session. Also, 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.

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)
(current-input-port (make-readline-port))
(install-history-file #f "/.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 -Wl,-flat_namespace,-undefined,suppress"
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.

4.1.1: Slight changes to the toplevel commands interface.
4.1.0: Necessary updates in light of the changes in Chicken v4.10 as compared to Chicken v4.9.
4.0.0: Version bump due to v3.0b2 being considered newer than v3.1.1.
3.1.1: Removes `regex` as a dependency (patch).
3.1: Removes `current-history-line' and renames all of the history related functions.
3.0: Removes a lot of the stuff introduced by 2.0; adds toplevel-commands for convience.
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

chickadee » readline

Identifier search

TOC »

Contents »