\input texinfo @c -*-texinfo-*- @c %**start of header @setfilename evil.info @documentencoding UTF-8 @ifinfo @*Generated by Sphinx 4.3.2.@* @end ifinfo @settitle Evil documentation @defindex ge @paragraphindent 0 @exampleindent 4 @finalout @dircategory Emacs @direntry * evil: (evil.info). Extensible vi layer for Emacs @end direntry @definfoenclose strong,`,' @definfoenclose emph,`,' @c %**end of header @copying @quotation Evil 1.15.0, Jan 07, 2022 Eivind Fonn, Frank Fischer, Vegard Øye Copyright @copyright{} 2011-2019, Eivind Fonn, Frank Fischer, Vegard Øye @end quotation @end copying @titlepage @title Evil documentation @insertcopying @end titlepage @contents @c %** start of user preamble @c %** end of user preamble @ifnottex @node Top @top Evil documentation @insertcopying @end ifnottex @c %**start of body @anchor{index doc}@anchor{44} @c Evil documentation master file, created by @c sphinx-quickstart on Thu Dec 12 10:34:49 2019. @c You can adapt this file completely to your liking, but it should at least @c contain the root `toctree` directive. @menu * Overview:: * Settings:: * Keymaps:: * Hooks:: * Extension:: * Frequently Asked Questions:: * Internals:: * The GNU Free Documentation License:: * Emacs lisp functions and variables:: @detailmenu --- The Detailed Node Listing --- Overview * Installation via package.el: Installation via package el. * Manual installation:: * Modes and states:: Settings * The initial state:: * Keybindings and other behaviour:: * Search:: * Indentation:: * Cursor movement:: * Cursor display:: * Window management:: * Parenthesis highlighting:: * Miscellaneous:: Keymaps * evil-define-key:: * Leader keys:: Extension * Motions:: * Operators:: * Text objects:: * Range types:: * States:: Frequently Asked Questions * Problems with the escape key in the terminal:: * Underscore is not a word character:: Internals * Command properties:: @end detailmenu @end menu @node Overview,Settings,Top,Top @anchor{overview doc}@anchor{45}@anchor{overview evil}@anchor{46}@anchor{overview overview}@anchor{47} @chapter Overview Evil is an extensible vi layer for Emacs. It emulates the main features of Vim, @footnote{@w{(1)} Vim is the most popular version of @emph{vi}, a modal text editor with many implementations. Vim also adds some functions of its own, like visual selection and text objects. For more information see @uref{https://vim.org,the official Vim website}. } turning Emacs into a modal editor. Like Emacs in general, Evil is extensible in Emacs Lisp. @menu * Installation via package.el: Installation via package el. * Manual installation:: * Modes and states:: @end menu @node Installation via package el,Manual installation,,Overview @anchor{overview installation-via-package-el}@anchor{48} @section Installation via package.el Evil is available as a package from MELPA stable, MELPA unstable and NonGNU ELPA. This is the recommended way of installing Evil. To set up @cite{package.el} to work with one of the MELPA repositories, you can follow the instructions on melpa.org@footnote{https://melpa.org/#/getting-started}. Alternatively you can use NonGNU ELPA. It is part of the default package archives as of Emacs 28. For older Emacs versions you’ll need to add it yourself: @example (add-to-list 'package-archives (cons "nongnu" (format "http%s://elpa.nongnu.org/nongnu/" (if (gnutls-available-p) "s" "")))) @end example Once that is done, you can execute the following commands: @example M-x package-refresh-contents M-x package-install RET evil RET @end example Finally, add the following lines to your Emacs init file: @example (require 'evil) (evil-mode 1) @end example @node Manual installation,Modes and states,Installation via package el,Overview @anchor{overview manual-installation}@anchor{49} @section Manual installation First, install @cite{goto-chg} and @cite{cl-lib}. If you have an Emacs version of 24.3 or newer, you should already have @cite{cl-lib}. Evil lives in a git repository. To download Evil, do: @example git clone --depth 1 https://github.com/emacs-evil/evil.git @end example Then add the following lines to your Emacs init file: @example (add-to-list 'load-path "path/to/evil") (require 'evil) (evil-mode 1) @end example Ensure that your replace @code{path/to/evil} with the actual path to where you cloned Evil. @node Modes and states,,Manual installation,Overview @anchor{overview modes-and-states}@anchor{4a} @section Modes and states The next time Emacs is started, it will come up in @emph{normal state}, denoted by @code{} in the mode line. This is where the main vi bindings are defined. Note that you can always disable normal state with @code{C-z}, which switches to an “Emacs state” (denoted by @code{}) in which vi keys are completely disabled. Press @code{C-z} again to switch back to normal state. @table @asis @item state Evil uses the term @emph{state} for what is called a “mode” in regular vi usage, because @emph{modes} are understood in Emacs terms to mean something else. @end table Evil defines a number of states by default: @table @asis @item normal state (@code{}) This is the default “resting state” of Evil, in which the main body of vi bindings are defined. @item insert state (@code{}) This is the state for insertion of text, where non-modified keys will insert the corresponding character in the buffer. @item visual state (@code{}) A state for selecting text regions. Motions are available for modifying the selected region, and operators are available for acting on it. @item replace state (@code{}) A special state mostly similar to insert state, except it replaces text instead of inserting. @item operator-pending state (@code{}) A special state entered after launching an operator, but before specifying the corresponding motion or text object. @item motion state (@code{}) A special state useful for buffers that are read-only, where motions are available but editing operations are not. @item Emacs state (@code{}) A state that as closely as possible mimics default Emacs behaviour, by eliminating all vi bindings, except for @code{C-z}, to re-enter normal state. @end table @node Settings,Keymaps,Overview,Top @anchor{settings doc}@anchor{4b}@anchor{settings settings}@anchor{4c} @chapter Settings Evil’s behaviour can be adjusted by setting some variables. The list of all available variables and their current values can be inspected by doing: @example M-x customize-group RET evil RET @end example To change the value of a variable, you can use this interface, or add a @code{setq} form to your Emacs init file, preferably before Evil is loaded. @footnote{@w{(1)} Strictly speaking, the order only matters if the variable affects the way Evil is loaded. This is the case with some variables. } @example (setq evil-shift-width 0) ;; Load Evil (require 'evil) @end example What follows is a non-exhaustive list of the most relevant customization options. @menu * The initial state:: * Keybindings and other behaviour:: * Search:: * Indentation:: * Cursor movement:: * Cursor display:: * Window management:: * Parenthesis highlighting:: * Miscellaneous:: @end menu @node The initial state,Keybindings and other behaviour,,Settings @anchor{settings the-initial-state}@anchor{4d} @section The initial state The initial state of a buffer is determined by its major mode. Evil maintains an association between major modes and their corresponding states, which is most easily modified using the function @ref{30,,evil-set-initial-state}. @anchor{settings elispobj-evil-set-initial-state}@anchor{30} @deffn {Emacs Lisp Autofunction} (evil@w{-}set@w{-}initial@w{-}state MODE STATE) Set the initial state for major mode @emph{MODE} to @emph{STATE}. This is the state the buffer comes up in. @end deffn If no state can be found, Evil uses the default initial state. @anchor{settings elispobj-evil-default-state}@anchor{d} @deffn {Emacs Lisp Autovariable} evil@w{-}default@w{-}state The default Evil state. This is the state a buffer starts in when it is not otherwise configured (see @ref{30,,evil-set-initial-state} and @ref{5,,evil-buffer-regexps}). The value may be one of @code{normal}, @code{insert}, @code{visual}, @code{replace}, @code{operator}, @code{motion} and @code{emacs}. Default: @code{normal} @end deffn Alternatively, it is possible to select the initial state based on the buffer @emph{name} rather than its major mode. This is checked first, so it takes precedence over the other methods for setting the state. @anchor{settings elispobj-evil-buffer-regexps}@anchor{5} @deffn {Emacs Lisp Autovariable} evil@w{-}buffer@w{-}regexps Regular expressions determining the initial state for a buffer. Entries have the form @code{(REGEXP . STATE)}, where @emph{REGEXP} is a regular expression matching the buffer’s name and @emph{STATE} is one of @code{normal}, @code{insert}, @code{visual}, @code{replace}, @code{operator}, @code{motion}, @code{emacs} and @code{nil}. If @emph{STATE} is @code{nil}, Evil is disabled in the buffer. Default: @code{(("^ \\*load\\*"))} @end deffn @node Keybindings and other behaviour,Search,The initial state,Settings @anchor{settings keybindings-and-other-behaviour}@anchor{4e} @section Keybindings and other behaviour Evil comes with a rich system for modifying its key bindings @ref{4f,,Keymaps}. For the most common tweaks, the following variables are available. @anchor{settings elispobj-evil-toggle-key}@anchor{37} @deffn {Emacs Lisp Autovariable} evil@w{-}toggle@w{-}key The key used to change to and from Emacs state. Must be readable by @code{read-kbd-macro}. For example: “C-z”. Default: @code{"C-z"} @end deffn @anchor{settings elispobj-evil-want-C-i-jump}@anchor{3c} @deffn {Emacs Lisp Autovariable} evil@w{-}want@w{-}C@w{-}i@w{-}jump Whether @code{C-i} jumps forward in the jump list (like Vim). Otherwise, @code{C-i} inserts a tab character. Default: @code{t} @end deffn @anchor{settings elispobj-evil-want-C-u-delete}@anchor{3d} @deffn {Emacs Lisp Autovariable} evil@w{-}want@w{-}C@w{-}u@w{-}delete Whether @code{C-u} deletes back to indentation in insert state. Otherwise, @code{C-u} applies a prefix argument. The binding of @code{C-u} mirrors Emacs behaviour by default due to the relative ubiquity of prefix arguments. Default: @code{nil} @end deffn @anchor{settings elispobj-evil-want-C-u-scroll}@anchor{3e} @deffn {Emacs Lisp Autovariable} evil@w{-}want@w{-}C@w{-}u@w{-}scroll Whether @code{C-u} scrolls up (like Vim). Otherwise, @code{C-u} applies a prefix argument. The binding of @code{C-u} mirrors Emacs behaviour by default due to the relative ubiquity of prefix arguments. Default: @code{nil} @end deffn @anchor{settings elispobj-evil-want-C-d-scroll}@anchor{3b} @deffn {Emacs Lisp Autovariable} evil@w{-}want@w{-}C@w{-}d@w{-}scroll Whether @code{C-d} scrolls down (like Vim). Default: @code{t} @end deffn @anchor{settings elispobj-evil-want-C-w-delete}@anchor{3f} @deffn {Emacs Lisp Autovariable} evil@w{-}want@w{-}C@w{-}w@w{-}delete Whether @code{C-w} deletes a word in Insert state. Default: @code{t} @end deffn @anchor{settings elispobj-evil-want-C-w-in-emacs-state}@anchor{40} @deffn {Emacs Lisp Autovariable} evil@w{-}want@w{-}C@w{-}w@w{-}in@w{-}emacs@w{-}state Whether @code{C-w} prefixes windows commands in Emacs state. Default: @code{nil} @end deffn @anchor{settings elispobj-evil-want-Y-yank-to-eol}@anchor{43} @deffn {Emacs Lisp Autovariable} evil@w{-}want@w{-}Y@w{-}yank@w{-}to@w{-}eol Whether @code{Y} yanks to the end of the line. The default behavior is to yank the whole line, like Vim. Default: @code{nil} @end deffn @anchor{settings elispobj-evil-disable-insert-state-bindings}@anchor{15} @deffn {Emacs Lisp Autovariable} evil@w{-}disable@w{-}insert@w{-}state@w{-}bindings Whether insert state bindings should be used. Bindings for escape, delete and @ref{37,,evil-toggle-key} are always available. If this is non-nil, default Emacs bindings are by and large accessible in insert state. Default: @code{nil} @end deffn @node Search,Indentation,Keybindings and other behaviour,Settings @anchor{settings search}@anchor{50} @section Search @anchor{settings elispobj-evil-search-module}@anchor{2a} @deffn {Emacs Lisp Autovariable} evil@w{-}search@w{-}module The search module to be used. May be either @code{isearch}, for Emacs’ isearch module, or @code{evil-search}, for Evil’s own interactive search module. N.b. changing this will not affect keybindings. To swap out relevant keybindings, see @code{evil-select-search-module} function. Default: @code{isearch} @end deffn @anchor{settings elispobj-evil-regexp-search}@anchor{27} @deffn {Emacs Lisp Autovariable} evil@w{-}regexp@w{-}search Whether to use regular expressions for searching in @code{/} and @code{?}. Default: @code{t} @end deffn @anchor{settings elispobj-evil-search-wrap}@anchor{2b} @deffn {Emacs Lisp Autovariable} evil@w{-}search@w{-}wrap Whether search with @code{/} and @code{?} wraps around the buffer. If this is non-nil, search stops at the buffer boundaries. Default: @code{t} @end deffn @anchor{settings elispobj-evil-flash-delay}@anchor{19} @deffn {Emacs Lisp Autovariable} evil@w{-}flash@w{-}delay Time in seconds to flash search matches after @code{n} and @code{N}. Default: @code{2} @end deffn @anchor{settings elispobj-evil-ex-hl-update-delay}@anchor{18} @deffn {Emacs Lisp Autovariable} evil@w{-}ex@w{-}hl@w{-}update@w{-}delay Time in seconds of idle before updating search highlighting. Setting this to a period shorter than that of keyboard’s repeat rate allows highlights to update while scrolling. Default: @code{0.02} @end deffn @node Indentation,Cursor movement,Search,Settings @anchor{settings indentation}@anchor{51} @section Indentation @anchor{settings elispobj-evil-auto-indent}@anchor{2} @deffn {Emacs Lisp Autovariable} evil@w{-}auto@w{-}indent Whether to auto-indent when opening lines with @code{o} and @code{O}. Default: @code{t}, buffer-local @end deffn @anchor{settings elispobj-evil-shift-width}@anchor{33} @deffn {Emacs Lisp Autovariable} evil@w{-}shift@w{-}width The number of columns by which a line is shifted. This applies to the shifting operators @code{>} and @code{<}. Default: @code{4}, buffer-local @end deffn @anchor{settings elispobj-evil-shift-round}@anchor{32} @deffn {Emacs Lisp Autovariable} evil@w{-}shift@w{-}round Whether shifting rounds to the nearest multiple. If non-nil, @code{>} and @code{<} adjust line indentation to the nearest multiple of @ref{33,,evil-shift-width}. Default: @code{t}, buffer-local @end deffn @anchor{settings elispobj-evil-indent-convert-tabs}@anchor{1e} @deffn {Emacs Lisp Autovariable} evil@w{-}indent@w{-}convert@w{-}tabs If non-nil, the @code{=} operator converts between leading tabs and spaces. Whether tabs are converted to spaces or vice versa depends on the value of @code{indent-tabs-mode}. Default: @code{t} @end deffn @node Cursor movement,Cursor display,Indentation,Settings @anchor{settings cursor-movement}@anchor{52} @section Cursor movement In standard Emacs terms, the cursor is generally understood to be located between two characters. In Vim, and therefore also Evil, this is the case in insert state, but in other states the cursor is understood to be @emph{on} a character, and that this character is not a newline. Forcing this behaviour in Emacs is the source of some potentially surprising results (especially for traditional Emacs users—users used to Vim may find the default behavior to their satisfaction). Many of them can be tweaked using the following variables. @anchor{settings elispobj-evil-repeat-move-cursor}@anchor{28} @deffn {Emacs Lisp Autovariable} evil@w{-}repeat@w{-}move@w{-}cursor Whether repeating commands with @code{.} may move the cursor. If nil, the original cursor position is preserved, even if the command normally would have moved the cursor. Default: @code{t} @end deffn @anchor{settings elispobj-evil-move-cursor-back}@anchor{26} @deffn {Emacs Lisp Autovariable} evil@w{-}move@w{-}cursor@w{-}back Whether the cursor is moved backwards when exiting insert state. If non-nil, the cursor moves “backwards” when exiting insert state, so that it ends up on the character to the left. Otherwise it remains in place, on the character to the right. Default: @code{t} @end deffn @anchor{settings elispobj-evil-move-beyond-eol}@anchor{25} @deffn {Emacs Lisp Autovariable} evil@w{-}move@w{-}beyond@w{-}eol Whether the cursor can move past the end of the line. If non-nil, the cursor is allowed to move one character past the end of the line, as in Emacs. Default: @code{nil} @end deffn @anchor{settings elispobj-evil-cross-lines}@anchor{7} @deffn {Emacs Lisp Autovariable} evil@w{-}cross@w{-}lines Whether horizontal motions may move to other lines. If non-nil, certain motions that conventionally operate in a single line may move the cursor to other lines. Otherwise, they are restricted to the current line. This applies to @code{h}, @code{SPC}, @code{f}, @code{F}, @code{t}, @code{T}, @code{~}. Default: @code{nil} @end deffn @anchor{settings elispobj-evil-respect-visual-line-mode}@anchor{29} @deffn {Emacs Lisp Autovariable} evil@w{-}respect@w{-}visual@w{-}line@w{-}mode Whether movement commands respect @code{visual-line-mode}. If non-nil, @code{visual-line-mode} is generally respected when it is on. In this case, motions such as @code{j} and @code{k} navigate by visual lines (on the screen) rather than “physical” lines (defined by newline characters). If nil, the setting of @code{visual-line-mode} is ignored. This variable must be set before Evil is loaded. Default: @code{nil} @end deffn @anchor{settings elispobj-evil-track-eol}@anchor{38} @deffn {Emacs Lisp Autovariable} evil@w{-}track@w{-}eol Whether @code{$} “sticks” the cursor to the end of the line. If non-nil, vertical motions after @code{$} maintain the cursor at the end of the line, even if the target line is longer. This is analogous to @code{track-eol}, but respects Evil’s interpretation of end-of-line. Default: @code{t} @end deffn @anchor{settings elispobj-evil-start-of-line}@anchor{36} @deffn {Emacs Lisp Autovariable} evil@w{-}start@w{-}of@w{-}line Analogue of vim’s @code{startofline}. If nil, preserve column when making relevant movements of the cursor. Otherwise, move the cursor to the start of the line. Default: @code{nil} @end deffn @node Cursor display,Window management,Cursor movement,Settings @anchor{settings cursor-display}@anchor{53} @section Cursor display A state may change the appearance of the cursor. Use the variable @ref{c,,evil-default-cursor} to set the default cursor, and the variables @code{evil-normal-state-cursor}, @code{evil-insert-state-cursor} etc. to set the cursors for specific states. The acceptable values for all of them are the same. @anchor{settings elispobj-evil-default-cursor}@anchor{c} @deffn {Emacs Lisp Autovariable} evil@w{-}default@w{-}cursor The default cursor. May be a cursor type as per @code{cursor-type}, a color string as passed to @code{set-cursor-color}, a zero-argument function for changing the cursor, or a list of the above. Default: @code{t} @end deffn @node Window management,Parenthesis highlighting,Cursor display,Settings @anchor{settings window-management}@anchor{54} @section Window management @anchor{settings elispobj-evil-auto-balance-windows}@anchor{1} @deffn {Emacs Lisp Autovariable} evil@w{-}auto@w{-}balance@w{-}windows If non-nil window creation and deletion trigger rebalancing. Default: @code{t} @end deffn @anchor{settings elispobj-evil-split-window-below}@anchor{35} @deffn {Emacs Lisp Autovariable} evil@w{-}split@w{-}window@w{-}below If non-nil split windows are created below. Default: @code{nil} @end deffn @anchor{settings elispobj-evil-vsplit-window-right}@anchor{3a} @deffn {Emacs Lisp Autovariable} evil@w{-}vsplit@w{-}window@w{-}right If non-nil vertically split windows with are created to the right. Default: @code{nil} @end deffn @node Parenthesis highlighting,Miscellaneous,Window management,Settings @anchor{settings parenthesis-highlighting}@anchor{55} @section Parenthesis highlighting These settings concern the integration between Evil and @code{show-paren-mode}. They take no effect if this mode is not enabled. @anchor{settings elispobj-evil-show-paren-range}@anchor{34} @deffn {Emacs Lisp Autovariable} evil@w{-}show@w{-}paren@w{-}range The minimal distance between point and a parenthesis which causes the parenthesis to be highlighted. Default: @code{0} @end deffn @anchor{settings elispobj-evil-highlight-closing-paren-at-point-states}@anchor{1d} @deffn {Emacs Lisp Autovariable} evil@w{-}highlight@w{-}closing@w{-}paren@w{-}at@w{-}point@w{-}states The states in which the closing parenthesis at point should be highlighted. All states listed here highlight the closing parenthesis at point (which is Vim’s default behavior). All others highlight the parenthesis before point (which is Emacs default behavior). If this list contains the symbol @code{not} then its meaning is inverted, i.e. all states listed here highlight the closing parenthesis before point. Default: @code{(not emacs insert replace)} @end deffn @node Miscellaneous,,Parenthesis highlighting,Settings @anchor{settings miscellaneous}@anchor{56} @section Miscellaneous @anchor{settings elispobj-evil-want-fine-undo}@anchor{42} @deffn {Emacs Lisp Autovariable} evil@w{-}want@w{-}fine@w{-}undo Whether actions are undone in several steps. There are two possible choices: nil (“no”) means that all changes made during insert state, including a possible delete after a change operation, are collected in a single undo step. Non-nil (“yes”) means that undo steps are determined according to Emacs heuristics, and no attempt is made to aggregate changes. For backward compatibility purposes, the value @code{fine} is interpreted as @code{nil}. This option was removed because it did not work consistently. Default: @code{nil} @end deffn @anchor{settings elispobj-evil-undo-system}@anchor{39} @deffn {Emacs Lisp Autovariable} evil@w{-}undo@w{-}system Undo system Evil should use. If equal to @code{undo-tree} or @code{undo-fu}, those packages must be installed. If equal to @code{undo-tree}, @code{undo-tree-mode} must also be activated. If equal to @code{undo-redo}, Evil uses commands natively available in Emacs 28. Default: @code{nil} @end deffn @anchor{settings elispobj-evil-backspace-join-lines}@anchor{3} @deffn {Emacs Lisp Autovariable} evil@w{-}backspace@w{-}join@w{-}lines Whether backward delete in insert state may join lines. Default: @code{t} @end deffn @anchor{settings elispobj-evil-kbd-macro-suppress-motion-error}@anchor{20} @deffn {Emacs Lisp Autovariable} evil@w{-}kbd@w{-}macro@w{-}suppress@w{-}motion@w{-}error Whether left/right motions signal errors in keyboard macros. This variable only affects beginning-of-line or end-of-line errors regarding the motions @code{h} and @code{SPC} respectively. This may be desired since such errors cause macro definition or execution to be terminated. There are four possibilities: @itemize - @item @code{record}: errors are suppressed when recording macros, but not when replaying them. @item @code{replay}: errors are suppressed when replaying macros, but not when recording them. @item @code{t}: errors are suppressed in both cases. @item @code{nil}: errors are never suppressed. @end itemize Default: @code{nil} @end deffn @anchor{settings elispobj-evil-mode-line-format}@anchor{23} @deffn {Emacs Lisp Autovariable} evil@w{-}mode@w{-}line@w{-}format The position of the state tag in the mode line. If set to @code{before} or @code{after}, the tag is placed at the beginning or the end of the mode-line, respectively. If nil, there is no tag. Otherwise it should be a cons cell @code{(WHERE . WHICH)}, where @emph{WHERE} is either @code{before} or @code{after}, and @emph{WHICH} is a symbol in @code{mode-line-format}. The tag is then placed before or after that symbol, respectively. Default: @code{before} @end deffn @anchor{settings elispobj-evil-mouse-word}@anchor{24} @deffn {Emacs Lisp Autovariable} evil@w{-}mouse@w{-}word The @emph{thing-at-point} symbol for double click selection. The double-click starts visual state in a special word selection mode. This symbol is used to determine the words to be selected. Possible values are @code{evil-word} or @code{evil-WORD}. Default: @code{evil-word} @end deffn @anchor{settings elispobj-evil-bigword}@anchor{4} @deffn {Emacs Lisp Autovariable} evil@w{-}bigword The set of characters to be interpreted as WORD boundaries. This is enclosed with square brackets and used as a regular expression. By default, whitespace characters are considered WORD boundaries. Default: @code{"^ \t\r\n"}, buffer-local @end deffn @anchor{settings elispobj-evil-esc-delay}@anchor{17} @deffn {Emacs Lisp Autovariable} evil@w{-}esc@w{-}delay The time, in seconds, to wait for another key after escape. If no further event arrives during this time, the event is translated to @code{ESC}. Otherwise, it is translated according to @code{input-decode-map}. This does not apply in Emacs state, and may also be inhibited by setting @code{evil-inhibit-esc}. Default: @code{0.01} @end deffn @anchor{settings elispobj-evil-intercept-esc}@anchor{1f} @deffn {Emacs Lisp Autovariable} evil@w{-}intercept@w{-}esc Whether Evil should intercept the escape key. In the terminal, escape and a meta key sequence both generate the same event. In order to distingush these, Evil uses @code{input-decode-map}. It is not necessary to do this in a graphical Emacs session. However, if you prefer to use @code{C-[} as escape (which is identical to the terminal escape key code), this interception must also happen in graphical Emacs sessions. Set this variable to @code{always}, t (only in the terminal) or nil (never intercept). Default: @code{always} @end deffn @anchor{settings elispobj-evil-kill-on-visual-paste}@anchor{21} @deffn {Emacs Lisp Autovariable} evil@w{-}kill@w{-}on@w{-}visual@w{-}paste Whether pasting in visual state adds the replaced text to the kill ring, making it the default for the next paste. The default, replicates the default Vim behavior. Default: @code{t} @end deffn @anchor{settings elispobj-evil-echo-state}@anchor{16} @deffn {Emacs Lisp Autovariable} evil@w{-}echo@w{-}state Whether to signal the current state in the echo area. Default: @code{t} @end deffn @anchor{settings elispobj-evil-complete-all-buffers}@anchor{6} @deffn {Emacs Lisp Autovariable} evil@w{-}complete@w{-}all@w{-}buffers Whether completion looks for matches in all buffers. This applies to @code{C-n} and @code{C-p} in insert state. Default: @code{t} @end deffn @anchor{settings elispobj-evil-want-empty-ex-last-command}@anchor{41} @deffn {Emacs Lisp Autovariable} evil@w{-}want@w{-}empty@w{-}ex@w{-}last@w{-}command Whether to default to evil-ex-previous-command at empty ex prompt. Default: @code{t} @end deffn @node Keymaps,Hooks,Settings,Top @anchor{keymaps doc}@anchor{57}@anchor{keymaps chapter-keymaps}@anchor{4f}@anchor{keymaps keymaps}@anchor{58} @chapter Keymaps Evil’s key bindings are stored in a number of different keymaps. Each state has a @emph{global keymap}, where the default bindings for that state are stored. They are named @code{evil-normal-state-map}, @code{evil-insert-state-map}, and so on. The bindings in these maps are visible in all buffers currently in the corresponding state. These keymaps function like ordinary Emacs keymaps and may be modified using the Emacs function @code{define-key}: @example (define-key evil-normal-state-map (kbd "w") 'some-function) @end example This binds the key @code{w} to the command @code{some-function} in normal state. The use of @code{kbd} is optional for simple key sequences, like this one, but recommended in general. Most of Evil’s bindings are defined in the file @code{evil-maps.el}. To facilitate shared keybindings between states, some states may activate keybindings from other states as well. For example, motion state bindings are visible in normal and visual state, and normal state bindings are also visible in visual state. Each state also has a @emph{buffer-local keymap} which is specific to the current buffer, and which takes precedence over the global keymap. These maps are most suitably modified by a mode hook. They are named @code{evil-normal-state-local-map}, @code{evil-insert-state-local-map}, and so on. @example (add-hook 'some-mode-hook (lambda () (define-key evil-normal-state-local-map (kbd "w") 'some-function))) @end example For convenience, the functions @ref{1c,,evil-global-set-key} and @ref{22,,evil-local-set-key} are available for setting global and local state keys. @anchor{keymaps elispobj-evil-global-set-key}@anchor{1c} @deffn {Emacs Lisp Autofunction} (evil@w{-}global@w{-}set@w{-}key STATE KEY DEF) Bind @emph{KEY} to @emph{DEF} in @emph{STATE}. @end deffn @anchor{keymaps elispobj-evil-local-set-key}@anchor{22} @deffn {Emacs Lisp Autofunction} (evil@w{-}local@w{-}set@w{-}key STATE KEY DEF) Bind @emph{KEY} to @emph{DEF} in @emph{STATE} in the current buffer. @end deffn The above examples could therefore have been written as follows: @example (evil-global-set-key 'normal (kbd "w") 'some-function) (add-hook 'some-mode-hook (lambda () (evil-local-set-key 'normal (kbd "w") 'some-function))) @end example @menu * evil-define-key:: * Leader keys:: @end menu @node evil-define-key,Leader keys,,Keymaps @anchor{keymaps evil-define-key}@anchor{59} @section evil-define-key Evil provides the macro @ref{f,,evil-define-key} for adding state bindings to ordinary keymaps. It is quite powerful, and is the preferred method for fine-tuning bindings to activate in specific circumstances. @anchor{keymaps elispobj-evil-define-key}@anchor{f} @deffn {Emacs Lisp Autofunction} (evil@w{-}define@w{-}key STATE KEYMAP KEY DEF [BINDINGS...]) Create a @emph{STATE} binding from @emph{KEY} to @emph{DEF} for @emph{KEYMAP}. @emph{STATE} is one of @code{normal}, @code{insert}, @code{visual}, @code{replace}, @code{operator}, @code{motion}, @code{emacs}, or a list of one or more of these. Omitting a state by using @code{nil} corresponds to a standard Emacs binding using @code{define-key}. The remaining arguments are like those of @code{define-key}. For example: @example (evil-define-key 'normal foo-map "a" 'bar) @end example This creates a binding from @code{a} to @code{bar} in normal state, which is active whenever @code{foo-map} is active. Using nil for the state, the following lead to identical bindings: @example (evil-define-key nil foo-map "a" 'bar) (define-key foo-map "a" 'bar) @end example It is possible to specify multiple states and/or bindings at once: @example (evil-define-key '(normal visual) foo-map "a" 'bar "b" 'foo) @end example If @code{foo-map} has not been initialized yet, this macro adds an entry to @code{after-load-functions}, delaying execution as necessary. @emph{KEYMAP} may also be a quoted symbol. If the symbol is @code{global}, the global evil keymap corresponding to the state(s) is used, meaning the following lead to identical bindings: @example (evil-define-key 'normal 'global "a" 'bar) (evil-global-set-key 'normal "a" 'bar) @end example The symbol @code{local} may also be used, which corresponds to using @ref{22,,evil-local-set-key}. If a quoted symbol is used that is not @code{global} or @code{local}, it is assumed to be the name of a minor mode, in which case @code{evil-define-minor-mode-key} is used. @end deffn There follows a brief overview of the main functions of this macro. @itemize - @item Define a binding in a given state @example (evil-define-key 'state 'global (kbd "key") 'target) @end example @item Define a binding in a given state in the current buffer @example (evil-define-key 'state 'local (kbd "key") 'target) @end example @item Define a binding in a given state under the @emph{foo-mode} major mode. @example (evil-define-key 'state foo-mode-map (kbd "key") 'target) @end example Note that @code{foo-mode-map} is unquoted, and that this form is safe before @code{foo-mode-map} is loaded. @item Define a binding in a given state under the @emph{bar-mode} minor mode. @example (evil-define-key 'state 'bar-mode (kbd "key") 'target) @end example Note that @code{bar-mode} is quoted, and that this form is safe before @code{bar-mode} is loaded. @end itemize The macro @ref{f,,evil-define-key} can be used to augment existing modes with state bindings, as well as creating packages with custom bindings. For example, the following will create a minor mode @code{foo-mode} with normal state bindings for the keys @code{w} and @code{e}: @example (define-minor-mode foo-mode "Foo mode." :keymap (make-sparse-keymap)) (evil-define-key 'normal 'foo-mode "w" 'bar) (evil-define-key 'normal 'foo-mode "e" 'baz) @end example This minor mode can then be enabled in any buffers where the custom bindings are desired: @example (add-hook 'text-mode-hook 'foo-mode) ; enable alongside text-mode @end example @node Leader keys,,evil-define-key,Keymaps @anchor{keymaps leader-keys}@anchor{5a} @section Leader keys Evil supports a simple implementation of Vim’s @emph{leader} keys. To bind a function to a leader key you can use the expression @code{} in a key mapping, e.g. @example (evil-define-key 'normal 'global (kbd "fs") 'save-buffer) @end example Likewise, you can use the expression @code{} to mimic Vim’s local leader, which is designed for mode-specific key bindings. You can use the function @ref{31,,evil-set-leader} to designate which key acts as the leader and the local leader. @anchor{keymaps elispobj-evil-set-leader}@anchor{31} @deffn {Emacs Lisp Autofunction} (evil@w{-}set@w{-}leader STATE KEY [LOCALLEADER]) Set @emph{KEY} to trigger leader bindings in @emph{STATE}. @emph{KEY} should be in the form produced by @code{kbd}. @emph{STATE} is one of @code{normal}, @code{insert}, @code{visual}, @code{replace}, @code{operator}, @code{motion}, @code{emacs}, a list of one or more of these, or @code{nil}, which means all of the above. If @emph{LOCALLEADER} is non-nil, set the local leader instead. @end deffn @node Hooks,Extension,Keymaps,Top @anchor{hooks doc}@anchor{5b}@anchor{hooks hooks}@anchor{5c} @chapter Hooks A @emph{hook} is a list of functions that are executed when certain events happen. Hooks are modified with the Emacs function @code{add-hook}. Evil provides entry and exit hooks for all its states. For example, when switching from normal state to insert state, all functions in @code{evil-normal-state-exit-hook} and @code{evil-insert-state-entry-hook} are executed. It is guaranteed that the exit hook will be executed before the entry hook on all state switches. During the hook execution, the variables @code{evil-next-state} and @code{evil-previous-state} contain information about the states being switched to and from, respectively. @node Extension,Frequently Asked Questions,Hooks,Top @anchor{extension doc}@anchor{5d}@anchor{extension extension}@anchor{5e} @chapter Extension The main functionality of Evil is implemented in terms of reusable macros. Package writers can use these to define new commands. @menu * Motions:: * Operators:: * Text objects:: * Range types:: * States:: @end menu @node Motions,Operators,,Extension @anchor{extension motions}@anchor{5f} @section Motions A @emph{motion} is a command which moves the cursor, such as @code{w} or @code{e}. Motions are defined with the macro @ref{10,,evil-define-motion}. Motions not defined in this way should be declared with @ref{9,,evil-declare-motion}. @anchor{extension elispobj-evil-declare-motion}@anchor{9} @deffn {Emacs Lisp Autofunction} (evil@w{-}declare@w{-}motion COMMAND) Declare @emph{COMMAND} to be a movement function. This ensures that it behaves correctly in visual state. @end deffn @anchor{extension elispobj-evil-define-motion}@anchor{10} @deffn {Emacs Lisp Autofunction} (evil@w{-}define@w{-}motion MOTION (COUNT ARGS...) DOC [[KEY VALUE]...] BODY...) Define a motion command @emph{MOTION}. @emph{ARGS} is a list of arguments. Motions can have any number of arguments, but the first (if any) has the predefined meaning of count. @emph{BODY} must execute the motion by moving point. Optional keyword arguments are: @itemize - @item @code{:type} - determines how the motion works after an operator (one of @code{inclusive}, @code{line}, @code{block} and @code{exclusive}, or a self-defined motion type) @item @code{:jump} - if non-nil, the previous position is stored in the jump list, so that it can be restored with @code{C-o} @end itemize @end deffn For example, this is a motion that moves the cursor forward by a number of characters: @example (evil-define-motion foo-forward (count) "Move to the right by COUNT characters." :type inclusive (forward-char (or count 1))) @end example The @emph{type} of a motion determines how it works when used together with an operator. Inclusive motions include the endpoint in the range being operated on, while exclusive motions do not. Line motions extend the whole range to linewise positions, effectively behaving as if the endpoint were really at the end of the line. Blockwise ranges behave as a “rectangle” on screen rather than a contiguous range of characters. @node Operators,Text objects,Motions,Extension @anchor{extension operators}@anchor{60} @section Operators An operator is a command that acts on the text moved over by a motion, such as @code{c} (change), @code{d} (delete) or @code{y} (yank or copy, not to be confused with “yank” in Emacs terminology which means @emph{paste}). @anchor{extension elispobj-evil-define-operator}@anchor{11} @deffn {Emacs Lisp Autofunction} (evil@w{-}define@w{-}operator OPERATOR (BEG END ARGS...) DOC [[KEY VALUE]...] BODY...) Define an operator command @emph{OPERATOR}. The operator acts on the range of characters @emph{BEG} through @emph{END}. @emph{BODY} must execute the operator by potentially manipulating the buffer contents, or otherwise causing side effects to happen. Optional keyword arguments are: @itemize - @item @code{:type} - force the input range to be of a given type (@code{inclusive}, @code{line}, @code{block}, and @code{exclusive}, or a self-defined motion type). @item @code{:motion} - use a predetermined motion instead of waiting for one from the keyboard. This does not affect the behavior in visual state, where selection boundaries are always used. @item @code{:repeat} - if non-nil (default), then @code{.} will repeat the operator. @item @code{:move-point} - if non-nil (default), the cursor will be moved to the beginning of the range before the body executes @item @code{:keep-visual} - if non-nil, the selection is not disabled when the operator is executed in visual state. By default, visual state is exited automatically. @end itemize @end deffn For example, this is an operator that performs ROT13 encryption on the text under consideration: @example (evil-define-operator evil-rot13 (beg end) "ROT13 encrypt text." (rot13-region beg end)) @end example Binding this to @code{g?} (where it is by default) will cause a key sequence such as @code{g?w} to encrypt from the current cursor to the end of the word. @node Text objects,Range types,Operators,Extension @anchor{extension text-objects}@anchor{61} @section Text objects Text objects are like motions in that they define a range over which an operator may act. Unlike motions, text objects can set both a beginning and an endpoint. In visual state, text objects alter both ends of the selection. Text objects are not directly usable in normal state. Instead, they are bound in the two keymaps @code{evil-inner-text-ojects-map} and @code{evil-outer-text-objects-map}, which are available in visual and operator-pending state under the keys @code{i} and @code{a} respectively. @anchor{extension elispobj-evil-define-text-object}@anchor{13} @deffn {Emacs Lisp Autofunction} (evil@w{-}define@w{-}text@w{-}object OBJECT (COUNT) DOC [[KEY VALUE]...] BODY...) Define a text object command @emph{OBJECT}. @emph{BODY} should return a range @code{(BEG END)} to the right of point if @emph{COUNT} is positive, and to the left of it if negative. Optional keyword arguments: @itemize - @item @code{:type} - determines how the range applies after an operator (@code{inclusive}, @code{line}, @code{block}, and @code{exclusive}, or a self-defined motion type). @item @code{:extend-selection} - if non-nil (default), the text object always enlarges the current selection. Otherwise, it replaces the current selection. @end itemize @end deffn For eample, this is a text object which selects the next three characters after the current location: @example (evil-define-text-object foo (count) "Select three characters." (list (point) (+ 3 (point)))) @end example For convenience, Evil provides several functions returning a list of positions which can be used for defining text objects. All of them follow the convention that a positive @emph{count} selects text after the current location, while negative @emph{count} selects text before it. @cartouche @quotation Note The @emph{thingatpt} library is used quite extensively in Evil to define text objects, and this dependency leaks through in the following functions. A @emph{thing} in this context is any symbol for which there is a function called @code{forward-THING} @footnote{@w{(1)} There are many more ways that a @emph{thing} can be defined, but the definition of @code{forward-THING} is perhaps the most straightforward way to go about it. } which moves past a number of @emph{things}. @end quotation @end cartouche @anchor{extension elispobj-evil-select-inner-object}@anchor{2d} @deffn {Emacs Lisp Autofunction} (evil@w{-}select@w{-}inner@w{-}object THING BEG END TYPE [COUNT LINE]) Return an inner text object range of @emph{COUNT} objects. If @emph{COUNT} is positive, return objects following point; if @emph{COUNT} is negative, return objects preceding point. If one is unspecified, the other is used with a negative argument. @emph{THING} is a symbol understood by @emph{thing-at-point}. @emph{BEG}, @emph{END} and @emph{TYPE} specify the current selection. If @emph{LINE} is non-nil, the text object should be linewise, otherwise it is character wise. @end deffn @anchor{extension elispobj-evil-select-an-object}@anchor{2c} @deffn {Emacs Lisp Autofunction} (evil@w{-}select@w{-}an@w{-}object THING BEG END TYPE COUNT [LINE]) Return an outer text object range of @emph{COUNT} objects. If @emph{COUNT} is positive, return objects following point; if @emph{COUNT} is negative, return objects preceding point. If one is unspecified, the other is used with a negative argument. @emph{THING} is a symbol understood by @emph{thing-at-point}. @emph{BEG}, @emph{END} and @emph{TYPE} specify the current selection. If @emph{LINE} is non-nil, the text object should be linewise, otherwise it is character wise. @end deffn @anchor{extension elispobj-evil-select-paren}@anchor{2e} @deffn {Emacs Lisp Autofunction} (evil@w{-}select@w{-}paren OPEN CLOSE BEG END TYPE COUNT [INCLUSIVE]) Return a range @code{(BEG END)} of @emph{COUNT} delimited text objects. @emph{OPEN} and @emph{CLOSE} specify the opening and closing delimiter, respectively. @emph{BEG} @emph{END} @emph{TYPE} are the currently selected (visual) range. If @emph{INCLUSIVE} is non-nil, @emph{OPEN} and @emph{CLOSE} are included in the range; otherwise they are excluded. The types of @emph{OPEN} and @emph{CLOSE} specify which kind of THING is used for parsing with @code{evil-select-block}. If @emph{OPEN} and @emph{CLOSE} are characters @code{evil-up-paren} is used. Otherwise @emph{OPEN} and @emph{CLOSE} must be regular expressions and @code{evil-up-block} is used. If the selection is exclusive, whitespace at the end or at the beginning of the selection until the end-of-line or beginning-of-line is ignored. @end deffn @node Range types,States,Text objects,Extension @anchor{extension range-types}@anchor{62} @section Range types A @emph{type} is a transformation acting on a pair of buffer positions. Evil defines the types @code{inclusive}, @code{line}, @code{block} and @code{exclusive}, which are used for motion ranges and visual selection. New types may be defined with the macro @emph{evil-define-type}. @anchor{extension elispobj-evil-define-type}@anchor{14} @deffn {Emacs Lisp Autofunction} (evil@w{-}define@w{-}type TYPE DOC [[KEY FUNC]...]) Define type @emph{TYPE}. @emph{DOC} is a general description and shows up in all docstrings. Optional keyword arguments: @itemize - @item @code{:expand} - expansion function. This function should accept two positions in the current buffer, BEG and END,and return a pair of expanded buffer positions. @item @code{:contract} - the opposite of @code{:expand}. Optional. @item @code{:one-to-one} - non-nil if expansion is one-to-one. This means that @code{:expand} followed by @code{:contract} always return the original range. @item @code{:normalize} - normalization function. This function should accept two unexpanded positions and adjust them before expansion. May be used to deal with buffer boundaries. @item @code{:string} - description function. Takes two buffer positions and returns a human-readable string. For example “2 lines” @end itemize If further keywords and functions are specified, they are assumed to be transformations on buffer positions, like @code{:expand} and @code{:contract}. @end deffn @node States,,Range types,Extension @anchor{extension states}@anchor{63} @section States States are defined with the macro @ref{12,,evil-define-state}, which takes care to define the necessary hooks, keymaps and variables, as well as a toggle function @code{evil-NAME-state} and a predicate function @code{evil-NAME-state-p} for checking whether the state is active. @anchor{extension elispobj-evil-define-state}@anchor{12} @deffn {Emacs Lisp Autofunction} (evil@w{-}define@w{-}state STATE DOC [[KEY VAL]...] BODY...) Define an Evil state @emph{STATE}. @emph{DOC} is a general description and shows up in all docstrings; the first line of the string should be the full name of the state. @emph{BODY} is executed each time the state is enabled or disabled. Optional keyword arguments: @itemize - @item @code{:tag} - the mode line indicator, e.g. “”. @item @code{:message} - string shown in the echo area when the state is activated. @item @code{:cursor} - default cursor specification. @item @code{:enable} - list of other state keymaps to enable when in this state. @item @code{:entry-hook} - list of functions to run when entering this state. @item @code{:exit-hook} - list of functions to run when exiting this state. @item @code{:suppress-keymap} - if non-nil, effectively disables bindings to @code{self-insert-command} by making @code{evil-suppress-map} the parent of the global state keymap. @end itemize The global keymap of this state will be @code{evil-test-state-map}, the local keymap will be @code{evil-test-state-local-map}, and so on. @end deffn For example: @example (evil-define-state test "Test state." :tag " " (message (if (evil-test-state-p) "Enabling test state." "Disabling test state."))) @end example @node Frequently Asked Questions,Internals,Extension,Top @anchor{faq doc}@anchor{64}@anchor{faq frequently-asked-questions}@anchor{65} @chapter Frequently Asked Questions @menu * Problems with the escape key in the terminal:: * Underscore is not a word character:: @end menu @node Problems with the escape key in the terminal,Underscore is not a word character,,Frequently Asked Questions @anchor{faq problems-with-the-escape-key-in-the-terminal}@anchor{66} @section Problems with the escape key in the terminal A common problem when using Evil in terminal mode is a certain delay after pressing the escape key. Even more, when pressing the escape key followed quickly by another key the command is recognized as @code{M-} instead of two separate keys: @code{ESC} followed by @code{}. In fact, it is perfectly valid to simulate @code{M-} by pressing @code{ESC } quickly (but see below). The reason for this is that in terminal mode a key sequence involving the meta key (or alt key) always generates a so called “escape sequence”, i.e. a sequence of two events sent to Emacs, the first being @code{ESC} and the second the key pressed simultaneously. The problem is that pressing the escape key itself also generates the @code{ESC} event. Thus, if Emacs (and therefore Evil) receives an @code{ESC} event there is no way to tell whether the escape key has been pressed (and no further event will arrive) or a @code{M-} combination has been pressed (and the @code{} event will arrive soon). In order to distinguish both situations Evil does the following. After receiving an @code{ESC} event Evil waits for a short time period (specified by the variable @ref{17,,evil-esc-delay} which defaults to 0.01 seconds) for another event. If no other event arrives Evil assumes that the plain escape key has been pressed, otherwise it assumes a @code{M-} combination has been pressed and combines the @code{ESC} event with the second one. Because a @code{M-} sequence usually generates both events in very quick succession, 0.01 seconds are usually enough and the delay is hardly noticeable by the user. If you use a terminal multiplexer like @emph{tmux} or @emph{screen} the situation may be worse. These multiplexers have exactly the same problem recognizing @code{M-} sequences and often introduce their own delay for the @code{ESC} key. There is no way for Evil to influence this delay. In order to reduce it you must reconfigure your terminal multiplexer. Note that this problem should not arise when using Evil in graphical mode. The reason is that in this case the escape key itself generates a different command, namely @code{escape} (a symbol) and hence Evil can distinguish whether the escape key or a @code{M-} combination has been pressed. But this also implies that pressing @code{ESC} followed by cannot be used to simulate @code{M-} in graphical mode! @node Underscore is not a word character,,Problems with the escape key in the terminal,Frequently Asked Questions @anchor{faq underscore-is-not-a-word-character}@anchor{67} @section Underscore is not a word character An underscore @code{_} is a word character in Vim. This means that word motions like @code{w} skip over underlines in a sequence of letters as if it was a letter itself. In contrast, in Evil the underscore is often a non-word character like operators, e.g. @code{+}. The reason is that Evil uses Emacs’ definition of a word and this definition does often not include the underscore. In Emacs word characters are determined by the syntax-class of the buffer. The syntax-class usually depends on the major-mode of this buffer. This has the advantage that the definition of a “word” may be adapted to the particular type of document being edited. Evil uses Emacs’ definition and does not simply use Vim’s definition in order to be consistent with other Emacs functions. For example, word characters are exactly those characters that are matched by the regular expression character class @code{[:word:]}. If you would be satisfied by having the @code{*} and @code{#} searches use symbols instead of words, this can be achieved by setting the @code{evil-symbol-word-search} variable to @code{t}. If you want the underscore to be recognised as word character for other motions, you can modify its entry in the syntax-table: @example (modify-syntax-entry ?_ "w") @end example This gives the underscore the ‘word’ syntax class. You can use a mode-hook to modify the syntax-table in all buffers of some mode, e.g.: @example (add-hook 'c-mode-common-hook (lambda () (modify-syntax-entry ?_ "w"))) @end example This gives the underscore the word syntax-class in all C-like buffers. Similarly to Emacs’ definition of a word, the definition of a “symbol” is also dependent on the syntax-class of the buffer, which often includes the underscore. The default text objects keymap associates kbd::@cite{o} with the symbol object, making kbd::@cite{cio} a good alternative to Vim’s kbd::@cite{ciw}, for example. The following will swap between the word and symbol objects in the keymap: @example (define-key evil-outer-text-objects-map "w" 'evil-a-symbol) (define-key evil-inner-text-objects-map "w" 'evil-inner-symbol) (define-key evil-outer-text-objects-map "o" 'evil-a-word) (define-key evil-inner-text-objects-map "o" 'evil-inner-word) @end example This will not change the motion keys, however. One way to make word motions operate as symbol motions is to alias the @code{evil-word} @emph{thing} @footnote{@w{(1)} Many of Evil’s text objects and motions are defined in terms of the @emph{thingatpt} library, which in this case are defined entirely in terms of @code{forward-THING} functions. Thus aliasing one to another should make all motions and text objects implemented in terms of that @emph{thing} behave the same. } to the @code{evil-symbol} thing: @example (defalias 'forward-evil-word 'forward-evil-symbol) @end example @node Internals,The GNU Free Documentation License,Frequently Asked Questions,Top @anchor{internals doc}@anchor{68}@anchor{internals internals}@anchor{69} @chapter Internals @menu * Command properties:: @end menu @node Command properties,,,Internals @anchor{internals command-properties}@anchor{6a} @section Command properties Evil defines @emph{command properties} to store information about commands @footnote{@w{(1)} In this context, a @emph{command} may mean any Evil motion, text object, operator or indeed other Emacs commands, which have not been defined through the Evil machinery. }, such as whether they should be repeated. A command property is a @code{:keyword} with an associated value, e.g. @code{:repeat nil}. @anchor{internals elispobj-evil-add-command-properties}@anchor{0} @deffn {Emacs Lisp Autofunction} (evil@w{-}add@w{-}command@w{-}properties COMMAND [PROPERTIES...]) Add @emph{PROPERTIES} to @emph{COMMAND}. @emph{PROPERTIES} should be a property list. To replace all properties at once, use @ref{2f,,evil-set-command-properties}. @end deffn @anchor{internals elispobj-evil-set-command-properties}@anchor{2f} @deffn {Emacs Lisp Autofunction} (evil@w{-}set@w{-}command@w{-}properties COMMAND [PROPERTIES...]) Replace all of @emph{COMMAND}’s properties with @emph{PROPERTIES}. @emph{PROPERTIES} should be a property list. This erases all previous properties; to only add properties, use @code{evil-set-command-property}. @end deffn @anchor{internals elispobj-evil-get-command-properties}@anchor{1a} @deffn {Emacs Lisp Autofunction} (evil@w{-}get@w{-}command@w{-}properties COMMAND) Return all Evil properties of @emph{COMMAND}. See also @ref{1b,,evil-get-command-property}. @end deffn @anchor{internals elispobj-evil-get-command-property}@anchor{1b} @deffn {Emacs Lisp Autofunction} (evil@w{-}get@w{-}command@w{-}property COMMAND PROPERTY [DEFAULT]) Return the value of Evil @emph{PROPERTY} of @emph{COMMAND}. If the command does not have the property, return @emph{DEFAULT}. See also @ref{1a,,evil-get-command-properties}. @end deffn @anchor{internals elispobj-evil-define-command}@anchor{e} @deffn {Emacs Lisp Autofunction} (evil@w{-}define@w{-}command COMMAND (ARGS...) DOC [[KEY VALUE]...] BODY...) Define a command @emph{COMMAND}. @end deffn For setting repeat properties, use the following functions: @anchor{internals elispobj-evil-declare-repeat}@anchor{b} @deffn {Emacs Lisp Autofunction} (evil@w{-}declare@w{-}repeat COMMAND) Declare @emph{COMMAND} to be repeatable. @end deffn @anchor{internals elispobj-evil-declare-not-repeat}@anchor{a} @deffn {Emacs Lisp Autofunction} (evil@w{-}declare@w{-}not@w{-}repeat COMMAND) Declare @emph{COMMAND} to be nonrepeatable. @end deffn @anchor{internals elispobj-evil-declare-change-repeat}@anchor{8} @deffn {Emacs Lisp Autofunction} (evil@w{-}declare@w{-}change@w{-}repeat COMMAND) Declare @emph{COMMAND} to be repeatable by buffer changes rather than keystrokes. @end deffn @node The GNU Free Documentation License,Emacs lisp functions and variables,Internals,Top @anchor{license doc}@anchor{6b}@anchor{license the-gnu-free-documentation-license}@anchor{6c} @chapter The GNU Free Documentation License Version 1.3, 3 November 2008 @quotation Copyright (c) 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc. @indicateurl{http://fsf.org/} Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed. @end quotation @enumerate 0 @item PREAMBLE The purpose of this License is to make a manual, textbook, or other functional and useful document @emph{free} in the sense of freedom: to assure everyone the effective freedom to copy and redistribute it, with or without modifying it, either commercially or noncommercially. Secondarily, this License preserves for the author and publisher a way to get credit for their work, while not being considered responsible for modifications made by others. This License is a kind of “copyleft”, which means that derivative works of the document must themselves be free in the same sense. It complements the GNU General Public License, which is a copyleft license designed for free software. We have designed this License in order to use it for manuals for free software, because free software needs free documentation: a free program should come with manuals providing the same freedoms that the software does. But this License is not limited to software manuals; it can be used for any textual work, regardless of subject matter or whether it is published as a printed book. We recommend this License principally for works whose purpose is instruction or reference. @item APPLICABILITY AND DEFINITIONS This License applies to any manual or other work, in any medium, that contains a notice placed by the copyright holder saying it can be distributed under the terms of this License. Such a notice grants a world-wide, royalty-free license, unlimited in duration, to use that work under the conditions stated herein. The “Document”, below, refers to any such manual or work. Any member of the public is a licensee, and is addressed as “you”. You accept the license if you copy, modify or distribute the work in a way requiring permission under copyright law. A “Modified Version” of the Document means any work containing the Document or a portion of it, either copied verbatim, or with modifications and/or translated into another language. A “Secondary Section” is a named appendix or a front-matter section of the Document that deals exclusively with the relationship of the publishers or authors of the Document to the Document’s overall subject (or to related matters) and contains nothing that could fall directly within that overall subject. (Thus, if the Document is in part a textbook of mathematics, a Secondary Section may not explain any mathematics.) The relationship could be a matter of historical connection with the subject or with related matters, or of legal, commercial, philosophical, ethical or political position regarding them. The “Invariant Sections” are certain Secondary Sections whose titles are designated, as being those of Invariant Sections, in the notice that says that the Document is released under this License. If a section does not fit the above definition of Secondary then it is not allowed to be designated as Invariant. The Document may contain zero Invariant Sections. If the Document does not identify any Invariant Sections then there are none. The “Cover Texts” are certain short passages of text that are listed, as Front-Cover Texts or Back-Cover Texts, in the notice that says that the Document is released under this License. A Front-Cover Text may be at most 5 words, and a Back-Cover Text may be at most 25 words. A “Transparent” copy of the Document means a machine-readable copy, represented in a format whose specification is available to the general public, that is suitable for revising the document straightforwardly with generic text editors or (for images composed of pixels) generic paint programs or (for drawings) some widely available drawing editor, and that is suitable for input to text formatters or for automatic translation to a variety of formats suitable for input to text formatters. A copy made in an otherwise Transparent file format whose markup, or absence of markup, has been arranged to thwart or discourage subsequent modification by readers is not Transparent. An image format is not Transparent if used for any substantial amount of text. A copy that is not “Transparent” is called “Opaque”. Examples of suitable formats for Transparent copies include plain ASCII without markup, Texinfo input format, LaTeX input format, SGML or XML using a publicly available DTD, and standard-conforming simple HTML, PostScript or PDF designed for human modification. Examples of transparent image formats include PNG, XCF and JPG. Opaque formats include proprietary formats that can be read and edited only by proprietary word processors, SGML or XML for which the DTD and/or processing tools are not generally available, and the machine-generated HTML, PostScript or PDF produced by some word processors for output purposes only. The “Title Page” means, for a printed book, the title page itself, plus such following pages as are needed to hold, legibly, the material this License requires to appear in the title page. For works in formats which do not have any title page as such, “Title Page” means the text near the most prominent appearance of the work’s title, preceding the beginning of the body of the text. The “publisher” means any person or entity that distributes copies of the Document to the public. A section “Entitled XYZ” means a named subunit of the Document whose title either is precisely XYZ or contains XYZ in parentheses following text that translates XYZ in another language. (Here XYZ stands for a specific section name mentioned below, such as “Acknowledgements”, “Dedications”, “Endorsements”, or “History”.) To “Preserve the Title” of such a section when you modify the Document means that it remains a section “Entitled XYZ” according to this definition. The Document may include Warranty Disclaimers next to the notice which states that this License applies to the Document. These Warranty Disclaimers are considered to be included by reference in this License, but only as regards disclaiming warranties: any other implication that these Warranty Disclaimers may have is void and has no effect on the meaning of this License. @item VERBATIM COPYING You may copy and distribute the Document in any medium, either commercially or noncommercially, provided that this License, the copyright notices, and the license notice saying this License applies to the Document are reproduced in all copies, and that you add no other conditions whatsoever to those of this License. You may not use technical measures to obstruct or control the reading or further copying of the copies you make or distribute. However, you may accept compensation in exchange for copies. If you distribute a large enough number of copies you must also follow the conditions in section 3. You may also lend copies, under the same conditions stated above, and you may publicly display copies. @item COPYING IN QUANTITY If you publish printed copies (or copies in media that commonly have printed covers) of the Document, numbering more than 100, and the Document’s license notice requires Cover Texts, you must enclose the copies in covers that carry, clearly and legibly, all these Cover Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on the back cover. Both covers must also clearly and legibly identify you as the publisher of these copies. The front cover must present the full title with all words of the title equally prominent and visible. You may add other material on the covers in addition. Copying with changes limited to the covers, as long as they preserve the title of the Document and satisfy these conditions, can be treated as verbatim copying in other respects. If the required texts for either cover are too voluminous to fit legibly, you should put the first ones listed (as many as fit reasonably) on the actual cover, and continue the rest onto adjacent pages. If you publish or distribute Opaque copies of the Document numbering more than 100, you must either include a machine-readable Transparent copy along with each Opaque copy, or state in or with each Opaque copy a computer-network location from which the general network-using public has access to download using public-standard network protocols a complete Transparent copy of the Document, free of added material. If you use the latter option, you must take reasonably prudent steps, when you begin distribution of Opaque copies in quantity, to ensure that this Transparent copy will remain thus accessible at the stated location until at least one year after the last time you distribute an Opaque copy (directly or through your agents or retailers) of that edition to the public. It is requested, but not required, that you contact the authors of the Document well before redistributing any large number of copies, to give them a chance to provide you with an updated version of the Document. @item MODIFICATIONS You may copy and distribute a Modified Version of the Document under the conditions of sections 2 and 3 above, provided that you release the Modified Version under precisely this License, with the Modified Version filling the role of the Document, thus licensing distribution and modification of the Modified Version to whoever possesses a copy of it. In addition, you must do these things in the Modified Version: @enumerate A @item Use in the Title Page (and on the covers, if any) a title distinct from that of the Document, and from those of previous versions (which should, if there were any, be listed in the History section of the Document). You may use the same title as a previous version if the original publisher of that version gives permission. @item List on the Title Page, as authors, one or more persons or entities responsible for authorship of the modifications in the Modified Version, together with at least five of the principal authors of the Document (all of its principal authors, if it has fewer than five), unless they release you from this requirement. @item State on the Title page the name of the publisher of the Modified Version, as the publisher. @item Preserve all the copyright notices of the Document. @item Add an appropriate copyright notice for your modifications adjacent to the other copyright notices. @item Include, immediately after the copyright notices, a license notice giving the public permission to use the Modified Version under the terms of this License, in the form shown in the Addendum below. @item Preserve in that license notice the full lists of Invariant Sections and required Cover Texts given in the Document’s license notice. @item Include an unaltered copy of this License. @item Preserve the section Entitled “History”, Preserve its Title, and add to it an item stating at least the title, year, new authors, and publisher of the Modified Version as given on the Title Page. If there is no section Entitled “History” in the Document, create one stating the title, year, authors, and publisher of the Document as given on its Title Page, then add an item describing the Modified Version as stated in the previous sentence. @item Preserve the network location, if any, given in the Document for public access to a Transparent copy of the Document, and likewise the network locations given in the Document for previous versions it was based on. These may be placed in the “History” section. You may omit a network location for a work that was published at least four years before the Document itself, or if the original publisher of the version it refers to gives permission. @item For any section Entitled “Acknowledgements” or “Dedications”, Preserve the Title of the section, and preserve in the section all the substance and tone of each of the contributor acknowledgements and/or dedications given therein. @item Preserve all the Invariant Sections of the Document, unaltered in their text and in their titles. Section numbers or the equivalent are not considered part of the section titles. @item Delete any section Entitled “Endorsements”. Such a section may not be included in the Modified Version. @item Do not retitle any existing section to be Entitled “Endorsements” or to conflict in title with any Invariant Section. @item Preserve any Warranty Disclaimers. @end enumerate If the Modified Version includes new front-matter sections or appendices that qualify as Secondary Sections and contain no material copied from the Document, you may at your option designate some or all of these sections as invariant. To do this, add their titles to the list of Invariant Sections in the Modified Version’s license notice. These titles must be distinct from any other section titles. You may add a section Entitled “Endorsements”, provided it contains nothing but endorsements of your Modified Version by various parties—for example, statements of peer review or that the text has been approved by an organization as the authoritative definition of a standard. You may add a passage of up to five words as a Front-Cover Text, and a passage of up to 25 words as a Back-Cover Text, to the end of the list of Cover Texts in the Modified Version. Only one passage of Front-Cover Text and one of Back-Cover Text may be added by (or through arrangements made by) any one entity. If the Document already includes a cover text for the same cover, previously added by you or by arrangement made by the same entity you are acting on behalf of, you may not add another; but you may replace the old one, on explicit permission from the previous publisher that added the old one. The author(s) and publisher(s) of the Document do not by this License give permission to use their names for publicity for or to assert or imply endorsement of any Modified Version. @item COMBINING DOCUMENTS You may combine the Document with other documents released under this License, under the terms defined in section 4 above for modified versions, provided that you include in the combination all of the Invariant Sections of all of the original documents, unmodified, and list them all as Invariant Sections of your combined work in its license notice, and that you preserve all their Warranty Disclaimers. The combined work need only contain one copy of this License, and multiple identical Invariant Sections may be replaced with a single copy. If there are multiple Invariant Sections with the same name but different contents, make the title of each such section unique by adding at the end of it, in parentheses, the name of the original author or publisher of that section if known, or else a unique number. Make the same adjustment to the section titles in the list of Invariant Sections in the license notice of the combined work. In the combination, you must combine any sections Entitled “History” in the various original documents, forming one section Entitled “History”; likewise combine any sections Entitled “Acknowledgements”, and any sections Entitled “Dedications”. You must delete all sections Entitled “Endorsements.” @item COLLECTIONS OF DOCUMENTS You may make a collection consisting of the Document and other documents released under this License, and replace the individual copies of this License in the various documents with a single copy that is included in the collection, provided that you follow the rules of this License for verbatim copying of each of the documents in all other respects. You may extract a single document from such a collection, and distribute it individually under this License, provided you insert a copy of this License into the extracted document, and follow this License in all other respects regarding verbatim copying of that document. @item AGGREGATION WITH INDEPENDENT WORKS A compilation of the Document or its derivatives with other separate and independent documents or works, in or on a volume of a storage or distribution medium, is called an “aggregate” if the copyright resulting from the compilation is not used to limit the legal rights of the compilation’s users beyond what the individual works permit. When the Document is included in an aggregate, this License does not apply to the other works in the aggregate which are not themselves derivative works of the Document. If the Cover Text requirement of section 3 is applicable to these copies of the Document, then if the Document is less than one half of the entire aggregate, the Document’s Cover Texts may be placed on covers that bracket the Document within the aggregate, or the electronic equivalent of covers if the Document is in electronic form. Otherwise they must appear on printed covers that bracket the whole aggregate. @item TRANSLATION Translation is considered a kind of modification, so you may distribute translations of the Document under the terms of section 4. Replacing Invariant Sections with translations requires special permission from their copyright holders, but you may include translations of some or all Invariant Sections in addition to the original versions of these Invariant Sections. You may include a translation of this License, and all the license notices in the Document, and any Warranty Disclaimers, provided that you also include the original English version of this License and the original versions of those notices and disclaimers. In case of a disagreement between the translation and the original version of this License or a notice or disclaimer, the original version will prevail. If a section in the Document is Entitled “Acknowledgements”, “Dedications”, or “History”, the requirement (section 4) to Preserve its Title (section 1) will typically require changing the actual title. @item TERMINATION You may not copy, modify, sublicense, or distribute the Document except as expressly provided under this License. Any attempt otherwise to copy, modify, sublicense, or distribute it is void, and will automatically terminate your rights under this License. However, if you cease all violation of this License, then your license from a particular copyright holder is reinstated (a) provisionally, unless and until the copyright holder explicitly and finally terminates your license, and (b) permanently, if the copyright holder fails to notify you of the violation by some reasonable means prior to 60 days after the cessation. Moreover, your license from a particular copyright holder is reinstated permanently if the copyright holder notifies you of the violation by some reasonable means, this is the first time you have received notice of violation of this License (for any work) from that copyright holder, and you cure the violation prior to 30 days after your receipt of the notice. Termination of your rights under this section does not terminate the licenses of parties who have received copies or rights from you under this License. If your rights have been terminated and not permanently reinstated, receipt of a copy of some or all of the same material does not give you any rights to use it. @item FUTURE REVISIONS OF THIS LICENSE @end enumerate @quotation The Free Software Foundation may publish new, revised versions of the GNU Free Documentation License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. See @indicateurl{http://www.gnu.org/copyleft}. Each version of the License is given a distinguishing version number. If the Document specifies that a particular numbered version of this License “or any later version” applies to it, you have the option of following the terms and conditions either of that specified version or of any later version that has been published (not as a draft) by the Free Software Foundation. If the Document does not specify a version number of this License, you may choose any version ever published (not as a draft) by the Free Software Foundation. If the Document specifies that a proxy can decide which future versions of this License can be used, that proxy’s public statement of acceptance of a version permanently authorizes you to choose that version for the Document. @end quotation @enumerate 11 @item RELICENSING @end enumerate @quotation “Massive Multiauthor Collaboration Site” (or “MMC Site”) means any World Wide Web server that publishes copyrightable works and also provides prominent facilities for anybody to edit those works. A public wiki that anybody can edit is an example of such a server. A “Massive Multiauthor Collaboration” (or “MMC”) contained in the site means any set of copyrightable works thus published on the MMC site. “CC-BY-SA” means the Creative Commons Attribution-Share Alike 3.0 license published by Creative Commons Corporation, a not-for-profit corporation with a principal place of business in San Francisco, California, as well as future copyleft versions of that license published by that same organization. “Incorporate” means to publish or republish a Document, in whole or in part, as part of another Document. An MMC is “eligible for relicensing” if it is licensed under this License, and if all works that were first published under this License somewhere other than this MMC, and subsequently incorporated in whole or in part into the MMC, (1) had no cover texts or invariant sections, and (2) were thus incorporated prior to November 1, 2008. The operator of an MMC Site may republish an MMC contained in the site under CC-BY-SA on the same site at any time before August 1, 2009, provided the MMC is eligible for relicensing. @end quotation @node Emacs lisp functions and variables,,The GNU Free Documentation License,Top @unnumbered Emacs lisp functions and variables @menu * evil-add-command-properties: 0. * evil-auto-balance-windows: 1. * evil-auto-indent: 2. * evil-backspace-join-lines: 3. * evil-bigword: 4. * evil-buffer-regexps: 5. * evil-complete-all-buffers: 6. * evil-cross-lines: 7. * evil-declare-change-repeat: 8. * evil-declare-motion: 9. * evil-declare-not-repeat: a. * evil-declare-repeat: b. * evil-default-cursor: c. * evil-default-state: d. * evil-define-command: e. * evil-define-key: f. * evil-define-motion: 10. * evil-define-operator: 11. * evil-define-state: 12. * evil-define-text-object: 13. * evil-define-type: 14. * evil-disable-insert-state-bindings: 15. * evil-echo-state: 16. * evil-esc-delay: 17. * evil-ex-hl-update-delay: 18. * evil-flash-delay: 19. * evil-get-command-properties: 1a. * evil-get-command-property: 1b. * evil-global-set-key: 1c. * evil-highlight-closing-paren-at-point-states: 1d. * evil-indent-convert-tabs: 1e. * evil-intercept-esc: 1f. * evil-kbd-macro-suppress-motion-error: 20. * evil-kill-on-visual-paste: 21. * evil-local-set-key: 22. * evil-mode-line-format: 23. * evil-mouse-word: 24. * evil-move-beyond-eol: 25. * evil-move-cursor-back: 26. * evil-regexp-search: 27. * evil-repeat-move-cursor: 28. * evil-respect-visual-line-mode: 29. * evil-search-module: 2a. * evil-search-wrap: 2b. * evil-select-an-object: 2c. * evil-select-inner-object: 2d. * evil-select-paren: 2e. * evil-set-command-properties: 2f. * evil-set-initial-state: 30. * evil-set-leader: 31. * evil-shift-round: 32. * evil-shift-width: 33. * evil-show-paren-range: 34. * evil-split-window-below: 35. * evil-start-of-line: 36. * evil-toggle-key: 37. * evil-track-eol: 38. * evil-undo-system: 39. * evil-vsplit-window-right: 3a. * evil-want-C-d-scroll: 3b. * evil-want-C-i-jump: 3c. * evil-want-C-u-delete: 3d. * evil-want-C-u-scroll: 3e. * evil-want-C-w-delete: 3f. * evil-want-C-w-in-emacs-state: 40. * evil-want-empty-ex-last-command: 41. * evil-want-fine-undo: 42. * evil-want-Y-yank-to-eol: 43. @end menu @c %**end of body @bye