cl-readline

API Reference

cl-readline

Common Lisp bindings to GNU Readline library

CL-READLINE

  • 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.
  • 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.
  • 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.
  • Cffi-Function COPY-KEYMAP ((keymap pointer))
    Return a new keymap which is a copy of KEYMAP.
  • Function COPY-KEYMAP (keymap)
    Return a new keymap which is a copy of KEYMAP.
  • Cffi-Function FREE-KEYMAP ((keymap pointer))
    Free all storage associated with KEYMAP.
  • Function FREE-KEYMAP (keymap)
    Free all storage associated with KEYMAP.
  • Cffi-Function GET-KEYMAP
    Return currently active keymap.
  • Function GET-KEYMAP
    Return currently active keymap.
  • Cffi-Function SET-KEYMAP ((keymap pointer))
    Make KEYMAP the currently active keymap.
  • Function SET-KEYMAP (keymap)
    Make KEYMAP the currently active keymap.
  • Cffi-Function GET-KEYMAP-BY-NAME ((name string))
    Return the keymap matching NAME. NAME is one which would be supplied in a set keymap inputrc line.
  • Function GET-KEYMAP-BY-NAME (name)
    Return the keymap matching NAME. NAME is one which would be supplied in a set keymap inputrc line.
  • Cffi-Function GET-KEYMAP-NAME ((keymap pointer))
    Return the name matching KEYMAP. Name is one which would be supplied in a set keymap inputrc line.
  • Function GET-KEYMAP-NAME (keymap)
    Return the name matching KEYMAP. 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.
  • 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.
  • 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.
  • Macro UNDO-GROUP (&body body)
    All insertion and deletion inside this macro will be grouped together into one undo operation.
  • Cffi-Function ADD-UNDO ((what undo-code) (start int) (end int) (text string))
    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 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.
  • Cffi-Function FREE-UNDO-LIST
    Free the existing undo list.
  • Function FREE-UNDO-LIST
    Free the existing undo list.
  • Cffi-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 DO-UNDO
    Undo the first thing on the undo list. Returns NIL if there was nothing to undo, T if something was undone.
  • Cffi-Function MODIFYING ((start int) (end int))
    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.
  • 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.
  • Cffi-Function REDISPLAY
    Change what's displayed on the screen to reflect the current contents of `*line-buffer*'.
  • Function REDISPLAY
    Change what's displayed on the screen to reflect the current contents of `*line-buffer*'.
  • Cffi-Function FORCED-UPDATE-DISPLAY
    Force the line to be updated and redisplayed, whether or not Readline thinks the screen display is correct.
  • 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'.
  • Cffi-Function RESET-LINE-STATE
    Reset the display state to a clean state and redisplay the current line starting on a new line.
  • Function RESET-LINE-STATE
    Reset the display state to a clean state and redisplay the current line starting on a new line.
  • Cffi-Function CRLF
    Move the cursor to the start of the next screen line.
  • Function CRLF
    Move the cursor to the start of the next screen line.
  • Cffi-Function SHOW-CHAR ((char int-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 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.
  • 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.
  • Cffi-Function SET-PROMPT ((prompt string))
    Make Readline use PROMPT for subsequent redisplay. This calls `expand-prompt' to expand the prompt and sets `+prompt+' to the result.
  • 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.
  • Cffi-Function INSERT-TEXT ((text string))
    Insert TEXT into the line at the current cursor position. Return the number of characters inserted.
  • Function INSERT-TEXT (text)
    Insert TEXT into the line at the current cursor position. Return the number of characters inserted.
  • Cffi-Function DELETE-TEXT ((start int) (end int))
    Delete the text between START and END in the current line. Return the number of characters deleted.
  • Function DELETE-TEXT (start end)
    Delete the text between START and END in the current line. Return the number of characters deleted.
  • Cffi-Function KILL-TEXT ((start int) (end int))
    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.
  • 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.
  • Cffi-Function READ-KEY
    Return the next character available from Readline's current input stream.
  • Function READ-KEY
    Return the next character available from Readline's current input stream.
  • Cffi-Function STUFF-CHAR ((char int-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 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.
  • Cffi-Function EXECUTE-NEXT ((char int-char))
    Make CHAR be the next command to be executed when `read-key' is called.
  • Function EXECUTE-NEXT (char)
    Make CHAR be the next command to be executed when `read-key' is called.
  • Cffi-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 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'.
  • Cffi-Function SET-KEYBOARD-INPUT-TIMEOUT ((u int))
    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.
  • 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.
  • Cffi-Function PREP-TERMINAL ((eight-bit-input boolean))
    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 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.
  • Cffi-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 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.
  • Cffi-Function TTY-UNSET-DEFAULT-BINDINGS ((keymap pointer))
    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 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.
  • Cffi-Function RESET-TERMINAL ((terminal string))
    Reinitialize Readline's idea of the terminal settings using TERMINAL as the terminal type (e.g., vt100).
  • Function RESET-TERMINAL (terminal)
    Reinitialize Readline's idea of the terminal settings using TERMINAL as the terminal type (e.g., vt100).
  • Cffi-Function REPLACE-LINE ((text string) (clear-undo boolean))
    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 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.
  • Cffi-Function EXTEND-LINE-BUFFER ((len int))
    Ensure that line buffer has enough space to hold LEN characters, possibly reallocating it if necessary.
  • Function EXTEND-LINE-BUFFER (len)
    Ensure that line buffer has enough space to hold LEN characters, possibly reallocating it if necessary.
  • Cffi-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.
  • 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.
  • Cffi-Function DING
    Ring the terminal bell, obeying the setting of bell-style.
  • Function DING
    Ring the terminal bell, obeying the setting of bell-style.
  • 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.
  • Cffi-Function SET-PAREN-BLINK-TIMEOUT ((micros int))
    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 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.
  • Cffi-Function CLEAR-HISTORY
    Clear the history list by deleting all of the entries.
  • Function CLEAR-HISTORY
    Clear the history list by deleting all of the entries.
  • Cffi-Function READ-HISTORY ((filename string))
    Add the contents of filename to the history list, a line at a time.
  • Function READ-HISTORY (filename)
    Add the contents of filename to the history list, a line at a time.
  • Cffi-Function WRITE-HISTORY ((filename string))
    Write the current history to filename, overwriting filename if necessary.
  • Function WRITE-HISTORY (filename)
    Write the current history to filename, overwriting filename if necessary.
  • Cffi-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 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*'.
  • Cffi-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 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.
  • Cffi-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 RESET-AFTER-SIGNAL
    This will reinitialize the terminal and reinstall any Readline signal handlers, depending on the values of `*catch-signals*' and `*catch-sigwinch*'.
  • Cffi-Function ECHO-SIGNAL-CHAR ((sig unix-signal))
    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 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.
  • Cffi-Function SET-SCREEN-SIZE ((rows int) (cols int))
    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 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.
  • Cffi-Function RESET-SCREEN-SIZE
    Cause Readline to reobtain the screen size and recalculate its dimensions.
  • Function RESET-SCREEN-SIZE
    Cause Readline to reobtain the screen size and recalculate its dimensions.
  • Cffi-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 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*'.
  • Cffi-Function CLEAR-SIGNALS
    Remove all of the Readline signal handlers installed by `set-signals'.
  • Function CLEAR-SIGNALS
    Remove all of the Readline signal handlers installed by `set-signals'.