== breadline

[[toc:]]

=== Introduction

This egg provides an incomplete set of bindings to the
[[http://tiswww.case.edu/php/chet/readline/rltop.html|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

* Basic interface for reading input and managing history
* Completion interface
* Customization of aspects crucial for Scheme programming

=== 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

<procedure>(history-length)</procedure>

Returns the current history length.

<parameter>(history-file)</parameter>
<parameter>(history-file PATH)</parameter>

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)</procedure>

Adds {{ITEM}} to the current history.

<procedure>(read-history! FILE)</procedure>

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

<procedure>(write-history! FILE)</procedure>

Writes out current history items to {{FILE}}.

<procedure>(stifle-history! MAX)</procedure>

Configure the current history to hold at most {{MAX}} items.

<procedure>(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

<procedure>(completer-set! PROC)</procedure>

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)</procedure>

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)</procedure>

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

<procedure>(delete-text START END)</procedure>

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

<procedure>(stuff-char CHAR)</procedure>

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)</procedure>

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

==== Event hooks

<procedure>(event-hook-set! PROCEDURE)</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)</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)</procedure>

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

<procedure>(variable-value VARIABLE)</procedure>

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

<procedure>(basic-quote-characters-set STRING)</procedure>

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)</procedure>

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)</procedure>

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])</procedure>

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

<enscript highlight="scheme">
(use readline)

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

Further examples for usage in {{csi}} and writing your own completer
can be found
[[https://github.com/wasamasa/readline/tree/master/examples|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

TBD