chickadee » breadline

breadline

Introduction

This egg provides an incomplete set of bindings to the GNU Readline library, suitable for augmenting csi and writing a csi-like application with line editing support. See the bundled examples for a .csirc providing Scheme completion.

Author

Vasilij Schneidermann

Repository

https://depp.brause.cc/breadline

Current state of the bindings

Requirements

You'll need to have a not too old version of GNU Readline installed. This egg has been tested with version 7, but version 6 should work as well. In case the auto-detected flags don't work for you, make sure to set READLINE_CFLAGS and READLINE_LDLIBS before installation. The following subsections show known workarounds for platforms where the default build script does not suffice:

Ubuntu 18.04

export READLINE_CFLAGS=-I/usr/include/readline
export READLINE_LDLIBS=-lreadline
chicken-install breadline

An alternative solution is to set up /usr/share/pkgconfig/readline.pc as described on Simon Marache-Francisco's blog. Edit the file to contain the following, then run chicken-install breadline:

Name: Readline
Description: Gnu Readline library for command line editing
URL: http://tiswww.cwru.edu/php/chet/readline/rltop.html
Version: 7.0
Requires.private: tinfo
Libs: -lreadline
Cflags: -I/usr/include/readline

mingw-msys2

Assuming a 64bit installation, the egg can be installed as follows:

pacman -S pkg-config mingw-w64-x86_64-readline
export READLINE_CFLAGS=$(pkg-config --cflags readline)
export READLINE_LDLIBS=$(pkg-config --libs readline)
chicken-install breadline

API

History

history-lengthprocedure

Returns the current history length.

history-fileparameter
history-file PATHparameter

Specifies the location of the history file for make-readline-port. Defaults to #f which means to neither read nor write out the history. PATH may be relative to the current working directory.

add-history! ITEMprocedure

Adds ITEM to the current history.

read-history! FILEprocedure

Reads in history items from FILE and adds them to the current history.

write-history! FILEprocedure

Writes out current history items to FILE.

stifle-history! MAXprocedure

Configure the current history to hold at most MAX items.

unstifle-history!procedure

Undo any history stifling. Returns the previously set maximum amount of history items as set by stifle-history!. If the history was not stifled before, the value is negative.

Completion

completer-set! PROCprocedure

Set the completion handler to PROC. PROC is called repeatedly to collect completions with a fixnum state argument and a string prefix. A state argument of zero means that the completion procedure may initialize its data, it is incremented for every subsequent call. The completion procedure must either return a completion matching the given string prefix or #f to signal that no further completions follow. It is up to the completion procedure to keep track of what completions have been offered and whether any further completions are vailable.

completer-word-break-characters-set STRINGprocedure

Sets the word-breaking characters for completion to STRING. The default value of \t\n\"\\'`@$><=;|&{( is suitable for Bash's completion.

Text Manipulation

insert-text STRINGprocedure

Insert STRING into the line at the current cursor position. Returns the number of characters inserted.

delete-text START ENDprocedure

Delete the text between START and END in the current line. Returns the number of characters deleted.

stuff-char CHARprocedure

Insert CHAR into the Readline input stream. It will be "read" before Readline attempts to read characters from the terminal. Up to 512 characters may be pushed back. Returns 1 if the character was successfully inserted; 0 otherwise.

redisplayprocedure

Change what's displayed on the screen to reflect the current contents of Readline's buffer.

Event hooks

event-hook-set! PROCEDUREprocedure

Registers a hook that will be called periodically when Readline is waiting for terminal input. By default, this will be called at most ten times a second if there is no keyboard input. The argument should be a thunk. Its return value is ignored.

Only one event hook may be registered at a time. A previously-registered hook may be disabled by passing #f.

pre-input-hook-set! PROCEDUREprocedure

Registers a hook that will be called every time the first input prompt has been printed, just before readline starts reading input characters. The argument should be a thunk. Its return value is ignored.

Only one pre-input hook may be registered at a time. A previously-registered hook may be disabled by passing #f.

Customization

variable-bind! VARIABLE VALUEprocedure

Sets a GNU Readline variable to a value. Both VARIABLE and VALUE must be strings.

variable-value VARIABLEprocedure

Retrieves the current value of the given GNU Readline variable. VARIABLE must be a string.

basic-quote-characters-set STRINGprocedure

Sets the quoting characters to STRING, the default value being "'. This setting is used for paren blinking to determine strings.

Sets the timeout for paren blinking in microseconds, the default value being 500000 microseconds. Note that typing a closing paren will not blink the opening paren unless blink-matching-paren has been set.

Line editing

readline PROMPTprocedure

Read in a line of user input after printing PROMPT. Returns the user input or #f if input has been terminated with C-d.

make-readline-port #!optional PROMPTprocedure

Returns an input port using GNU Readline for line editing and history management. PROMPT may be a string or a thunk returning a string and defaults to (repl-prompt).

Cleanup

cleanup-after-signal!procedure
reset-after-signal!procedure

Procedures to call in sequence after receiving a signal in a signal handler to ensure a clean terminal and readline state.

reset-terminal! #!optional TERMINAL-NAMEprocedure

Procedure to call after program exit to ensure a clean terminal state. The optional argument TERMINAL-NAME defaults to the value of the TERM environment variable.

Examples

(import (chicken process signal))
(import breadline)

(set-signal-handler! signal/int
                     (lambda _
                       (cleanup-after-signal!)
                       (reset-after-signal!)))
(on-exit reset-terminal!)

(let loop ()
  (let ((input (readline "> ")))
    (if input
        (begin
          ;; processing code goes here
          (print input)
          (add-history! input)
          (loop))
        (newline))))

Further examples for usage in csi and writing your own completer can be found in the repository.

License

Copyright 2016 Vasilij Schneidermann

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

A full copy of the GPL license can be found at
<http://www.gnu.org/licenses/>.

Version history

0.8

0.7

0.6

0.5

0.4

0.3

0.2

0.1

Contents »