parley

You are looking at historical revision 24613 of this page. It may differ significantly from its current revision.

parley - Negotiate your input

Introduction

parley is a BSD licensed line editing module implemented in scheme which integrates nicely with CHICKEN's scheduler.

Usage

(require-extension parley)

Documentation

[procedure] (parley STRING)

Prompts the user with prompt STRING and reads a whole line. This uses non-blocking I/O and returns a string or #eof!.

terminal-supported?

[procedure] (terminal-supported? PORT STRING)

Checks if the terminal connected on PORT with name STRING is supported. If not parley will resort back to a dumb (non-blocking) readline implementation. Unsupported terminals will not trigger any user defined key-bindings.

history-to-file

[procedure] (history-to-file STRING)

Dumps the current history to a file named in STRING. The file is overwritten if it already exists.

history-from-file

[procedure] (history-from-file STRING)

Reads a previously saved history into memory. Note that currently parley's history is global.

add-key-binding!

[procedure] (add-key-binding! CHAR PROC #!key (esc-sequence #f))

Register's PROC to be executed when CHAR is entered. If esc-sequence is #t, PROC will be called upon the sequence #\1b[CHAR.

make-parley-port

[procedure] (make-parley-port PORT #!optional (prompt ""))

Creates a scheme port that reads from PORT and writes to (current-output-port. See below for a usage example in CSI.

Example

#;1> (parley "> ")
> Hello, World!
"Hello, World!"
#;2>

Parameters:

[parameter] (history-max-lines NUMBER)

Number of lines the history will hold. If this maximum is exceeded the oldest line will be discarded.

Core Keybindings

Currently the following keybindings are implemented:

Cursor movement: Arrow keys (left right), CTRL-A, CTRL-E
History: Arrow keys (up down), CTRL-P, CTRL-N for previous and next in history
Editing / Deletion: CTRL-U for the current line, CTRL-K for everything after the cursor, CTRL-T swap current char with previous

User defined key bindings

A handler for a character is a procedure that accepts and returns this (rather long) list of the following arguments:

prompt: The shown prompt for the line or ""
in: the input port
out: the output port
line: The current line as string
pos: The current (0-based) cursor position wrt to line
return: A continuation that should be called if the input is done. This usually breaks out of the prompt loop.

New keybindings are added with the add-key-binding! procedure, which will override the current handler for the given key if present. If you like to add an escape sequence set the esc-sequence: keyword parameter to #t. This will match on ESQ Sequences like '\x1b[<char>'.

Example key binding

This handler deletes the word before the cursor:

(use parley srfi-14)

(define (delete-last-word line pos)
  (let* ((del-pos (or (string-index-right
                      line
                      (char-set-union char-set:whitespace
                                      char-set:punctuation)
                      pos)
                     0))
         (left-part (if (> del-pos 0) (string-take line del-pos)
                    ""))
         (npos (- pos (- pos
                         del-pos))))
    (values (string-append left-part (string-drop line pos))
            npos)))

(define (cw prompt in out line pos exit)
  (receive (l p) (delete-last-word line pos)
           (list prompt in out l p exit)))

(add-key-binding! #\x17 cw)

Using parley in CSI

Parley of course can also be used within csi. Just add this to .csirc:

(use parley)
(let ((old (current-input-port)))
     (current-input-port (make-parley-port old)))

Author

Christian Kellermann

License

Copyright 2011 Christian Kellermann <ckeen@pestilenz.org>. All
rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:
   1. Redistributions of source code must retain the above
   copyright notice, this list of conditions and the following
   disclaimer.
   2. Redistributions in binary form must reproduce the above
   copyright notice, this list of conditions and the following
   disclaimer in the documentation and/or other materials provided
   with the distribution.
THIS SOFTWARE IS PROVIDED BY CHRISTIAN KELLERMANN ``AS IS'' AND ANY
EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL CHRISTIAN KELLERMANN OR
CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
SUCH DAMAGE.
The views and conclusions contained in the software and
documentation are those of the authors and should not be
interpreted as representing official policies, either expressed or
implied, of Christian Kellermann.

Version History

0.1: initial release
0.2: bugfix release, thanks to certainty
0.3: do not flush input when setting terminal attributes, thanks again certainty