(use-modules (ice-9 readline))

— 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”.

— 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).

— 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). 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).

— Function: make-completion-function string-list

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