diff options
Diffstat (limited to 'doc/ref/repl-modules.texi')
-rw-r--r-- | doc/ref/repl-modules.texi | 139 |
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 |