From 2aee394b440e57b3b5518976bad2ce5d245a3973 Mon Sep 17 00:00:00 2001 From: Joachim Nilsson Date: Sat, 27 Apr 2019 12:32:58 +0200 Subject: [PATCH] Major update of man page, exand on APIs and history of library - Convert from obtruse troff syntax to simpler mdoc format - Add history APIs, most relevant extra APIs available - Expand on the history of the library - Rewrite some sections for accessiblilty Signed-off-by: Joachim Nilsson --- man/editline.3 | 442 +++++++++++++++++++++++++++++-------------------- 1 file changed, 258 insertions(+), 184 deletions(-) diff --git a/man/editline.3 b/man/editline.3 index 991a31a..daf8a1c 100644 --- a/man/editline.3 +++ b/man/editline.3 @@ -1,200 +1,274 @@ -.TH EDITLINE 3 -.SH NAME -editline \- command-line editing library with history -.SH SYNOPSIS -.nf -.B "char *readline(char *prompt);" -.fi -.SH DESCRIPTION -.I Editline -is a library that provides an line-editing interface with history. -It is intended to be functionally equivalent with the -.I readline -library provided by the Free Software Foundation, but much smaller. -The bulk of this manual page describes the user interface. -.PP +.Dd April 27, 2019 +.Dt EDITLINE 3 +.Os +.Sh NAME +.Nm editline +.Nd command-line editing library with history +.Sh LIBRARY +.Lb libeditline +.Sh SYNOPSIS +.In editline.h +.Fn "char *readline" "const char *prompt" +.Fn "void add_history" "const char *line" +.Fn "int read_history" "const char *filename" +.Fn "int write_history" "const char *filename" +.Sh DESCRIPTION +.Nm +is a library that provides n line-editing interface with history. It +is intended to be functionally equivalent with the +.Nm readline +library provided by the Free Software Foundation, but much smaller. The +bulk of this manual page describes the basic user interface. More APIs, +both native and for +.Nm readline +compatibility , +are also available. See the +.Cm editline.h +header file for details. +.Pp The -.I readline() +.Fn readline function displays the given -.I prompt -on stdout, waits for user input on stdin and then -returns a line of text with the trailing newline removed. The data is returned in a -buffer allocated with -.IR malloc (3), +.Fa prompt +on stdout, waits for user input on stdin and then returns a line of text +with the trailing newline removed. The data is returned in a buffer +allocated with +.Xr malloc 3 , so the space should be released with -.IR free (3) +.Xr free 3 when the calling program is done with it. -.PP -Each line returned is copied to the internal history list, unless it happens -to be equal to the previous line. This is configurable if you are building editline -from source. -.SS User Interface -A program that uses this library provides a simple emacs-like editing interface to -its users. A line may be edited before it is sent to the calling program by typing -either control characters or escape sequences. A control character, shown as a caret -followed by a letter, is typed by holding down the ``control'' key while the letter -is typed. For example, ``^A'' is a control-A. An escape sequence is entered by -typing the ``escape'' key followed by one or more characters. The escape key is -abbreviated as ``ESC''. Note that unlike control keys, case matters in escape -sequences; ``ESC\ F'' is not the same as ``ESC\ f''. -.PP -An editing command may be typed anywhere on the line, not just at the beginning. In -addition, a return may also be typed anywhere on the line, not just at the end. -.PP +.Pp +Each line returned is automatically saved in the internal history list, +unless it happens to be equal to the previous line. This is +configurable if you are building editline from source, i.e. if you would +rather like to call +.Fn add_history +manually. +.Pp +The +.Fn read_history +and +.Fn write_history +functions can be used to load and store the history of your application. +.Em Note: +these APIs do not do any tilde or environment variable expansion of the +given filename. +.Ss User Interface +A program that uses this library provides a simple emacs-like editing +interface to its users. A line may be edited before it is sent to the +calling program by typing either control characters or escape sequences. +A control character, shown as a caret followed by a letter, is typed by +holding down the control key while the letter is typed. For example, +.Cm ^A +is a control-A. An escape sequence is entered by typing the escape key +followed by one or more characters. The escape key is abbreviated as +.Cm ESC . +Note that unlike control keys, case matters in escape sequences; +.Cm ESC F +is not the same as +.Cm ESC f . +.Pp +An editing command may be typed anywhere on the line, not just at the +beginning. In addition, a return may also be typed anywhere on the +line, not just at the end. +.Pp Most editing commands may be given a repeat count, -.IR n , +.Ar n , where -.I n -is a number. -To enter a repeat count, type the escape key, the number, and then -the command to execute. -For example, ``ESC\ 4\ ^f'' moves forward four characters. -If a command may be given a repeat count then the text ``[n]'' is given at the -end of its description. -.PP +.Ar n +is a number. To enter a repeat count, type the escape key, the number, +and then the command to execute. For example, +.Cm ESC 4 ^f +moves forward four characters. If a command may be given a repeat count +then the text +.Cm [n] +is given at the end of its description. +.Pp The following control characters are accepted: -.RS -.nf -.ta \w'ESC DEL 'u -^A Move to the beginning of the line -^B Move left (backwards) [n] -^D Delete character [n] -^E Move to end of line -^F Move right (forwards) [n] -^G Ring the bell -^H Delete character before cursor (backspace key) [n] -^I Complete filename (tab key); see below -^J Done with line (return key) -^K Kill to end of line (or column [n]) -^L Redisplay line -^M Done with line (alternate return key) -^N Get next line from history [n] -^P Get previous line from history [n] -^R Search backward (forward if [n]) through history for -\& text; must start line if text begins with an uparrow -^T Transpose characters -^V Insert next character, even if it is an edit command -^W Wipe to the mark -^X^X Exchange current location and mark -^Y Yank back last killed text -^[ Start an escape sequence (escape key) -^]c Move forward to next character ``c'' -^? Delete character before cursor (delete key) [n] -.fi -.RE -.PP -The following escape sequences are provided. -.RS -.nf -.ta \w'ESC DEL 'u -ESC\ ^H Delete previous word (backspace key) [n] -ESC\ DEL Delete previous word (delete key) [n] -ESC\ SP Set the mark (space key); see ^X^X and ^Y above -ESC\ \. Get the last (or [n]'th) word from previous line -ESC\ ? Show possible completions; see below -ESC\ < Move to start of history -ESC\ > Move to end of history -ESC\ b Move backward a word [n] -ESC\ d Delete word under cursor [n] -ESC\ f Move forward a word [n] -ESC\ l Make word lowercase [n] -ESC\ m Toggle if 8bit chars display normally or with an -\& ``M\-'' prefix -ESC\ u Make word uppercase [n] -ESC\ y Yank back last killed text -ESC\ v Show library version -ESC\ w Make area up to mark yankable -ESC\ nn Set repeat count to the number nn -ESC\ C Read from environment variable ``_C_'', where C is -\& an uppercase letter -.fi -.RE -.PP +.Pp +.Bl -tag -width "ESC DEL " -compact +.It ^A +Move to the beginning of the line +.It ^B +Move left (backwards) [n] +.It ^D +Delete character [n] +.It ^E +Move to end of line +.It ^F +Move right (forwards) [n] +.It ^G +Ring the bell +.It ^H +Delete character before cursor (backspace key) [n] +.It ^I +Complete filename (tab key); see below +.It ^J +Done with line (return key) +.It ^K +Kill to end of line (or column [n]) +.It ^L +Redisplay line +.It ^M +Done with line (alternate return key) +.It ^N +Get next line from history [n] +.It ^P +Get previous line from history [n] +.It ^R +Search backward (forward if [n]) through history for text; prefixing the +string with a caret (^) forces it to match only at the beginning of a +history line +.It ^T +Transpose characters +.It ^V +Insert next character, even if it is an edit command +.It ^W +Wipe to the mark +.It ^X^X +Exchange current location and mark +.It ^Y +Yank back last killed text +.It ^[ +Start an escape sequence (escape key) +.It ^]c +Move forward to next character +.Cm c +.It ^? +Delete character before cursor (delete key) [n] +.El +.Pp +The following escape sequences are provided: +.Pp +.Bl -tag -width "ESC DEL " -compact +.It ESC ^H +Delete previous word (backspace key) [n] +.It ESC DEL +Delete previous word (delete key) [n] +.It ESC SP +Set the mark (space key); see ^X^X and ^Y above +.It ESC\ . +Get the last (or [n]'th) word from previous line +.It ESC\ ? +Show possible completions; see below +.It ESC < +Move to start of history +.It ESC > +Move to end of history +.It ESC b +Move backward a word [n] +.It ESC d +Delete word under cursor [n] +.It ESC f +Move forward a word [n] +.It ESC l +Make word lowercase [n] +.It ESC m +Toggle if 8bit chars display normally or with an +.Ar M- +prefix +.It ESC u +Make word uppercase [n] +.It ESC y +Yank back last killed text +.It ESC v +Show library version +.It ESC w +Make area up to mark yankable +.It ESC nn +Set repeat count to the number nn +.It ESC C +Read from environment variable +.Ar $C , +where +.Ar C +is an uppercase letter +.El +.Pp The -.I editline -library has a small macro facility. -If you type the escape key followed by an uppercase letter, -.IR C , +.Nm +library has a small macro facility. If you type the escape key followed +by an uppercase letter, +.Ar C , then the contents of the environment variable -.I _C_ -are read in as if you had typed them at the keyboard. -For example, if the variable -.I _L_ +.Ar $C +are read in as if you had typed them at the keyboard. For example, if +the variable +.Ar $L contains the following: -.PP -.RS -^A^Kecho '^V^[[H^V^[[2J'^M -.RE -.PP -Then typing ``ESC L'' will move to the beginning of the line, kill the -entire line, enter the echo command needed to clear the terminal (if your -terminal is like a VT-100), and send the line back to the shell. -.PP +.Pp +.Dl ^A^Kecho '^V^[[H^V^[[2J'^M +.Pp +Then typing +.Cm ESC L +will move to the beginning of the line, kill the entire line, enter the +echo command needed to clear the terminal (if your terminal is like a +VT-100), and send the line back to the shell. +.Pp The -.I editline -library also does filename completion. -Suppose the root directory has the following files in it: -.PP -.RS -.nf -.ta \w'core 'u -bin vmunix -core vmunix.old -.fi -.RE -.PP -If you type ``rm\ /v'' and then the tab key. -.I Editline -will then finish off as much of the name as possible by adding ``munix''. -Because the name is not unique, it will then beep. -If you type the escape key and a question mark, it will display the -two choices. -If you then type a period and a tab, the library will finish off the filename +.Nm +library also does filename completion. Suppose the root directory has +the following files in it: +.Pp +.Dl bin vmunix +.Dl core vmunix.old +.Pp +If you type +.Cm rm /v +and then the tab key, +.Nm +will then finish off as much of the name as possible by adding +.Ar munix . +Because the name is not unique, it will then beep. If you type the +escape key and a question mark, it will display the two choices. If you +then type a period and a tab, the library will finish off the filename for you: -.PP -.RS -.nf -.RI "rm /v[TAB]" munix ".[TAB]" old -.fi -.RE -.PP -The tab key is shown by ``[TAB]'' and the automatically-entered text -is shown in italics. -.SH USAGE +.Pp +.Bd -ragged -offset indent +rm /v[TAB] +.Em munix +\&.[TAB] +.Em old +.Ed +.Pp +The tab key is shown by [TAB] and the automatically-entered text +is shown in italics, or underline. +.Sh USAGE To include -.I readline() -in your program, simply call it as you do any other function. Just make sure to link -your program with libeditline. -.SS Example +.Nm +in your program, call it as you do any other function and link your +program with +.Ar -leditline . +.Ss Example The following brief example lets you enter a line and edit it, then displays it. -.nf -.B "" -.B #include -.B "" -.B extern char *readline(char *prompt); -.B "" -.B int main(void) -.B { -.RS -.B char *p; -.B "" -.B while ((p = readline("CLI>"))) { -.RS -.B puts(p); -.B free(p); -.RE -.B } -.B "" -.B return 0; -.RE -.B } -.fi -.SH AUTHORS -The original editline library was created by Simmule R. Turner and Rich -Salz. It now exists in several forks: Heimdal, Festival speech tools, -Mozilla, Google Gadgets for Linux, and many other places. The original -manual page was made by David W. Sanderson. This version is maintained -by Joachim Nilsson at GitHub, +.Pp +.Bd -literal -offset indent +#include +#include +#include + +int main(void) +{ + char *p; + + while ((p = readline("CLI> "))) { + puts(p); + free(p); + } + + return 0; +} +.El +.Sh AUTHORS +The original editline library was posted to comp.sources.unix newsgroup +by created by Simmule R. Turner and Rich Salz in 1992. It now exists in +several forks: Debian, Minix, Heimdal, Festival speech tools, Mozilla, +Google Gadgets for Linux, and many other places. The original manual +page was made by David W. Sanderson. +.Pp +This version was originally based on the Minix 2 sources, but has since +evolved to include patches from all relevant forks. It is currently +maintained by Joachim Nilsson at GitHub, .Aq http://github.com/troglobit/editline -.SH BUGS +.Sh BUGS Does not handle multiple lines or unicode characters well.