patch 8.2.5011: Replacing an autocommand requires several lines
Problem: Replacing an autocommand requires several lines.
Solution: Add the "replace" flag to autocmd_add(). (Yegappan Lakshmanan,
closes #10473)
diff --git a/runtime/doc/autocmd.txt b/runtime/doc/autocmd.txt
index fb4532f..0ef7c4c 100644
--- a/runtime/doc/autocmd.txt
+++ b/runtime/doc/autocmd.txt
@@ -47,6 +47,28 @@
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 @@
}
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 29cc506..5b20ea3 100644
--- a/runtime/doc/builtin.txt
+++ b/runtime/doc/builtin.txt
@@ -940,13 +940,19 @@
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 @@
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