diff options
Diffstat (limited to 'runtime/doc/autocmd.txt')
| -rw-r--r-- | runtime/doc/autocmd.txt | 141 |
1 files changed, 102 insertions, 39 deletions
diff --git a/runtime/doc/autocmd.txt b/runtime/doc/autocmd.txt index 2737ac9b9f..07158982f2 100644 --- a/runtime/doc/autocmd.txt +++ b/runtime/doc/autocmd.txt @@ -40,10 +40,10 @@ effects. Be careful not to destroy your text. 2. Defining autocommands *autocmd-define* *:au* *:autocmd* -:au[tocmd] [group] {event} {pat} [++once] [++nested] {cmd} +:au[tocmd] [group] {event} {aupat} [++once] [++nested] {cmd} Add {cmd} to the list of commands that Vim will execute automatically on {event} for a file matching - {pat} |autocmd-pattern|. + {aupat} |autocmd-pattern|. Note: A quote character is seen as argument to the :autocmd and won't start a comment. Nvim always adds {cmd} after existing autocommands so @@ -57,7 +57,7 @@ The special pattern <buffer> or <buffer=N> defines a buffer-local autocommand. See |autocmd-buflocal|. Note: The ":autocmd" command can only be followed by another command when the -'|' appears before {cmd}. This works: > +'|' appears where the pattern is expected. This works: > :augroup mine | au! BufRead | augroup END But this sees "augroup" as part of the defined command: > :augroup mine | au! BufRead * | augroup END @@ -119,19 +119,19 @@ prompt. When one command outputs two messages this can happen anyway. ============================================================================== 3. Removing autocommands *autocmd-remove* -:au[tocmd]! [group] {event} {pat} [++once] [++nested] {cmd} +:au[tocmd]! [group] {event} {aupat} [++once] [++nested] {cmd} Remove all autocommands associated with {event} and - {pat}, and add the command {cmd}. + {aupat}, and add the command {cmd}. See |autocmd-once| for [++once]. See |autocmd-nested| for [++nested]. -:au[tocmd]! [group] {event} {pat} +:au[tocmd]! [group] {event} {aupat} Remove all autocommands associated with {event} and - {pat}. + {aupat}. -:au[tocmd]! [group] * {pat} - Remove all autocommands associated with {pat} for all - events. +:au[tocmd]! [group] * {aupat} + Remove all autocommands associated with {aupat} for + all events. :au[tocmd]! [group] {event} Remove ALL autocommands for {event}. @@ -151,12 +151,12 @@ with ":augroup"); otherwise, Vim uses the group defined with [group]. ============================================================================== 4. Listing autocommands *autocmd-list* -:au[tocmd] [group] {event} {pat} +:au[tocmd] [group] {event} {aupat} Show the autocommands associated with {event} and - {pat}. + {aupat}. -:au[tocmd] [group] * {pat} - Show the autocommands associated with {pat} for all +:au[tocmd] [group] * {aupat} + Show the autocommands associated with {aupat} for all events. :au[tocmd] [group] {event} @@ -499,10 +499,10 @@ CursorMoved After the cursor was moved in Normal or Visual mode or to another window. Also when the text of the cursor line has been changed, e.g. with "x", "rx" or "p". - Not triggered when there is typeahead, while - executing a script file, when an operator is - pending, or when moving to another window while - remaining at the same cursor position. + Not always triggered when there is typeahead, + while executing commands in a script file, or + when an operator is pending. Always triggered + when moving to another window. For an example see |match-parens|. Note: Cannot be skipped with |:noautocmd|. Careful: This is triggered very often, don't @@ -525,8 +525,19 @@ DirChanged After the |current-directory| was changed. "global" to trigger on `:cd` "auto" to trigger on 'autochdir'. Sets these |v:event| keys: - cwd: current working directory - scope: "global", "tab", "window" + cwd: current working directory + scope: "global", "tabpage", "window" + changed_window: v:true if we fired the event + switching window (or tab) + <afile> is set to the new directory name. + Non-recursive (event cannot trigger itself). + *DirChangedPre* +DirChangedPre When the |current-directory| is going to be + changed, as with |DirChanged|. + The pattern is like with |DirChanged|. + Sets these |v:event| keys: + directory: new working directory + scope: "global", "tabpage", "window" changed_window: v:true if we fired the event switching window (or tab) <afile> is set to the new directory name. @@ -663,15 +674,19 @@ FuncUndefined When a user function is used but it isn't alternative is to use an autoloaded function. See |autoload-functions|. *UIEnter* -UIEnter After a UI connects via |nvim_ui_attach()|, - after VimEnter. Can be used for GUI-specific - configuration. +UIEnter After a UI connects via |nvim_ui_attach()|, or + after builtin TUI is started, after |VimEnter|. Sets these |v:event| keys: - chan + chan: 0 for builtin TUI + 1 for |--embed| + |channel-id| of the UI otherwise *UILeave* -UILeave After a UI disconnects from Nvim. +UILeave After a UI disconnects from Nvim, or after + builtin TUI is stopped, after |VimLeave|. Sets these |v:event| keys: - chan + chan: 0 for builtin TUI + 1 for |--embed| + |channel-id| of the UI otherwise *InsertChange* InsertChange When typing <Insert> while in Insert or Replace mode. The |v:insertmode| variable @@ -718,7 +733,27 @@ MenuPopup Just before showing the popup menu (under the o Operator-pending i Insert c Command line - *OptionSet* + *ModeChanged* +ModeChanged After changing the mode. The pattern is + matched against `'old_mode:new_mode'`, for + example match against `*:c` to simulate + |CmdlineEnter|. + The following values of |v:event| are set: + old_mode The mode before it changed. + new_mode The new mode as also returned + by |mode()| called with a + non-zero argument. + When ModeChanged is triggered, old_mode will + have the value of new_mode when the event was + last triggered. + This will be triggered on every minor mode + change. + Usage example to use relative line numbers + when entering visual mode: > + :au ModeChanged [vV\x16]*:* let &l:rnu = mode() =~# '^[vV\x16]' + :au ModeChanged *:[vV\x16]* let &l:rnu = mode() =~# '^[vV\x16]' + :au WinEnter,WinLeave * let &l:rnu = mode() =~# '^[vV\x16]' +< *OptionSet* OptionSet After setting an option (except during |startup|). The |autocmd-pattern| is matched against the long option name. |<amatch>| @@ -793,7 +828,7 @@ QuitPre When using `:quit`, `:wq` or `:qall`, before before QuitPre is triggered. Can be used to close any non-essential window if the current window is the last ordinary window. - See also |ExitPre|, ||WinClosed|. + See also |ExitPre|, |WinClosed|. *RemoteReply* RemoteReply When a reply from a Vim that functions as server was received |server2client()|. The @@ -804,6 +839,25 @@ RemoteReply When a reply from a Vim that functions as Note that even if an autocommand is defined, the reply should be read with |remote_read()| to consume it. + *SearchWrapped* +SearchWrapped After making a search with |n| or |N| if the + search wraps around the document back to + the start/finish respectively. + *RecordingEnter* +RecordingEnter When a macro starts recording. + The pattern is the current file name, and + |reg_recording()| is the current register that + is used. + *RecordingLeave* +RecordingLeave When a macro stops recording. + The pattern is the current file name, and + |reg_recording()| is the recorded + register. + |reg_recorded()| is only updated after this + event. + Sets these |v:event| keys: + regcontents + regname *SessionLoadPost* SessionLoadPost After loading the session file created using the |:mksession| command. @@ -816,7 +870,7 @@ ShellCmdPost After executing a shell command with |:!cmd|, *Signal* Signal After Nvim receives a signal. The pattern is matched against the signal name. Only - "SIGUSR1" is supported. Example: > + "SIGUSR1" and "SIGWINCH" are supported. Example: > autocmd Signal SIGUSR1 call some#func() < *ShellFilterPost* ShellFilterPost After executing a shell command with @@ -1025,27 +1079,36 @@ WinLeave Before leaving a window. If the window to be executes the BufLeave autocommands before the WinLeave autocommands (but not for ":new"). Not used for ":qa" or ":q" when exiting Vim. - After WinClosed. + Before WinClosed. *WinNew* WinNew When a new window was created. Not done for the first window, when Vim has just started. Before WinEnter. - *WinScrolled* -WinScrolled After scrolling the viewport of the current - window. + *WinScrolled* +WinScrolled After scrolling the content of a window or + resizing a window. + The pattern is matched against the + |window-ID|. Both <amatch> and <afile> are + set to the |window-ID|. + Non-recursive (the event cannot trigger + itself). However, if the command causes the + window to scroll or change size another + WinScrolled event will be triggered later. + Does not trigger when the command is added, + only after the first scroll or resize. ============================================================================== -6. Patterns *autocmd-pattern* *{pat}* +6. Patterns *autocmd-pattern* *{aupat}* -The {pat} argument can be a comma separated list. This works as if the -command was given with each pattern separately. Thus this command: > +The {aupat} argument of `:autocmd` can be a comma-separated list. This works +as if the command was given with each pattern separately. Thus this command: > :autocmd BufRead *.txt,*.info set et Is equivalent to: > :autocmd BufRead *.txt set et :autocmd BufRead *.info set et -The file pattern {pat} is tested for a match against the file name in one of +The file pattern {aupat} is tested for a match against the file name in one of two ways: 1. When there is no '/' in the pattern, Vim checks for a match against only the tail part of the file name (without its leading directory path). @@ -1356,7 +1419,7 @@ Examples for reading and writing compressed files: > : autocmd BufReadPre,FileReadPre *.gz set bin : autocmd BufReadPost,FileReadPost *.gz '[,']!gunzip : autocmd BufReadPost,FileReadPost *.gz set nobin - : autocmd BufReadPost,FileReadPost *.gz execute ":doautocmd BufReadPost " . expand("%:r") + : autocmd BufReadPost,FileReadPost *.gz execute ":doautocmd BufReadPost " .. expand("%:r") : autocmd BufWritePost,FileWritePost *.gz !mv <afile> <afile>:r : autocmd BufWritePost,FileWritePost *.gz !gzip <afile>:r @@ -1455,7 +1518,7 @@ To insert the current date and time in a *.html file when writing it: > : else : let l = line("$") : endif - : exe "1," . l . "g/Last modified: /s/Last modified: .*/Last modified: " . + : exe "1," .. l .. "g/Last modified: /s/Last modified: .*/Last modified: " .. : \ strftime("%Y %b %d") :endfun |