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

Last change on this file since 31943 was 31943, checked in by Christian Kellermann, 7 years ago

mention new repo location

File size: 9.5 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
11As of version 0.9 either single line editing mode or multiline editing
12mode is supported. See ''(refresh-line)'' in the parameter listing
13below.
14
15=== Usage
16
17<enscript highlight=scheme>
18(require-extension parley)
19(require-extension parley-auto-completion) ;; Add when needed
20</enscript>
21
22
23=== Requirements
24
25[[stty]] and core units.
26
27=== Source code
28
29The parley source code repository is hosted on bitbucket:
30[[https://bitbucket.org/ckeen/parley]]
31
32=== Documentation
33
34==== parley
35
36<procedure>(parley STRING)</procedure>
37
38Prompts the user with prompt STRING and reads a whole line. This uses
39non-blocking I/O and returns a string or {{#eof!}}.
40
41==== terminal-supported?
42
43<procedure>(terminal-supported? PORT STRING)</procedure>
44
45Checks if the terminal connected on PORT with name STRING is
46supported. If not {{parley}} will resort back to a dumb (non-blocking)
47readline implementation. Unsupported terminals will not trigger any
48user defined key-bindings.
49
50==== history-to-file
51
52<procedure>(history-to-file STRING)</procedure>
53
54Dumps the current history to a file named in STRING. The file is
55overwritten if it already exists.
56
57==== history-from-file
58
59<procedure>(history-from-file STRING)</procedure>
60
61Reads a previously saved history into memory. Note that currently
62{{parley}}'s history is global.
63
64==== add-key-binding!
65
66<procedure>(add-key-binding! CHAR PROC #!key (esc-sequence #f))</procedure>
67
68Register's PROC to be executed when CHAR is entered. If
69{{esc-sequence}} is {{#t}}, PROC will be called upon the sequence
70{{#\1b[CHAR}}.
71
72==== make-parley-port
73
74<procedure>(make-parley-port PORT #!optional (prompt ""))</procedure>
75
76Creates a scheme port that reads from PORT and writes to
77{{(current-output-port}}. See below for a usage example in CSI.
78
79==== Example
80
81<enscript highlight="scheme">
82#;1> (parley "> ")
83> Hello, World!
84"Hello, World!"
85#;2>
86</enscript>
87
88==== Parameters:
89
90<parameter>(history-max-lines NUMBER)</parameter>
91
92Number of lines the history will hold. If this maximum is exceeded the
93oldest line will be discarded.
94
95<parameter>(mark-more-input? STRING)</parameter>
96
97If not set to ''#f'' the string will be printed over the left and
98right edges, when there is more input hidden on either side of the
99screen. Defaults to "
" and is effective in single line mode only.
100
101<parameter>(refresh-line REFRESH-PROCEDURE)</parameter>
102
103This parameter sets the editing mode for parley. It is either
104''singleline-refresh'' the default or ''muliline-refresh''.
105
106==== Core Keybindings
107
108Currently the following keybindings are implemented:
109
110* Cursor movement: Arrow keys (left right), CTRL-A, CTRL-E
111* History: Arrow keys (up down), CTRL-P, CTRL-N for previous and next
112  in history
113* Editing / Deletion: CTRL-U for the current line, CTRL-K for
114  everything after the cursor, CTRL-T swap current char with previous
115* Terminal handling: CTRL-L clears the screen
116
117==== User defined key bindings
118
119A handler for a character is a procedure that accepts and returns a
120parley state record.  The following getters and setters for the
121record ''state'' are exported:
122
123; prompt : The shown prompt for the line or "", getter only
124; line : The current line as string
125; pos : The current (0-based) cursor position wrt to line
126; return : A continuation that should be called if the input is done. This usually breaks out of the prompt loop.
127; offset : The offset of the current line. This is non zero if earlier function printed something on our line (like ''display'')
128
129New keybindings are added with the ''add-key-binding!'' procedure,
130which will override the current handler for the given key if present.
131If you like to add an escape sequence set the ''esc-sequence:''
132keyword parameter to ''#t''. This will match on ESQ Sequences like
133'\x1b[<char>'.
134
135===== Example key binding
136
137This handler deletes the  all the text from the cursor position to the end of the line:
138
139<enscript highlight="scheme">
140(use parley srfi-14)
141
142(define (delete-last-word line pos)
143  (let* ((del-pos (or (string-index-right
144                      line
145                      (char-set-union char-set:whitespace
146                                      char-set:punctuation)
147                      0
148                      pos)
149                     0))
150         (left-part (if (> del-pos 0) (string-take line del-pos)
151                    ""))
152         (npos (- pos (- pos
153                         del-pos))))
154    (values (string-append left-part (string-drop line pos))
155            npos)))
156
157(define (cw parley-state)
158  (receive (l p)
159           (delete-last-word (state-line parley-state)
160                             (state-pos parley-state))
161           (state-pos-set! parley-state p)
162           (state-line-set! parley-state l)
163           parley-state))
164
165(add-key-binding! #\x17 cw)
166</enscript>
167
168==== Using parley in CSI
169
170Parley of course can also be used within csi. Just add
171this to .csirc:
172
173<enscript highlight="scheme>
174(use parley)
175(let ((old (current-input-port)))
176     (current-input-port (make-parley-port old)))
177</enscript>
178
179==== Using parley-auto-completion
180
181Parley offers by default no support for autocompletion. One could add
182her own handler and bind this to a convenient key, but as this might
183be of a more general interest this module is provided to enable
184programmers to add completion to their input prompts.
185
186The behaviour of the completion mechanism can be tweaked through a
187small number of parameters. The items to look for completions can
188either be a simple list of strings (by using the '''completion-list'''
189procedure) or a more sophisticated handler procedure that can react to
190the already written input, cursor position and last word. This makes
191command/argument completions possible that are depending on the
192context. Of course one can also define what a word actually means for
193the running application.
194
195===== auto-completion-handler
196
197A procedure to pass to '''add-key-binding!''' (see above).
198
199===== beep?
200
201<parameter>(beep? #t)</parameter>
202
203If #t (the default) a alarm character is sent when there are more than
204one possible completions.
205
206===== completion-choices
207
208<parameter>(completion-choices (lambda (input position last-word) '()))</parameter>
209
210A parameter holding the selection procedure. The procedure is called
211to actually return a list of possible completions depending on the
212whole '''input''' line, the current cursor '''position''' and the
213detected '''last-word'''. Should return either the empty list if no
214completions can be found or a list of strings.
215
216===== completion-list
217
218<procedure>(completion-list list-of-strings)</procedure>
219
220Convenience procedure to provide a simple string list to look for
221possible completions. Sets the '''completion-choices''' parameter.
222
223===== print-completions
224
225<parameter>(print-completions (lambda (completions) ...))</parameter>
226
227Handles how the completions are handled. By default it prints the
228number of completions a newline and each completion separated by a space
229character, ending with a newline.
230
231===== word-class
232
233<parameter>(word-class '(+ (~ whitespace)))</parameter>
234
235This defines how the last word in the input string is
236found. '''word-class''' takes any '''irregex''' expression.
237
238=== Author
239
240[[/users/christian kellermann|Christian Kellermann]]
241
242=== License
243
244 Copyright 2014 Christian Kellermann <ckeen@pestilenz.org>. All
245 rights reserved.
246 
247 Redistribution and use in source and binary forms, with or without
248 modification, are permitted provided that the following conditions
249 are met:
250    1. Redistributions of source code must retain the above
251    copyright notice, this list of conditions and the following
252    disclaimer.
253    2. Redistributions in binary form must reproduce the above
254    copyright notice, this list of conditions and the following
255    disclaimer in the documentation and/or other materials provided
256    with the distribution.
257 THIS SOFTWARE IS PROVIDED BY CHRISTIAN KELLERMANN ``AS IS'' AND ANY
258 EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
259 IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
260 PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL CHRISTIAN KELLERMANN OR
261 CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
262 SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
263 LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
264 USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
265 ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
266 OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
267 OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
268 SUCH DAMAGE.
269 The views and conclusions contained in the software and
270 documentation are those of the authors and should not be
271 interpreted as representing official policies, either expressed or
272 implied, of Christian Kellermann.
273
274=== Version History
275; 0.9 : Multiline edit and incompatible handler API change, fixed single line mode
276; 0.8.2 : Bugfix which has been shadowed by a flaw in stty
277; 0.8 : Add input history, mark when there's off the screen input, thanks Jean Snell-Pym, parley-auto-completion module added
278; 0.7 : Internal refactoring and support for CTRL-L thanks to Moritz Heidkamp
279; 0.6 : Bugfix for bug 721 (thanks to Alan Post for the report), improved pasting support.
280; 0.5 : Do not overwrite output on the same line, when starting. Thanks to Matthias Bauer.
281; 0.4 : Handle eof correctly
282; 0.3 : do not flush input when setting terminal attributes, thanks again certainty
283; 0.2 : bugfix release, thanks to certainty
284; 0.1 : initial release
Note: See TracBrowser for help on using the repository browser.