path: root/libtecla-1.6.3/man/misc/tecla.in

.\" Copyright (c) 2000, 2001, 2002, 2003, 2004, 2012 by Martin C. Shepherd
.\" 
.\" All rights reserved.
.\" 
.\" Permission is hereby granted, free of charge, to any person obtaining a
.\" copy of this software and associated documentation files (the
.\" "Software"), to deal in the Software without restriction, including
.\" without limitation the rights to use, copy, modify, merge, publish,
.\" distribute, and/or sell copies of the Software, and to permit persons
.\" to whom the Software is furnished to do so, provided that the above
.\" copyright notice(s) and this permission notice appear in all copies of
.\" the Software and that both the above copyright notice(s) and this
.\" permission notice appear in supporting documentation.
.\" 
.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
.\" OF THIRD PARTY RIGHTS. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
.\" HOLDERS INCLUDED IN THIS NOTICE BE LIABLE FOR ANY CLAIM, OR ANY SPECIAL
.\" INDIRECT OR CONSEQUENTIAL DAMAGES, OR ANY DAMAGES WHATSOEVER RESULTING
.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\" 
.\" Except as contained in this notice, the name of a copyright holder
.\" shall not be used in advertising or otherwise to promote the sale, use
.\" or other dealings in this Software without prior written authorization
.\" of the copyright holder.
.TH tecla @MISC_MANEXT@
.SH NAME
tecla, teclarc \- The user interface provided by the Tecla library.
.SH DESCRIPTION

This man page describes the command-line editing features that are
available to users of programs that read keyboard input via the Tecla
library. Users of the tcsh shell will find the default key-bindings
very familiar. Users of the bash shell will also find it quite
familiar, but with a few minor differences, most notably in how
forward and backward searches through the list of historical commands
are performed. There are two major editing modes, one with emacs-like
key-bindings and another with vi-like key-bindings. By default emacs
mode is enabled, but vi mode can alternatively be selected via the
user's configuration file. This file can also be used to change the
bindings of individual keys to suit the user's preferences. By
default, tab completion is provided. If the application hasn't
reconfigured this to complete other types of symbols, then tab
completion completes file-names.

.SH KEY SEQUENCE NOTATION

In the rest of this man page, and also in all Tecla configuration
files, key-sequences are expressed as follows.

.sp
.nf
\f3^A\f1  or  \f3C-a\f1
    This is a control-A, entered by pressing the control key at
    the same time as the \f3A\f1 key.

\f3\\E\f1    or   \f3M-\f1
    In key-sequences, both of these notations can be entered
    either by pressing the escape key, then the following key, or by
    pressing the Meta key at the same time as the following key. Thus
    the key sequence \f3M-p\f1 can be typed in two ways, by pressing
    the escape key, followed by pressing \f3p\f1, or by pressing the
    Meta key at the same time as \f3p\f1.

\f3up\f1
    This refers to the up-arrow key.

\f3down\f1
    This refers to the down-arrow key.

\f3left\f1
    This refers to the left-arrow key.

\f3right\f1
    This refers to the right-arrow key.

\f3a\f1
    This is just a normal A key.
.fi
.sp

.SH THE TECLA CONFIGURATION FILE

By default, Tecla looks for a file called \f3\&.teclarc\f1 in your
home directory (ie. \f3~/.teclarc\f1).  If it finds this file, it
reads it, interpreting each line as defining a new key binding or an
editing configuration option. Since the emacs keybindings are
installed by default, if you want to use the non-default vi editing
mode, the most important item to go in this file is the following
line:

.nf
  edit-mode vi
.fi

This will re-configure the default bindings for vi-mode. The
complete set of arguments that this command accepts are:
.sp
.nf
  vi     -  Install key-bindings like those of the vi
            editor.
  emacs  -  Install key-bindings like those of the emacs
            editor. This is the default.
  none   -  Use just the native line editing facilities
            provided by the terminal driver.
.fi
.sp
To prevent the terminal bell from being rung, such as when
an unrecognized control-sequence is typed, place the
following line in the configuration file:

.nf
  nobeep
.fi

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

If you create a \f3~/.teclarc\f1 configuration file, but it appears to
have no effect on the program, check the documentation of the program
to see if the author chose a different name for this file.

.SH FILENAME AND TILDE COMPLETION

With the default key bindings, pressing the TAB key (aka. \f3^I\f1)
results in Tecla attempting to complete the incomplete filename that
precedes the cursor. Tecla 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,
then Tecla 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, Tecla 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, Tecla
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_complete_word(@LIBR_MANEXT@)\f1 man page for more details.

.SH FILENAME EXPANSION

