gl_get_line.3

BCAST Implementation for NS2

An example of a key binding line in the configuration file is
the following.

.nf
  bind M-[2~ insert-mode
.fi

On many keyboards, the above key sequence is generated when one
presses the \f3insert\f1 key, so with this keybinding, one can toggle
between the emacs-mode insert and overwrite modes by hitting one
key. One could also do it by typing out the above sequence of
characters one by one. As explained above, the \f3M-\f1 part of this
sequence can be typed either by pressing the escape key before the
following key, or by pressing the Meta key at the same time as the
following key. Thus if you had set the above key binding, and the
insert key on your keyboard didn't generate the above key sequence,
you could still type it in either of the following 2 ways.

.nf
  1. Hit the escape key momentarily, then press '[', then '2', then
     finally '~'.

  2. Press the meta key at the same time as pressing the '[' key,
     then press '2', then '~'.
.fi

If you set a keybinding for a key-sequence that is already bound to a function,
the new binding overrides the old one. If in the new binding you omit the name
of the new function to bind to the key-sequence, the original binding becomes
undefined.
.sp
Starting with versions of libtecla later than 1.3.3 it is now possible
to bind keysequences that begin with a printable character. Previously
key-sequences were required to start with a control or meta character.
.sp
Note that the special keywords "up", "down", "left" and "right" refer
to the arrow keys, and are thus not treated as keysequences. So, for
example, to rebind the up and down arrow keys to use the history
search mechanism instead of the simple history recall method, you
could place the following in your configuration file:

.nf
  bind up history-search-backwards
  bind down history-search-backwards
.fi
.sp
To unbind an existing binding, you can do this with the bind command
by omitting to name any action to rebind the key sequence to.  For
example, by not specifying an action function, the following command
unbinds the default beginning-of-line action from the ^A key sequence:

.nf
  bind ^A
.fi

.SH ALTERNATE CONFIGURATION SOURCES

As mentioned above, by default users have the option of configuring
the behavior of \f3gl_get_line()\f1 via a configuration file called
\f3\&.teclarc\f1 in their home directories. The fact that all
applications share this same configuration file is both an advantage
and a disadvantage.  In most cases it is an advantage, since it
encourages uniformity, and frees the user from having to configure
each application separately.  In some applications, however, this
single means of configuration is a problem. This is particularly true
of embedded software, where there's no filesystem to read a
configuration file from, and also in applications where a radically
different choice of keybindings is needed to emulate a legacy keyboard
interface.  To cater for such cases, the following function allows the
application to control where configuration information is read from.

.sp
.nf
  int gl_configure_getline(GetLine *gl,
                           const char *app_string,
                           const char *app_file,
                           const char *user_file);
.fi
.sp

It allows the configuration commands that would normally be read from
a user's \f3~/.teclarc\f1 file, to be read from any or none of, a
string, an application specific configuration file, and/or a
user-specific configuration file. If this function is called before
the first call to \f3gl_get_line()\f1, the default behavior of
reading \f3~/.teclarc\f1 on the first call to \f3gl_get_line()\f1 is
disabled, so all configuration must be achieved using the
configuration sources specified with this function.

If \f3app_string != NULL\f1, then it is interpreted as a string
containing one or more configuration commands, separated from each
other in the string by embedded newline characters. If \f3app_file !=
NULL\f1 then it is interpreted as the full pathname of an
application-specific configuration file. If \f3user_file != NULL\f1
then it is interpreted as the full pathname of a user-specific
configuration file, such as \f3~/.teclarc\f1. For example, in the
following call,

  gl_configure_getline(gl, "edit-mode vi \\n nobeep",
                           "/usr/share/myapp/teclarc",
                           "~/.teclarc");

the \f3app_string\f1 argument causes the calling application to start
in vi edit-mode, instead of the default emacs mode, and turns off the
use of the terminal bell by the library. It then attempts to read
system-wide configuration commands from an optional file called
\f3/usr/share/myapp/teclarc\f1, then finally reads user-specific
configuration commands from an optional \f3\&.teclarc\f1 file in the
user's home directory. Note that the arguments are listed in ascending
order of priority, with the contents of \f3app_string\f1 being
potentially overriden by commands in \f3app_file\f1, and commands in
\f3app_file\f1 potentially being overriden by commands in
\f3user_file\f1.
.sp
You can call this function as many times as needed, the results being
cumulative, but note that copies of any filenames specified via the
\f3app_file\f1 and \f3user_file\f1 arguments are recorded internally
for subsequent use by the \f3read-init-files\f1 key-binding function,
so if you plan to call this function multiple times, be sure that the
last call specifies the filenames that you want re-read when the user
requests that the configuration files be re-read.

.SH FILENAME AND TILDE COMPLETION

With the default key bindings, pressing the TAB key (aka. ^I) results
in \f3gl_get_line()\f1 attempting to complete the incomplete filename
that precedes the cursor. \f3gl_get_line()\f1 searches backwards from
the cursor, looking for the start of the filename, stopping when it
hits either a space or the start of the line. If more than one file
has the specified prefix, \f3gl_get_line()\f1 completes the filename
up to the point at which the ambiguous matches start to differ, then
lists the possible matches.
.sp
In addition to literally written filenames, \f3gl_get_line()\f1 can
complete files that start with \f3~/\f1 and \f3~user/\f1 expressions
and that contain \f3$envvar\f1 expressions. In particular, if you hit
TAB within an incomplete \f3~user\f1, expression, \f3gl_get_line()\f1
will attempt to complete the username, listing any ambiguous matches.
.sp
The completion binding is implemented using the
\f3cpl_word_completions()\f1 function, which is also available
separately to users of this library. See the
\f3cpl_word_completions(3)\f1 man page for more details.

.SH CUSTOMIZED WORD COMPLETION

If in your application, you would like to have TAB completion complete
other things in addition to or instead of filenames, you can arrange
this by registering an alternate completion callback function, via a
call to the \f3gl_customize_completion()\f1 function.
.sp
.nf
  int gl_customize_completion(GetLine *gl, void *data,
                              CplMatchFn *match_fn);
.fi
.sp
The \f3data\f1 argument provides a way for your application to pass
arbitrary, application-specific information to the callback
function. This is passed to the callback every time that it is
called. It might for example, point to the symbol table from which
possible completions are to be sought. The \f3match_fn\f1 argument
specifies the callback function to be called. The \f3CplMatchFn\f1
function type is defined in \f3libtecla.h\f1, as is a
\f3CPL_MATCH_FN()\f1 macro that you can use to declare and prototype
callback functions. The declaration and responsibilities of callback
functions are described in depth in the \f1cpl_complete_word(3)\f1 man
page.
.sp
In brief, the callback function is responsible for looking backwards
in the input line, back from the point at which the user pressed TAB,
to find the start of the word being completed. It then must lookup
possible completions of this word, and record them one by one in the
\f3WordCompletion\f1 object that is passed to it as an argument, by
calling the \f3cpl_add_completion()\f1 function. If the callback
function wishes to provide filename completion in addition to its own
specific completions, it has the option of itself calling the builtin
file-name completion callback. This also, is documented in the
\f3cpl_complete_word(3)\f1 man page.
.sp
Note that if you would like \f3gl_get_line()\f1 to return the current
input line when a successful completion is been made, you can arrange
this when you call \f3cpl_add_completion()\f1, by making the last
character of the continuation suffix a newline character. If you do
this, the input line will be updated to display the completion,
together with any contiuation suffix up to the newline character, then
\f3gl_get_line()\f1 will return this input line.

.SH FILENAME EXPANSION

With the default key bindings, pressing \f3^X*\f1 causes
\f3gl_get_line()\f1 to expand the filename that precedes the cursor,
replacing \f3~/\f1 and \f3~user/\f1 expressions with the corresponding
home directories, and replacing \f3$envvar\f1 expressions with the
value of the specified environment variable, then if there are any
wildcards, replacing the so far expanded filename with a
space-separated list of the files which match the wild cards.
.sp
The expansion binding is implemented using the \f3ef_expand_file()\f1 function.
See the \f3ef_expand_file(3)\f1 man page for more details.

.SH RECALLING PREVIOUSLY TYPED LINES

Every time that a new line is entered by the user, it is appended to a
list of historical input lines maintained within the GetLine resource
object. You can traverse up and down this list using the up and down
arrow keys. Alternatively, you can do the same with the \f3^P\f1, and
\f3^N\f1 keys, and in vi command mode you can alternatively use the k
and j characters. Thus pressing up-arrow once, replaces the current
input line with the previously entered line. Pressing up-arrow again,
replaces this with the line that was entered before it, etc.. Having
gone back one or more lines into the history list, one can return to
newer lines by pressing down-arrow one or more times. If you do this
sufficient times, you will return to the original line that you were
entering when you first hit up-arrow.
.sp
Note that in vi mode, all of the history recall functions switch the
library into command mode.
.sp
In emacs mode the \f3M-p\f1 and \f3M-n\f1 keys work just like the
\f3^P\f1 and \f3^N\f1 keys, except that they skip all but those
historical lines which share the prefix that precedes the cursor. In
vi command mode the upper case \f3K\f1 and \f3J\f1 characters do the
same thing, except that the string that they search for includes the
character under the cursor as well as what precedes it.
.sp
Thus for example, suppose that you were in emacs mode, and you had
just entered the following list of commands in the order shown:

.nf
  ls ~/tecla/
  cd ~/tecla
  ls -l getline.c
  emacs ~/tecla/getline.c
.fi

If you next typed:

.nf
  ls
.fi

and then hit \f3M-p\f1, then rather than returning the previously
typed emacs line, which doesn't start with "ls", \f3gl_get_line()\f1
would recall the "ls -l getline.c" line. Pressing \f3M-p\f1 again
would recall the "ls ~/tecla/" line.

.SH HISTORY FILES

To save the contents of the history buffer before quitting your
application, and subsequently restore them when you next start the
application, the following functions are provided.

.sp
.nf
 int gl_save_history(GetLine *gl, const char *filename,
                     const char *comment, int max_lines);
 int gl_load_history(GetLine *gl, const char *filename,
                     const char *comment);
.fi
.sp

The \f3filename\f1 argument specifies the name to give the history
file when saving, or the name of an existing history file, when
loading. This may contain home-directory and environment variable
expressions, such as "~/.myapp_history" or "$HOME/.myapp_history".
.sp
Along with each history line, extra information about it, such as when
it was entered by the user, and what its nesting level is, is recorded
as a comment preceding the line in the history file. Writing this as a
comment allows the history file to double as a command file, just in
case you wish to replay a whole session using it. Since comment
prefixes differ in different languages, the \f3comment\f1 argument is
provided for specifying the comment prefix. For example, if your
application were a unix shell, such as the bourne shell, you would
specify "#" here. Whatever you choose for the comment character, you
must specify the same prefix to \f3gl_load_history()\f1 that you used
when you called \f3gl_save_history()\f1 to write the history file.
.sp
The \f3max_lines\f1 must be either -1 to specify that all lines in the
history list be saved, or a positive number specifying a ceiling on
how many of the most recent lines should be saved.
.sp
Both fuctions return non-zero on error, after writing an error message
to stderr. Note that \f3gl_load_history()\f1 does not consider the
non-existence of a file to be an error.

.SH MULTIPLE HISTORY LISTS

If your application uses a single \f3GetLine\f1 object for entering
many different types of input lines, you may wish \f3gl_get_line()\f1
to distinguish the different types of lines in the history list, and
only recall lines that match the current type of line. To support this
requirement, \f3gl_get_line()\f1 marks lines being recorded in the
history list with an integer identifier chosen by the application.
Initially this identifier is set