--- /dev/null
+@c -*-texinfo-*-
+@c This is part of the GNU Guile Reference Manual.
+@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004
+@c Free Software Foundation, Inc.
+@c See the file guile.texi for copying conditions.
+
+@page
+@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
+
+@c FIXME::martin: Review me!
+
+@cindex 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 (@pxref{Runtime Options}).
+
+@findex readline-options
+@findex readline-enable
+@findex readline-disable
+@findex readline-set!
+Here is the list of readline options generated by typing
+@code{(readline-options 'full)} in Guile. You can also see the
+default values.
+
+@smalllisp
+bounce-parens 500 Time (ms) to show matching opening parenthesis (0 = off).
+history-length 200 History length.
+history-file yes Use history file.
+@end smalllisp
+
+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.
+
+@lisp
+(readline-disable 'history)
+@end lisp
+
+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
+@section Value History
+
+@c FIXME::martin: Review me!
+
+@cindex value history
+Another module which makes command line usage more convenient is
+@code{(ice-9 history)}. This module will change the REPL so that each
+value which is evaluated and printed will be remembered under a name
+constructed from the dollar character (@code{$}) and the number of the
+evaluated expression.
+
+Consider an example session.
+
+@example
+guile> (use-modules (ice-9 history))
+guile> 1
+$1 = 1
+guile> (+ $1 $1)
+$2 = 2
+guile> (* $2 $2)
+$3 = 4
+@end example
+
+After loading the value history module @code{(ice-9 history)}, one
+(trivial) expression is evaluated. The result is stored into the
+variable @code{$1}. This fact is indicated by the output @code{$1 = },
+which is also caused by @code{(ice-9 history)}. In the next line, this
+variable is used two times, to produce the value @code{$2}, which in
+turn is used in the calculation for @code{$3}.
+
+
+@c Local Variables:
+@c TeX-master: "guile.texi"
+@c End:
projects / lilypond.git / blobdiff