
=============
pure-readline
=============

.. default-domain:: pure
.. module:: readline

Version 0.1, |today|

Albert Graef <Dr.Graef@t-online.de>

Get the latest source from
http://pure-lang.googlecode.com/files/pure-readline-0.1.tar.gz.

This is a trivial wrapper around GNU readline, which gives Pure scripts access
to the ``readline`` and ``add_history`` functions. The wrapper can also be
used with the BSD editline a.k.a. libedit library, a readline replacement
licensed under the 3-clause BSD license. You can find these at:

- GNU readline: http://tiswww.tis.case.edu/~chet/readline/rltop.html

- BSD editline/libedit: http://www.thrysoee.dk/editline

We recommend GNU readline because it's easier to use and has full UTF-8
support, but in some situations BSD editline/libedit may be preferable for
license reasons or because it's what the operating system provides. Note that
in either case Pure programs using this module are subject to the license
terms of the library that you use (GPLv3+ in case of GNU readline, BSD license
in the case of BSD editline/libedit).

Normally, you should choose the same library that you use with the Pure
interpreter, to avoid having two different versions of the library linked into
your program. (This doesn't matter if you only use this module with
batch-compiled scripts, though, since the Pure runtime doesn't depend on
readline in any way.) By default, the module will be built with GNU readline.
To select editline/libedit instead, you only have to uncomment a line at the
beginning of the Makefile. Also, you might want to check the beginning of
readline.c for the proper location of the corresponding header files.

The module provides two functions:

.. function:: readline prompt

   Read a line of input from the user, with prompting and command line
   editing. Returns the input line (with the trailing newline removed), or
   :const:`NULL` when reaching end of file.

.. function:: add_history line

   Adds the given line (a string) to the command history.

Example::

  > readline "input> ";
  input> Hello, world!
  "Hello, world!"
  > add_history ans;
  ()
  > readline "input> ";
  input> <EOF>
  #<pointer 0>
