Rudimentary Changes
===================
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 au
<SPC>' will complete the command to `:set autoindent'; `:se ta <SPC>'
will complete the command and prompt further like this: `:set tabstop =
'. However, typing `:se ts <SPC>' 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>'.
`viper-auto-indent nil'
`:se ai (:se autoindent)'
`:se ai-g (:se autoindent-global)'
If `t', enable auto indentation. by <RET>, `o' or `O' command.
`viper-auto-indent' is a local variable. To change the value
globally, use `setq-default'. It may be useful for certain major
modes to have their own values of `viper-auto-indent'. This can
be achieved by using `setq' to change the local value of this
variable in the hooks to the appropriate major modes.
`:se ai' changes the value of `viper-auto-indent' in the current
buffer only; `:se ai-g' does the same globally.
`viper-electric-mode t'
If not `nil', auto-indentation becomes electric, which means that
<RET>, `O', and `o' indent cursor according to the current major
mode. In the future, this variable may control additional electric
features.
This is a local variable: `setq' changes the value of this variable
in the current buffer only. Use `setq-default' to change the
value in all buffers.
`viper-case-fold-search nil'
`:se ic (:se ignorecase)'
If not `nil', search ignores cases. This can also be toggled by
quickly hitting `/' twice.
`viper-re-search nil'
`:se magic'
If not `nil', search will use regular expressions; if `nil' then
use vanilla search. This behavior can also be toggled by quickly
hitting `/' trice.
`buffer-read-only'
`:se ro (:se readonly)'
Set current buffer to read only. To change globally put
`(setq-default buffer-read-only t)' in your `.emacs' file.
`blink-matching-paren t'
`:se sm (:se showmatch)'
Show matching parens by blinking cursor.
`tab-width t (default setting via `setq-default')'
`:se ts=value (:se tabstop=value)'
`:se ts-g=value (:se tabstop-global=value)'
`tab-width' is a local variable that controls the width of the tab
stops. To change the value globally, use `setq-default'; for
local settings, use `setq'.
The command `:se ts' sets the tab width in the current buffer
only; it has no effect on other buffers.
The command `:se ts-g' sets tab width globally, for all buffers
where the tab is not yet set locally, including the new buffers.
Note that typing <TAB> normally doesn't insert the tab, since this
key is usually bound to a text-formatting function,
`indent-for-tab-command' (which facilitates programming and
document writing). Instead, the tab is inserted via the command
`viper-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 `viper-insert-tab' to some other convenient key.
`viper-shift-width 8'
`:se sw=value (:se shiftwidth=value)'
The number of columns shifted by `>' and `<' commands.
`viper-search-wrap-around t'
`:se ws (:se wrapscan)'
If not `nil', search wraps around the end/beginning of buffer.
`viper-search-scroll-threshold 2'
If search lands within this many lines of the window top or
bottom, the window will be scrolled up or down by about 1/7-th of
its size, to reveal the context. If the value is negative--don't
scroll.
`viper-tags-file-name "TAGS"'
The name of the file used as the tag table.
`viper-re-query-replace nil'
If not `nil', use reg-exp replace in query replace.
`viper-want-ctl-h-help nil'
If not `nil', `C-h' is bound to `help-command'; otherwise, `C-h'
is bound as usual in Vi.
`viper-vi-style-in-minibuffer t'
If not `nil', 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.
`viper-no-multiple-ESC t'
If you set this to `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.
`viper-ESC-keyseq-timeout 200 on tty, 0 on windowing display'
Escape key sequences separated by this much delay (in
milliseconds) are interpreted as command, ignoring the special
meaning of <ESC> in VI. The default is suitable for most
terminals. However, if your terminal is extremely slow, you might
want to increase this slightly. You will know if your terminal is
slow if the <ESC> key sequences emitted by the arrow keys are
interpreted as separately typed characters (and thus the arrow
keys won't work). Making this value too large will slow you down,
so exercise restraint.
`viper-fast-keyseq-timeout 200'
Key sequences separated by this many milliseconds are treated as
Vi-style keyboard macros. If the key sequence is defined as such
a macro, it will be executed. Otherwise, it is processed as an
ordinary sequence of typed keys.
Setting this variable too high may slow down your typing. Setting
it too low may make it hard to type macros quickly enough.
`viper-translate-all-ESC-keysequences t on tty, nil on windowing display'
Normally, Viper lets Emacs translate only those ESC key sequences
that are defined in the low-level key-translation-map or
function-key-map, such as those emitted by the arrow and function
keys. Other sequences, e.g., `\\e/', are treated as `ESC' command
followed by a `/'. This is good for people who type fast and tend
to hit other characters right after they hit ESC. Other people
like Emacs to translate `ESC' sequences all the time. The default
is to translate all sequences only when using a dumb terminal.
This permits you to use `ESC' as a meta key in insert mode. For
instance, hitting `ESC x' fast would have the effect of typing
`M-x'. If your dumb terminal is not so dumb and understands the
meta key, then you probably will be better off setting this
variable to nil. Try and see which way suits you best.
`viper-ex-style-motion t'
Set this to `nil', if you want `l,h' to cross lines, etc. Note:Movement and Markers, for more info.
`viper-ex-style-editing t'
Set this to `nil', if you want `C-h' and <DEL> to not stop at the
beginning of a line in Insert state, <X> and <x> to delete
characters across lines in Vi command state, etc.
`viper-ESC-moves-cursor-back t'
It t, cursor moves back 1 character when switching from insert
state to vi state. If nil, the cursor stays where it was before
the switch.
`viper-always t'
`t' means: leave it to Viper to decide when a buffer must be
brought up in Vi state, Insert state, or Emacs state. This
heuristics works well in virtually all cases. `nil' means you
either has to invoke `viper-mode' manually for each buffer (or you
can add `viper-mode' to the appropriate major mode hooks using
`viper-load-hook').
This option must be set in the file `~/.viper'.
`viper-custom-file-name "~/.viper"'
File used for Viper-specific customization. Change this setting,
if you want. Must be set in `.emacs' (not `.viper'!) before
Viper is loaded. Note that you have to set it as a string inside
double quotes.
`viper-spell-function 'ispell-region'
Function used by the command `#c<move>' to spell.
`viper-glob-function'
The value of this variable is the function symbol used to expand
wildcard symbols. This is platform-dependent. The default tries to
set this variable to work with most shells, MS Windows, OS/2, etc.
However, if it doesn't work the way you expect, you should write
your own. Use `viper-glob-unix-files' and
`viper-glob-mswindows-files' in `viper-util.el' as examples.
This feature is used to expand wildcards in the Ex command `:e'.
Note that Viper doesn't support wildcards in the `:r' and `:w'
commands, because file completion is a better mechanism.
`ex-cycle-other-window t'
If not `nil', `:n' and `:b' will cycle through files in another
window, if one exists.
`ex-cycle-through-non-files nil'
`:n' does not normally cycle through buffers. Set this to get
buffers also.
`viper-want-emacs-keys-in-insert'
This is set to `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.
`viper-want-emacs-keys-in-vi'
This is set to `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.
`viper-keep-point-on-repeat t'
If not `nil', point is not moved when the user repeats the previous
command by typing `.' This is very useful for doing repeated
changes with the `.' key.
`viper-repeat-from-history-key 'f12'
Prefix key used to invoke the macros `f12 1' and `f12 2' that
repeat the second-last and the third-last destructive command.
Both these macros are bound (as Viper macros) to
`viper-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 `~/.viper'. Note:Vi Macros, for how to do this.
`viper-keep-point-on-undo nil'
If not `nil', 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.
`viper-delete-backwards-in-replace nil'
If not `nil', <DEL> key will delete characters while moving the
cursor backwards. If `nil', the cursor will move backwards
without deleting anything.
`viper-replace-overlay-face 'viper-replace-overlay-face'
On a graphical display, Viper highlights replacement regions
instead of putting a `$' at the end. This variable controls the
so called "face" used to highlight the region.
By default, `viper-replace-overlay-face' underlines the
replacement on monochrome displays and also lays a stipple over
them. On color displays, replacement regions are highlighted with
color.
If you know something about Emacs faces and don't like how Viper
highlights replacement regions, you can change
`viper-replace-overlay-face' by specifying a new face. (Emacs
faces are described in the Emacs Lisp reference.) On a color
display, the following customization method is usually most
effective:
(set-face-foreground viper-replace-overlay-face "DarkSlateBlue")
(set-face-background viper-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.
`viper-replace-overlay-cursor-color "Red"'
Cursor color when it is inside the replacement region. This has
effect only on color displays and only when Emacs runs as an X
application.
`viper-insert-state-cursor-color nil'
If set to a valid color, this will be the cursor color when Viper
is in insert state.
`viper-replace-region-end-delimiter "$"'
A string used to mark the end of replacement regions. It is used
only on TTYs or if `viper-use-replace-region-delimiters' is
non-nil.
`viper-replace-region-start-delimiter ""'
A string used to mark the beginning of replacement regions. It is
used only on TTYs or if `viper-use-replace-region-delimiters' is
non-nil.
`viper-use-replace-region-delimiters'
If non-nil, Viper will always use
`viper-replace-region-end-delimiter' and
`viper-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.
`viper-allow-multiline-replace-regions t'
If non-nil, multi-line text replacement regions, such as those
produced by commands `c55w', `3C', etc., will stay around until
the user exits the replacement mode. In this variable is set to
`nil', Viper will emulate the standard Vi behavior, which supports
only intra-line replacement regions (and multi-line replacement
regions are deleted).
`viper-toggle-key "\C-z"'
Specifies the key used to switch from Emacs to Vi and back. Must
be set in `.viper'. This variable can't be changed interactively
after Viper is loaded.
In Insert state, this key acts as a temporary escape to Vi state,
i.e., it will set Viper up so that the very next command will be
executed as if it were typed in Vi state.
`viper-ESC-key "\e"'
Specifies the key used to escape from Insert/Replace states to Vi.
Must be set in `.viper'. This variable cannot be changed
interactively after Viper is loaded.
`viper-buffer-search-char nil'
Key used for buffer search. Note:Viper Specials, for details.
`viper-surrounding-word-function 'viper-surrounding-word'
The value of this variable is a function name that is used to
determine what constitutes a word clicked upon by the mouse. This
is used by mouse search and insert.
`viper-search-face 'viper-search-face'
Variable that controls how search patterns are highlighted when
they are found.
`viper-vi-state-hook nil'
List of parameterless functions to be run just after entering the
Vi command state.
`viper-insert-state-hook nil'
Same for Insert state. This hook is also run after entering
Replace state.
`viper-replace-state-hook nil'
List of (parameterless) functions called just after entering
Replace state (and after all `viper-insert-state-hook').
`viper-emacs-state-hook nil'
List of (parameterless) functions called just after switching from
Vi state to Emacs state.
`viper-load-hook nil'
List of (parameterless) functions called just after loading Viper.
This is the last chance to do customization before Viper is up
and running.
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 `.viper' file:
(setq viper-case-fold-search t)