Document string-bytes-per-char and %string-dump

[bpt/guile.git] / doc / ref / repl-modules.texi

@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: