source: project/wiki/eggref/4/parley @ 24828

Last change on this file since 24828 was 24828, checked in by Christian Kellermann, 10 years ago

parley: Fix history

File size: 6.0 KB
Line 
1[[tags: egg]]
2[[toc:]]
3
4== parley - Negotiate your input
5
6=== Introduction
7
8{{parley}} is a BSD licensed line editing module implemented in scheme which
9integrates nicely with CHICKEN's scheduler.
10
11=== Usage
12
13<enscript highlight=scheme>
14(require-extension parley)
15</enscript>
16
17
18=== Requirements
19
20[[stty]]
21
22=== Documentation
23
24==== parley
25
26<procedure>(parley STRING)</procedure>
27
28Prompts the user with prompt STRING and reads a whole line. This uses
29non-blocking I/O and returns a string or {{#eof!}}.
30
31==== terminal-supported?
32
33<procedure>(terminal-supported? PORT STRING)</procedure>
34
35Checks if the terminal connected on PORT with name STRING is
36supported. If not {{parley}} will resort back to a dumb (non-blocking)
37readline implementation. Unsupported terminals will not trigger any
38user defined key-bindings.
39
40==== history-to-file
41
42<procedure>(history-to-file STRING)</procedure>
43
44Dumps the current history to a file named in STRING. The file is
45overwritten if it already exists.
46
47==== history-from-file
48
49<procedure>(history-from-file STRING)</procedure>
50
51Reads a previously saved history into memory. Note that currently
52{{parley}}'s history is global.
53
54==== add-key-binding!
55
56<procedure>(add-key-binding! CHAR PROC #!key (esc-sequence #f))</procedure>
57
58Register's PROC to be executed when CHAR is entered. If
59{{esc-sequence}} is {{#t}}, PROC will be called upon the sequence
60{{#\1b[CHAR}}.
61
62==== make-parley-port
63
64<procedure>(make-parley-port PORT #!optional (prompt ""))</procedure>
65
66Creates a scheme port that reads from PORT and writes to
67{{(current-output-port}}. See below for a usage example in CSI.
68
69==== Example
70
71<enscript highlight="scheme">
72#;1> (parley "> ")
73> Hello, World!
74"Hello, World!"
75#;2>
76</enscript>
77
78==== Parameters:
79
80<parameter>(history-max-lines NUMBER)</parameter>
81
82Number of lines the history will hold. If this maximum is exceeded the
83oldest line will be discarded.
84
85==== Core Keybindings
86
87Currently the following keybindings are implemented:
88
89* Cursor movement: Arrow keys (left right), CTRL-A, CTRL-E
90* History: Arrow keys (up down), CTRL-P, CTRL-N for previous and next
91  in history
92* Editing / Deletion: CTRL-U for the current line, CTRL-K for
93  everything after the cursor, CTRL-T swap current char with previous
94
95
96==== User defined key bindings
97
98A handler for a character is a procedure that accepts and returns this
99(rather long) list of the following arguments:
100
101; prompt : The shown prompt for the line or ""
102; in : the input port
103; out : the output port
104; line : The current line as string
105; pos : The current (0-based) cursor position wrt to line
106; return : A continuation that should be called if the input is done. This usually breaks out of the prompt loop.
107; offset : The offset of the current line. This is non zero if earlier function printed something on our line (like ''display'')
108
109New keybindings are added with the ''add-key-binding!'' procedure,
110which will override the current handler for the given key if present.
111If you like to add an escape sequence set the ''esc-sequence:''
112keyword parameter to ''#t''. This will match on ESQ Sequences like
113'\x1b[<char>'.
114
115===== Example key binding
116
117This handler deletes the word before the cursor:
118
119<enscript highlight="scheme">
120(use parley srfi-14)
121
122(define (delete-last-word line pos)
123  (let* ((del-pos (or (string-index-right
124                      line
125                      (char-set-union char-set:whitespace
126                                      char-set:punctuation)
127                      pos)
128                     0))
129         (left-part (if (> del-pos 0) (string-take line del-pos)
130                    ""))
131         (npos (- pos (- pos
132                         del-pos))))
133    (values (string-append left-part (string-drop line pos))
134            npos)))
135
136(define (cw prompt in out line pos exit offset)
137  (receive (l p) (delete-last-word line pos)
138           (list prompt in out l p exit offset)))
139
140(add-key-binding! #\x17 cw)
141</enscript>
142
143==== Using parley in CSI
144
145Parley of course can also be used within csi. Just add
146this to .csirc:
147
148<enscript highlight="scheme>
149(use parley)
150(let ((old (current-input-port)))
151     (current-input-port (make-parley-port old)))
152</enscript>
153
154=== Author
155
156[[/users/christian kellermann|Christian Kellermann]]
157
158=== License
159
160 Copyright 2011 Christian Kellermann <ckeen@pestilenz.org>. All
161 rights reserved.
162 
163 Redistribution and use in source and binary forms, with or without
164 modification, are permitted provided that the following conditions
165 are met:
166    1. Redistributions of source code must retain the above
167    copyright notice, this list of conditions and the following
168    disclaimer.
169    2. Redistributions in binary form must reproduce the above
170    copyright notice, this list of conditions and the following
171    disclaimer in the documentation and/or other materials provided
172    with the distribution.
173 THIS SOFTWARE IS PROVIDED BY CHRISTIAN KELLERMANN ``AS IS'' AND ANY
174 EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
175 IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
176 PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL CHRISTIAN KELLERMANN OR
177 CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
178 SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
179 LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
180 USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
181 ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
182 OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
183 OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
184 SUCH DAMAGE.
185 The views and conclusions contained in the software and
186 documentation are those of the authors and should not be
187 interpreted as representing official policies, either expressed or
188 implied, of Christian Kellermann.
189
190=== Version History
191
192; 0.5 : Do not overwrite output on the same line, when starting. Thanks to Matthias Bauer.
193; 0.4 : Handle eof correctly
194; 0.3 : do not flush input when setting terminal attributes, thanks again certainty
195; 0.2 : bugfix release, thanks to certainty
196; 0.1 : initial release
Note: See TracBrowser for help on using the repository browser.