(Readline Functions): New section on how to call readline from scheme code.

doc/ref/repl-modules.texi

@@ -23,6 +23,7 @@ history entries.
 @menu
 * Loading Readline Support::    How to load readline support into Guile.
 * Readline Options::            How to modify readline's behaviour.
+* Readline Functions::          Programming with readline.
 @end menu
 
 
@@ -32,7 +33,6 @@ history entries.
 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:
 
-@findex activate-readline
 @lisp
 (use-modules (ice-9 readline))
 (activate-readline)
@@ -91,7 +91,7 @@ $endif
 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 (@pxref{User level options interfaces}.)
+debugging options (@pxref{Runtime Options}).
 
 @findex readline-options
 @findex readline-enable
@@ -119,6 +119,141 @@ usage of the history file using the following call.
 The readline options interface can only be used @emph{after} loading
 the readline module, because it is defined in that module.
 
+@node Readline Functions
+@subsection Readline Functions
+
+The following functions are provided by
+
+@example
+(use-modules (ice-9 readline))
+@end example
+
+There are two ways to use readline from Scheme code, either make calls
+to @code{readline} directly to get line by line input, or use the
+readline port below with all the usual reading functions.
+
+@defun readline [prompt]
+Read a line of input from the user and return it as a string (without
+a newline at the end).  @var{prompt} is the prompt to show, or the
+default is the string set in @code{set-readline-prompt!} below.
+
+@example
+(readline "Type something: ") @result{} "hello"
+@end example
+@end defun
+
+@defun set-readline-input-port! port
+@defunx set-readline-output-port! port
+Set the input and output port the readline function should read from
+and write to.  @var{port} must be a file port (@pxref{File Ports}),
+and should usually be a terminal.
+
+The default is the @code{current-input-port} and
+@code{current-output-port} (@pxref{Default Ports}) when @code{(ice-9
+readline)} loads, which in an interactive user session means the Unix
+``standard input'' and ``standard output''.
+@end defun
+
+@subsubsection Readline Port
+
+@defun readline-port
+Return a buffered input port (@pxref{Buffered Input}) which calls the
+@code{readline} function above to get input.  This port can be used
+with all the usual reading functions (@code{read}, @code{read-char},
+etc), and the user gets the interactive editing features of readline.
+
+There's only a single readline port created.  @code{readline-port}
+creates it when first called, and on subsequent calls just returns
+what it previously made.
+@end defun
+
+@defun activate-readline
+If the @code{current-input-port} is a terminal (@pxref{Terminals and
+Ptys,, @code{isatty?}}) then enable readline for all reading from
+@code{current-input-port} (@pxref{Default Ports}) and enable readline
+features in the interactive REPL (@pxref{The REPL}).
+
+@example
+(activate-readline)
+(read-char)
+@end example
+
+@code{activate-readline} enables readline on @code{current-input-port}
+simply by a @code{set-current-input-port} to the @code{readline-port}
+above.  An application can do that directly if the extra REPL features
+that @code{activate-readline} adds are not wanted.
+@end defun
+
+@defun set-readline-prompt! prompt1 [prompt2]
+Set the prompt string to print when reading input.  This is used when
+reading through @code{readline-port}, and is also the default prompt
+for the @code{readline} function above.
+
+@var{prompt1} is the initial prompt shown.  If a user might enter an
+expression across multiple lines, then @var{prompt2} is a different
+prompt to show further input required.  In the Guile REPL for instance
+this is an ellipsis (@samp{...}).
+
+See @code{set-buffered-input-continuation?!} (@pxref{Buffered Input})
+for an application to indicate the boundaries of logical expressions
+(assuming of course an application has such a notion).
+@end defun
+
+@subsubsection Completion
+
+@defun with-readline-completion-function completer thunk
+Call @code{(@var{thunk})} with @var{completer} as the readline tab
+completion function to be used in any readline calls within that
+@var{thunk}.  @var{completer} can be @code{#f} for no completion.
+
+@var{completer} will be called as @code{(@var{completer} text state)},
+as described in (@pxref{How Completing Works,,, readline, GNU Readline
+Library}).  @var{text} is a partial word to be completed, and each
+@var{completer} call should return a possible completion string or
+@code{#f} when no more.  @var{state} is @code{#f} for the first call
+asking about a new @var{text} then @code{#t} while getting further
+completions of that @var{text}.
+
+Here's an example @var{completer} for user login names from the
+password file (@pxref{User Information}), much like readline's own
+@code{rl_username_completion_function},
+
+@example
+(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))))
+@end example
+@end defun
+
+@defun apropos-completion-function text state
+A completion function offering completions for Guile functions and
+variables (all @code{define}s).  This is the default completion
+function.
+@c
+@c  FIXME: Cross reference the ``apropos'' stuff when it's documented.
+@c
+@end defun
+
+@defun filename-completion-function text state
+A completion function offering filename completions.  This is
+readline's @code{rl_filename_completion_function} (@pxref{Completion
+Functions,,, readline, GNU Readline Library}).
+@end defun
+
+@defun make-completion-function string-list
+Return a completion function which offers completions from the
+possibilities in @var{string-list}.  Matching is case-sensitive.
+@end defun
+
 
 @page
 @node Value History