mirror of
https://github.com/troglobit/editline.git
synced 2025-05-06 21:01:12 +08:00
192 lines
6.9 KiB
Markdown
192 lines
6.9 KiB
Markdown
Editline
|
|
========
|
|
[![Travis Status]][Travis] [![Coverity Status]][Coverity Scan]
|
|
|
|
|
|
Table of Contents
|
|
-----------------
|
|
|
|
* [Introduction](#introduction)
|
|
* [API](#api)
|
|
* [Example](#example)
|
|
* [Build & Install](#build--install)
|
|
* [Origin & References](#origin--references)
|
|
|
|
|
|
Introduction
|
|
------------
|
|
|
|
This is a small [line editing][] library. It can be linked into almost
|
|
any program to provide command line editing and history functions. It
|
|
is call compatible with the [FSF readline][] library, but at a fraction
|
|
of the size, and as a result fewer features. It is also distributed
|
|
under a much more liberal [LICENSE][].
|
|
|
|
The small size (<30k), lack of dependencies (ncurses not needed!), and
|
|
the free license should make this library interesting to many embedded
|
|
developers.
|
|
|
|
Editline has several optional build-time features that can be enabled by
|
|
supplying different options to the GNU configure script. See the output
|
|
from <kbd>configure --help</kbd> for details. Some useful hints on how
|
|
to use the library is available in the `examples/` directory.
|
|
|
|
Editline is maintained collaboratively at [GitHub][].
|
|
|
|
|
|
API
|
|
---
|
|
|
|
Here is the interface to editline. It has a small compatibility layer
|
|
to [FSF readline][], which may not be entirely up-to-date.
|
|
|
|
```C
|
|
/* Editline specific global variables. */
|
|
int el_no_echo; /* Do not echo input characters */
|
|
int el_no_hist; /* Disable auto-save of and access to history,
|
|
* e.g. for password prompts or wizards */
|
|
int el_hist_size; /* Size of history scrollback buffer, default: 15 */
|
|
|
|
/* Editline specific functions. */
|
|
char * el_find_word(void);
|
|
void el_print_columns(int ac, char **av);
|
|
el_status_t el_ring_bell(void);
|
|
el_status_t el_del_char(void);
|
|
|
|
/* Callback function for key binding */
|
|
typedef el_status_t el_keymap_func_t(void);
|
|
|
|
/* Bind key to a callback, use CTL('f') to change Ctrl-F, for example */
|
|
el_status_t el_bind_key(int key, el_keymap_func_t function);
|
|
el_status_t el_bind_key_in_metamap(int key, el_keymap_func_t function);
|
|
|
|
/* For compatibility with FSF readline. */
|
|
int rl_point;
|
|
int rl_mark;
|
|
int rl_end;
|
|
int rl_inhibit_complete;
|
|
char *rl_line_buffer;
|
|
const char *rl_readline_name;
|
|
|
|
void rl_initialize(void);
|
|
void rl_uninitialize(void);
|
|
void rl_reset_terminal(const char *terminal_name);
|
|
|
|
void rl_save_prompt(void);
|
|
void rl_restore_prompt(void);
|
|
void rl_set_prompt(const char *prompt);
|
|
|
|
void rl_clear_message(void);
|
|
void rl_forced_update_display(void);
|
|
|
|
/* Main function to use, saves history by default */
|
|
char *readline(const char *prompt);
|
|
|
|
/* Use to save a read line to history, when el_no_hist is set */
|
|
void add_history(const char *line);
|
|
|
|
/* Load and save editline history from/to a file. */
|
|
int read_history(const char *filename);
|
|
int write_history(const char *filename);
|
|
|
|
/* Magic completion API, see examples/cli.c for more info */
|
|
rl_complete_func_t *rl_set_complete_func(rl_complete_func_t *func);
|
|
rl_list_possib_func_t *rl_set_list_possib_func(rl_list_possib_func_t *func);
|
|
```
|
|
|
|
|
|
Example
|
|
-------
|
|
|
|
Here is a very brief example to illustrate how one can use Editline to
|
|
create a simple CLI. More examples are availble in the source tree.
|
|
|
|
```C
|
|
#include <stdlib.h>
|
|
|
|
extern char *readline(char *prompt);
|
|
|
|
int main (void)
|
|
{
|
|
char *p;
|
|
|
|
while ((p = readline("CLI> ")) != NULL) {
|
|
puts(p);
|
|
free(p);
|
|
}
|
|
|
|
return 0;
|
|
}
|
|
```
|
|
|
|
|
|
Build & Install
|
|
---------------
|
|
|
|
Editline was originally designed for older UNIX systems and Plan 9. The
|
|
current maintainer works exclusively on GNU/Linux systems, so it may use
|
|
GCC and GNU Make specific extensions here and there. This is not on
|
|
purpose and patches or pull requests to correct this are most welcome!
|
|
|
|
1. Configure editline with default features: <kbd>./configure</kbd>
|
|
2. Build the library and examples: <kbd>make all</kbd>
|
|
3. Install using <kbd>make install</kbd>
|
|
|
|
The `$DESTDIR` environment variable is honored at install. For more
|
|
options, see <kbd>./configure --help</kbd>
|
|
|
|
|
|
Origin & References
|
|
--------------------
|
|
|
|
This [line editing][] library was created by [Rich Salz][] and Simmule
|
|
Turner and in 1992. It is distributed under a “C News-like” license,
|
|
similar to the [BSD license][]. Rich's latest version is however under
|
|
the Apache license. For details on the licensing terms of this version
|
|
of the software, see [LICENSE][].
|
|
|
|
This version of the editline library was forked from the [Minix 3][]
|
|
source tree and is *not* related to the similarily named NetBSD version
|
|
that [Jess Thrysøe][jess] disitributes to the world outside *BSD. The
|
|
libraries have much in common, but the latter is heavily refactored and
|
|
also relies on libtermcap (usually supplied by ncurses), whereas this
|
|
library only uses termios from the standard C library.
|
|
|
|
Patches and bug fixes from the following forks, based on the original
|
|
[comp.sources.unix][] posting, have been merged:
|
|
|
|
* Debian [libeditline][]
|
|
* [Heimdal][]
|
|
* [Festival][] speech-tools
|
|
* [Steve Tell][]'s editline patches
|
|
|
|
The version numbering scheme today follows that of the Debian version,
|
|
details available in the [ChangeLog.md][]. The current [maintainer][]
|
|
was unaware of the Debian version for quite some time, so a different
|
|
name and versioning scheme was used. In June 2009 this was changed to
|
|
line up alongside Debian, with the intent is to eventually merge the
|
|
efforts.
|
|
|
|
Outstanding issues are listed in the [TODO.md][] file.
|
|
|
|
[GitHub]: https://github.com/troglobit/editline
|
|
[line editing]: https://github.com/troglobit/editline/blob/master/doc/README
|
|
[maintainer]: http://troglobit.com
|
|
[LICENSE]: https://github.com/troglobit/editline/blob/master/LICENSE
|
|
[TODO.md]: https://github.com/troglobit/editline/blob/master/TODO.md
|
|
[ChangeLog.md]: https://github.com/troglobit/editline/blob/master/ChangeLog.md
|
|
[FSF readline]: http://www.gnu.org/software/readline/
|
|
[Rich Salz]: https://github.com/richsalz/editline/
|
|
[comp.sources.unix]: http://ftp.cs.toronto.edu/pub/white/pub/rc/editline.shar
|
|
[Minix 3]: http://www.cise.ufl.edu/~cop4600/cgi-bin/lxr/http/source.cgi/lib/editline/
|
|
[jess]: http://thrysoee.dk/editline/
|
|
[BSD license]: http://en.wikipedia.org/wiki/BSD_licenses
|
|
[libeditline]: http://packages.qa.debian.org/e/editline.html
|
|
[Heimdal]: http://www.h5l.org
|
|
[Festival]: http://festvox.org/festival/
|
|
[Steve Tell]: http://www.cs.unc.edu/~tell/dist.html
|
|
[Travis]: https://travis-ci.org/troglobit/editline
|
|
[Travis Status]: https://travis-ci.org/troglobit/editline.png?branch=master
|
|
[Coverity Scan]: https://scan.coverity.com/projects/2982
|
|
[Coverity Status]: https://scan.coverity.com/projects/2982/badge.svg
|