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

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.

Author

Vasilij Schneidermann

Repository

https://github.com/wasamasa/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.

API

History

[procedure] (history-length)

Returns the current history length.

[parameter] (history-file)
[parameter] (history-file PATH)

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.

[procedure] (add-history! ITEM)

Adds ITEM to the current history.

[procedure] (read-history! FILE)

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

[procedure] (write-history! FILE)

Writes out current history items to FILE.

[procedure] (stifle-history! MAX)

Configure the current history to hold at most MAX items.

[procedure] (unstifle-history!)

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

[procedure] (completer-set! PROC)

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.

[procedure] (completer-word-break-characters-set STRING)

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

Text Manipulation

[procedure] (insert-text STRING)

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

[procedure] (delete-text START END)

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

[procedure] (stuff-char CHAR)

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.

[procedure] (redisplay)

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

Event hooks

[procedure] (event-hook-set! PROCEDURE)

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.

[procedure] (pre-input-hook-set! PROCEDURE)

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

[procedure] (variable-bind! VARIABLE VALUE)

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

[procedure] (variable-value VARIABLE)

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

[procedure] (basic-quote-characters-set STRING)

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

[procedure] (paren-blink-timeout-set MICROSECS)

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

[procedure] (readline PROMPT)

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

[procedure] (make-readline-port [PROMPT])

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

Examples

(import breadline)

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

0.5

0.4

0.3

0.2

0.1