Readline Support
================

Guile comes with an interface module to the readline library (see GNU Readline Library).  This makes interactive use much more convenient, because of the command-line editing features of readline.  Using (ice-9 readline), you can navigate through the current input line with the cursor keys, retrieve older command lines from the input history and even search through the history entries.

Loading Readline Support
------------------------

The module is not loaded by default and so has to be loaded and activated explicitly.  This is done with two simple lines of code:

     (use-modules (ice-9 readline))
     (activate-readline)

The first line will load the necessary code, and the second will activate readline's features for the REPL.  If you plan to use this module often, you should save these to lines to your .guile personal startup file.

You will notice that the REPL's behaviour changes a bit when you have loaded the readline module.  For example, when you press Enter before typing in the closing parentheses of a list, you will see the continuation prompt, three dots: ...  This gives you a nice visual feedback when trying to match parentheses.  To make this even easier, bouncing parentheses are implemented.  That means that when you type in a closing parentheses, the cursor will jump to the corresponding opening parenthesis for a short time, making it trivial to make them match.

Once the readline module is activated, all lines entered interactively will be stored in a history and can be recalled later using the cursor-up and -down keys.  Readline also understands the Emacs keys for navigating through the command line and history.

When you quit your Guile session by evaluating (quit) or pressing Ctrl-D, the history will be saved to the file .guile_history and read in when you start Guile for the next time.  Thus you can start a new Guile session and still have the (probably long-winded) definition expressions available.

You can specify a different history file by setting the environment variable GUILE_HISTORY.  And you can make Guile specific customizations to your .inputrc by testing for application Guile (see Conditional Init Constructs (GNU Readline Library)).  For instance to define a key inserting a matched pair of parentheses,

     $if Guile
       "\C-o": "()\C-b"
     $endif

Readline Options
----------------

The readline interface module can be configured in several ways to better suit the user's needs.  Configuration is done via the readline module's options interface, in a similar way to the evaluator and debugging options (see Runtime Options).

Here is the list of readline options generated by typing (readline-options 'help) in Guile.  You can also see the default values.

     history-file    yes     Use history file.
     history-length  200     History length.
     bounce-parens   500     Time (ms) to show matching opening parenthesis
                             (0 = off).

The history length specifies how many input lines will be remembered. If the history contains that many lines and additional lines are entered, the oldest lines will be lost.  You can switch on/off the usage of the history file using the following call.

     (readline-disable 'history)

The readline options interface can only be used after loading the readline module, because it is defined in that module.

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''.

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

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