.\" 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)