source: project/wiki/eggref/5/linenoise @ 36200

Last change on this file since 36200 was 36200, checked in by Christian Kellermann, 14 months ago

wiki: Add linenoise docs

File size: 4.8 KB
Line 
1[[tags: egg]]
2
3== Linenoise
4
5[[toc:]]
6
7=== Description
8
9A minimal, zero-config, BSD licensed, readline replacement.
10
11From the [[http://github.com/antirez/linenoise/blob/master/README.markdown|author's readme]]:
12
13
14Line editing with some support for history is a really important
15feature for command line utilities. Instead of retyping almost the
16same stuff again and again it's just much better to hit the up arrow
17and edit on syntax errors, or in order to try a slightly different
18command. But apparently code dealing with terminals is some sort of
19Black Magic: readline is 30k lines of code, libedit 20k. Is it
20reasonable to link small utilities to huge libraries just to get a
21minimal support for line editing?
22
23(...)
24
25* Linux text only console ($TERM = linux)
26* Linux KDE terminal application ($TERM = xterm)
27* Linux xterm ($TERM = xterm)
28* Mac OS X iTerm ($TERM = xterm)
29* Mac OS X default Terminal.app ($TERM = xterm)
30* OpenBSD 4.5 through an OSX Terminal.app ($TERM = screen)
31* IBM AIX 6.1
32* FreeBSD xterm ($TERM = xterm)
33
34This information has been collected on 2010-06-13.
35
36=== Author
37
38Salvatore Sanfilippo <antirez@gmail.com>, ported to chicken by
39[[/users/Christian Kellermann|Christian Kellermann]]
40
41=== Interface
42
43The library is very small and exposes six procedures:
44
45<procedure>(linenoise prompt)</procedure>
46
47Prompts the user for a line of input. Returns the entered line as a
48string or #f if the user aborted.
49
50<procedure>(history-add line)</procedure>
51
52Adds the string line to the internal history.
53
54<procedure>(set-history-length! number)</procedure>
55
56Sets the number of maximum entries in the history. Linenoise is
57initialised with 100 lines of history.
58
59<procedure>(save-history-to-file filename)</procedure>
60
61Saves the current history buffer to filename.
62
63<procedure>(load-history-from-file filename)</procedure>
64
65Loads the history from file.
66
67<procedure>(make-linenoise-port)</procedure>
68
69Returns an input port connected to a linenoise prompt. Useful for inserting it into CSI (see below).
70
71=== Controls
72
73* arrow keys move the cursor, as well as ctrl-b, ctrl-f (back and
74  forward), ctrl-p and ctrl-n (up / down)
75* ctrl-d and enter will finish the input and a string containing the current line will be returned.
76* ctrl-c aborts input and the linenoise procedure will return {{#f}}
77* Deletion of one character is done by pressing backspace or ctrl-h
78* ctrl-u deletes the whole line
79* ctrl-k deletes from point (the cursor) to the end of the line
80* ctrl-a moves to the beginning of the line
81* ctrl-e moves to the end of the line
82* ctrl-t permutes the char after the cursor with the one under the cursor
83
84=== Currently missing features
85
86* No searching of history
87* No deletion of whole words (ctrl-w)
88* No tab completion
89
90=== Example
91
92This example shows a minimal prompt loop echoing all user input:
93
94<enscript highlight=scheme>
95(use linenoise)
96
97(set-history-length! 300)
98
99(load-history-from-file ".linenoise-history")
100
101(let loop ((l (linenoise "> ")))
102   (cond ((equal? l "bye")
103       (save-history-to-file ".linenoise-history")
104       "Bye!")
105       (else
106          (display l)
107          (newline)
108          (history-add l)
109          (loop (linenoise "> ")))))
110</enscript>
111
112=== Using linenoise in csi
113
114Since version 0.4 linenoise can be used as editing help in csi, simply add the following to your {{.csirc}}
115
116<enscript highlight=scheme>
117(use linenoise)
118(current-input-port (make-linenoise-port))
119</enscript>
120
121=== Changelog
122
123; 1.0 First chicken 5 port, identical to version 0.7 for chicken 4
124
125=== License
126
127 Copyright (c) 2010, Salvatore Sanfilippo <antirez at gmail dot com>
128 Copyright (c) 2010, Pieter Noordhuis <pcnoordhuis at gmail dot com>
129 
130 All rights reserved.
131 
132 Redistribution and use in source and binary forms, with or without
133 modification, are permitted provided that the following conditions are
134 met:
135 
136 * Redistributions of source code must retain the above copyright
137 notice, this list of conditions and the following disclaimer.
138 
139 * Redistributions in binary form must reproduce the above copyright
140 notice, this list of conditions and the following disclaimer in the
141 documentation and/or other materials provided with the distribution.
142 
143 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
144 "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
145 LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
146 A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
147 HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
148 SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
149 LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
150 DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
151 THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
152 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
153 OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
Note: See TracBrowser for help on using the repository browser.