README

-*- Text -*-

LINEDIT

 Linedit is a readline-style library written in Common Lisp that
 provides customizable line-editing for Common Lisp programs.

 Version 0.11 uses UFFI for foreign bindings, and is hence
 theoretically portable. The development and testing has so far been
 carried out on SBCL, however. Patches are welcome.

 The current input handling is only empirically correct -- which is a
 gentile way of saying "works on my box, dunno about yours". Once
 again: patches are welcome.

 For more information, and the latest version of Linedit visit
 the Linedit homepage:

   http://common-lisp.net/project/linedit/

 Questions, feature requests, and bug-reports to

   linedit-devel@common-lisp.net.


 USAGE
 -----

  > (asdf:load-system :linedit)

  > (linedit:linedit :prompt "-> ")

  > (linedit:formedit :prompt1 "=> " :prompt2 "|   ")

  Meta-H in the prompt display help. (Try ESC-H if your terminal
  misbehaves with meta-proper.)


 USING LINEDIT IN THE REPL (SBCL AND CCL ONLY)
 ---------------------------------------------

  Do

    (when (interactive-stream-p *standard-input*)
      (asdf:load-system :linedit)
      (funcall (intern "INSTALL-REPL" :linedit)
               ;; Keeps toplevel commands intact, etc.
               :wrap-current t
               ;; Should EOF quit after verification?
               :eof-quits t
               ;; Persistent history
               :history "~/.linedit_history"))

  in eg. your Lisp initialization file (~/.sbclrc for SBCL).


 INTERFACE
 ---------

  function INSTALL-REPL &key wrap-current eof-quits history killring

    Installs the Linedit at REPL. (SBCL and CCL only.)

    WRAP-CURRENT keeps current input handlers (eg. toplevel command
    processors) in place.

    If EOF-QUITS is true, EOF on *STANDARD-INPUT* causes the system to
    exit after verification.

    HISTORY and KILLRING can be pathname designators, in which case
    they indicate the file to use for history and killring
    persistence, respectively."

  function UNINSTALL-REPL

    Removes Linedit REPL input handler. (SBCL and CCL only.)

  function LINEDIT &rest keys &key prompt history killring

    Reads a single line of input with line-editing from standard input
    of the process and returns it as a string.

    Results are unspecified if *STANDARD-INPUT* has been bound or
    altered.

    PROMPT specifies the string to print to *STANDARD-OUTPUT* before
    starting the accept input.

    HISTORY and KILLRING can be pathname designators, in which case
    they indicate the file to use for history and killring
    persistence, respectively.

    Further keyword arguments to LINEDIT are an advanced and
    undocumented topic, but if you're willing to dive into sources you
    can eg. use multiple kill-rings not shared between different
    invocations of LINEDIT, or change the function responsible for
    providing input completion.

  function FORMEDIT &rest keys &key prompt1 prompt2 history killring

    Reads a single form (s-expession) of input with line-editing from
    standard input of the process and returns it as a string.

    Results are unspecified if *STANDARD-INPUT* has been bound or
    altered, or if *READTABLE* is not the standard readtable.

    PROMPT1 specifies the string to print to *STANDARD-OUTPUT* before
    starting the accept input.

    PROMPT2 specifies the string to print to *STANDARD-OUTPUT* when
    input spans multiple lines (ie. prefixing every but first line of
    input.)

    HISTORY and KILLRING can be pathname designators, in which case
    they indicate the file to use for history and killring
    persistence, respectively.

    Further keyword arguments to FORMEDIT are an advanced and
    undocumented topic, but if you're willing to dive into sources you
    can eg. use multiple kill-rings not shared between different
    invocations of FORMEDIT, or change the function responsible for
    providing input completion.