
The _readline_ collection (not to be confused with MzScheme's
`read-line' procedure) provides glue for using GNU's readline library
with the MzScheme read-eval-print-loop.


Normal use of readline
----------------------

The _rep.ss_ library installs a readline-based input port, and hooks
the prompt-and-read part of MzScheme's read-eval-print loop to
interact with it.

You can start MzScheme with

  mzscheme -L rep.ss readline

or you can put the following in your ~/.mzschemerc so that MzScheme
starts with readline support when appropriate:

  (when (regexp-match? #rx"xterm" (getenv "TERM"))
    (dynamic-require '(lib "rep.ss" "readline") #f))

The "rep.ss" module is actually a wrapper around "rep-start.ss", it
will *not* invoke it if the input port is not a terminal port (eg,
when the input is redirected from a file).  Still the TERM condition
above is useful for starting MzScheme in dumb terminals, eg, inside
Emacs.

Completion is set to use the visible bindings in the current
namespace; this is far from ideal, but it's better than readline's
default filename completion which is rarely useful.  In addition, the
readline history is stored across invocations in MzScheme's
preferences file, assuming MzScheme exits normally.


Interacting with the readline-enabled input port
------------------------------------------------

The _pread.ss_ library provides customization, and support for
prompt-reading after "rep.ss" installs the new input port.

The reading facility that the new input port provides can be
customized with these parameters:

> currnet-prompt
  The prompt that is used, as a byte string.  Defaults to #"> ".

> show-all-prompts
  If #f, no prompt is shown until you write input that is completely
  readable.  For example, when you type
    (foo bar) (+ 1
                 2)
  you will see a single prompt in the beginning.

  The problem is that the first expression can be `(read-line)' which
  normally consumes the rest of the text on the *same* line.  The
  default value of this parameter is therefore #t, making it mimic
  plain I/O interactions.

> max-history
  The number of history entries to save.  Defaults to 100.

> keep-duplicates
  If this is #f (the default), then lines that are equal to the
  previous one are not added as new history items.

> keep-blanks
  If #f (the default), blank input lines are not kept in history.

The new input port that you get when you require "rep.ss" is a custom
port that uses readline for all inputs.  The problem is when you want
to display a prompt and then read some input: readline will get
confused if it's not used when the cursor is at the beginning of the
line, which is why it has a `prompt' argument.  To use this prompt:

  (parameterize ([readline-prompt some-byte-string])
    ...code-that-reads...)

This will make the first call to readline use the prompt, and
subsequent calls will use an all-spaces prompt of the same length (for
example, when you're reading an s-expression).  The normal value of
`readline-prompt' is #f for an empty prompt (and 'spaces after the
prompt is used, which is why you should use `parameterize' to restore
it to #f).

A proper solution would be to install a custom output port too which
keeps track of text that is displayed without a trailing newline.  As
a cheaper solution, if line-counting is enabled for the terminal's
output-port, then a newline is printed before reading if the column is
not 0.  ("rep.ss" enables line-counting for the output port.)


Warning
-------

The readline library uses the output port directly.  You should not
use it when `current-input-port' has been modified, or when it was not
a terminal port when MzScheme was started (eg, when reading input from
a pipe).  Expect problems if you ignore this warning (not too bad,
mostly problems with detecting an EOF).


Direct bindings for readline hackers
------------------------------------

The _readline.ss_ library provides these functions:

> (readline prompt-string)
  prints the given prompt string and reads a line

> (readline-bytes prompt-bytes)
  same as above, but using raw byte-strings for the prompt and
  returning a byte string

> (add-history s)
  adds the given string to the readline history, which is accessible
  to the user via the up-arrow key

> (add-history-bytes s)
  adds the given byte string to the readline history, which is
  accessible to the user via the up-arrow key

> (set-completion-function! proc [type])
  sets readline's `rl_completion_entry_function' function according to
  proc, which is expected to be a `string -> (list-of string/bytes)'
  procedure; the `type' argument defaults to `_string' but you can use
  it with `_bytes' instead to have your function receive a byte
  string.


License Issues
--------------

GNU's readline library is covered by the GPL, and that applies to code
that links with it.  PLT Scheme is LGPL, so this code is not used by
default -- you should explicitly enable it if you want to.  Also, be
aware that if you write code that uses this library, it will make your
code link to the readline library when invoked -- with the usual GPL
implications.
