breadline

  1. breadline
    1. Introduction
    2. Author
    3. Repository
    4. Current state of the bindings
    5. Requirements
    6. API
      1. History
      2. Completion
      3. Customization
      4. Line editing
    7. Examples
    8. License
    9. Version history
      1. 0.2
      2. 0.1

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.

API

History

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

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 defaults to the value of calling (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.2

0.1