With the default key bindings, pressing \f3^X*\f1 causes Tecla 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(@LIBR_MANEXT@)\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", Tecla
would recall the "ls -l getline.c" line. Pressing \f3M-p\f1 again
would recall the "ls ~/tecla/" line.

Note that if the string that you are searching for, contains any of
the special characters, *, ?, or '[', then it is interpretted as a
pattern to be matched. Thus, cotinuing with the above example, after
typing in the list of commands shown, if you then typed:

.nf
  *tecla*
.fi

and hit \f3M-p\f1, then the "emacs ~/tecla/getline.c" line would be
recalled first, since it contains the word tecla somewhere in the
line, Similarly, hitting \f3M-p\f1 again, would recall the "ls
~/tecla/" line, and hitting it once more would recall the "ls
~/tecla/" line. The pattern syntax is the same as that described for
filename expansion, in the \f3ef_expand_file(@LIBR_MANEXT@\f1 man
page.

.SH HISTORY FILES

Authors of programs that use the Tecla library have the option of
saving historical command-lines in a file before exiting, and
subsequently reading them back in from this file when the program is
next started. There is no standard name for this file, since it makes
sense for each application to use its own history file, so that
commands from different applications don't get mixed up.

.SH INTERNATIONAL CHARACTER SETS

Since libtecla version 1.4.0, Tecla has been 8-bit clean. This means
that all 8-bit characters that are printable in the user's current
locale are now displayed verbatim and included in the returned input
line.  Assuming that the calling program correctly contains a call
like the following,
.sp
.nf
  setlocale(LC_CTYPE, "");
.fi
.sp
then the current locale is determined by the first of the environment
variables \f3LC_CTYPE\f1, \f3LC_ALL\f1, and \f3LANG\f1, that is found
to contain a valid locale name. If none of these variables are
defined, or the program neglects to call setlocale, then the default
\f3C\f1 locale is used, which is US 7-bit ASCII. On most unix-like
platforms, you can get a list of valid locales by typing the command:
.sp
.nf
  locale -a
.fi
.sp
at the shell prompt.
.sp
.SS "Meta keys and locales"

Beware that in most locales other than the default C locale, meta
characters become printable, and they are then no longer considered to
match \f3M-c\f1 style key bindings. This allows international
characters to be entered with the compose key without unexpectedly
triggering meta key bindings. You can still invoke meta bindings,
since there are actually two ways to do this. For example the binding
\f3M-c\f1 can also be invoked by pressing the escape key momentarily,
then pressing the \f3c\f1 key, and this will work regardless of
locale. Moreover, many modern terminal emulators, such as gnome's
gnome-terminal's and KDE's konsole terminals, already generate escape
pairs like this when you use the meta key, rather than a real meta
character, and other emulators usually have a way to request this
behavior, so you can continue to use the meta key on most systems.
.sp
For example, although xterm terminal emulators generate real 8-bit
meta characters by default when you use the meta key, they can be
configured to output the equivalent escape pair by setting their
\f3EightBitInput\f1 X resource to \f3False\f1. You can either do this
by placing a line like the following in your \f3~/.Xdefaults\f1 file,
.sp
.nf
  XTerm*EightBitInput: False
.sp
.fi
or by starting an xterm with an \f3-xrm '*EightBitInput: False'\f1
command-line argument. In recent versions of xterm you can toggle this
feature on and off with the \f3"Meta Sends Escape"\f1 option in the
menu that is displayed when you press the left mouse button and the
control key within an xterm window. In CDE, dtterms can be similarly
coerced to generate escape pairs in place of meta characters, by
setting the \f3Dtterm*KshMode\f1 resource to \f3True\f1.
.sp
.SS "Entering international characters"

If you don't have a keyboard that generates all of the
international characters that you need, there is usually a
compose key that will allow you to enter special characters,
or a way to create one. For example, under X windows on
unix-like systems, if your keyboard doesn't have a compose
key, you can designate a redundant key to serve this purpose
with the xmodmap command. For example, on many PC keyboards
there is a microsoft-windows key, which is otherwise useless
under Linux. On my laptop the \f3xev\f1 program reports that
pressing this key generates keycode 115, so to turn this key
into a compose key, I do the following:
.sp
.nf
  xmodmap -e 'keycode 115 = Multi_key'
.fi
.sp
I can then enter an i with a umlaut over it by typing this key,
followed by \f3"\f1, followed by i.

.SH THE AVAILABLE KEY BINDING FUNCTIONS

The following is a list of the editing functions provided by the Tecla
library. The names in the leftmost column of the list can be used in
configuration files to specify which function a given key or
combination of keys should invoke. They are also used in the next two
sections to list the default key-bindings in emacs and vi modes.

.nf
  user-interrupt           -  Send a SIGINT signal to the
                              parent process.
  abort                    -  Send a SIGABRT signal to the
                              parent process.
  suspend                  -  Suspend the parent process.
  stop-output              -  Pause terminal output.
  start-output             -  Resume paused terminal output.
  literal-next             -  Arrange for the next character
                              to be treated as a normal
                              character. This allows control
                              characters to be entered.
  cursor-right             -  Move the cursor one character
                              right.
  cursor-left              -  Move the cursor one character
                              left.
  insert-mode              -  Toggle between insert mode and
                              overwrite mode.
  beginning-of-line        -  Move the cursor to the
                              beginning of the line.
  end-of-line              -  Move the cursor to the end of
                              the line.
  delete-line              -  Delete the contents of the
                              current line.
  kill-line                -  Delete everything that follows
                              the cursor.
  backward-kill-line       -  Delete all characters between
                              the cursor and the start of the
                              line.
  forward-word             -  Move to the end of the word
                              which follows the cursor.
  forward-to-word          -  Move the cursor to the start of
                              the word that follows the
                              cursor.
  backward-word            -  Move to the start of the word
                              which precedes the cursor.
  goto-column              -  Move the cursor to the
                              1-relative column in the line
                              specified by any preceding
                              digit-argument sequences (see
                              ENTERING REPEAT COUNTS below).
  find-parenthesis         -  If the cursor is currently
                              over a parenthesis character,
                              move it to the matching
                              parenthesis character. If not
                              over a parenthesis character
                              move right to the next close
                              parenthesis.
  forward-delete-char      -  Delete the character under the
                              cursor.
  backward-delete-char     -  Delete the character which
                              precedes the cursor.
  list-or-eof              -  This is intended for binding
                              to ^D. When invoked when the
                              cursor is within the line it
                              displays all possible
                              completions then redisplays
                              the line unchanged. When
                              invoked on an empty line, it
                              signals end-of-input (EOF) to
                              the caller of gl_get_line().
  del-char-or-list-or-eof  -  This is intended for binding
                              to ^D. When invoked when the
                              cursor is within the line it
                              invokes forward-delete-char.
                              When invoked at the end of the
                              line it displays all possible
                              completions then redisplays
                              the line unchanged. When
                              invoked on an empty line, it
                              signals end-of-input (EOF) to
                              the caller of gl_get_line().
  forward-delete-word      -  Delete the word which follows
                              the cursor.
  backward-delete-word     -  Delete the word which precedes
                              the cursor.
  upcase-word              -  Convert all of the characters
                              of the word which follows the
                              cursor, to upper case.
  downcase-word            -  Convert all of the characters
                              of the word which follows the
                              cursor, to lower case.
  capitalize-word          -  Capitalize the word which
                              follows the cursor.
  change-case              -  If the next character is upper
                              case, toggle it to lower case
                              and vice versa.
  redisplay                -  Redisplay the line.
  clear-screen             -  Clear the terminal, then
                              redisplay the current line.
  transpose-chars          -  Swap the character under the
                              cursor with the character just
                              before the cursor.
  set-mark                 -  Set a mark at the position of
                              the cursor.
  exchange-point-and-mark  -  Move the cursor to the last
                              mark that was set, and move
                              the mark to where the cursor
                              used to be.
  kill-region              -  Delete the characters that lie
                              between the last mark that was
                              set, and the cursor.
  copy-region-as-kill      -  Copy the text between the mark
                              and the cursor to the cut
                              buffer, without deleting the
                              original text.
  yank                     -  Insert the text that was last
                              deleted, just before the
                              current position of the cursor.
  append-yank              -  Paste the current contents of
                              the cut buffer, after the
                              cursor.
  up-history               -  Recall the next oldest line
                              that was entered. Note that
                              in vi mode you are left in
                              command mode.
  down-history             -  Recall the next most recent
                              line that was entered. If no
                              history recall session is
                              currently active, the next
                              line from a previous recall
                              session is recalled. Note that
                              in vi mode you are left in
                              command mode.
  history-search-backward  -  Recall the next oldest line
                              who's prefix matches the string
                              which currently precedes the
                              cursor (in vi command-mode the
                              character under the cursor is
                              also included in the search
                              string).  Note that in vi mode
                              you are left in command mode.
  history-search-forward   -  Recall the next newest line
                              who's prefix matches the string
                              which currently precedes the
                              cursor (in vi command-mode the
                              character under the cursor is
                              also included in the search
                              string).  Note that in vi mode
                              you are left in command mode.
  history-re-search-backward -Recall the next oldest line
                              who's prefix matches that
                              established by the last
                              invocation of either
                              history-search-forward or
                              history-search-backward.
  history-re-search-forward - Recall the next newest line
                              who's prefix matches that
                              established by the last
                              invocation of either
                              history-search-forward or
                              history-search-backward.
  complete-word            -  Attempt to complete the
                              incomplete word which
                              precedes the cursor. Unless
                              the host program has customized
                              word completion, filename
                              completion is attempted. In vi
                              commmand mode the character
                              under the cursor is also
                              included in the word being
                              completed, and you are left in
                              vi insert mode.
  expand-filename          -  Within the command line, expand
                              wild cards, tilde expressions
                              and dollar expressions in the
                              filename which immediately
                              precedes the cursor. In vi
                              commmand mode the character
                              under the cursor is also
                              included in the filename being
                              expanded, and you are left in
                              vi insert mode.
  list-glob                -  List any filenames which match
                              the wild-card, tilde and dollar
                              expressions in the filename
                              which immediately precedes the
                              cursor, then redraw the input
                              line unchanged.
  list-history             -  Display the contents of the
                              history list for the current
                              history group. If a repeat
                              count of > 1 is specified,
                              only that many of the most
                              recent lines are displayed.
                              See the "ENTERING REPEAT
                              COUNTS" section.
  read-from-file           -  Temporarily switch to reading
                              input from the file who's
                              name precedes the cursor.
  read-init-files          -  Re-read teclarc configuration
                              files.
  beginning-of-history     -  Move to the oldest line in the
                              history list. Note that in vi
                              mode you are left in command
                              mode.
  end-of-history           -  Move to the newest line in the
                              history list (ie. the current
                              line). Note that in vi mode
                              this leaves you in command
                              mode.
  digit-argument           -  Enter a repeat count for the
                              next key-binding function.
                              For details, see the ENTERING
                              REPEAT COUNTS section.
  newline                  -  Terminate and return the
                              current contents of the
                              line, after appending a
                              newline character. The newline
                              character is normally '\\n',
                              but will be the first
                              character of the key-sequence
                              that invoked the newline
                              action, if this happens to be
                              a printable character. If the
                              action was invoked by the
                              '\\n' newline character or the
                              '\\r' carriage return
                              character, the line is
                              appended to the history
                              buffer.
  repeat-history           -  Return the line that is being
                              edited, then arrange for the
                              next most recent entry in the
                              history buffer to be recalled
                              when Tecla is next called.
                              Repeatedly invoking this
                              action causes successive
                              historical input lines to be
                              re-executed. Note that this
                              action is equivalent to the
                              'Operate' action in ksh.
  ring-bell                -  Ring the terminal bell, unless
                              the bell has been silenced via
                              the \f3nobeep\f1 configuration
                              option (see the THE TECLA
                              CONFIGURATION FILE section).
  forward-copy-char        -  Copy the next character into
                              the cut buffer (NB. use repeat
                              counts to copy more than one).
  backward-copy-char       -  Copy the previous character
                              into the cut buffer.
  forward-copy-word        -  Copy the next word into the cut
                              buffer.
  backward-copy-word       -  Copy the previous word into the
                              cut buffer.
  forward-find-char        -  Move the cursor to the next
                              occurrence of the next
                              character that you type.
  backward-find-char       -  Move the cursor to the last
                              occurrence of the next
                              character that you type.
  forward-to-char          -  Move the cursor to the
                              character just before the next
                              occurrence of the next
                              character that the user types.
  backward-to-char         -  Move the cursor to the
                              character just after the last
                              occurrence before the cursor
                              of the next character that the
                              user types.
  repeat-find-char         -  Repeat the last
                              backward-find-char,
                              forward-find-char,
                              backward-to-char or
                              forward-to-char.
  invert-refind-char       -  Repeat the last
                              backward-find-char,
                              forward-find-char,
                              backward-to-char, or
                              forward-to-char in the
                              opposite direction.
  delete-to-column         -  Delete the characters from the
                              cursor up to the column that
                              is specified by the repeat
                              count.
  delete-to-parenthesis    -  Delete the characters from the
                              cursor up to and including
                              the matching parenthesis, or
                              next close parenthesis.
  forward-delete-find      -  Delete the characters from the
                              cursor up to and including the
                              following occurence of the
                              next character typed.
  backward-delete-find     -  Delete the characters from the
                              cursor up to and including the
                              preceding occurence of the
                              next character typed.
  forward-delete-to        -  Delete the characters from the
                              cursor up to, but not
                              including, the following
                              occurence of the next
                              character typed.
  backward-delete-to       -  Delete the characters from the
                              cursor up to, but not
                              including, the preceding
                              occurence of the next
                              character typed.
  delete-refind            -  Repeat the last *-delete-find
                              or *-delete-to action.
  delete-invert-refind     -  Repeat the last *-delete-find
                              or *-delete-to action, in the
                              opposite direction.
  copy-to-column           -  Copy the characters from the
                              cursor up to the column that
                              is specified by the repeat
                              count, into the cut buffer.
  copy-to-parenthesis      -  Copy the characters from the
                              cursor up to and including
                              the matching parenthesis, or
                              next close parenthesis, into
                              the cut buffer.
  forward-copy-find        -  Copy the characters from the
                              cursor up to and including the
                              following occurence of the
                              next character typed, into the
                              cut buffer.
  backward-copy-find       -  Copy the characters from the
                              cursor up to and including the
                              preceding occurence of the
                              next character typed, into the
                              cut buffer.
  forward-copy-to          -  Copy the characters from the
                              cursor up to, but not
                              including, the following
                              occurence of the next
                              character typed, into the cut
                              buffer.
  backward-copy-to         -  Copy the characters from the
                              cursor up to, but not
                              including, the preceding
                              occurence of the next
                              character typed, into the cut
                              buffer.
  copy-refind              -  Repeat the last *-copy-find
                              or *-copy-to action.
  copy-invert-refind       -  Repeat the last *-copy-find
                              or *-copy-to action, in the
                              opposite direction.
  vi-mode                  -  Switch to vi mode from emacs
                              mode.
  emacs-mode               -  Switch to emacs mode from vi
                              mode.
  vi-insert                -  From vi command mode, switch to
                              insert mode.
  vi-overwrite             -  From vi command mode, switch to
                              overwrite mode.
  vi-insert-at-bol         -  From vi command mode, move the
                              cursor to the start of the line
                              and switch to insert mode.
  vi-append-at-eol         -  From vi command mode, move the
                              cursor to the end of the line
                              and switch to append mode.
  vi-append                -  From vi command mode, move the
                              cursor one position right, and
                              switch to insert mode.
  vi-replace-char          -  From vi command mode, replace
                              the character under the cursor
                              with the the next character
                              entered.
  vi-forward-change-char   -  From vi command mode, delete
                              the next character then enter
                              insert mode.
  vi-backward-change-char  -  From vi command mode, delete
                              the preceding character then
                              enter insert mode.
  vi-forward-change-word   -  From vi command mode, delete
                              the next word then enter
                              insert mode.
  vi-backward-change-word  -  From vi command mode, delete
                              the preceding word then
                              enter insert mode.
  vi-change-rest-of-line   -  From vi command mode, delete
                              from the cursor to the end of
                              the line, then enter insert
                              mode.
  vi-change-line           -  From vi command mode, delete
                              the current line, then enter
                              insert mode.
  vi-change-to-bol         -  From vi command mode, delete
                              all characters between the
                              cursor and the beginning of
                              the line, then enter insert
                              mode.
  vi-change-to-column      -  From vi command mode, delete
                              the characters from the cursor
                              up to the column that is
                              specified by the repeat count,
                              then enter insert mode.
  vi-change-to-parenthesis -  Delete the characters from the
                              cursor up to and including
                              the matching parenthesis, or
                              next close parenthesis, then
                              enter vi insert mode.
  vi-forward-change-find   -  From vi command mode, delete
                              the characters from the
                              cursor up to and including the
                              following occurence of the
                              next character typed, then
                              enter insert mode.
  vi-backward-change-find  -  From vi command mode, delete
                              the characters from the
                              cursor up to and including the
                              preceding occurence of the
                              next character typed, then
                              enter insert mode.
  vi-forward-change-to     -  From vi command mode, delete
                              the characters from the
                              cursor up to, but not
                              including, the following
                              occurence of the next
                              character typed, then enter
                              insert mode.
  vi-backward-change-to    -  From vi command mode, delete
                              the characters from the
                              cursor up to, but not
                              including, the preceding
                              occurence of the next
                              character typed, then enter
                              insert mode.
  vi-change-refind         -  Repeat the last
                              vi-*-change-find or
                              vi-*-change-to action.
  vi-change-invert-refind  -  Repeat the last
                              vi-*-change-find or
                              vi-*-change-to action, in the
                              opposite direction.
  vi-undo                  -  In vi mode, undo the last
                              editing operation.
  vi-repeat-change         -  In vi command mode, repeat the
                              last command that modified the
                              line.
.fi

.SH DEFAULT KEY BINDINGS IN EMACS MODE

The following default key bindings, which can be overriden by
the Tecla configuration file, are designed to mimic most of
the bindings of the unix \f3tcsh\f1 shell, when it is in
emacs editing mode.
.sp
This is the default editing mode of the Tecla library.
.sp
Under UNIX the terminal driver sets a number of special keys for certain
functions. The tecla library attempts to use the same keybindings to maintain
consistency. The key sequences shown for the following 6 bindings are thus just
examples of what they will probably be set to. If you have used the \f3stty\f1
command to change these keys, then the default bindings should match.

.nf
  ^C     ->   user-interrupt
  ^\\     ->   abort
  ^Z     ->   suspend
  ^Q     ->   start-output
  ^S     ->   stop-output
  ^V     ->   literal-next
.fi

The cursor keys are refered to by name, as follows. This is necessary
because different types of terminals generate different key sequences
when their cursor keys are pressed.

  right  ->   cursor-right
  left   ->   cursor-left
  up     ->   up-history
  down   ->   down-history

The remaining bindings don't depend on the terminal setttings.

.nf
  ^F     ->   cursor-right
  ^B     ->   cursor-left
  M-i    ->   insert-mode
  ^A     ->   beginning-of-line
  ^E     ->   end-of-line
  ^U     ->   delete-line
  ^K     ->   kill-line
  M-f    ->   forward-word
  M-b    ->   backward-word
  ^D     ->   del-char-or-list-or-eof
  ^H     ->   backward-delete-char
  ^?     ->   backward-delete-char
  M-d    ->   forward-delete-word
  M-^H   ->   backward-delete-word
  M-^?   ->   backward-delete-word
  M-u    ->   upcase-word
  M-l    ->   downcase-word
  M-c    ->   capitalize-word
  ^R     ->   redisplay
  ^L     ->   clear-screen
  ^T     ->   transpose-chars
  ^@     ->   set-mark
  ^X^X   ->   exchange-point-and-mark
  ^W     ->   kill-region
  M-w    ->   copy-region-as-kill
  ^Y     ->   yank
  ^P     ->   up-history
  ^N     ->   down-history
  M-p    ->   history-search-backward
  M-n    ->   history-search-forward
  ^I     ->   complete-word
  ^X*    ->   expand-filename
  ^X^F   ->   read-from-file
  ^X^R   ->   read-init-files
  ^Xg    ->   list-glob
  ^Xh    ->   list-history
  M-<    ->   beginning-of-history
  M->    ->   end-of-history
  \\n     ->   newline
  \\r     ->   newline
  M-o    ->   repeat-history
  M-^V   ->   vi-mode

  M-0, M-1, ... M-9  ->  digit-argument  (see below)
.fi

Note that \f3^I\f1 is what the TAB key generates, and that \f3^@\f1
can be generated not only by pressing the control key and the \f3@\f1
key simultaneously, but also by pressing the control key and the space
bar at the same time.

.SH DEFAULT KEY BINDINGS IN VI MODE

The following default key bindings are designed to mimic the
vi style of editing as closely as possible. This means that
very few editing functions are provided in the initial
character input mode, editing functions instead being
provided by the vi command mode. Vi command mode is entered
whenever the escape character is pressed, or whenever a
key-sequence that starts with a meta character is entered. In
addition to mimicing vi, libtecla provides bindings for tab
completion, wild-card expansion of file names, and historical
line recall.
.sp
To learn how to tell the Tecla library to use vi mode instead
of the default emacs editing mode, see the earlier section entitled
THE TECLA CONFIGURATION FILE.
.sp
Under UNIX the terminal driver sets a number of special keys
for certain functions. The Tecla library attempts to use the
same keybindings to maintain consistency, binding them both
in input mode and in command mode. The key sequences shown
for the following 6 bindings are thus just examples of what
they will probably be set to. If you have used the \f3stty\f1
command to change these keys, then the default bindings
should match.

.nf
  ^C     ->   user-interrupt
  ^\\     ->   abort
  ^Z     ->   suspend
  ^Q     ->   start-output
  ^S     ->   stop-output
  ^V     ->   literal-next
  M-^C   ->   user-interrupt
  M-^\\   ->   abort
  M-^Z   ->   suspend
  M-^Q   ->   start-output
  M-^S   ->   stop-output
.fi

Note that above, most of the bindings are defined twice, once
as a raw control code like \f3^C\f1 and then a second time as
a meta character like \f3M-^C\f1. The former is the binding
for vi input mode, whereas the latter is the binding for vi
command mode. Once in command mode all key-sequences that the
user types that they don't explicitly start with an escape or
a meta key, have their first key secretly converted to a meta
character before the key sequence is looked up in the key
binding table. Thus, once in command mode, when you type the
letter \f3i\f1, for example, the Tecla library actually looks
up the binding for \f3M-i\f1.

The cursor keys are refered to by name, as follows. This is necessary
because different types of terminals generate different key sequences
when their cursor keys are pressed.

  right  ->   cursor-right
  left   ->   cursor-left
  up     ->   up-history
  down   ->   down-history

The cursor keys normally generate a keysequence that start
with an escape character, so beware that using the arrow keys
will put you into command mode (if you aren't already in
command mode).
.sp
The following are the terminal-independent key bindings for vi input
mode.

.nf
  ^D     ->   list-or-eof
  ^G     ->   list-glob
  ^H     ->   backward-delete-char
  ^I     ->   complete-word
  \\r     ->   newline
  \\n     ->   newline
  ^L     ->   clear-screen
  ^N     ->   down-history
  ^P     ->   up-history
  ^R     ->   redisplay
  ^U     ->   backward-kill-line
  ^W     ->   backward-delete-word
  ^X*    ->   expand-filename
  ^X^F   ->   read-from-file
  ^X^R   ->   read-init-files
  ^?     ->   backward-delete-char
.fi

The following are the key bindings that are defined in vi
command mode, this being specified by them all starting with
a meta character. As mentioned above, once in command mode
the initial meta character is optional. For example, you
might enter command mode by typing Esc, and then press h
twice to move the cursor two positions to the left. Both h
characters get quietly converted to M-h before being compared
to the key-binding table, the first one because Escape
followed by a character is always converted to the equivalent
meta character, and the second because command mode was
already active.

.nf
  M-\\     ->   cursor-right     (Meta-space)
  M-$     ->   end-of-line
  M-*     ->   expand-filename
  M-+     ->   down-history
  M--     ->   up-history
  M-<     ->   beginning-of-history
  M->     ->   end-of-history
  M-^     ->   beginning-of-line
  M-;     ->   repeat-find-char
  M-,     ->   invert-refind-char
  M-|     ->   goto-column
  M-~     ->   change-case
  M-.     ->   vi-repeat-change
  M-%     ->   find-parenthesis
  M-a     ->   vi-append
  M-A     ->   vi-append-at-eol
  M-b     ->   backward-word
  M-B     ->   backward-word
  M-C     ->   vi-change-rest-of-line
  M-cb    ->   vi-backward-change-word
  M-cB    ->   vi-backward-change-word
  M-cc    ->   vi-change-line
  M-ce    ->   vi-forward-change-word
  M-cE    ->   vi-forward-change-word
  M-cw    ->   vi-forward-change-word
  M-cW    ->   vi-forward-change-word
  M-cF    ->   vi-backward-change-find
  M-cf    ->   vi-forward-change-find
  M-cT    ->   vi-backward-change-to
  M-ct    ->   vi-forward-change-to
  M-c;    ->   vi-change-refind
  M-c,    ->   vi-change-invert-refind
  M-ch    ->   vi-backward-change-char
  M-c^H   ->   vi-backward-change-char
  M-c^?   ->   vi-backward-change-char
  M-cl    ->   vi-forward-change-char
  M-c\\    ->   vi-forward-change-char  (Meta-c-space)
  M-c^    ->   vi-change-to-bol
  M-c0    ->   vi-change-to-bol
  M-c$    ->   vi-change-rest-of-line
  M-c|    ->   vi-change-to-column
  M-c%    ->   vi-change-to-parenthesis
  M-dh    ->   backward-delete-char
  M-d^H   ->   backward-delete-char
  M-d^?   ->   backward-delete-char
  M-dl    ->   forward-delete-char
  M-d     ->   forward-delete-char    (Meta-d-space)
  M-dd    ->   delete-line
  M-db    ->   backward-delete-word
  M-dB    ->   backward-delete-word
  M-de    ->   forward-delete-word
  M-dE    ->   forward-delete-word
  M-dw    ->   forward-delete-word
  M-dW    ->   forward-delete-word
  M-dF    ->   backward-delete-find
  M-df    ->   forward-delete-find
  M-dT    ->   backward-delete-to
  M-dt    ->   forward-delete-to
  M-d;    ->   delete-refind
  M-d,    ->   delete-invert-refind
  M-d^    ->   backward-kill-line
  M-d0    ->   backward-kill-line
  M-d$    ->   kill-line
  M-D     ->   kill-line
  M-d|    ->   delete-to-column
  M-d%    ->   delete-to-parenthesis
  M-e     ->   forward-word
  M-E     ->   forward-word
  M-f     ->   forward-find-char
  M-F     ->   backward-find-char
  M--     ->   up-history
  M-h     ->   cursor-left
  M-H     ->   beginning-of-history
  M-i     ->   vi-insert
  M-I     ->   vi-insert-at-bol
  M-j     ->   down-history
  M-J     ->   history-search-forward
  M-k     ->   up-history
  M-K     ->   history-search-backward
  M-l     ->   cursor-right
  M-L     ->   end-of-history
  M-n     ->   history-re-search-forward
  M-N     ->   history-re-search-backward
  M-p     ->   append-yank
  M-P     ->   yank
  M-r     ->   vi-replace-char
  M-R     ->   vi-overwrite
  M-s     ->   vi-forward-change-char
  M-S     ->   vi-change-line
  M-t     ->   forward-to-char
  M-T     ->   backward-to-char
  M-u     ->   vi-undo
  M-w     ->   forward-to-word
  M-W     ->   forward-to-word
  M-x     ->   forward-delete-char
  M-X     ->   backward-delete-char
  M-yh    ->   backward-copy-char
  M-y^H   ->   backward-copy-char
  M-y^?   ->   backward-copy-char
  M-yl    ->   forward-copy-char
  M-y\\    ->   forward-copy-char  (Meta-y-space)
  M-ye    ->   forward-copy-word
  M-yE    ->   forward-copy-word
  M-yw    ->   forward-copy-word
  M-yW    ->   forward-copy-word
  M-yb    ->   backward-copy-word
  M-yB    ->   backward-copy-word
  M-yf    ->   forward-copy-find
  M-yF    ->   backward-copy-find
  M-yt    ->   forward-copy-to
  M-yT    ->   backward-copy-to
  M-y;    ->   copy-refind
  M-y,    ->   copy-invert-refind
  M-y^    ->   copy-to-bol
  M-y0    ->   copy-to-bol
  M-y$    ->   copy-rest-of-line
  M-yy    ->   copy-line
  M-Y     ->   copy-line
  M-y|    ->   copy-to-column
  M-y%    ->   copy-to-parenthesis
  M-^E    ->   emacs-mode
  M-^H    ->   cursor-left
  M-^?    ->   cursor-left
  M-^L    ->   clear-screen
  M-^N    ->   down-history
  M-^P    ->   up-history
  M-^R    ->   redisplay
  M-^D    ->   list-or-eof
  M-^I    ->   complete-word
  M-\\r    ->   newline
  M-\\n    ->   newline
  M-^X^R  ->   read-init-files
  M-^Xh   ->   list-history

  M-0, M-1, ... M-9  ->  digit-argument  (see below)
.fi

Note that \f3^I\f1 is what the TAB key generates.

.SH ENTERING REPEAT COUNTS

Many of the key binding functions described previously, take an
optional count, typed in before the target keysequence.  This is
interpreted as a repeat count by most bindings. A notable exception is
the goto-column binding, which interprets the count as a column
number.
.sp
By default you can specify this count argument by pressing the meta
key while typing in the numeric count. This relies on the
\f3digit-argument\f1 action being bound to Meta-0, Meta-1 etc.  Once
any one of these bindings has been activated, you can optionally take
your finger off the meta key to type in the rest of the number, since
every numeric digit thereafter is treated as part of the number,
unless it is preceded by the \f3literal-next\f1 binding. As soon as a
non-digit, or literal digit key is pressed the repeat count is
terminated and either causes the just typed character to be added to
the line that many times, or causes the next key-binding function to
be given that argument.
.sp
For example, in emacs mode, typing:
.sp
.nf
  M-12a
.fi
.sp
causes the letter 'a' to be added to the line 12 times,
whereas
.sp
.nf
  M-4M-c
.fi
.sp
Capitalizes the next 4 words.
.sp
In vi command mode the Meta modifier is automatically added to all
characters typed in, so to enter a count in vi command-mode, just
involves typing in the number, just as it does in the vi editor
itself. So for example, in vi command mode, typing:
.sp
.nf
  4w2x
.fi
.sp
moves the cursor four words to the right, then deletes two characters.
.sp
You can also bind \f3digit-argument\f1 to other key sequences. If
these end in a numeric digit, that digit gets appended to the current
repeat count. If it doesn't end in a numeric digit, a new repeat count
is started with a value of zero, and can be completed by typing in the
number, after letting go of the key which triggered the digit-argument
action.

.SH FILES
.nf
libtecla.a      -    The Tecla library
libtecla.h      -    The Tecla header file.
~/.teclarc      -    The personal Tecla customization file.
.fi

.SH SEE ALSO

.nf
libtecla(@LIBR_MANEXT@), gl_get_line(@LIBR_MANEXT@), gl_io_mode(@LIBR_MANEXT@), ef_expand_file(@LIBR_MANEXT@),
cpl_complete_word(@LIBR_MANEXT@), pca_lookup_file(@LIBR_MANEXT@)
.fi
  
.SH AUTHOR
Martin Shepherd  (mcs@astro.caltech.edu)