7.9.3 Readline Functions

The following functions are provided by

(use-modules (ice-9 readline))

There are two ways to use readline from Scheme code, either make calls to readline directly to get line by line input, or use the readline port below with all the usual reading functions.

Function: readline [prompt]

Read a line of input from the user and return it as a string (without a newline at the end). prompt is the prompt to show, or the default is the string set in set-readline-prompt! below.

(readline "Type something: ") ⇒ "hello"

Function: set-readline-input-port! port

Function: set-readline-output-port! port

Set the input and output port the readline function should read from and write to. port must be a file port (see File Ports), and should usually be a terminal.

The default is the current-input-port and current-output-port (see Default Ports) when (ice-9 readline) loads, which in an interactive user session means the Unix “standard input” and “standard output”.

7.9.3.1 Readline Port

Function: readline-port

Return a buffered input port (see Buffered Input) which calls the readline function above to get input. This port can be used with all the usual reading functions (read, read-char, etc), and the user gets the interactive editing features of readline.

There’s only a single readline port created. readline-port creates it when first called, and on subsequent calls just returns what it previously made.

Function: activate-readline

If the current-input-port is a terminal (see isatty?) then enable readline for all reading from current-input-port (see Default Ports) and enable readline features in the interactive REPL (see The REPL).

(activate-readline)
(read-char)

activate-readline enables readline on current-input-port simply by a set-current-input-port to the readline-port above. An application can do that directly if the extra REPL features that activate-readline adds are not wanted.

Function: set-readline-prompt! prompt1 [prompt2]

Set the prompt string to print when reading input. This is used when reading through readline-port, and is also the default prompt for the readline function above.

prompt1 is the initial prompt shown. If a user might enter an expression across multiple lines, then prompt2 is a different prompt to show further input required. In the Guile REPL for instance this is an ellipsis (‘...’).

See set-buffered-input-continuation?! (see Buffered Input) for an application to indicate the boundaries of logical expressions (assuming of course an application has such a notion).

7.9.3.2 Completion

Function: with-readline-completion-function completer thunk

Call (thunk) with completer as the readline tab completion function to be used in any readline calls within that thunk. completer can be #f for no completion.

completer will be called as (completer text state), as described in (see How Completing Works in GNU Readline Library). text is a partial word to be completed, and each completer call should return a possible completion string or #f when no more. state is #f for the first call asking about a new text then #t while getting further completions of that text.

Here’s an example completer for user login names from the password file (see User Information), much like readline’s own rl_username_completion_function,

(define (username-completer-function text state)
  (if (not state)
      (setpwent))  ;; new, go to start of database
  (let more ((pw (getpwent)))
    (if pw
        (if (string-prefix? text (passwd:name pw))
            (passwd:name pw)     ;; this name matches, return it
            (more (getpwent)))   ;; doesn't match, look at next
        (begin
          ;; end of database, close it and return #f
          (endpwent)
          #f))))

Function: apropos-completion-function text state

A completion function offering completions for Guile functions and variables (all defines). This is the default completion function.

Function: filename-completion-function text state

A completion function offering filename completions. This is readline’s rl_filename_completion_function (see Completion Functions in GNU Readline Library).

Function: make-completion-function string-list

Return a completion function which offers completions from the possibilities in string-list. Matching is case-sensitive.