cl-readline Library

Table of Contents

cl-readline Library

This document describes cl-readline library, bindings to GNU Readline library. This program is distributed under GNU General Public License, version 3.

All symbols described in this document live in cl-readline package, it has the following nicknames: rl.

1 Basic Functionality

This section describes most basic functions and symbol-macros that represent underlying C variables. For every symbol macro we give data type it evaluates to. If name of a symbol macro is enclosed in plus signs (for example, +prompt+), it means that you should not (and, in fact, cannot) modify its value. Other symbol macros are setfable and you can set their values with setf macro.

Symbol Macro: *line-buffer*

String. This is the line gathered so far. You are welcome to modify the contents of the line, but remember about undoing (see Allowing Undoing). The function extend-line-buffer is available to increase the memory allocated to *line-buffer*.

Symbol Macro: *point*

Integer. The offset of the current cursor position in *line-buffer* (the point).

Symbol Macro: +end+

Integer. The number of characters present in *line-buffer*. When *point* is at the end of the line, *point* and +end+ are equal.

Symbol Macro: *mark*

Integer. The mark (saved position) in the current line. If set, the mark and point define a region.

Symbol Macro: *done*

Boolean. Setting this to a non-nil value causes Readline to return the current line immediately.

Symbol Macro: +prompt+

String. The prompt Readline uses. This is set from the argument to readline, and should not be assigned to directly. The set-prompt function may be used to modify the prompt string after calling readline.

Symbol Macro: *display-prompt*

String. The string displayed as the prompt. This is usually identical to +prompt+, but may be changed temporarily by functions that use the prompt string as a message area, such as incremental search.

Symbol Macro: +library-version+

String. The version number of this revision of the library.

Symbol Macro: +readline-version+

Two integer values. Major and minor version numbers of Readline library.

Symbol Macro: +gnu-readline-p+

Boolean. Always evaluated to t, denoting that this is GNU readline rather than some emulation.

Symbol Macro: *readline-name*

String. This symbol-macro should be set to a unique name by each application using Readline. The value allows conditional parsing of the inputrc file.

Symbol Macro: +readline-state+

List of keywords. This symbol macro is evaluated to a list containing keywords that denote state of Readline. The following flags are used:

• :initializing – initializing;
• :initialized – initialization done;
• :termprepped – terminal is prepped;
• :readcmd – reading a command key;
• :metanext – reading input after ESC;
• :dispatching – dispatching to a command;
• :moreinput – reading more input in a command function;
• :isearch – doing incremental search;
• :nsearch – doing non-incremental search;
• :search – doing a history search;
• :numericarg – reading numeric argument;
• :macroinput – getting input from a macro;
• :macrodef – defining keyboard macro;
• :overwrite – overwrite mode;
• :completing – doing completion;
• :sighandler – in readline sighandler;
• :undoing – doing a undo;
• :inputpending – execute-next called;
• :ttycsaved – tty special chars saved;
• :callback – using the callback interface;
• :vimotion – reading vi motion argument;
• :multikey – reading multiple-key command;
• :vicmdonce – entered vi command at least once;
• :redisplaying – undating terminal display;
• :done – done; accepted line.

Symbol macro: +editing-mode+

Keyword. Evaluated to keyword denoting actual editing mode: :emacs or :vi.

Function: readline &key prompt already-prompted num-chars erase-empty-line add-history novelty-check

Get a line from user with editing. prompt, if supplied, is printed before reading of input. Non-nil value of already-prompted will tell Readline that the application has printed prompt already. However, prompt must be supplied in this case too, so redisplay functions can update the display properly. If num-chars argument is a positive number, Readline will return after accepting that many characters. If erase-empty-line is not nil, readline will completely erase the current line, including any prompt, any time a newline is typed as the only character on an otherwise-empty line. The cursor is moved to the beginning of the newly-blank line. Supplying add-history tells Readline that user’s input should be added to history. However, blank lines don’t get into history anyway. novelty-check, if given, must be a predicate that takes two strings: the actual line and the most recent history line. Only when the predicate evaluates to non-nil value new line will be added to the history. Return value on success is the actual string and nil on failure.

2 Hooks and Custom Functions

cl-readline provides ways to register custom functions, so you can rewrite some parts of Readline library in Lisp.

Symbol macro: *basic-word-break-characters*

String. The basic list of characters that signal a break between words for the completer routine. The default value of this variable is the characters which break words for completion in Bash.

Symbol macro: *basic-quote-characters*

String. A list of quote characters which can cause a word break.

Symbol macro: *completer-word-break-characters*

String. The list of characters that signal a break between words for complete-internal. The default list is the value of *basic-word-break-characters*.

Symbol macro: *completion-query-items*

Up to this many items will be displayed in response to a possible-completions call. After that, Readline asks the user if she is sure she wants to see them all. The default value is 100. A negative value indicates that Readline should never ask the user.

Symbol macro: *completion-append-character*

Character. When a single completion alternative matches at the end of the command line, this character is appended to the inserted completion text. The default is a space character. Setting this to the null character prevents anything being appended automatically. This can be changed in application-specific completion functions to provide the ’most sensible word separator character’ according to an application-specific command line syntax specification.

Symbol macro: *ignore-completion-duplicates*

Boolean. If non-nil, then duplicates in the matches are removed. The default is t.

Symbol macro: *sort-completion-matches*

