aboutsummaryrefslogtreecommitdiff
path: root/examples/redis-unstable/deps/linenoise/README.markdown
diff options
context:
space:
mode:
Diffstat (limited to 'examples/redis-unstable/deps/linenoise/README.markdown')
-rw-r--r--examples/redis-unstable/deps/linenoise/README.markdown247
1 files changed, 0 insertions, 247 deletions
diff --git a/examples/redis-unstable/deps/linenoise/README.markdown b/examples/redis-unstable/deps/linenoise/README.markdown
deleted file mode 100644
index b3752da..0000000
--- a/examples/redis-unstable/deps/linenoise/README.markdown
+++ /dev/null
@@ -1,247 +0,0 @@
1# Linenoise
2
3A minimal, zero-config, BSD licensed, readline replacement used in Redis,
4MongoDB, and Android.
5
6* Single and multi line editing mode with the usual key bindings implemented.
7* History handling.
8* Completion.
9* Hints (suggestions at the right of the prompt as you type).
10* About 1,100 lines of BSD license source code.
11* Only uses a subset of VT100 escapes (ANSI.SYS compatible).
12
13## Can a line editing library be 20k lines of code?
14
15Line editing with some support for history is a really important feature for command line utilities. Instead of retyping almost the same stuff again and again it's just much better to hit the up arrow and edit on syntax errors, or in order to try a slightly different command. But apparently code dealing with terminals is some sort of Black Magic: readline is 30k lines of code, libedit 20k. Is it reasonable to link small utilities to huge libraries just to get a minimal support for line editing?
16
17So what usually happens is either:
18
19 * Large programs with configure scripts disabling line editing if readline is not present in the system, or not supporting it at all since readline is GPL licensed and libedit (the BSD clone) is not as known and available as readline is (Real world example of this problem: Tclsh).
20 * Smaller programs not using a configure script not supporting line editing at all (A problem we had with Redis-cli for instance).
21
22The result is a pollution of binaries without line editing support.
23
24So I spent more or less two hours doing a reality check resulting in this little library: is it *really* needed for a line editing library to be 20k lines of code? Apparently not, it is possibe to get a very small, zero configuration, trivial to embed library, that solves the problem. Smaller programs will just include this, supporting line editing out of the box. Larger programs may use this little library or just checking with configure if readline/libedit is available and resorting to Linenoise if not.
25
26## Terminals, in 2010.
27
28Apparently almost every terminal you can happen to use today has some kind of support for basic VT100 escape sequences. So I tried to write a lib using just very basic VT100 features. The resulting library appears to work everywhere I tried to use it, and now can work even on ANSI.SYS compatible terminals, since no
29VT220 specific sequences are used anymore.
30
31The library is currently about 1100 lines of code. In order to use it in your project just look at the *example.c* file in the source distribution, it is trivial. Linenoise is BSD code, so you can use both in free software and commercial software.
32
33## Tested with...
34
35 * Linux text only console ($TERM = linux)
36 * Linux KDE terminal application ($TERM = xterm)
37 * Linux xterm ($TERM = xterm)
38 * Linux Buildroot ($TERM = vt100)
39 * Mac OS X iTerm ($TERM = xterm)
40 * Mac OS X default Terminal.app ($TERM = xterm)
41 * OpenBSD 4.5 through an OSX Terminal.app ($TERM = screen)
42 * IBM AIX 6.1
43 * FreeBSD xterm ($TERM = xterm)
44 * ANSI.SYS
45 * Emacs comint mode ($TERM = dumb)
46
47Please test it everywhere you can and report back!
48
49## Let's push this forward!
50
51Patches should be provided in the respect of Linenoise sensibility for small
52easy to understand code.
53
54Send feedbacks to antirez at gmail
55
56# The API
57
58Linenoise is very easy to use, and reading the example shipped with the
59library should get you up to speed ASAP. Here is a list of API calls
60and how to use them.
61
62 char *linenoise(const char *prompt);
63
64This is the main Linenoise call: it shows the user a prompt with line editing
65and history capabilities. The prompt you specify is used as a prompt, that is,
66it will be printed to the left of the cursor. The library returns a buffer
67with the line composed by the user, or NULL on end of file or when there
68is an out of memory condition.
69
70When a tty is detected (the user is actually typing into a terminal session)
71the maximum editable line length is `LINENOISE_MAX_LINE`. When instead the
72standard input is not a tty, which happens every time you redirect a file
73to a program, or use it in an Unix pipeline, there are no limits to the
74length of the line that can be returned.
75
76The returned line should be freed with the `free()` standard system call.
77However sometimes it could happen that your program uses a different dynamic
78allocation library, so you may also used `linenoiseFree` to make sure the
79line is freed with the same allocator it was created.
80
81The canonical loop used by a program using Linenoise will be something like
82this:
83
84 while((line = linenoise("hello> ")) != NULL) {
85 printf("You wrote: %s\n", line);
86 linenoiseFree(line); /* Or just free(line) if you use libc malloc. */
87 }
88
89## Single line VS multi line editing
90
91By default, Linenoise uses single line editing, that is, a single row on the
92screen will be used, and as the user types more, the text will scroll towards
93left to make room. This works if your program is one where the user is
94unlikely to write a lot of text, otherwise multi line editing, where multiple
95screens rows are used, can be a lot more comfortable.
96
97In order to enable multi line editing use the following API call:
98
99 linenoiseSetMultiLine(1);
100
101You can disable it using `0` as argument.
102
103## History
104
105Linenoise supporst history, so that the user does not have to retype
106again and again the same things, but can use the down and up arrows in order
107to search and re-edit already inserted lines of text.
108
109The followings are the history API calls:
110
111 int linenoiseHistoryAdd(const char *line, int is_sensitive);
112 int linenoiseHistorySetMaxLen(int len);
113 int linenoiseHistorySave(const char *filename);
114 int linenoiseHistoryLoad(const char *filename);
115
116Use `linenoiseHistoryAdd` every time you want to add a new element
117to the top of the history (it will be the first the user will see when
118using the up arrow).
119
120Note that for history to work, you have to set a length for the history
121(which is zero by default, so history will be disabled if you don't set
122a proper one). This is accomplished using the `linenoiseHistorySetMaxLen`
123function.
124
125Linenoise has direct support for persisting the history into an history
126file. The functions `linenoiseHistorySave` and `linenoiseHistoryLoad` do
127just that. Both functions return -1 on error and 0 on success.
128
129## Mask mode
130
131Sometimes it is useful to allow the user to type passwords or other
132secrets that should not be displayed. For such situations linenoise supports
133a "mask mode" that will just replace the characters the user is typing
134with `*` characters, like in the following example:
135
136 $ ./linenoise_example
137 hello> get mykey
138 echo: 'get mykey'
139 hello> /mask
140 hello> *********
141
142You can enable and disable mask mode using the following two functions:
143
144 void linenoiseMaskModeEnable(void);
145 void linenoiseMaskModeDisable(void);
146
147## Completion
148
149Linenoise supports completion, which is the ability to complete the user
150input when she or he presses the `<TAB>` key.
151
152In order to use completion, you need to register a completion callback, which
153is called every time the user presses `<TAB>`. Your callback will return a
154list of items that are completions for the current string.
155
156The following is an example of registering a completion callback:
157
158 linenoiseSetCompletionCallback(completion);
159
160The completion must be a function returning `void` and getting as input
161a `const char` pointer, which is the line the user has typed so far, and
162a `linenoiseCompletions` object pointer, which is used as argument of
163`linenoiseAddCompletion` in order to add completions inside the callback.
164An example will make it more clear:
165
166 void completion(const char *buf, linenoiseCompletions *lc) {
167 if (buf[0] == 'h') {
168 linenoiseAddCompletion(lc,"hello");
169 linenoiseAddCompletion(lc,"hello there");
170 }
171 }
172
173Basically in your completion callback, you inspect the input, and return
174a list of items that are good completions by using `linenoiseAddCompletion`.
175
176If you want to test the completion feature, compile the example program
177with `make`, run it, type `h` and press `<TAB>`.
178
179## Hints
180
181Linenoise has a feature called *hints* which is very useful when you
182use Linenoise in order to implement a REPL (Read Eval Print Loop) for
183a program that accepts commands and arguments, but may also be useful in
184other conditions.
185
186The feature shows, on the right of the cursor, as the user types, hints that
187may be useful. The hints can be displayed using a different color compared
188to the color the user is typing, and can also be bold.
189
190For example as the user starts to type `"git remote add"`, with hints it's
191possible to show on the right of the prompt a string `<name> <url>`.
192
193The feature works similarly to the history feature, using a callback.
194To register the callback we use:
195
196 linenoiseSetHintsCallback(hints);
197
198The callback itself is implemented like this:
199
200 char *hints(const char *buf, int *color, int *bold) {
201 if (!strcasecmp(buf,"git remote add")) {
202 *color = 35;
203 *bold = 0;
204 return " <name> <url>";
205 }
206 return NULL;
207 }
208
209The callback function returns the string that should be displayed or NULL
210if no hint is available for the text the user currently typed. The returned
211string will be trimmed as needed depending on the number of columns available
212on the screen.
213
214It is possible to return a string allocated in dynamic way, by also registering
215a function to deallocate the hint string once used:
216
217 void linenoiseSetFreeHintsCallback(linenoiseFreeHintsCallback *);
218
219The free hint callback will just receive the pointer and free the string
220as needed (depending on how the hits callback allocated it).
221
222As you can see in the example above, a `color` (in xterm color terminal codes)
223can be provided together with a `bold` attribute. If no color is set, the
224current terminal foreground color is used. If no bold attribute is set,
225non-bold text is printed.
226
227Color codes are:
228
229 red = 31
230 green = 32
231 yellow = 33
232 blue = 34
233 magenta = 35
234 cyan = 36
235 white = 37;
236
237## Screen handling
238
239Sometimes you may want to clear the screen as a result of something the
240user typed. You can do this by calling the following function:
241
242 void linenoiseClearScreen(void);
243
244## Related projects
245
246* [Linenoise NG](https://github.com/arangodb/linenoise-ng) is a fork of Linenoise that aims to add more advanced features like UTF-8 support, Windows support and other features. Uses C++ instead of C as development language.
247* [Linenoise-swift](https://github.com/andybest/linenoise-swift) is a reimplementation of Linenoise written in Swift.