zhangyiss/editline
1
0
Fork 0
mirror of https://github.com/troglobit/editline.git synced 2025-05-06 04:21:24 +08:00
Code Issues Actions Packages Projects Releases Wiki Activity

Major update of man page, exand on APIs and history of library

Browse Source 
- 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 <troglobit@gmail.com>
This commit is contained in:
Joachim Nilsson 2019-04-27 12:32:58 +02:00
parent dd1af360c3
commit 2aee394b44
1 changed files with 258 additions and 184 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

442
man/editline.3
View File

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