Boolean. If an application sets this variable to nil, Readline will not sort the list of completions (which implies that it cannot remove any duplicate completions). The default value is t, which means that Readline will sort the completions and, depending on the value of *ignore-completion-duplicates*, will attempt to remove duplicate matches.

Symbol macro: +completion-type+

Keyword. Set to a keyword describing the type of completion Readline is currently attempting. Possible values are:

• :standard-completion tells Readline to do standard completion;
• :display-and-perform means to display all possible completions if there is more than one, as well as performing partial completion;
• :insert-all means insert all possible completions;
• :list-all means list the possible completions;
• :not-list-cmn-prefix is similar to :display-and-perform but possible completions are not listed if the possible completions share a common prefix.

Symbol macro: *inhibit-completion*

Boolean. If this variable is non-nil, completion is inhibited. The completion character will be inserted as any other bound to self-insert.

Function: register-hook hook function

Register a hook. hook should be a keyword, one of the following:

• :startup hook is called just before readline prints the prompt.
• :pre-input hook is called after prompt has been printed and just before readline starts reading input characters.
• :event hook is called periodically when waiting for terminal input. By default, this will be called at most ten times a second if there is no keyboard input.
• :signal hook is called when a read system call is interrupted when readline is reading terminal input.
• :inputp hook is called when Readline need to determine whether or not there is available input on the current input source. If function returns nil, it means that there is no available input.
• :lsmatches hook is called to display list of completions. function must be able to take three arguments: list of completions, length of the list, and length of the longest completion in the list. It’s up to the function how to display these completions.

Other values of hook will be ignored.

function must be a function that takes no arguments and returns nil on success and t on failure. If function is nil, hook will be removed (or default function will be used).

Function: register-function func function

Register a function. func should be a keyword, one of the following:

• :getc function is used to get a character from the input stream, thus function should take pointer to C stream and return a character if this function is desired to be registered. In general, an application that registers :getc function should consider registering :inputp hook as well (see register-hook).
• :redisplay function is used to update the display with the current contents of the editing buffer, thus function should take no arguments and return nil on success and non-nil of failure. By default, it is set to redisplay, the default Readline redisplay function.
• :prep-term function is used to initialize the terminal, so function must be able to take one argument, a flag that says whether or not to use eight-bit characters. By default, prep-terminal is used.
• :deprep-term function is used to reset the terminal. This function should undo the effects of :prep-term function.
• :complete function is used to generate list of possible completions for given partially entered word. The function must be able to take three arguments: partially entered word, start index of the word in *line-buffer*, and end index of the word in the buffer. The function must return a list where first element is the actual completion (or part of completion if two or more completions share common prefix) and the rest arguments are possible completions.

Other values of func will be ignored.

function must be a function, if function is nil, result is unpredictable.

3 Work with Keymaps

Keymaps tell Readline which function should it invoke when the user presses certain key. Readline provides some pre-existing keymaps and let you create your own and modify existing ones.

Symbol macro: +executing-keymap+

C pointer. This symbol macro is evaluated to the keymap in which the currently executing Readline function was found.

Symbol macro: +binding-keymap+

C pointer. This symbol macro is evaluated to the keymap in which the last key binding occurred.

Function: make-keymap &optional bare

Return a new keymap with self-inserting printing characters, the lowercase Meta characters bound to run their equivalents, and the Meta digits bound to produce numeric arguments. If bare is supplied and it’s not nil, empty keymap will be returned.

Function: copy-keymap keymap

Return a new keymap which is a copy of keymap.

Function: free-keymap keymap

Free all storage associated with keymap.

Function: get-keymap

Return currently active keymap.

Function: set-keymap keymap

Make keymap currently active keymap.

Function: get-keymap-by-name name

Return the keymap matching name. name is one which would be supplied in a set keymap inputrc line.

Macro: with-new-keymap form &body body

Create new keymap evaluating form, bind symbol keymap to the result, then free it when control flow leaves body. make-keymap and copy-keymap can be used to produce new keymap.

4 Binding Keys

Key sequences are associated with functions through the keymap. Here are the functions that may be of interest when working with keymaps.

Symbol macro: +executing-macro+

String. This symbol macro is evaluated to the text of any currently-executing macro.

Symbol macro: +executing-key+

Character. The key that caused the dispatch to the currently-executing Readline function.

Symbol macro: +executing-keyseq+

String. The full key sequence that caused the dispatch to the currently-executing Readline function.

Symbol macro: +key-sequence-length+

Integer. The number of characters in +executing-keyseq+.

Symbol macro: +dispatching+

Boolean. Set to a non-nil value if a function is being called from a key binding; nil otherwise. Application functions can test this to discover whether they were called directly or by Readline’s dispatching mechanism.

Function: add-defun name function &optional key

Add name to the list of named functions. Make function be the function that gets called. If key is not nil and it’s a character, then bind it to function using bind-key. function must be able to take two arguments: integer representing its argument and character representing key that has invoked it.

Function: bind-key key function &key keymap if-unbound

Bind key to function in the currently active keymap. If keymap argument supplied, binding takes place in specified keymap. If if-unbound is supplied and it’s not nil, key will be bound to function only if it’s not already bound.

Function: unbind-key key &optional keymap

Unbind key in keymap. If keymap is not supplied or it’s nil, key will be unbound in currently active keymap. The function returns nil on success and t on failure.

