michael@0: .TH EDITLINE 3 michael@0: .SH NAME michael@0: editline \- command-line editing library with history michael@0: .SH SYNOPSIS michael@0: .nf michael@0: .B "char *" michael@0: .B "readline(prompt)" michael@0: .B " char *prompt;" michael@0: michael@0: .B "void" michael@0: .B "add_history(line)" michael@0: .B " char *line;" michael@0: .fi michael@0: .SH DESCRIPTION michael@0: .I Editline michael@0: is a library that provides an line-editing interface with text recall. michael@0: It is intended to be compatible with the michael@0: .I readline michael@0: library provided by the Free Software Foundation, but much smaller. michael@0: The bulk of this manual page describes the user interface. michael@0: .PP michael@0: The michael@0: .I readline michael@0: routine returns a line of text with the trailing newline removed. michael@0: The data is returned in a buffer allocated with michael@0: .IR malloc (3), michael@0: so the space should be released with michael@0: .IR free (3) michael@0: when the calling program is done with it. michael@0: Before accepting input from the user, the specified michael@0: .I prompt michael@0: is displayed on the terminal. michael@0: .PP michael@0: The michael@0: .I add_history michael@0: routine makes a copy of the specified michael@0: .I line michael@0: and adds it to the internal history list. michael@0: .SS "User Interface" michael@0: A program that uses this library provides a simple emacs-like editing michael@0: interface to its users. michael@0: A line may be edited before it is sent to the calling program by typing either michael@0: control characters or escape sequences. michael@0: A control character, shown as a caret followed by a letter, is typed by michael@0: holding down the ``control'' key while the letter is typed. michael@0: For example, ``^A'' is a control-A. michael@0: An escape sequence is entered by typing the ``escape'' key followed by one or michael@0: more characters. michael@0: The escape key is abbreviated as ``ESC.'' michael@0: Note that unlike control keys, case matters in escape sequences; ``ESC\ F'' michael@0: is not the same as ``ESC\ f''. michael@0: .PP michael@0: An editing command may be typed anywhere on the line, not just at the michael@0: beginning. michael@0: In addition, a return may also be typed anywhere on the line, not just at michael@0: the end. michael@0: .PP michael@0: Most editing commands may be given a repeat count, michael@0: .IR n , michael@0: where michael@0: .I n michael@0: is a number. michael@0: To enter a repeat count, type the escape key, the number, and then michael@0: the command to execute. michael@0: For example, ``ESC\ 4\ ^f'' moves forward four characters. michael@0: If a command may be given a repeat count then the text ``[n]'' is given at the michael@0: end of its description. michael@0: .PP michael@0: The following control characters are accepted: michael@0: .RS michael@0: .nf michael@0: .ta \w'ESC DEL 'u michael@0: ^A Move to the beginning of the line michael@0: ^B Move left (backwards) [n] michael@0: ^D Delete character [n] michael@0: ^E Move to end of line michael@0: ^F Move right (forwards) [n] michael@0: ^G Ring the bell michael@0: ^H Delete character before cursor (backspace key) [n] michael@0: ^I Complete filename (tab key); see below michael@0: ^J Done with line (return key) michael@0: ^K Kill to end of line (or column [n]) michael@0: ^L Redisplay line michael@0: ^M Done with line (alternate return key) michael@0: ^N Get next line from history [n] michael@0: ^P Get previous line from history [n] michael@0: ^R Search backward (forward if [n]) through history for text; michael@0: \& must start line if text begins with an uparrow michael@0: ^T Transpose characters michael@0: ^V Insert next character, even if it is an edit command michael@0: ^W Wipe to the mark michael@0: ^X^X Exchange current location and mark michael@0: ^Y Yank back last killed text michael@0: ^[ Start an escape sequence (escape key) michael@0: ^]c Move forward to next character ``c'' michael@0: ^? Delete character before cursor (delete key) [n] michael@0: .fi michael@0: .RE michael@0: .PP michael@0: The following escape sequences are provided. michael@0: .RS michael@0: .nf michael@0: .ta \w'ESC DEL 'u michael@0: ESC\ ^H Delete previous word (backspace key) [n] michael@0: ESC\ DEL Delete previous word (delete key) [n] michael@0: ESC\ SP Set the mark (space key); see ^X^X and ^Y above michael@0: ESC\ \. Get the last (or [n]'th) word from previous line michael@0: ESC\ \? Show possible completions; see below michael@0: ESC\ < Move to start of history michael@0: ESC\ > Move to end of history michael@0: ESC\ b Move backward a word [n] michael@0: ESC\ d Delete word under cursor [n] michael@0: ESC\ f Move forward a word [n] michael@0: ESC\ l Make word lowercase [n] michael@0: ESC\ m Toggle if 8bit chars display normally or with ``M\-'' prefix michael@0: ESC\ u Make word uppercase [n] michael@0: ESC\ y Yank back last killed text michael@0: ESC\ v Show library version michael@0: ESC\ w Make area up to mark yankable michael@0: ESC\ nn Set repeat count to the number nn michael@0: ESC\ C Read from environment variable ``_C_'', where C is michael@0: \& an uppercase letter michael@0: .fi michael@0: .RE michael@0: .PP michael@0: The michael@0: .I editline michael@0: library has a small macro facility. michael@0: If you type the escape key followed by an uppercase letter, michael@0: .IR C , michael@0: then the contents of the environment variable michael@0: .I _C_ michael@0: are read in as if you had typed them at the keyboard. michael@0: For example, if the variable michael@0: .I _L_ michael@0: contains the following: michael@0: .RS michael@0: ^A^Kecho '^V^[[H^V^[[2J'^M michael@0: .RE michael@0: Then typing ``ESC L'' will move to the beginning of the line, kill the michael@0: entire line, enter the echo command needed to clear the terminal (if your michael@0: terminal is like a VT-100), and send the line back to the shell. michael@0: .PP michael@0: The michael@0: .I editline michael@0: library also does filename completion. michael@0: Suppose the root directory has the following files in it: michael@0: .RS michael@0: .nf michael@0: .ta \w'core 'u michael@0: bin vmunix michael@0: core vmunix.old michael@0: .fi michael@0: .RE michael@0: If you type ``rm\ /v'' and then the tab key. michael@0: .I Editline michael@0: will then finish off as much of the name as possible by adding ``munix''. michael@0: Because the name is not unique, it will then beep. michael@0: If you type the escape key and a question mark, it will display the michael@0: two choices. michael@0: If you then type a period and a tab, the library will finish off the filename michael@0: for you: michael@0: .RS michael@0: .nf michael@0: .RI "rm /v[TAB]" munix .TAB old michael@0: .fi michael@0: .RE michael@0: The tab key is shown by ``[TAB]'' and the automatically-entered text michael@0: is shown in italics. michael@0: .SH "BUGS AND LIMITATIONS" michael@0: Cannot handle lines more than 80 columns. michael@0: .SH AUTHORS michael@0: Simmule R. Turner michael@0: and Rich $alz . michael@0: Original manual page by DaviD W. Sanderson .