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