| .\" Note that in silly ol' [nt]roff, even trailing white space is |
| .\" significant. I went through and eliminated it. |
| .\" I adopted a convention of using a bold 'getline' when referring to |
| .\" the whole package, but an italic 'getline' when referring to the |
| .\" specific function. |
| .\" Note that in [nt]roff that "-" is a hyphen, while "\-" is a dash. |
| .\" I adjusted some source text lines to keep them short (I keep line |
| .\" numbers turned on in vi, so I only have 72 cols w/o wrapping). |
| .\" It's too bad that getline() doesn't realloc() the buffer as |
| .\" necessary. Then it could have an unlimited input line length. |
| .\" Note that .RI et al are limited in how many args they can take. |
| .\" I corrected gl_addhist to gl_histadd, which is what is actually |
| .\" used! Perhaps it really should be gl_addhist, to preserve the |
| .\" gl_<verb><object> pattern in the other function names. |
| .\" I tried to rephrase certain sections to avoid the passive voice. |
| .\" I find the active voice much easier to understand, since I can tell |
| .\" more easily what acts on what. |
| .TH GETLINE 3 |
| .SH NAME |
| getline \- command-line editing library with history |
| .SH SYNOPSIS |
| .RI "char *getline(char *" prompt ); |
| .PP |
| .RI "void gl_histadd(char *" line ); |
| .br |
| .RI "void gl_setwidth(int " width ); |
| .br |
| .RI "void gl_strwidth(int " (*width_func)() ); |
| .PP |
| .RI "extern int (*gl_in_hook)(char *" buf ); |
| .br |
| .RI "extern int (*gl_out_hook)(char *" buf ); |
| .br |
| .RI "extern int (*gl_tab_hook)(char *" buf , |
| .RI "int " prompt_width ", int *" cursor_loc ); |
| .SH DESCRIPTION |
| The |
| .B getline |
| package is a set of library routines that implement |
| an editable command-line history. |
| .PP |
| .B "Programming Interface" |
| .br |
| .I getline |
| returns a pointer to a line of text read from the user, |
| prompting the user with the specified |
| .IR prompt . |
| The pointer refers to a static buffer allocated by the |
| .B getline |
| package. |
| Clients may assume that the pointer |
| .I getline |
| returns is always the same, and is never NULL. |
| The buffer |
| .I getline |
| returns to the caller contains the terminating newline character, |
| except on end of file, |
| in which case the first character in the buffer is 0 |
| .RB ( NUL ). |
| File descriptors 0 and 1 must be connected to the terminal |
| (not redirected), |
| so the caller should check for this condition (using |
| .IR isatty (\|)) |
| and call stdio routines if the session is not interactive. |
| .PP |
| .I gl_histadd |
| adds the given |
| .I line |
| to the |
| .B getline |
| history list if the |
| .I line |
| is not empty and if it is different from the last line |
| in the history list |
| (so the caller need not check for these conditions). |
| .I gl_histadd |
| makes its own copies of all the lines it adds to the history list. |
| This is so the caller can reuse the buffer it supplies to |
| .IR gl_histadd . |
| .PP |
| .I gl_setwidth |
| specifies the terminal |
| .I width |
| to use for horizontal scrolling. |
| The default value is 80 columns, |
| and it is important to properly specify the |
| .I width |
| or lines may wrap inadvertently. |
| .PP |
| .I gl_strwidth |
| allows the application program to supply a prompt string width calculation |
| function that returns the number of screen positions used by the argument |
| string. |
| By default strlen is used, but if the prompt contains escape sequences the user |
| can bind a function that returns the actual number of screen postitions |
| used by the argument string, not including the escape characters. |
| .PP |
| In addition to the function call interface, |
| .B getline |
| has three externally accessible function pointers |
| that act as hooks if bound to user-defined functions. |
| .B getline |
| supplies each of the functions with a pointer to the current buffer |
| as the first argument, |
| and expects the return value to be the index |
| of the first change the function made in the buffer |
| (or \-1 if the function did not alter the buffer). |
| After the functions return, |
| .B getline |
| updates the screen as necessary. |
| .\"------- |
| .\" DWS comment -- |
| .\"------- |
| Note that the functions may not alter the size of the buffer. |
| Indeed, they do not even know how large the buffer is! |
| .PP |
| .I getline |
| calls |
| .I gl_in_hook |
| (initially NULL) |
| each time it loads a new buffer. |
| More precisely, this is |
| .TP |
| \(bu |
| at the first call to |
| .I getline |
| (with an empty buffer) |
| .TP |
| \(bu |
| each time the user enters a new buffer from the history list (with |
| .B ^P |
| or |
| .BR ^N ) |
| .TP |
| \(bu |
| when the user accepts an incremental search string |
| (when the user terminates the search). |
| .PP |
| .I getline |
| calls |
| .I gl_out_hook |
| (initially NULL) |
| when a line has been completed by the user entering a |
| .B NEWLINE |
| .RB (\| ^J \|) |
| or |
| .B RETURN |
| .RB (\| ^M \|). |
| The buffer |
| .I gl_out_hook |
| sees does not yet have the newline appended, and |
| .I gl_out_hook |
| should not add a newline. |
| .PP |
| .I getline |
| calls |
| .I gl_tab_hook |
| whenever the user types a |
| .BR TAB . |
| In addition to the buffer, |
| .I getline |
| supplies the current |
| .I prompt_width |
| (presumably needed for tabbing calculations) and |
| .IR cursor_loc , |
| a pointer to the cursor location. |
| .RI ( *cursor_loc |
| \(eq 0 corresponds to the first character in the buffer) |
| .I *cursor_loc |
| tells |
| .I gl_tab_hook |
| where the |
| .B TAB |
| was typed. |
| Note that when it redraws the screen, |
| .I getline |
| will honor any change |
| .I gl_tab_hook |
| may make to |
| .IR *cursor_loc . |
| .\"------- |
| .\" DWS comment -- |
| .\"------- |
| Note also that |
| .I prompt_width |
| may not correspond to the actual width of |
| .I prompt |
| on the screen if |
| .I prompt |
| contains escape sequences. |
| .I gl_tab_hook |
| is initially bound to the |
| .B getline |
| internal static function |
| .IR gl_tab , |
| which acts like a normal |
| .B TAB |
| key by inserting spaces. |
| .PP |
| .B "User Interface" |
| .br |
| .\"------- |
| .\" I adapted the prologue to this section from the ksh man page (dws). |
| .\"------- |
| To edit, the user moves the cursor to the point needing correction and |
| then inserts or deletes characters or words as needed. |
| All the editing commands are control characters, |
| which typed by holding the |
| CTRL key down while typing another character. |
| Control characters are indicated below as the caret |
| .RB (\| ^ \|) |
| followed by another character, |
| such as |
| .BR ^A . |
| .PP |
| All edit commands operate from any place on the line, |
| not just at the beginning. |
| .PP |
| These are the |
| .I getline |
| key bindings. |
| .\"------- |
| .\" Tt - max width of tag |
| .\" Tw - max width of tag + spacing to the paragraph |
| .\" Tp - special .TP, with the best indent for the editing command |
| .\" descriptions. |
| .\" The first version of Tp prints the tags left-justified. |
| .\" The second version of Tp prints the tags as follows: |
| .\" If one argument is given, it is printed right-justified. |
| .\" If two arguments are given, the first is printed left-justified |
| .\" and the second is printed right-justified. |
| .\"------- |
| .nr Tt \w'BACKSPACE' |
| .nr Tw \w'BACKSPACE\0\0\0' |
| .\" .de Tp |
| .\" .TP \n(Twu |
| .\" \fB\\$1\fR |
| .\" .. |
| .de Tp |
| .TP \n(Twu |
| .if \\n(.$=1 \h@\n(Ttu-\w'\fB\\$1\fR'u@\fB\\$1\fR |
| .if \\n(.$=2 \fB\\$1\fR\h@\n(Ttu-\w'\fB\\$1\\$2\fR'u@\fB\\$2\fR |
| .. |
| .PP |
| .\"------- |
| .\" Set interparagraph spacing to zero so binding descriptions are |
| .\" kept together. |
| .\"------- |
| .PD 0 |
| .Tp "^A" |
| Move cursor to beginning of line. |
| .Tp "^B" |
| Move cursor left (back) 1 column. |
| .Tp ESC-B |
| Move cursor back one word. |
| .Tp "^D" |
| Delete the character under the cursor. |
| .Tp "^E" |
| Move cursor to end of line. |
| .Tp "^F" |
| Move cursor right (forward) 1 column. |
| .Tp ESC-F |
| Move cursor forward one word. |
| .Tp "^H" |
| Delete the character left of the cursor.@ |
| .Tp "^I" |
| Jump to next tab stop (may be redefined by the program). |
| .Tp "^J" |
| Return the current line. |
| .Tp "^K" |
| Kill from cursor to the end of the line (see |
| .BR "^Y" \|). |
| .Tp "^L" |
| Redisplay current line. |
| .Tp "^M" |
| Return the current line. |
| .Tp "^N" |
| Fetches next line from the history list. |
| .Tp "^O" |
| Toggle overwrite/insert mode, initially in insert mode. |
| .Tp "^P" |
| Fetches previous line from the history list. |
| .Tp "^R" |
| Begin a reverse incremental search through history list. |
| Each printing character typed adds to the search substring |
| (initially empty), and |
| .B getline |
| finds and displays the first matching location. |
| Typing |
| .B ^R |
| again marks the current starting location and begins a new |
| search for the current substring. |
| Typing |
| .B ^H |
| or |
| .B DEL |
| deletes the last character from the search string, |
| and |
| .B getline |
| restarts the search from the last starting location. |
| Repeated |
| .B ^H |
| or |
| .B DEL |
| characters therefore appear to unwind the search to the match nearest |
| the point where the user last typed |
| .B ^R |
| or |
| .BR ^S . |
| Typing |
| .B ^H |
| or |
| .B DEL |
| until the search string is empty causes |
| .B getline |
| to reset the start of the search to the beginning of the history list. |
| Typing |
| .B ESC |
| or any other editing character accepts the current match |
| and terminates the search. |
| .Tp "^S" |
| Begin a forward incremental search through the history list. |
| The behavior is like that of |
| .B ^R |
| but in the opposite direction through the history list. |
| .Tp "^T" |
| Transpose current and previous character. |
| .Tp "^U" |
| Kill the entire line (see |
| .BR "^Y" \|). |
| .Tp "^Y" |
| Yank previously killed text back at current location. |
| .Tp BACKSPACE |
| Delete the character left of the cursor. |
| .Tp DEL |
| Delete the character left of the cursor. |
| .Tp RETURN |
| Return the current line. |
| .Tp TAB |
| Jump to next tab stop (may be redefined by the program). |
| .\"------- |
| .\" Restore default interparagraph spacing. |
| .\"------- |
| .PD |
| .PP |
| .B getline |
| recognizes DOS and ANSI arrow keys. |
| They cause the following actions: |
| .B up |
| is the same as |
| .BR ^P , |
| .B down |
| is the same as |
| .BR ^N , |
| .B left |
| is the same as |
| .BR ^P , |
| and |
| .B right |
| is the same as |
| .BR ^F . |
| .SH AUTHORS |
| .PP |
| Program by |
| Christopher R. Thewalt (thewalt\|@ce.berkeley.edu) |
| .PP |
| Original man page by |
| DaviD W. Sanderson (dws\|@cs.wisc.edu) |
| and Christopher R. Thewalt |
| .SH COPYRIGHT |
| \& |
| .br |
| .if n (C) |
| .if t \s+8\v'+2p'\fB\(co\fR\v'-2p'\s0 |
| \s+2Copyright 1992,1993 by Christopher R. Thewalt and DaviD W. Sanderson\s0 |
| (but freely redistributable) |