diff options
author | Yegappan Lakshmanan <yegappan@yahoo.com> | 2022-05-24 11:40:11 +0100 |
---|---|---|
committer | Bram Moolenaar <Bram@vim.org> | 2022-05-24 11:40:11 +0100 |
commit | 971f6825ee845828bd5c8869487928a3f32cd467 (patch) | |
tree | 05a3c033c0ed013b0b4f80feb4d163aa1d2f1e14 /runtime | |
parent | c9a431c7638ecebb6f2cb3eabd0e1b2b5e269c1e (diff) |
patch 8.2.5011: Replacing an autocommand requires several linesv8.2.5011
Problem: Replacing an autocommand requires several lines.
Solution: Add the "replace" flag to autocmd_add(). (Yegappan Lakshmanan,
closes #10473)
Diffstat (limited to 'runtime')
-rw-r--r-- | runtime/doc/autocmd.txt | 25 | ||||
-rw-r--r-- | runtime/doc/builtin.txt | 22 |
2 files changed, 38 insertions, 9 deletions
diff --git a/runtime/doc/autocmd.txt b/runtime/doc/autocmd.txt index fb4532fc4e..0ef7c4c67b 100644 --- a/runtime/doc/autocmd.txt +++ b/runtime/doc/autocmd.txt @@ -47,6 +47,28 @@ effects. Be careful not to destroy your text. It's a good idea to use the same autocommands for the File* and Buf* events when possible. +Recommended use: +- Always use a group, so that it's easy to delete the autocommand. +- Keep the command itself short, call a function to do more work. +- Make it so that the script it is defined it can be sourced several times + without the autocommand being repeated. + +Example in Vim9 script: > + autocmd_add({replace: true, + group: 'DemoGroup', + event: 'BufEnter', + pattern: '*.txt', + cmd: 'call DemoBufEnter()' + }) + +In legacy script: > + call autocmd_add(#{replace: v:true, + \ group: 'DemoGroup', + \ event: 'BufEnter', + \ pattern: '*.txt', + \ cmd: 'call DemoBufEnter()' + \ }) + ============================================================================== 2. Defining autocommands *autocmd-define* @@ -83,7 +105,8 @@ triggered. } The |autocmd_add()| function can be used to add a list of autocmds and autocmd -groups from a Vim script. +groups from a Vim script. It is preferred if you have anything that would +require using `:execute` with `:autocmd`. Note: The ":autocmd" command can only be followed by another command when the '|' appears where the pattern is expected. This works: > diff --git a/runtime/doc/builtin.txt b/runtime/doc/builtin.txt index 29cc506273..5b20ea3322 100644 --- a/runtime/doc/builtin.txt +++ b/runtime/doc/builtin.txt @@ -940,13 +940,19 @@ autocmd_add({acmds}) *autocmd_add()* If this group doesn't exist then it is created. If not specified or empty, then the default group is used. - nested set to v:true to add a nested autocmd. - Refer to |autocmd-nested|. - once set to v:true to add a autocmd which executes - only once. Refer to |autocmd-once|. + nested boolean flag, set to v:true to add a nested + autocmd. Refer to |autocmd-nested|. + once boolean flag, set to v:true to add a autocmd + which executes only once. Refer to + |autocmd-once|. pattern autocmd pattern string. Refer to |autocmd-patterns|. If "bufnr" item is present, then this item is ignored. + replace boolean flag, set to v:true to remove all the + commands associated with the specified autocmd + event and group and add the {cmd}. This is + useful to avoid adding the same command + multiple times for a autocmd event in a group. Returns v:true on success and v:false on failure. Examples: > @@ -1037,10 +1043,10 @@ autocmd_get([{opts}]) *autocmd_get()* cmd Command executed for this autocmd. event Autocmd event name. group Autocmd group name. - nested Set to v:true for a nested autocmd. See - |autocmd-nested|. - once Set to v:true, if the autocmd will be executed - only once. See |autocmd-once|. + nested Boolean flag, set to v:true for a nested + autocmd. See |autocmd-nested|. + once Boolean flag, set to v:true, if the autocmd + will be executed only once. See |autocmd-once|. pattern Autocmd pattern. For a buffer-local autocmd, this will be of the form "<buffer=n>". If there are multiple commands for an autocmd event in a |