Function: unbind-command command keymap

Unbind all keys that are bound to command in keymap.

Function: bind-keyseq keyseq function &key keymap if-unbound

Bind the key sequence represented by the string keyseq to the function function, beginning in the current keymap. This makes new keymaps as necessary. If keymap is supplied and it’s not nil, initial bindings are performed in keymap. If if-unbound is supplied and it’s not nil, keyseq will be bound to function only if it’s not already bound. The return value is t if keyseq is invalid and nil otherwise.

Function: parse-and-bind line

Parse line as if it had been read from the inputrc file and perform any key bindings and variable assignments found.

Function: read-init-file filename

Read keybindings and variable assignments from filename.

5 Associating Function Names and Bindings

Note that this section is stripped-down. Many functions are missing. It’s because C functions take addresses of other functions as arguments. In cl-readline we use dynamic generation of callbacks, so once you have registered a new function, it’s tricky to identify it later. Note that this problem is solvable, but hairy. If you need to use functions that are missing, open an issue and describe your problem.

Function: function-dumper readable &optional filename append

Print the Readline function names and the key sequences currently bound to them to stdout. If readable is non-nil, the list is formatted in such a way that it can be made part of an inputrc file and re-read. If filename is supplied and it’s a string or path, output will be redirected to the file. append allows to append text to the file instead of overwriting it.

Function: list-funmap-names &optional filename append

Print the names of all bindable Readline functions to stdout. If filename is supplied and it’s a string or path, output will be redirected to the file. append allows append text to the file instead of overwriting it.

Function: funmap-names

Return a list of known function names. The list is sorted.

Function: add-funmap-entry name function

Add name to the list of bindable Readline command names, and make function the function to be called when name is invoked.

6 Allowing Undoing

If your function simply inserts text once, or deletes text once, and uses insert-text or delete-text to do it, then undoing is already done for you automatically.

If you do multiple insertions or multiple deletions, or any combination of these operations, you should group them together into one operation. This is done with undo-group macro.

Function: add-undo what start end text

Remember how to undo an event (according to what). The affected text runs from start to end, and encompasses text. Possible values of what include: :undo-delete, :undo-insert, :undo-begin, and :undo-end

Function: free-undo-list

Free the existing undo list.

Function: do-undo

Undo the first thing on the undo list. Returns nil if there was nothing to undo, t if something was undone.

Function: modifying start end

Tell Readline to save the text between start and end as a single undo unit. It is assumed that you will subsequently modify that text.

Macro: undo-group &body body

All insertion and deletion inside this macro will be grouped together into one undo operation.

7 Redisplay

Function: redisplay

Change what’s displayed on the screen to reflect the current contents of *line-buffer*.

Function: forced-update-display

Force the line to be updated and redisplayed, whether or not Readline thinks the screen display is correct.

Function: on-new-line &optional with-prompt

Tell the update functions that we have moved onto a new (empty) line, usually after outputting a newline. When with-prompt is not nil, Readline will think that prompt is already displayed. This could be used by applications that want to output the prompt string themselves, but still need Readline to know the prompt string length for redisplay. This should be used together with :already-prompted keyword argument of readline.

Function: reset-line-state

Reset the display state to a clean state and redisplay the current line starting on a new line.

Function: crlf

Move the cursor to the start of the next screen line.

Function: show-char char

Display character char on outstream. If Readline has not been set to display meta characters directly, this will convert meta characters to a meta-prefixed key sequence. This is intended for use by applications which wish to do their own redisplay.

Function: set-prompt prompt

Make Readline use prompt for subsequent redisplay. This calls expand-prompt to expand the prompt and sets +prompt+ to the result.

Macro: with-message message save-prompt &body body

Show message message in the echo area while executing body. If save-prompt is not nil, save prompt before showing the message and restore it before clearing the message.

8 Adding and modifying Text

Once a prompt is started, you can insert and delete text at the current cursor position.

See also crlf and the section “Moving the cursor”.

Function: insert-text text

Insert text into the line at the current cursor position. Return the number of characters inserted.

Function: delete-text start end

Delete the text between start and end in the current line. Return the number of characters deleted.

Function: kill-text start end

Copy the text between start and end in the current line to the kill ring, appending or prepending to the last kill if the last command was a kill command. The text is deleted. If start is less than end, the text is appended, otherwise prepended. If the last command was not a kill, a new kill ring slot is used.

9 Character Input

Function: read-key

Return the next character available from Readline’s current input stream.

Function: stuff-char char

Insert char into the Readline input stream. It will be “read” before Readline attempts to read characters from the terminal with read-key. Up to 512 characters may be pushed back. stuff-char returns t if the character was successfully inserted; nil otherwise.

Function: execute-next char

Make char be the next command to be executed when read-key is called.

Function: clear-pending-input

Negate the effect of any previous call to execute-next. This works only if the pending input has not already been read with read-key.

Function: set-keyboard-input-timeout u

While waiting for keyboard input in read-key, Readline will wait for u microseconds for input before calling any function assigned to event-hook. u must be greater than or equal to zero (a zero-length timeout is equivalent to a poll). The default waiting period is one-tenth of a second. Return the old timeout value.

10 Moving the cursor

You can move the cursor by characters and words, or move to the beginning and end of the line.

We also have commands to clear the line and the screen.

