table of contents
- NAME
- DESCRIPTION
- KEY SEQUENCE NOTATION
- THE TECLA CONFIGURATION FILE
- FILENAME AND TILDE COMPLETION
- FILENAME EXPANSION
- RECALLING PREVIOUSLY TYPED LINES
- HISTORY FILES
- INTERNATIONAL CHARACTER SETS
- THE AVAILABLE KEY BINDING FUNCTIONS
- DEFAULT KEY BINDINGS IN EMACS MODE
- DEFAULT KEY BINDINGS IN VI MODE
- ENTERING REPEAT COUNTS
- FILES
- SEE ALSO
- AUTHOR
other versions
- wheezy 1.6.1-5
tecla(7) | Miscellaneous Information Manual | tecla(7) |
NAME¶
tecla, teclarc - The user interface provided by the Tecla library.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.KEY SEQUENCE NOTATION¶
In the rest of this man page, and also in all Tecla configuration files, key-sequences are expressed as follows.^A or C-a This is a control-A, entered by pressing the control key at the same time as the A key. \E or M- 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 M-p can be typed in two ways, by pressing the escape key, followed by pressing p, or by pressing the Meta key at the same time as p. up This refers to the up-arrow key. down This refers to the down-arrow key. left This refers to the left-arrow key. right This refers to the right-arrow key. a This is just a normal A key.
THE TECLA CONFIGURATION FILE¶
By default, Tecla looks for a file called .teclarc in your home directory (ie. ~/.teclarc). 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
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.
nobeep
bind M-[2~ insert-mode
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 '~'.
bind up history-search-backwards bind down history-search-backwards
bind ^A
FILENAME AND TILDE COMPLETION¶
With the default key bindings, pressing the TAB key (aka. ^I) 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.FILENAME EXPANSION¶
With the default key bindings, pressing ^X* causes Tecla to expand the filename that precedes the cursor, replacing ~/ and ~user/ expressions with the corresponding home directories, and replacing $envvar 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.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 ^P, and ^N 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.ls ~/tecla/ cd ~/tecla ls -l getline.c emacs ~/tecla/getline.c
ls
*tecla*
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.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,setlocale(LC_CTYPE, "");
locale -a
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 M-c 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 M-c can also be invoked by pressing the escape key momentarily, then pressing the c 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.XTerm*EightBitInput: Falseor by starting an xterm with an -xrm '*EightBitInput: False' command-line argument. In recent versions of xterm you can toggle this feature on and off with the "Meta Sends Escape" 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 Dtterm*KshMode resource to True.
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 xev 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'
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.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 nobeep 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.
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 tcsh shell, when it is in emacs editing mode.^C -> user-interrupt ^\ -> abort ^Z -> suspend ^Q -> start-output ^S -> stop-output ^V -> literal-next
right -> cursor-right
left -> cursor-left
up -> up-history
down -> down-history
^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)
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.^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
right -> cursor-right
left -> cursor-left
up -> up-history
down -> down-history
^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
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)
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.M-12a
M-4M-c
4w2x
FILES¶
libtecla.a - The Tecla library libtecla.h - The Tecla header file. ~/.teclarc - The personal Tecla customization file.
SEE ALSO¶
libtecla(3), gl_get_line(3), gl_io_mode(3), ef_expand_file(3), cpl_complete_word(3), pca_lookup_file(3)