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.
tecla, teclarc - The user interface provided by the Tecla library. 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. In the rest of this man page, and also in all Tecla configuration files, key-sequences are expressed as follows.

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

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:

 edit-mode vi

This will re-configure the default bindings for vi-mode. The complete set of arguments that this command accepts are:

 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.

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:

 nobeep

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

 bind M-[2~ insert-mode

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.

 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 '~'.

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. 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. 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:

 bind up history-search-backwards
 bind down history-search-backwards

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:

 bind ^A

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. 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. 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. 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. 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. 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. 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. Note that in vi mode, all of the history recall functions switch the library into command mode. 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. Thus for example, suppose that you were in emacs mode, and you had just entered the following list of commands in the order shown:

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

If you next typed:

 ls

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:

 *tecla*

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. 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. 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,

 setlocale(LC_CTYPE, "");

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:

 locale -a

at the shell prompt. 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. 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,

 XTerm*EightBitInput: False

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. 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:

 xmodmap -e 'keycode 115 = Multi_key'

I can then enter an i with a umlaut over it by typing this key, followed by \f3"\f1, followed by i. 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.

 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.

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. This is the default editing mode of the Tecla library. 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.

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

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.

 ^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)

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. 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. 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. 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.

 ^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

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). The following are the terminal-independent key bindings for vi input mode.

 ^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

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.

 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)

Note that \f3^I\f1 is what the TAB key generates. 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. 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. For example, in emacs mode, typing:

 M-12a

causes the letter 'a' to be added to the line 12 times, whereas

 M-4M-c

Capitalizes the next 4 words. 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:

 4w2x

moves the cursor four words to the right, then deletes two characters. 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.

libtecla.a - The Tecla library
libtecla.h - The Tecla header file.
~/.teclarc - The personal Tecla customization file.

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@)

Martin Shepherd (mcs@astro.caltech.edu)