diff options
Diffstat (limited to 'libtecla-1.6.3/man/misc/tecla.in')
| -rw-r--r-- | libtecla-1.6.3/man/misc/tecla.in | 1201 |
1 files changed, 1201 insertions, 0 deletions
diff --git a/libtecla-1.6.3/man/misc/tecla.in b/libtecla-1.6.3/man/misc/tecla.in new file mode 100644 index 0000000..567a810 --- /dev/null +++ b/libtecla-1.6.3/man/misc/tecla.in @@ -0,0 +1,1201 @@ +.\" 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) |