diff options
Diffstat (limited to 'doc/ref/repl-modules.texi')
-rw-r--r-- | doc/ref/repl-modules.texi | 256 |
1 files changed, 256 insertions, 0 deletions
diff --git a/doc/ref/repl-modules.texi b/doc/ref/repl-modules.texi new file mode 100644 index 000000000..e20393ba2 --- /dev/null +++ b/doc/ref/repl-modules.texi @@ -0,0 +1,256 @@ +@c -*-texinfo-*- +@c This is part of the GNU Guile Reference Manual. +@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2010, 2011 +@c Free Software Foundation, Inc. +@c See the file guile.texi for copying conditions. + +@node Readline Support +@section Readline Support + +@c FIXME::martin: Review me! + +@cindex readline +@cindex command line history +Guile comes with an interface module to the readline library +(@pxref{Top,,, readline, GNU Readline Library}). This +makes interactive use much more convenient, because of the command-line +editing features of readline. Using @code{(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. + +@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 + + +@node Loading Readline Support +@subsection 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: + +@lisp +(use-modules (ice-9 readline)) +(activate-readline) +@end lisp + +@c FIXME::martin: Review me! + +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 @file{.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 +@dfn{continuation} prompt, three dots: @code{...} This gives you a nice +visual feedback when trying to match parentheses. To make this even +easier, @dfn{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. + +@cindex @file{.guile_history} +When you quit your Guile session by evaluating @code{(quit)} or pressing +Ctrl-D, the history will be saved to the file @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. + +@cindex @env{GUILE_HISTORY} +@cindex @file{.inputrc} +You can specify a different history file by setting the environment +variable @env{GUILE_HISTORY}. And you can make Guile specific +customizations to your @file{.inputrc} by testing for application +@samp{Guile} (@pxref{Conditional Init Constructs,,, readline, GNU +Readline Library}). For instance to define a key inserting a matched +pair of parentheses, + +@example +$if Guile + "\C-o": "()\C-b" +$endif +@end example + +@node Readline Options +@subsection Readline Options + +@cindex readline options +The readline interface module can be tweaked in a few 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{Runtime Options}). + +@deffn {Scheme Procedure} readline-options +@deffnx {Scheme Procedure} readline-enable option-name +@deffnx {Scheme Procedure} readline-disable option-name +@deffnx {Scheme Syntax} readline-set! option-name value +Accessors for the readline options. Note that unlike the enable/disable +procedures, @code{readline-set!} is syntax, which expects an unquoted +option name. +@end deffn + +Here is the list of readline options generated by typing +@code{(readline-options 'help)} in Guile. You can also see the +default values. + +@smalllisp +history-file yes Use history file. +history-length 200 History length. +bounce-parens 500 Time (ms) to show matching opening parenthesis + (0 = off). +bracketed-paste yes Disable interpretation of control characters + in pastes. +@end smalllisp + +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 + + +@c Local Variables: +@c TeX-master: "guile.texi" +@c End: |