Note that these functions bind readline commands, thus they must accept two arguments: count (defaults to 1) and key (the key identifier that fired this command). The key is not used in the Lisp functions.

Function: backward-word &optional (count 1)

Move backward COUNT words (1 by default).

Function: forward-word &optional (count 1)

Move forward COUNT word(s).

Function: backward-char &optional (count 1)

Move forward COUNT characters.

Function: forward-char &optional (count 1)

Move forward COUNT characters.

Function: beginning-of-line

Move to the beginning of the line.

Function: end-of-line

Move to the end of the line.

Function: refresh-line

Clear the current line. A numeric argument to C-l does this.

Function: clear-screen

C-l typed to a line without quoting clears the screen, and then reprints the prompt and the current input line.

Function: clear-display

Clear the screen and update the display."

Here’s an example to enter an opening ( and a closing ), and move the cursor in between the parenthesis:

(defun insert-parens (&optional count key)
  (rl:insert-text "()")
  (rl:backward-char))

(defun run-example ()
  (rl:bind-keyseq "(" #'insert-parens)  ;; this function must accept COUNT and KEY

  ;; start a prompt
  (rl:readline :prompt "go > ")
  ;; and now you can type "(".
  )

(run-example)

11 Terminal Management

Function: prep-terminal eight-bit-input

Modify the terminal settings for Readline’s use, so readline can read a single character at a time from the keyboard. The eight-bit-input argument should be non-nil if Readline should read eight-bit input.

Function: deprep-terminal

Undo the effects of prep-terminal, leaving the terminal in the state in which it was before the most recent call to prep-terminal.

Function: tty-set-default-bindings keymap

Read the operating system’s terminal editing characters (as would be displayed by stty) to their Readline equivalents. The bindings are performed in keymap.

Function: tty-unset-default-bindings keymap

Reset the bindings manipulated by tty-set-default-bindings so that the terminal editing characters are bound to insert. The bindings are performed in keymap.

Function: reset-terminal terminal

Reinitialize Readline’s idea of the terminal settings using terminal as the terminal type (e.g., "vt100").

12 Utility Functions

Function: replace-line text clear-undo

Replace the contents of *line-buffer* with text. The point and mark are preserved, if possible. If clear-undo is non-nil, the undo list associated with the current line is cleared.

Function: extend-line-buffer len

Ensure that line buffer has enough space to hold len characters, possibly reallocating it if necessary.

Function: initialize

Initialize or re-initialize Readline’s internal state. It’s not strictly necessary to call this; readline calls it before reading any input. cl-readline also makes sure that Readline is always initialized when you use it.

Function: ding

Ring the terminal bell, obeying the setting of bell-style.

13 Miscellaneous Functions

Function: macro-dumper readable &optional filename append

Print the key sequences bound to macros and their values, using the current keymap to stdout. If readable is non-nil, the list is formatted in such a way that it can be made part of an inputrc file and re-read. If filename is supplied and it’s a string or path, output will be redirected to the file. append allows to append text to the file instead of overwriting it.

Function: variable-bind variable value

Make the Readline variable variable have value. This behaves as if the readline command set variable value had been executed in an inputrc file.

Function: variable-value variable

Return a string representing the value of the Readline variable variable. For Boolean variables, this string is either ’on’ or ’off’.

Function: variable-dumper readable &optional filename append

Print the readline variable names and their current values to stdout. If readable is not nil, the list is formatted in such a way that it can be made part of an inputrc file and re-read. If filename is supplied and it’s a string or path, output will be redirected to the file. append allows to append text to the file instead of overwriting it.

Function: set-paren-blink-timeout micros

Set the time interval (in microseconds) that Readline waits when showing a balancing character when blink-matching-paren has been enabled. The function returns previous value of the parameter.

Function: clear-history

Clear the history list by deleting all of the entries.

Function: read-history filename

Add the contents of filename to the history list, a line at a time.

Function: write-history filename

Write the current history to filename, overwriting filename if necessary.

14 Signal Handling

Signals are asynchronous events sent to a process by the Unix kernel, sometimes on behalf of another process. They are intended to indicate exceptional events, like a user pressing the interrupt key on his terminal, or a network connection being broken. There is a class of signals that can be sent to the process currently reading input from the keyboard. Since Readline changes the terminal attributes when it is called, it needs to perform special processing when such a signal is received in order to restore the terminal to a sane state, or provide application writers with functions to do so manually.

Readline contains an internal signal handler that is installed for a number of signals (SIGINT, SIGQUIT, SIGTERM, SIGHUP, SIGALRM, SIGTSTP, SIGTTIN, and SIGTTOU). When one of these signals is received, the signal handler will reset the terminal attributes to those that were in effect before readline was called, reset the signal handling to what it was before readline was called, and resend the signal to the calling application. If and when the calling application’s signal handler returns, Readline will reinitialize the terminal and continue to accept input. When a SIGINT is received, the Readline signal handler performs some additional work, which will cause any partially-entered line to be aborted (see the description of free-line-state below).

There is an additional Readline signal handler, for SIGWINCH, which the kernel sends to a process whenever the terminal’s size changes (for example, if a user resizes an xterm). The Readline SIGWINCH handler updates Readline’s internal screen size information, and then calls any SIGWINCH signal handler the calling application has installed. Readline calls the application’s SIGWINCH signal handler without resetting the terminal to its original state. If the application’s signal handler does more than update its idea of the terminal size and return (for example, a longjmp back to a main processing loop), it must call cleanup-after-signal (described below), to restore the terminal state.

Readline provides two variables that allow application writers to control whether or not it will catch certain signals and act on them when they are received. It is important that applications change the values of these variables only when calling readline, not in a signal handler, so Readline’s internal signal state is not corrupted.

Symbol macro: *catch-signals*

Boolean. If this variable is non-nil, Readline will install signal handlers for SIGINT, SIGQUIT, SIGTERM, SIGHUP, SIGALRM, SIGTSTP, SIGTTIN, and SIGTTOU. The default value of *catch-signals* is t.

Symbol macro: *catch-sigwinch*

If this variable is set to a non-nil value, Readline will install a signal handler for SIGWINCH. The default value of *catch-sigwinch* is t.

Symbol macro: *change-environment*

If this variable is set to a non-nil value, and Readline is handling SIGWINCH, Readline will modify the LINES and COLUMNS environment variables upon receipt of a SIGWINCH. The default value of *change-environment* is t.

Function: cleanup-after-signal

This function will reset the state of the terminal to what it was before readline was called, and remove the Readline signal handlers for all signals, depending on the values of *catch-signals* and *catch-sigwinch*.

Function: free-line-state

This will free any partial state associated with the current input line (undo information, any partial history entry, any partially-entered keyboard macro, and any partially-entered numeric argument). This should be called before cleanup-after-signal. The Readline signal handler for SIGINT calls this to abort the current input line.

Function: reset-after-signal

This will reinitialize the terminal and reinstall any Readline signal handlers, depending on the values of *catch-signals* and *catch-sigwinch*.

Function: echo-signal-char sig

If an application wishes to install its own signal handlers, but still have readline display characters that generate signals, calling this function with sig set to :sigint, :sigquit, or :sigtstp will display the character generating that signal.

Function: resize-terminal

Update Readline’s internal screen size by reading values from the kernel.

Function: set-screen-size rows cols

Set Readline’s idea of the terminal size to rows rows and cols columns. If either rows or columns is less than or equal to 0, Readline’s idea of that terminal dimension is unchanged.

Function: get-screen-size

Return Readline’s idea of the terminal’s size. The function returns multiple values: number of rows and columns.

Function: reset-screen-size

Cause Readline to reobtain the screen size and recalculate its dimensions.

Function: set-signals

Install Readline’s signal handler for SIGINT, SIGQUIT, SIGTERM, SIGHUP, SIGALRM, SIGTSTP, SIGTTIN, SIGTTOU, and SIGWINCH, depending on the values of *catch-signals* and *catch-sigwinch*.

Function: clear-signals

Remove all of the Readline signal handlers installed by set-signals.

15 Example

This program demonstrates some basic capacities of cl-readline. Note that you should run it in terminal, not via SLIME. See more at https://github.com/vindarel/cl-readline-example.

;;; Load some systems and define a package...

(asdf:load-system :str)
(asdf:load-system :cl-readline)

(cl:defpackage :example
  (:use    #:common-lisp)
  (:export #:run-example))

(in-package :example)

;;; Now let's define lists of verbs and fruits:

(defvar *verbs*  '("eat" "get" "throw" "quit"))
(defvar *fruits* '("banana" "apple" "orange" "banana_two"))

;;; Define and register function that does custom completion: if the user enters
;;; a first word, it will be completed as a verb, and the second and later words will
;;; be completed as fruits.

(defun custom-complete (text start end)
  (declare (ignore end))
  (labels ((select-completions (list)
             (let ((els (remove-if-not (lambda (it)
                                         (str:starts-with? text it))
                                       list)))
               (if (cdr els)
                   (cons (str:prefix els) els)
                   els))))
    (if (zerop start)
        (select-completions *verbs*)
        (select-completions *fruits*))))

(rl:register-function :complete #'custom-complete)

;;; Let's also create a custom command and bind it to some key
;;; sequence so the user can invoke it. In this example the user can
;;; automagically insert the phrase 'inserted text' pressing
;;; Control-o.

(defun print-some-text (arg key)
  (declare (ignore arg key))
  (rl:insert-text "inserted text"))

(rl:bind-keyseq "\\C-o" #'print-some-text)

;;; Let's write novelty-check, so if the actual line is equal to the most
;;; recent history line it will not be added to the history.

(defun novelty-check (x y)
  (string/= (string-trim " " x)
            (string-trim " " y)))

;;; Finally, this is our main function. To exit from the loop, enter 'quit'.

(defun run-example ()
  ;; see cl-readline-example to see how to catch a C-c.
  (do ((i 0 (1+ i))
       (text ""))
      ((string= "quit" (string-trim " " text)))
    (setf text
          (rl:readline :prompt (format nil "[~a]> " i)
                       :add-history t
                       :novelty-check #'novelty-check))))

Appendix A GNU Free Documentation License

Copyright © 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc.
http://fsf.org/

Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.

0. PREAMBLE

   The purpose of this License is to make a manual, textbook, or other functional and useful document free in the sense of freedom: to assure everyone the effective freedom to copy and redistribute it, with or without modifying it, either commercially or noncommercially. Secondarily, this License preserves for the author and publisher a way to get credit for their work, while not being considered responsible for modifications made by others.

   This License is a kind of “copyleft”, which means that derivative works of the document must themselves be free in the same sense. It complements the GNU General Public License, which is a copyleft license designed for free software.

   We have designed this License in order to use it for manuals for free software, because free software needs free documentation: a free program should come with manuals providing the same freedoms that the software does. But this License is not limited to software manuals; it can be used for any textual work, regardless of subject matter or whether it is published as a printed book. We recommend this License principally for works whose purpose is instruction or reference.

1. APPLICABILITY AND DEFINITIONS

   This License applies to any manual or other work, in any medium, that contains a notice placed by the copyright holder saying it can be distributed under the terms of this License. Such a notice grants a world-wide, royalty-free license, unlimited in duration, to use that work under the conditions stated herein. The “Document”, below, refers to any such manual or work. Any member of the public is a licensee, and is addressed as “you”. You accept the license if you copy, modify or distribute the work in a way requiring permission under copyright law.

   A “Modified Version” of the Document means any work containing the Document or a portion of it, either copied verbatim, or with modifications and/or translated into another language.

   A “Secondary Section” is a named appendix or a front-matter section of the Document that deals exclusively with the relationship of the publishers or authors of the Document to the Document’s overall subject (or to related matters) and contains nothing that could fall directly within that overall subject. (Thus, if the Document is in part a textbook of mathematics, a Secondary Section may not explain any mathematics.) The relationship could be a matter of historical connection with the subject or with related matters, or of legal, commercial, philosophical, ethical or political position regarding them.

   The “Invariant Sections” are certain Secondary Sections whose titles are designated, as being those of Invariant Sections, in the notice that says that the Document is released under this License. If a section does not fit the above definition of Secondary then it is not allowed to be designated as Invariant. The Document may contain zero Invariant Sections. If the Document does not identify any Invariant Sections then there are none.

   The “Cover Texts” are certain short passages of text that are listed, as Front-Cover Texts or Back-Cover Texts, in the notice that says that the Document is released under this License. A Front-Cover Text may be at most 5 words, and a Back-Cover Text may be at most 25 words.

   A “Transparent” copy of the Document means a machine-readable copy, represented in a format whose specification is available to the general public, that is suitable for revising the document straightforwardly with generic text editors or (for images composed of pixels) generic paint programs or (for drawings) some widely available drawing editor, and that is suitable for input to text formatters or for automatic translation to a variety of formats suitable for input to text formatters. A copy made in an otherwise Transparent file format whose markup, or absence of markup, has been arranged to thwart or discourage subsequent modification by readers is not Transparent. An image format is not Transparent if used for any substantial amount of text. A copy that is not “Transparent” is called “Opaque”.

   Examples of suitable formats for Transparent copies include plain ASCII without markup, Texinfo input format, LaTeX input format, SGML or XML using a publicly available DTD, and standard-conforming simple HTML, PostScript or PDF designed for human modification. Examples of transparent image formats include PNG, XCF and JPG. Opaque formats include proprietary formats that can be read and edited only by proprietary word processors, SGML or XML for which the DTD and/or processing tools are not generally available, and the machine-generated HTML, PostScript or PDF produced by some word processors for output purposes only.

   The “Title Page” means, for a printed book, the title page itself, plus such following pages as are needed to hold, legibly, the material this License requires to appear in the title page. For works in formats which do not have any title page as such, “Title Page” means the text near the most prominent appearance of the work’s title, preceding the beginning of the body of the text.

   The “publisher” means any person or entity that distributes copies of the Document to the public.

   A section “Entitled XYZ” means a named subunit of the Document whose title either is precisely XYZ or contains XYZ in parentheses following text that translates XYZ in another language. (Here XYZ stands for a specific section name mentioned below, such as “Acknowledgements”, “Dedications”, “Endorsements”, or “History”.) To “Preserve the Title” of such a section when you modify the Document means that it remains a section “Entitled XYZ” according to this definition.

   The Document may include Warranty Disclaimers next to the notice which states that this License applies to the Document. These Warranty Disclaimers are considered to be included by reference in this License, but only as regards disclaiming warranties: any other implication that these Warranty Disclaimers may have is void and has no effect on the meaning of this License.

2. VERBATIM COPYING

   You may copy and distribute the Document in any medium, either commercially or noncommercially, provided that this License, the copyright notices, and the license notice saying this License applies to the Document are reproduced in all copies, and that you add no other conditions whatsoever to those of this License. You may not use technical measures to obstruct or control the reading or further copying of the copies you make or distribute. However, you may accept compensation in exchange for copies. If you distribute a large enough number of copies you must also follow the conditions in section 3.

   You may also lend copies, under the same conditions stated above, and you may publicly display copies.

3. COPYING IN QUANTITY

   If you publish printed copies (or copies in media that commonly have printed covers) of the Document, numbering more than 100, and the Document’s license notice requires Cover Texts, you must enclose the copies in covers that carry, clearly and legibly, all these Cover Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on the back cover. Both covers must also clearly and legibly identify you as the publisher of these copies. The front cover must present the full title with all words of the title equally prominent and visible. You may add other material on the covers in addition. Copying with changes limited to the covers, as long as they preserve the title of the Document and satisfy these conditions, can be treated as verbatim copying in other respects.

   If the required texts for either cover are too voluminous to fit legibly, you should put the first ones listed (as many as fit reasonably) on the actual cover, and continue the rest onto adjacent pages.

   If you publish or distribute Opaque copies of the Document numbering more than 100, you must either include a machine-readable Transparent copy along with each Opaque copy, or state in or with each Opaque copy a computer-network location from which the general network-using public has access to download using public-standard network protocols a complete Transparent copy of the Document, free of added material. If you use the latter option, you must take reasonably prudent steps, when you begin distribution of Opaque copies in quantity, to ensure that this Transparent copy will remain thus accessible at the stated location until at least one year after the last time you distribute an Opaque copy (directly or through your agents or retailers) of that edition to the public.

   It is requested, but not required, that you contact the authors of the Document well before redistributing any large number of copies, to give them a chance to provide you with an updated version of the Document.

4. MODIFICATIONS

   You may copy and distribute a Modified Version of the Document under the conditions of sections 2 and 3 above, provided that you release the Modified Version under precisely this License, with the Modified Version filling the role of the Document, thus licensing distribution and modification of the Modified Version to whoever possesses a copy of it. In addition, you must do these things in the Modified Version:

   1. Use in the Title Page (and on the covers, if any) a title distinct from that of the Document, and from those of previous versions (which should, if there were any, be listed in the History section of the Document). You may use the same title as a previous version if the original publisher of that version gives permission.
   2. List on the Title Page, as authors, one or more persons or entities responsible for authorship of the modifications in the Modified Version, together with at least five of the principal authors of the Document (all of its principal authors, if it has fewer than five), unless they release you from this requirement.
   3. State on the Title page the name of the publisher of the Modified Version, as the publisher.
   4. Preserve all the copyright notices of the Document.
   5. Add an appropriate copyright notice for your modifications adjacent to the other copyright notices.
   6. Include, immediately after the copyright notices, a license notice giving the public permission to use the Modified Version under the terms of this License, in the form shown in the Addendum below.
   7. Preserve in that license notice the full lists of Invariant Sections and required Cover Texts given in the Document’s license notice.
   8. Include an unaltered copy of this License.
   9. Preserve the section Entitled “History”, Preserve its Title, and add to it an item stating at least the title, year, new authors, and publisher of the Modified Version as given on the Title Page. If there is no section Entitled “History” in the Document, create one stating the title, year, authors, and publisher of the Document as given on its Title Page, then add an item describing the Modified Version as stated in the previous sentence.
   10. Preserve the network location, if any, given in the Document for public access to a Transparent copy of the Document, and likewise the network locations given in the Document for previous versions it was based on. These may be placed in the “History” section. You may omit a network location for a work that was published at least four years before the Document itself, or if the original publisher of the version it refers to gives permission.
   11. For any section Entitled “Acknowledgements” or “Dedications”, Preserve the Title of the section, and preserve in the section all the substance and tone of each of the contributor acknowledgements and/or dedications given therein.
   12. Preserve all the Invariant Sections of the Document, unaltered in their text and in their titles. Section numbers or the equivalent are not considered part of the section titles.
   13. Delete any section Entitled “Endorsements”. Such a section may not be included in the Modified Version.
   14. Do not retitle any existing section to be Entitled “Endorsements” or to conflict in title with any Invariant Section.
   15. Preserve any Warranty Disclaimers.

   If the Modified Version includes new front-matter sections or appendices that qualify as Secondary Sections and contain no material copied from the Document, you may at your option designate some or all of these sections as invariant. To do this, add their titles to the list of Invariant Sections in the Modified Version’s license notice. These titles must be distinct from any other section titles.

   You may add a section Entitled “Endorsements”, provided it contains nothing but endorsements of your Modified Version by various parties—for example, statements of peer review or that the text has been approved by an organization as the authoritative definition of a standard.

   You may add a passage of up to five words as a Front-Cover Text, and a passage of up to 25 words as a Back-Cover Text, to the end of the list of Cover Texts in the Modified Version. Only one passage of Front-Cover Text and one of Back-Cover Text may be added by (or through arrangements made by) any one entity. If the Document already includes a cover text for the same cover, previously added by you or by arrangement made by the same entity you are acting on behalf of, you may not add another; but you may replace the old one, on explicit permission from the previous publisher that added the old one.

   The author(s) and publisher(s) of the Document do not by this License give permission to use their names for publicity for or to assert or imply endorsement of any Modified Version.

5. COMBINING DOCUMENTS

   You may combine the Document with other documents released under this License, under the terms defined in section 4 above for modified versions, provided that you include in the combination all of the Invariant Sections of all of the original documents, unmodified, and list them all as Invariant Sections of your combined work in its license notice, and that you preserve all their Warranty Disclaimers.

   The combined work need only contain one copy of this License, and multiple identical Invariant Sections may be replaced with a single copy. If there are multiple Invariant Sections with the same name but different contents, make the title of each such section unique by adding at the end of it, in parentheses, the name of the original author or publisher of that section if known, or else a unique number. Make the same adjustment to the section titles in the list of Invariant Sections in the license notice of the combined work.

   In the combination, you must combine any sections Entitled “History” in the various original documents, forming one section Entitled “History”; likewise combine any sections Entitled “Acknowledgements”, and any sections Entitled “Dedications”. You must delete all sections Entitled “Endorsements.”

6. COLLECTIONS OF DOCUMENTS

   You may make a collection consisting of the Document and other documents released under this License, and replace the individual copies of this License in the various documents with a single copy that is included in the collection, provided that you follow the rules of this License for verbatim copying of each of the documents in all other respects.

   You may extract a single document from such a collection, and distribute it individually under this License, provided you insert a copy of this License into the extracted document, and follow this License in all other respects regarding verbatim copying of that document.

7. AGGREGATION WITH INDEPENDENT WORKS

   A compilation of the Document or its derivatives with other separate and independent documents or works, in or on a volume of a storage or distribution medium, is called an “aggregate” if the copyright resulting from the compilation is not used to limit the legal rights of the compilation’s users beyond what the individual works permit. When the Document is included in an aggregate, this License does not apply to the other works in the aggregate which are not themselves derivative works of the Document.

   If the Cover Text requirement of section 3 is applicable to these copies of the Document, then if the Document is less than one half of the entire aggregate, the Document’s Cover Texts may be placed on covers that bracket the Document within the aggregate, or the electronic equivalent of covers if the Document is in electronic form. Otherwise they must appear on printed covers that bracket the whole aggregate.

8. TRANSLATION

   Translation is considered a kind of modification, so you may distribute translations of the Document under the terms of section 4. Replacing Invariant Sections with translations requires special permission from their copyright holders, but you may include translations of some or all Invariant Sections in addition to the original versions of these Invariant Sections. You may include a translation of this License, and all the license notices in the Document, and any Warranty Disclaimers, provided that you also include the original English version of this License and the original versions of those notices and disclaimers. In case of a disagreement between the translation and the original version of this License or a notice or disclaimer, the original version will prevail.

   If a section in the Document is Entitled “Acknowledgements”, “Dedications”, or “History”, the requirement (section 4) to Preserve its Title (section 1) will typically require changing the actual title.

9. TERMINATION

   You may not copy, modify, sublicense, or distribute the Document except as expressly provided under this License. Any attempt otherwise to copy, modify, sublicense, or distribute it is void, and will automatically terminate your rights under this License.

   However, if you cease all violation of this License, then your license from a particular copyright holder is reinstated (a) provisionally, unless and until the copyright holder explicitly and finally terminates your license, and (b) permanently, if the copyright holder fails to notify you of the violation by some reasonable means prior to 60 days after the cessation.

   Moreover, your license from a particular copyright holder is reinstated permanently if the copyright holder notifies you of the violation by some reasonable means, this is the first time you have received notice of violation of this License (for any work) from that copyright holder, and you cure the violation prior to 30 days after your receipt of the notice.

   Termination of your rights under this section does not terminate the licenses of parties who have received copies or rights from you under this License. If your rights have been terminated and not permanently reinstated, receipt of a copy of some or all of the same material does not give you any rights to use it.

10. FUTURE REVISIONS OF THIS LICENSE

    The Free Software Foundation may publish new, revised versions of the GNU Free Documentation License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. See http://www.gnu.org/copyleft/.

    Each version of the License is given a distinguishing version number. If the Document specifies that a particular numbered version of this License “or any later version” applies to it, you have the option of following the terms and conditions either of that specified version or of any later version that has been published (not as a draft) by the Free Software Foundation. If the Document does not specify a version number of this License, you may choose any version ever published (not as a draft) by the Free Software Foundation. If the Document specifies that a proxy can decide which future versions of this License can be used, that proxy’s public statement of acceptance of a version permanently authorizes you to choose that version for the Document.

11. RELICENSING

    “Massive Multiauthor Collaboration Site” (or “MMC Site”) means any World Wide Web server that publishes copyrightable works and also provides prominent facilities for anybody to edit those works. A public wiki that anybody can edit is an example of such a server. A “Massive Multiauthor Collaboration” (or “MMC”) contained in the site means any set of copyrightable works thus published on the MMC site.

    “CC-BY-SA” means the Creative Commons Attribution-Share Alike 3.0 license published by Creative Commons Corporation, a not-for-profit corporation with a principal place of business in San Francisco, California, as well as future copyleft versions of that license published by that same organization.

    “Incorporate” means to publish or republish a Document, in whole or in part, as part of another Document.

    An MMC is “eligible for relicensing” if it is licensed under this License, and if all works that were first published under this License somewhere other than this MMC, and subsequently incorporated in whole or in part into the MMC, (1) had no cover texts or invariant sections, and (2) were thus incorporated prior to November 1, 2008.

    The operator of an MMC Site may republish an MMC contained in the site under CC-BY-SA on the same site at any time before August 1, 2009, provided the MMC is eligible for relicensing.

ADDENDUM: How to use this License for your documents

To use this License in a document you have written, include a copy of the License in the document and put the following copyright and license notices just after the title page:

  Copyright (C)  year  your name.
  Permission is granted to copy, distribute and/or modify this document
  under the terms of the GNU Free Documentation License, Version 1.3
  or any later version published by the Free Software Foundation;
  with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
  Texts.  A copy of the license is included in the section entitled ``GNU
  Free Documentation License''.

If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, replace the “with…Texts.” line with this:

    with the Invariant Sections being list their titles, with
    the Front-Cover Texts being list, and with the Back-Cover Texts
    being list.

If you have Invariant Sections without Cover Texts, or some other combination of the three, merge those two alternatives to suit the situation.

If your document contains nontrivial examples of program code, we recommend releasing these examples in parallel under your choice of free software license, such as the GNU General Public License, to permit their use in free software.

Concept Index

Function and Variable Index