Customization can be done in 2 ways.
(require 'viper) line. This method is not recommended, unless you
are know what you are doing.Emacs customization is done in Emacs Lisp. For the common cases, examples are provided that you can use directly.
An easy way to customize Viper is to change the values of constants used in
Viper. Here is the list of the constants used in Viper and their default
values. The corresponding :se command is also indicated. (The symbols
t and nil represent "true" and "false" in Lisp).
Viper supports both the abbreviated Vi variable names and their full names. Variable completion is done on full names only. TAB and SPC complete variable names. Typing `=' will complete the name and then will prompt for a value, if applicable. For instance, :se auSPC will complete the command to :set autoindent; :se taSPC will complete the command and prompt further like this: :set tabstop = . However, typing :se tsSPC will produce a "No match" message because ts is an abbreviation for tabstop and Viper supports completion on full names only. However, you can still hit RET or =, which will complete the command like this: :set ts = and Viper will be waiting for you to type a value for the tabstop variable. To get the full list of Vi variables, type :se SPC TAB.
vip-auto-indent nil
:se ai (:se autoindent)
t then enable auto indentation.
by o or O command.
vip-case-fold-search nil
:se ic (:se ignorecase)
t search ignores cases.
vip-re-search nil
:se magic
t then search is reg-exp search, if nil then vanilla
search.
buffer-read-only
:se ro (:se readonly)
(setq-default buffer-read-only t) in your `.emacs' file.
blink-matching-paren t
:se sm (:se showmatch)
tab-width t (default setting, via setq-default)
:se ts=value (:se tabstop=value)
indent-for-tab-command (which facilitates
programming and document writing). Instead, the tab is inserted via the
command vip-insert-tab, which is bound to S-tab (shift + tab).
On some non-windowing terminals, Shift doesn't modify the TAB key, so
S-tab behaves as if it were TAB. In such a case, you will have
to bind vip-insert-tab to some other convenient key.
tab-width t (local setting via setq)
:se tab-stop-local=value
tab-width is set only for the current
buffer; it will have no effect on other buffers.
vip-shift-width 8
:se sw=value (:se shiftwidth=value)
vip-search-wrap-around t
:se ws (:se wrapscan)
t, search wraps around the end/beginning of buffer.
vip-tags-file-name "TAGS"
vip-re-query-replace nil
t, use reg-exp replace in query replace.
vip-want-ctl-h-help nil
t, C-h is bound to help-command;
if nil, it is bound to delete-backward-char.
vip-vi-style-in-minibuffer t
t, Viper provides a high degree of compatibility with Vi insert mode
when you type text in the Minibuffer; if nil, typing in the
Minibuffer feels like plain Emacs.
vip-no-multiple-ESC t
nil, you can use ESC as Meta in Vi state.
Normally, this is not necessary, since graphical displays have separate
Meta keys (usually on each side of the space bar). On a dumb terminal, Viper
sets this variable to twice, which is almost like nil, except
that double ESC beeps. This, too, lets ESC to be used as a Meta.
vip-keysequence-delay 140
vip-ex-style-motion t
nil, if you want l,h to cross
lines, etc. See section Movement and Markers, for more info.
vip-ex-style-editing-in-insert t
nil, if you want ESC to not move back and
C-h to not stop
at the beginning of a line in Insert state.
vip-always t
vip-custom-file-name "~/.vip"
vip-spell-function 'ispell-region
ex-find-file-shell "csh"
ex-cycle-other-window t
t, :n and :b will cycle through files in another
window, if one exists.
ex-cycle-through-non-files nil
vip-automatic-iso-accents nil
text-mode-hook is enough).
vip-want-emacs-keys-in-insert
nil for user levels 1 and 2 and to t for user
levels 3 and 4. Users who specify level 5 are allowed to set this variable
as they please (the default for this level is t). If set to
nil, complete Vi compatibility is provided in Insert state. This is
really not recommended, as this precludes you from using language-specific
features provided by the major modes.
vip-want-emacs-keys-in-vi
nil for user
level 1 and to t for user levels 2--4.
At level 5, users are allowed to set this variable as they please (the
default for this level is t).
If set to nil, complete Vi compatibility is provided
in Vi command state. Setting this to nil is really a bad idea,
unless you are a novice, as this precludes the use
of language-specific features provided by the major modes.
vip-keep-point-on-repeat t
t, point is not moved when the user repeats the previous command
by typing `.' This is very useful for doing repeated changes with the
. key.
vip-repeat-from-history-key 'f12
vip-repeat-from-history,
which checks the second key by which it is invoked to see which of the
previous commands to invoke. Viper binds f12 1 and f12 2 only,
but the user can bind more in `~/.vip'. See section Vi Macros, for how to do
this.
vip-keep-point-on-undo nil
t, Viper tries to not move point when undoing commands.
Instead, it will briefly move the cursor to the place where change has
taken place. However, if the undone piece of text is not seen in window,
then point will be moved to the place where the change took place.
Set it to t and see if you like it better.
vip-delete-backwards-in-replace nil
t, DEL key will delete characters while moving the cursor backwards.
If nil, the cursor will move backwards without deleting anything.
vip-replace-overlay-face 'vip-replace-overlay-face
vip-replace-overlay-face underlines the replacement
on monochrome displays and highlights it with color on color displays.
If you know something about Emacs
faces and don't like how Viper highlights replacement regions, you can change
this variable to specify a new face name. (Emacs faces are described in the
Emacs Lisp reference.)
On a color display, the following customization method is usually
most effective:
(set-face-foreground vip-replace-overlay-face "DarkSlateBlue") (set-face-background vip-replace-overlay-face "yellow")For a complete list of colors available to you, evaluate the expression
(x-defined-colors). (Type it in the buffer *scratch*
and then hit the C-j key.
vip-replace-overlay-cursor-color "Red"
vip-replace-region-end-delimiter "$"
vip-use-replace-region-delimiters is non-nil.
vip-replace-region-start-delimiter ""
vip-use-replace-region-delimiters is non-nil.
vip-use-replace-region-delimiters
vip-replace-region-end-delimiter and
vip-replace-region-start-delimiter to delimit replacement regions,
even on color displays (where this is unnecessary). By default, this
variable is non-nil only on TTYs or monochrome displays.
vip-toggle-key "\C-z"
vip-ESC-key "\e"
vip-buffer-search-char nil
vip-surrounding-word-function 'vip-surrounding-word
vip-search-face 'vip-search-face
vip-vi-state-hook nil
vip-insert-state-hook nil
vip-replace-state-hook nil
vip-insert-state-hook).
vip-emacs-state-hook nil
vip-load-hook nil
You can reset some of these constants in Viper with the Ex command :set (when so indicated in the table). Or you can include a line like this in your `.vip' file:
(setq vip-case-fold-search t)
Viper lets you define hot keys, i.e., you can associate keyboard keys such as F1, Help, PgDn, etc., with Emacs Lisp functions (that may already exist or that you will write). Each key has a "preferred form" in Emacs. For instance, the Up key's preferred form is [up], the Help key's preferred form is [help], and the Undo key has the preferred form [f14]. You can find out the preferred form of a key by typing M-x describe-key-briefly and then typing the key you want to know about.
Under X Windows, every keyboard key emits its preferred form, so you can just type
(global-set-key [f11] 'calendar) ; L1, Stop (global-set-key [f14] 'undo) ; L4, Undo
to bind L1 so it will invoke the Emacs Calendar and to bind L4 so it will
undo changes.
However, on a dumb terminal or in an Xterm window, even the standard arrow
keys may
not emit the right signals for Emacs to understand. To let Emacs know about
those keys, you will have to find out which key sequences they emit
by typing C-q and then the key (you should switch to Emacs state
first). Then you can bind those sequences to their preferred forms using
function-key-map as follows:
(cond ((string= (getenv "TERM") "xterm")
(define-key function-key-map "\e[192z" [f11]) ; L1
(define-key function-key-map "\e[195z" [f14]) ; L4, Undo
The above illustrates how to do this for Xterm. On VT100, you would have to replace "xterm" with "vt100" and also change the key sequences (the same key may emit different sequences on different types of terminals).
The above keys are global, so they are overwritten by the local maps defined by the major modes and by Viper itself. Therefore, if you wish to change a binding set by a major mode or by Viper, read this.
Viper users who wish to specify their own key bindings should be concerned
only with the following three keymaps:
vip-vi-global-user-map for Vi state commands,
vip-insert-global-user-map for Insert state commands,
and vip-emacs-global-user-map for Emacs state commands (note:
customized bindings for Emacs state made to vip-emacs-global-user-map
are not inherited by Insert state).
For more information on Viper keymaps, see the header of the file
`viper.el'.
If you wish to change a Viper binding, you can use the
define-key command, to modify vip-vi-global-user-map,
vip-insert-global-user-map, and vip-emacs-global-user-map, as
explained below. Each of these key maps affects the corresponding Viper state.
The keymap vip-vi-global-user-map also affects Viper's Replace state.
If you want to bind a key, say C-v, to the function that scrolls page down and to make 0 display information on the current buffer, putting this in `.vip' will do the trick in Vi state:
(define-key vip-vi-global-user-map "\C-v" 'scroll-down)
To set a key globally,
(define-key vip-emacs-global-user-map "\C-c m" 'smail) (define-key vip-vi-global-user-map "0" 'vip-info-on-file)
Note, however, that this binding may be overwritten by other keymaps, since the global keymap has the lowest priority. To make sure that nothing will override a binding in Emacs state, you can write this:
(define-key vip-emacs-global-user-map "\C-c m" 'smail)
To customize the binding for C-h in Insert state:
(define-key vip-insert-global-user-map "\C-h" 'my-del-backwards-function)
Each Emacs command key calls some lisp function. If you have enabled the Help, (See section Rudimentary Changes) C-h k will show you the function for each specific key; C-h b will show all bindings, and C-h m will provide information on the major mode in effect. If Help is not enabled, you can still get help in Vi state by prefixing the above commands with \, e.g., \ C-h k (or you can use the Help menu in the menu bar, if Emacs runs under X Windows).
Viper users can also change bindings on a per major mode basis. As with
global bindings, this can be done separately for each of the three main Viper
states. To this end, Viper provides the function
vip-modify-major-mode.
To modify keys in Emacs state for my-favorite-major-mode, the user
needs to create a sparse keymap, say, my-fancy-map, bind whatever
keys necessary in that keymap, and put
(vip-modify-major-mode 'dired-mode 'emacs-state my-fancy-map)
in `~/.vip'. To do the same in Vi and Insert states, one should use
vi-state and insert-state. Changes in Insert state are also
in effect in Replace state. For instance, suppose that the user wants to
use dd in Vi state under Dired mode to delete files, u to unmark
files, etc. The following code in `~/.vip' will then do the job:
(setq my-dired-modifier-map (make-sparse-keymap)) (define-key my-dired-modifier-map "dd" 'dired-flag-file-deletion) (define-key my-dired-modifier-map "u" 'dired-unmark) (vip-modify-major-mode 'dired-mode 'vi-state my-dired-modifier-map)
A Vi purist may want to modify Emacs state under Dired mode so that k, l, etc., will move around in directory buffers, as in Vi. Although this is not recommended, as these keys are bound to useful Dired functions, the trick can be accomplished via the following code:
(setq my-dired-vi-purist-map (make-sparse-keymap)) (define-key my-dired-vi-purist-map "k" 'vip-previous-line) (define-key my-dired-vi-purist-map "l" 'vip-forward-char) (vip-modify-major-mode 'dired-mode 'emacs-state my-dired-vi-purist-map)
Similar effect can be achieved by defining Vi keyboard macros using the Ex commands :map and :map!. The difference is that multi-key Vi macros do not override the keys they are bound to, unless these keys are typed in quick succession. So, with macros, one can use the normal keys alongside with the macros. If per-mode modifications are needed, the user can try both ways and see which one is more convenient. See section Vi Macros, for details.
Note: in major modes that come up in Emacs state by default, the
aforesaid modifications may not take place immediately (but only after the
buffer switches to some other Viper state and then back to Emacs state). To
avoid this, one should add vip-change-state-to-emacs to an
appropriate hook of that major mode. (Check the function
vip-set-hooks in `viper.el' for examples.) However, if you
have set vip-always to t, chances are that you won't need to
perform the above procedure, because Viper will take care of most useful
defaults.
Finally, Viper has a facility that lets the user define per-buffer
bindings, i.e., bindings that are in effect in some specific buffers
only. Unlike per-mode bindings described above, per-buffer bindings can be
defined based on considerations other than the major mode. This is done
via the function vip-add-local-keys, which lets one specify bindings
that should be in effect in the current buffer only and for a specific Viper
state. For instance,
(vip-add-local-keys 'vi-state '(("ZZ" . TeX-command-master)
("ZQ" . vip-save-kill-buffer)))
redefines ZZ to invoke TeX-command-master in vi-state
and ZQ to save-then-kill the current buffer. These bindings take
effect only in the buffer where this command is executed. The typical use
of this function is to execute the above expression from within a function
that is included in a hook to some major mode. For instance, the above
expression
could be called from a function, my-tex-init, which may be added to
tex-mode-hook as follows:
(add-hook 'tex-mode-hook 'my-tex-init)
When TeX mode starts, the hook is executed and the above Lisp expression is evaluated. Then, the bindings for ZZ and ZQ are changed in Vi command mode for all buffers in TeX mode.
Another useful application is to bind ZZ to send-mail
in the Mail mode buffers (the specifics of this depend on which mail
package you are using, rmail, mh-e, vm, etc.
For instance, here is how to do this for mh-e, the Emacs interface
to MH:
(defun mh-add-vi-keys ()
"Set up ZZ for MH-e and XMH."
(vip-add-local-keys 'vi-state '(("ZZ" . mh-send-letter))))
(add-hook 'mh-letter-mode-hook 'mh-add-vi-keys)
You can also use vip-add-local-keys to set per buffer
bindings in Insert state and Emacs state by passing as a parameter the
symbols 'insert-state and 'emacs-state, respectively.
As with global bindings, customized local bindings done to Emacs state
are not inherited by Insert state.
So much about Viper-specific bindings. See section `Customization' in The GNU Emacs Manual, and the Emacs quick reference card for the general info on key bindings in Emacs.
Viper is designed to coexist with all major and minor modes of Emacs. This
means that bindings set by those modes are generally available with Viper
(unless you explicitly prohibit them by setting
vip-want-emacs-keys-in-vi and vip-want-emacs-keys-in-insert to
nil).
If vip-always is set to t, Viper will try to bring each buffer
in the a Viper state that is most appropriate for that buffer.
Usually, this would be the Vi state, but sometimes it could be the Insert
state or the Emacs state.
Some major mode bindings will necessarily be overwritten by Viper. Indeed, in Vi state, most of the 1-character keys are used for Vi-style editing. This usually causes no problems because most packages designed for editing files typically do not bind such keys. Instead, they use key sequences that start with C-x and C-c. This is why it was so important for us to free up C-x and C-c. It is common for language-specific major modes to bind TAB and LFD (the line feed) keys to various formatting functions. This is extremely useful, but may require some getting used to for a Vi user. If you decide that this feature is not for you, you can re-bind these keys as explained earlier (See section Customization).
Binding for TAB is one of the most unusual aspects of Viper for many novice users. In Emacs, TAB is used to format text and programs, and is extremely useful. For instance, hitting TAB causes the current line to be re-indented in accordance with the context. In programming, this is very important, since improper automatic indentation would immediately alert the programmer to a possible error. For instance, if a ) or a " is missing somewhere above the current line, TAB is likely to mis-indent the line.
For this reason, Viper doesn't change the standard Emacs binding of TAB, thereby sacrificing Vi compatibility (except for users at level 1). Instead, in Viper, the key S-tab (shift+ tab) is chosen to emulate Vi's TAB.
We should note that on some non-windowing terminals, Shift doesn't modify
the TAB key, so S-tab behaves as if it were TAB. In such
a case, you will have to bind vip-insert-tab to some other
convenient key.
Some packages, notably Dired, Gnus, Info, etc., attach special meaning to common keys like SPC, x, d, v, and others. This means that Vi command state is inappropriate for working with these packages. Fortunately, these modes operate on read-only buffers and are designed not for editing files, but for special-purpose browsing, reading news, mail, etc., and Vi commands are meaningless in these situations. For this reason, Viper doesn't force Vi state on such major modes. Rather, it brings them in Emacs state. You can switch to Vi state by typing C-z if, for instance, you want to do Vi-style search in a buffer (although, usually, incremental search, which is bound to C-s, is sufficient in these situations). But you should then switch back to Emacs state if you plan to continue using these major modes productively. You can also switch to Vi temporarily, to execute one 1-character command. This is done by typing M-C-z (or ESC C-z). This facility cannot execute several complex Vi commands, such as dw, de, etc.
It is also possible to harness some major modes, even though they may bind
common keys to specialized commands. Harnessing can make sense for modes
that bind only a small number of common keys. For instance, if
vip-always is set to t in your `~/.vip' file, Viper will
harness the Shell mode by changing the bindings for C-m and C-d
using vip-add-local-keys described in section on customization
(See section Customization). In general, there is no single recipe for
harnessing modes. It can be as simple as adding the function
viper-mode to a hook associated with the mode, or it can be more
complex, as in the case of Shell mode and Emerge. Take a look at
vip-set-hooks function for some examples.
Conversely, it may be the case that most of the major modes harnessed
by vip-set-hooks function fit your working style, except one or two
cases. In this case, you may still be able to set vip-always to
t and then remove a hook that forces Vi command state. For instance,
to unharness lisp-interaction-mode, you can put the following line
in your `.emacs' (not .vip!) file after (require 'viper):
(remove-hook 'lisp-interaction-mode-hook 'viper-mode)
In some rare cases, some minor modes may override certain essential
bindings in Vi command state. This is not really catastrophic because this
may happen only in the beginning, when the minor mode kicks in. Typing
M-x viper-mode will correct the situation. Viper knows about
several such minor modes and takes care of them, so that the above trick
is usually not necessary. If you find that some minor mode, e.g.,
nasty-mode.el interferes with Viper, putting the following in
`.vip' should fix the problem:
(vip-harness-minor-mode "nasty-mode")
The argument to vip-harness-minor-mode is the name of the file for the
offending minor mode with the suffixes `.el' and `.elc' removed.
It may be tricky, however, to find out which minor mode is at fault. The
only guidance here is to look into the file that defines the minor mode you
are suspecting, say nasty-mode.el, and see if it has a variable
called nasty-mode-map. Then check if there is a statement of the form
(define-key nasty-mode-map key function)
that binds the misbehaving
keys. If so, use the above line to harness nasty-mode. If your
suspicion is wrong, no harm is done if you harness a minor mode that
doesn't need to be harnessed.
Viper extends Vi with a number of useful features. This includes various search functions, histories of search strings, Ex commands, insertions, and Vi's destructive commands. In addition, Viper supports file name completion and history, completion of Ex commands and variables, and many other features. Some of these features are explained in detail elsewhere in this document. Other features are explained here.
(vip-buffer-search-enable)
vip-buffer-search-char nil
vip-buffer-search-enable
sets vip-buffer-search-char to g. Alternatively, the user can
set vip-buffer-search-char in `.vip' to a key sequence
to be used for buffer search. There is no need to call
vip-buffer-search-enable in that case.
vip-toggle-search-style
(vip-unrecord-kbd-macro "//" 'vi-state) (vip-unrecord-kbd-macro "///" 'vi-state)See section Vi Macros, for more information on Vi macros.
vip-heading-start
vip-heading-end
M-x vip-set-expert-level
vip-smart-suffix-list '("" "tex" "c" "cc" "el" "p")
nil.
vip-insertion-ring-size 14
vip-insertion-ring-size.
If you enter Insert or Replace state you can reinsert strings from this
ring by typing C-c M-p or C-c M-n. The former will search the
ring in
the direction of older insertions, and the latter will search in
the direction of newer insertions. Hitting C-c M-p or C-c M-n
in succession
will undo the previous insertion from the ring and insert the next item on
the ring. If a larger ring size is needed, change the value of the above
variable in the `~/.vip' file.
Since typing these sequences of keys may be tedious, it is suggested that the
user should bind a function key, such as f31, as follows:
(define-key vip-insert-global-user-map [f31]
'vip-insert-prev-from-insertion-ring)
This binds f31 (which is usually R11 on a Sun workstation)
to the function that inserts the previous string in the insertion history.
To rotate the history in the opposite
direction, you can either bind an unused key to
vip-insert-next-from-insertion-ring or hit any digit (1 to 9) then
f31.
One should not bind the above functions to M-p or M-n, since
this will interfere with the Minibuffer histories and, possibly, other
major modes.
vip-command-ring-size 14
(define-key vip-vi-global-user-map [f31]
'vip-prev-destructive-command)
binds the key f31 (which is usually R11 on a Sun workstation)
to the function that searches the command history in the direction of older
commands. To search in the opposite
direction, you can either bind an unused key to
vip-next-destructive-command or hit any digit (1 to 9) then f31.
One should not bind the above functions to M-p or M-n, since
this will interfere with the Minibuffer histories and, possibly, other
major modes.
vip-minibuffer-vi-face 'vip-minibuffer-vi-face
vip-minibuffer-insert-face 'vip-minibuffer-insert-face
vip-minibuffer-emacs-face 'vip-minibuffer-emacs-face
(set-face-foreground vip-minibuffer-vi-face "blue") (set-face-background vip-minibuffer-emacs-face "orchid")This will make a blue foreground in the Minibuffer when it is in Vi state; its background will turn to orchid when it switches to Emacs state. Note that only the text you type in is affected by the above faces. Prompts and Minibuffer messages are not affected. Purists who do not like adornments in the minibuffer can always zap them by putting
(copy-face 'default 'vip-minibuffer-vi-face) (copy-face 'default 'vip-minibuffer-insert-face) (copy-face 'default 'vip-minibuffer-emacs-face)in the `~/.vip' file. However, in that case, the user will not have any indication of the current Viper state in the minibuffer. (This is important if the user accidentally switches to another Viper state by typing ESC or C-z.
Viper provides some support for multi-file documents and programs. If a document consists of several files we can designate one of them as a master and put the following at the end of that file:
;;; Local Variables: ;;; eval: (vip-setup-master-buffer "file1" "file2" "file3" "file5" "file5") ;;; End:
where file1 to file5 are names of files related to the master
file. Next time, when the master file is visited, the command
vip-setup-master-buffer will be evaluated and the above files will
be associated with the master file. Then, the new Ex command
:RelatedFile (abbr. :R) will display files 1 to 5 one after
another, so you can edit them. If a file is not in any Emacs buffer, it
will be visited. The command PreviousRelatedFile (abbr., :P)
goes through the file list in the opposite direction.
These commands are akin to :n and :N, but they allow the user to focus on relevant files only.
Note that only the master file needs to have the aforementioned block of commands. Also, ";;;" above can be replaced by some other markers. Semicolon is good for Lisp programs, since it is considered a comment designator there. For LaTeX, this could be "%%%", and for C the above block should be commented out.
Even though these commands are sometimes useful, they are no substitute for the powerful tag table facility of Emacs. Viper's :tag command in a primitive interface to Emacs tags. See section `Tags' in The Gnu Emacs Manual, for more information on tags.
The following two commands are normally bound to a mouse click and are part
of Viper. They work only if Emacs runs as an application under X
Windows (or under some other window system for which a port of GNU Emacs 19
is available). Clicking the mouse when Emacs is invoked in an Xterm window
(using emacs -nw) will do no good.
S-mouse-1 (Emacs)
meta shift button1up (XEmacs)
(global-set-key [M-mouse-1] 'vip-mouse-click-search-word) (global-set-key [M-down-mouse-1] 'vip-mouse-catch-frame-switch)This would bind mouse search to the action invoked by pressing the Meta key and clicking mouse button 1. Note: if
vip-mouse-click-search-word is bound to an action, then
vip-mouse-catch-frame-switch must be bound to a down-action, as
shown in the above example.
In XEmacs, you can change bindings as follows:
(global-set-key [(meta control button1up)]
'vip-mouse-click-search-word)
(global-set-key [(meta control button1)]
'vip-mouse-catch-frame-switch)
if, say, you prefer to hold both meta and control while clicking.
The reason why Viper uses different bindings for Emacs and XEmacs is
because these two incarnations of Emacs have different default bindings for
mouse actions.
Like in Emacs, there are special rules for binding these functions: the
first must be bound to a button-up event while the second must be bound to
a button-event (which is XEmacs' equivalent of a down-mouse event). Also,
in Emacs, the double-click and triple-click actions for the same button
(double-S-mouse-1, etc., if the above default binding is used)
should not be bound (or it should be bound to the same function,
vip-mouse-click-search-word).
The region that is chosen as a pattern to search for is determined as
follows. If search is invoked via a single click, Viper chooses the region
that lies between the beginning of the "word" under the pointer ("word" is
understood in Vi sense) and the end of that word.
The only difference with Vi's words is that in Lisp
major modes `-' is considered an alphanumeric symbol. This is done for the
convenience of working with Lisp symbols, which often have an `-' in them.
Also, if you click on a non-alphanumeric character that is not a word
separator (in Vi) then this character will also be considered alphanumeric,
provided that it is adjacent (from either side) to an alphanumeric character.
This useful feature gives added control over the patterns selected by the
mouse click.
On a double-click, the region is determined by the beginning of the current
Vi's "Word" (i.e., the largest non-separator chunk of text) and the End
of that "Word" (as determined by the E command).
On a triple-click, the region consists of the line where the click occurred
with all leading and trailing spaces and tabs removed.
S-mouse-2 (Emacs)
meta shift button2up (XEmacs)
(global-set-key [M-mouse-2] 'vip-mouse-click-insert-word) (global-set-key [M-down-mouse-2] 'vip-mouse-catch-frame-switch)In XEmacs, you can change the bindings as follows:
(global-set-key [(meta control button2up)]
'vip-mouse-click-insert-word)
(global-set-key [(meta control button2)]
'vip-mouse-catch-frame-switch)
vip-multiclick-timeout
double-click-time in Emacs and to
mouse-track-multi-click-time milliseconds in XEmacs.
Note: The above functions search and insert in the selected window of the latest active frame. This means that you can click in another window or another frame and have search or insertion done in the frame and window you just left. This lets one use these functions in a multi-frame configuration. However, this may require some getting used to. For instance, if you are typing in a frame, A, and then move the mouse to frame B and click to invoke mouse search, search (or insertion) will be performed in frame A. To perform search/insertion in frame B, you will first have to shift focus there, which doesn't happen until you type a character or perform some other action in frame B--mouse search doesn't shift focus (in XEmacs, to shift focus to frame B, you will have to select this frame with a mouse, by clicking.
If you decide that you don't like the above feature and always want
search/insertion be performed in the frame where the click occurs, don't
bind (and unbind, if necessary) vip-mouse-catch-frame-switch from
the mouse event it is bound to.
Mouse search is integrated with Vi-style search, so you can
repeat it with n and N. It should be also noted that, while
case-sensitivity of search in Viper is controlled by the variable
vip-case-fold-search, the case of mouse search is
controlled by the Emacs variable case-fold-search, which may be set
differently from vip-case-fold-search. Therefore, case-sensitivity
of mouse search may be different from that of the usual Vi-style search.
Finally, if the way Viper determines the word to be searched for or to be
inserted is not what you want, there is a variable,
vip-surrounding-word-function, which can be changed to indicate
another function for snarfing words out of the buffer. The catch is that
you will then have to write such a function and make it known to your
Emacs. The function vip-surrounding-word in `viper.el' can be
used as a guiding example.
Viper supports much enhanced Vi-style macros and also facilitates the use of Emacs-style macros. To define a temporary macro, it is generally more convenient to use Emacs keyboard macro facility. Emacs keyboard macros are usually defined anonymously, and the latest macro can be executed by typing C-x e (or *, if Viper is in Vi state). If you need to use several temporary macros, Viper lets you save them to a register (a lowercase letter); such macros can then be executed by typing @a in Vi state (if a macro was previously saved in register a). See section Macros and Registers, for details.
If, however, you need to use a macro regularly, it must be given a permanent name and saved. Emacs manual explains how to do this, but invocation of named Emacs macros is quite different from Vi's. First, invocation of permanent Emacs macros takes time because of the extra keys. Second, binding such macros to function keys, for fast access, hogs valuable real estate on the keyboard.
Vi-style macros are better in that respect, since Vi lets the user overload the meaning of key sequences: keys typed in fast succession are treated specially, if this key sequence is bound to a macro.
Viper provides keyboard macros through the usual Ex commands, :map and :map!. Vi-style macros are much more powerful in Viper than they are in the original Vi and in other emulators. This is because Viper implements an enhanced vi-style interface to the powerful Emacs keyboard macro facility.
First, any Emacs command can be executed while defining a macro, not just the Vi commands. In particular, the user can invoke Emacs commands via M-x command-name or by pressing various function keys on the keyboard. One can even use the mouse, although this is usually not useful and is not recommended (and macros defined with the use of the mouse cannot be saved in command history and in the startup file, for future use).
Macros defined by mixing Vi and Emacs commands are represented as vectors. So, don't be confused when you see one (usually through the history of Ex commands). For instance, if gg is defined by typing l, the up-arrow key and M-x next-line, its definition will look as follows in Emacs (in XEmacs, it looks slightly different, see below):
[l up (meta x) n e x t - l i n e return]
Second, Viper macros are defined in a WYSIWYG style. This means that
commands are executed as you type them, so you can see precisely what is
being defined. Third, macros can be bound to arbitrary sequences of keys,
not just to printable keys. For instance, one can define a macro that will
be invoked by hitting f3 then f2 function keys. (The keys
delete and backspace are excluded; also, a macro invocation
sequence can't start with ESC. Some other keys, such as f1 and
help, can't be bound to macros under Emacs (not XEmacs), since they
are bound in key-translation-map, which overrides any other binding
the user gives to keys. In general, keys that have a binding in
key-translation-map can't be bound to a macro.)
Fourth, in Viper, one can define macros that are specific to a given buffer, a given major mode, or macros that are defined for all buffers. In fact, the same macro name can have several different definitions: one global, several definitions for various major modes, and definitions for various specific buffers. Buffer-specific definitions override mode-specific definitions, which, in turn, override global definitions.
As if all that is not enough, Viper (through its interface to Emacs macros) lets the user define keyboard macros that ask for confirmation or even prompt the user for input and then continue. To do this, one should type C-x q (for confirmation) or C-u C-x q (for prompt). For details, see section `Customization' in The GNU Emacs Manual
When the user finishes defining a macro (which is done by typing C-x) ---
a departure from Vi), you will be asked whether you want this
macro to be global, mode-specific, or buffer-specific. You will also be
given a chance to save the macro in your `~/.vip' file.
This is the easiest way to save a macro and make
it permanently available. If you work your startup files with bare hands,
here is how Viper saves the above macro so that it will be
available in Viper's Insert state (and Replace state) in buffer my-buf
only:
(vip-record-kbd-macro "gg" 'insert-state
[l up (meta x) n e x t - l i n e return]
"my-buf")
To do the same for Vi state and all buffers with the major mode
cc-mode, use:
(vip-record-kbd-macro "gg" 'vi-state
[l up (meta x) n e x t - l i n e return]
'cc-mode)
Both macro names and macro definitions are vectors of symbols that denote keys on the keyboard. Some keys, like \, , or digit-keys must be escaped with a backslash. Modified keys are represented as lists. For instance, holding Meta and Control and pressing f4 is represented as (control meta f4). If all members of a vectors are printable characters (or sequences, such as \e, \t, for ESC and TAB), then they can also be represented as strings:
(vip-record-kbd-macro "aa" 'vi-state "aaa\e" "my-buffer")
Thus, typing aa fast in Vi state will switch Viper to Insert state
(due to the first a), insert aa, and then it will switch back to Vi
state. All this will take effect only in the buffer named my-buffer.
Note that the last argument to vip-record-kbd-macro must be either a
string (a buffer name), a symbol representing a major mode, or t;
the latter says that the macro is to be defined for all buffers
(which is how macros are defined in original Vi).
For convenience, Viper also lets you define Vi-style macros in its Emacs
state. There is no Ex command, like :map and :map! for doing
this, but the user can include such a macro in the `~/.vip' file. The
only thing is that the vip-record-kbd-macro command should specify
'emacs-state instead of 'vi-state or 'insert-state.
The user can get rid of a macro either by using the Ex commands :unmap
and :unmap! or by issuing a call to vip-unrecord-kbd-macro.
The latter is more powerful, since it can delete macros even in
'emacs-state. However, vip-unrecord-kbd-macro is usually
needed only when the user needs to get rid of the macros that are already
predefined in Viper.
The syntax is:
(vip-unrecord-kbd-macro macro state)
The second argument must be 'vi-state, 'insert-state, or
'emacs-state. The first argument is a name of a macro. To avoid
mistakes in specifying names of existing macros, type M-x
vip-describe-kbd-macros and use a name from the list displayed by this
command.
If an error occurs during macro definition, Emacs aborts the process, and it must be repeated. This is analogous to Vi, except that in Vi the user doesn't know there is an error until the macro is actually run. All that means that in order for a definition to be successful, the user must do some simple planning of the process in advance, to avoid errors. For instance, if you want to map gg to llll in Vi state, you must make sure that there is enough room on the current line. Since l moves the cursor forward, it may signal an error on reaching the end of line, which will abort the definition.
These precautions are necessary only when defining macros; they will help avoid the need to redo the job. When macros are actually run, an error during the execution will simply terminate the current execution (but the macro will remain mapped).
A macro name can be a string of characters or a vector of keys. The latter makes it possible to define macros bound to, say, double-hitts on a function key, such as up or f13. This is very useful if you run out of function keys on your keyboard; it makes Viper macro facility a keyboard doubler, so to speak.
Elsewhere (See section Keybindings, for details), we review the standard Emacs mechanism for binding function keys to commands. For instance,
(global-set-key [f13] 'repeat-complex-command)
binds the key f13 to the Emacs function that repeats the last minibuffer command. Under Viper, however, you may still use this key for additional purposes, if you bind, say, a double-hitting action for that key to some other function. Emacs doesn't allow the user to do that, but Viper does this through its keyboard macro facility. To do this, type :map first. When you are asked to enter a macro name, hit f13 twice, followed by RET or SPC.
Emacs will now start the mapping process by actually executing
Vi and Emacs commands, so that you could see what will happen each time the
macro is executed. Suppose now we wanted to bind the key sequence
f13 f13 to the command eval-last-sexp. To accomplish this, we
can type M-x eval-last-sexp followed by C-x ).
If you answer positively to Viper's offer to save this macro in `~/.vip'
for future uses, the following will be inserted in that file:
(vip-record-kbd-macro [f16 f16] 'vi-state
[(meta x) e v a l - l a s t - s e x p]
'lisp-interaction-mode)
To illustrate the above point, Viper provides two canned macros, which, by default, are bound to [f12 \1] and [f12 \2] (invoked by typing f12 then 1 and 2, respectively). These macros are useful shortcuts to Viper's command ring history. The first macro will execute the second-last destructive command (the last one is executed by ., as usual). The second macro executes the third-last command.
If you need to go deeper into the command history, you will have to use other commands, as described earlier in this section; or you can bind, say, f12 \3 like this:
(vip-record-kbd-macro [f12 \3] 'vi-state
[(meta x) r e p e a t - f r o m - h i s t o r y]
t)
Note that even though the macro uses the function key f12, the key is
actually free and can still be bound to some Emacs function via
define-key or global-set-key.
Viper allows the user to define macro names that are prefixes of other macros. For instance, one can define [[ and [[[[ to be macros. If you type the exact sequence of such keys and then pause, Viper will execute the right macro. However, if you don't pause and, say, type [[[[text then the conflict is resolved as follows. If only one of the key sequences, [[ or [[[[ has a definition applicable to the current buffer, then, in fact, there is no conflict and the right macro will be chosen. If both have applicable definitions, then the first one found will be executed. Usually this is the macro with a shorter name. So, in our case, [[[[text will cause the macro [[ to be executed twice and then the remaining keys, t e x t, will be processed.
When defining macros using :map or :map!, the user enters the actually keys to be used to invoke the macro. For instance, you should hit the actual key f6 if it is to be part of a macro name; you do not write `f 6'. When entering keys, Viper displays them as strings or vectors (e.g., "abc" or [f6 f7 a]). The same holds for unmapping. Hitting TAB while typing a macro name in the :unmap or :unmap! command will cause name completion. Completions are displayed as strings or vectors. However, as before, you don't actually type """, "[", or "]" that appear in the completions. These are meta-symbols that indicate whether the corresponding macro name is a vector or a string.
One last difference from Vi: Vi-style keyboard macros cannot be defined in terms of other Vi-style keyboard macros (but named Emacs macros are OK). More precisely, while defining or executing a macro, the special meaning of key sequences (as Vi macros) is ignored. This is because it is all too easy to create an infinite loop in this way. Since Viper macros are much more powerful than Vi's it is impossible to detect such loops. In practice, this is not really a limitation but, rather, a feature.
We should also note that Vi macros are disabled in the Minibuffer, which helps keep some potential troubles away.
The rate at which the user must type keys in order for them to be
recognized as a timeout macro is controlled by the variable
vip-fast-keyseq-timeout, which defaults to 200 milliseconds.
For the most part, Viper macros defined in `~/.vip' can be shared between Emacs, XEmacs, and X and TTY modes. However, macros defined via function keys may need separate definitions when XEmacs and Emacs have different names for the same keyboard key. For instance, the `Page Up' key may be known in Emacs as prior and in XEmacs as pgup. The problem with TTY may be that the function keys there generate sequences of events instead of a single event (as under a window system). Both Emacs and XEmacs mape some of these sequences back to the logical keys (e.g., the sequences generated by the arrow keys are mapped to up, left, etc.). However, not all function keys are mapped in this way. Macros that are bound to key sequences that contain such unmapped function keys have to be redefined for TTY's (and possibly for every type of TTY you may be using). To do this, start Emacs on an appropriate TTY device and define the macro using :map, as usual.
Finally, Viper provides a function that conveniently displays all macros currently defined. To see all macros along with their definitions, type M-x vip-describe-kbd-macros.