|
Name |
|
Date |
Size |
#Lines |
LOC |
| .. | | 03-May-2022 | - |
| aux/ | H | 23-Feb-2020 | - | 16,409 | 12,234 |
| examples/ | H | 03-May-2022 | - | 1,526 | 1,063 |
| include/ | H | 03-May-2022 | - | 698 | 567 |
| m4/ | H | 23-Feb-2020 | - | 9,076 | 8,204 |
| man/ | H | 03-May-2022 | - | 812 | 737 |
| src/ | H | 03-May-2022 | - | 3,593 | 2,742 |
| ChangeLog.md | H A D | 23-Feb-2020 | 9.5 KiB | 272 | 205 |
| INSTALL.md | H A D | 23-Feb-2020 | 1.2 KiB | 47 | 29 |
| LICENSE | H A D | 23-Feb-2020 | 978 | 19 | 16 |
| Makefile.am | H A D | 23-Feb-2020 | 1.5 KiB | 49 | 40 |
| Makefile.in | H A D | 03-May-2022 | 29.6 KiB | 937 | 833 |
| README.md | H A D | 23-Feb-2020 | 9.9 KiB | 273 | 205 |
| aclocal.m4 | H A D | 23-Feb-2020 | 41.1 KiB | 1,141 | 1,036 |
| config.h.in | H A D | 23-Feb-2020 | 4.5 KiB | 169 | 114 |
| configure | H A D | 23-Feb-2020 | 445.1 KiB | 15,309 | 12,844 |
| configure.ac | H A D | 23-Feb-2020 | 3.2 KiB | 101 | 78 |
| libeditline.pc.in | H A D | 23-Feb-2020 | 247 | 13 | 10 |
README.md
1Editline
2========
3[![License Badge][]][License] [![Travis Status]][Travis] [![Coverity Status]][Coverity Scan]
4
5
6Table of Contents
7-----------------
8
9* [Introduction](#introduction)
10* [API](#api)
11* [Example](#example)
12* [Build & Install](#build--install)
13* [Origin & References](#origin--references)
14
15
16Introduction
17------------
18
19This is a small [line editing][] library. It can be linked into almost
20any program to provide command line editing and history functions. It
21is call compatible with the [FSF readline][] library, but at a fraction
22of the size, and as a result fewer features. It is also distributed
23under a much more liberal [License][].
24
25The small size (<30k), lack of dependencies (ncurses not needed!), and
26the free license should make this library interesting to many embedded
27developers.
28
29Editline has several optional build-time features that can be enabled by
30supplying different options to the GNU configure script. See the output
31from <kbd>configure --help</kbd> for details. Some useful hints on how
32to use the library is available in the `examples/` directory.
33
34Editline is maintained collaboratively at [GitHub][].
35
36
37Example
38-------
39
40Below is a very brief example to illustrate how one can use Editline to
41create a simple CLI, Ctrl-D exits the program. A slightly more advanced
42example is Jush, <https://github.com/troglobit/jush/>, a small and very
43simplistic UNIX shell. The Editline sources also include an `examples/`
44sub-directory.
45
461. Build and install the library, preferably using a [release tarball][]
47 The configure script defaults to a `/usr/local` prefix.
48
49 tar xf editline-1.15.3.tar.xz
50 cd editline-1.15.3/
51 ./configure --prefix=/usr
52 make all
53 sudo make install
54
552. Place the below source code in a separate project directory,
56 e.g. `~/src/example.c`
57
58```C
59 #include <stdlib.h>
60 #include <editline.h>
61
62 int main(void)
63 {
64 char *p;
65
66 while ((p = readline("CLI> ")) != NULL) {
67 puts(p);
68 free(p);
69 }
70
71 return 0;
72 }
73```
74
753. Compile the example:
76
77 cd ~/src/
78 make LDLIBS=-leditline example
79
80Here I use `make` and rely on its implicit (built-in) rules to handle
81all the compiler magic, but you may want to create your own Makefile for
82the project. In particular if you don't change the default prefix
83(above), because then you need to specify the search path for the
84include file(s) and the library manually.
85
86A simple `~/src/Makefile` could look like this:
87
88 CFLAGS = -I/usr/local/include
89 LDFLAGS = -L/usr/local/lib
90 LDLIBS = -leditline
91 EXEC = example
92 OBJS = example.o
93
94 all: $(EXEC)
95
96 $(EXEC): $(OBJS)
97
98 clean:
99 $(RM) $(OBJS) $(EXEC)
100
101 distclean: clean
102 $(RM) *.o *~ *.bak
103
104Then simply type `make` from your `~/src/` directory. You can also use
105`pkg-config` for your `~/src/Makefile`, replace the following lines:
106
107 CFLAGS = $(shell pkg-config --cflags libeditline)
108 LDFLAGS = $(shell pkg-config --libs-only-L libeditline)
109 LDLIBS = $(shell pkg-config --libs-only-l libeditline)
110
111Then simply type <kbd>make</kbd>, like above.
112
113However, most `.rpm` based distributions `pkg-config` doesn't search in
114`/usr/local` anymore, so you need to call make like this:
115
116 PKG_CONFIG_LIBDIR=/usr/local/lib/pkgconfig make
117
118Debian/Ubuntu based systems do not have this problem.
119
120
121API
122---
123
124Here is the libeditline interfaces. It has a small compatibility layer
125to [FSF readline][], which may not be entirely up-to-date.
126
127```C
128 /* Editline specific global variables. */
129 int el_no_echo; /* Do not echo input characters */
130 int el_no_hist; /* Disable auto-save of and access to history,
131 * e.g. for password prompts or wizards */
132 int el_hist_size; /* Size of history scrollback buffer, default: 15 */
133
134 /* Editline specific functions. */
135 char * el_find_word (void);
136 void el_print_columns (int ac, char **av);
137 el_status_t el_ring_bell (void);
138 el_status_t el_del_char (void);
139
140 /* Callback function for key binding */
141 typedef el_status_t el_keymap_func_t(void);
142
143 /* Bind key to a callback, use CTL('f') to change Ctrl-F, for example */
144 el_status_t el_bind_key (int key, el_keymap_func_t function);
145 el_status_t el_bind_key_in_metamap (int key, el_keymap_func_t function);
146
147 /* For compatibility with FSF readline. */
148 int rl_point;
149 int rl_mark;
150 int rl_end;
151 int rl_inhibit_complete;
152 char *rl_line_buffer;
153 const char *rl_readline_name;
154
155 void (*rl_deprep_term_function)(void);
156 void rl_deprep_terminal (void);
157 void rl_reset_terminal (const char *terminal_name);
158
159 void rl_initialize (void);
160 void rl_uninitialize (void); /* Free all internal memory */
161
162 void rl_save_prompt (void);
163 void rl_restore_prompt (void);
164 void rl_set_prompt (const char *prompt);
165
166 void rl_clear_message (void);
167 void rl_forced_update_display (void);
168
169 /* Main function to use, saves history by default */
170 char *readline (const char *prompt);
171
172 /* Use to save a read line to history, when el_no_hist is set */
173 void add_history (const char *line);
174
175 /* Load and save editline history from/to a file. */
176 int read_history (const char *filename);
177 int write_history (const char *filename);
178
179 /* Magic completion API, see examples/cli.c for more info */
180 rl_complete_func_t *rl_set_complete_func (rl_complete_func_t *func);
181 rl_list_possib_func_t *rl_set_list_possib_func (rl_list_possib_func_t *func);
182
183 /* Alternate interface to plain readline(), for event loops */
184 void rl_callback_handler_install (const char *prompt, rl_vcpfunc_t *lhandler);
185 void rl_callback_read_char (void);
186 void rl_callback_handler_remove (void);
187```
188
189
190Build & Install
191---------------
192
193Editline was originally designed for older UNIX systems and Plan 9. The
194current maintainer works exclusively on GNU/Linux systems, so it may use
195GCC and GNU Make specific extensions here and there. This is not on
196purpose and patches or pull requests to correct this are most welcome!
197
1981. Configure editline with default features: <kbd>./configure</kbd>
1992. Build the library and examples: <kbd>make all</kbd>
2003. Install using <kbd>make install</kbd>
201
202The `$DESTDIR` environment variable is honored at install. For more
203options, see <kbd>./configure --help</kbd>
204
205Remember to run `ldconfig` after install to update the linker cache. If
206you've installed to a non-standard location (`--prefix`) you may also
207have to update your `/etc/ld.so.conf`, or use `pkg-confg` to build your
208application (above).
209
210**NOTE:** RedHat/Fedora/CentOS and other `.rpm`-based distributions do
211 not consider `/usr/local` as standard path anymore. So make sure to
212 `./configure --prefix=/usr`, otherwise the build system use the GNU
213 default, which is `/usr/local`. The Debian based distributions, like
214 Ubuntu, do not have this problem.
215
216
217Origin & References
218--------------------
219
220This [line editing][] library was created by [Rich Salz][] and Simmule
221Turner and in 1992. It is distributed with a “[C News][]-like” license,
222similar to the [BSD license][]. Rich's current version is however under
223the Apache license. For details on the licensing terms of this version
224of the software, see [License][].
225
226This version of the editline library was forked from the [Minix 2][]
227source tree and is *not* related to the similarily named NetBSD version
228that [Jess Thrysøe][jess] disitributes to the world outside *BSD. The
229libraries have much in common, but the latter is heavily refactored and
230also relies on libtermcap (usually supplied by ncurses), whereas this
231library only uses termios from the standard C library.
232
233Patches and bug fixes from the following forks, based on the original
234[comp.sources.unix][] posting, have been merged:
235
236* Debian [libeditline][]
237* [Heimdal][]
238* [Festival][] speech-tools
239* [Steve Tell][]'s editline patches
240
241The version numbering scheme today follows that of the Debian version,
242details available in the [ChangeLog.md][]. The current [maintainer][]
243was unaware of the Debian version for quite some time, so a different
244name and versioning scheme was used. In June 2009 this was changed to
245line up alongside Debian, with the intent is to eventually merge the
246efforts.
247
248Outstanding issues are listed in the [TODO.md][] file.
249
250[GitHub]: https://github.com/troglobit/editline
251[line editing]: https://github.com/troglobit/editline/blob/master/docs/README
252[release tarball]: https://github.com/troglobit/editline/releases
253[maintainer]: http://troglobit.com
254[C News]: https://en.wikipedia.org/wiki/C_News
255[TODO.md]: https://github.com/troglobit/editline/blob/master/docs/TODO.md
256[ChangeLog.md]: https://github.com/troglobit/editline/blob/master/ChangeLog.md
257[FSF readline]: http://www.gnu.org/software/readline/
258[Rich Salz]: https://github.com/richsalz/editline/
259[comp.sources.unix]: http://ftp.cs.toronto.edu/pub/white/pub/rc/editline.shar
260[Minix 2]: http://www.cise.ufl.edu/~cop4600/cgi-bin/lxr/http/source.cgi/lib/editline/
261[jess]: http://thrysoee.dk/editline/
262[BSD license]: http://en.wikipedia.org/wiki/BSD_licenses
263[libeditline]: http://packages.qa.debian.org/e/editline.html
264[Heimdal]: http://www.h5l.org
265[Festival]: http://festvox.org/festival/
266[Steve Tell]: http://www.cs.unc.edu/~tell/dist.html
267[License]: https://github.com/troglobit/editline/blob/master/LICENSE
268[License Badge]: https://img.shields.io/badge/License-C%20News-orange.svg
269[Travis]: https://travis-ci.org/troglobit/editline
270[Travis Status]: https://travis-ci.org/troglobit/editline.png?branch=master
271[Coverity Scan]: https://scan.coverity.com/projects/2982
272[Coverity Status]: https://scan.coverity.com/projects/2982/badge.svg
273