summaryrefslogtreecommitdiff
path: root/doc/ref/repl-modules.texi
diff options
context:
space:
mode:
Diffstat (limited to 'doc/ref/repl-modules.texi')
-rw-r--r--doc/ref/repl-modules.texi139
1 files changed, 137 insertions, 2 deletions
diff --git a/doc/ref/repl-modules.texi b/doc/ref/repl-modules.texi
index 45f410c3a..5f274e253 100644
--- a/doc/ref/repl-modules.texi
+++ b/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