patch 8.2.4981: it is not possible to manipulate autocommands
Problem: It is not possible to manipulate autocommands.
Solution: Add functions to add, get and set autocommands. (Yegappan
Lakshmanan, closes #10291)
diff --git a/runtime/doc/autocmd.txt b/runtime/doc/autocmd.txt
index 0bbfd34..fb4532f 100644
--- a/runtime/doc/autocmd.txt
+++ b/runtime/doc/autocmd.txt
@@ -82,6 +82,9 @@
/<start
}
+The |autocmd_add()| function can be used to add a list of autocmds and autocmd
+groups from a Vim script.
+
Note: The ":autocmd" command can only be followed by another command when the
'|' appears where the pattern is expected. This works: >
:augroup mine | au! BufRead | augroup END
@@ -146,6 +149,9 @@
==============================================================================
3. Removing autocommands *autocmd-remove*
+In addition to the below described commands, the |autocmd_delete()| function can
+be used to remove a list of autocmds and autocmd groups from a Vim script.
+
:au[tocmd]! [group] {event} {aupat} [++once] [++nested] {cmd}
Remove all autocommands associated with {event} and
{aupat}, and add the command {cmd}.
@@ -198,6 +204,9 @@
In order to list buffer-local autocommands, use a pattern in the form <buffer>
or <buffer=N>. See |autocmd-buflocal|.
+The |autocmd_get()| function can be used from a Vim script to get a list of
+autocmds.
+
*:autocmd-verbose*
When 'verbose' is non-zero, listing an autocommand will also display where it
was last defined. Example: >
diff --git a/runtime/doc/builtin.txt b/runtime/doc/builtin.txt
index 538f099..44997f3 100644
--- a/runtime/doc/builtin.txt
+++ b/runtime/doc/builtin.txt
@@ -60,6 +60,9 @@
assert_true({actual} [, {msg}]) Number assert {actual} is true
atan({expr}) Float arc tangent of {expr}
atan2({expr1}, {expr2}) Float arc tangent of {expr1} / {expr2}
+autocmd_add({acmds}) Bool add a list of autocmds and groups
+autocmd_delete({acmds}) Bool delete a list of autocmds and groups
+autocmd_get([{opts}]) List return a list of autocmds
balloon_gettext() String current text in the balloon
balloon_show({expr}) none show {expr} inside the balloon
balloon_split({msg}) List split {msg} as used for a balloon
@@ -922,6 +925,145 @@
<
{only available when compiled with the |+float| feature}
+
+autocmd_add({acmds}) *autocmd_add()*
+ Adds a List of autocmds and autocmd groups.
+
+ The {acmds} argument is a List where each item is a Dict with
+ the following optional items:
+ bufnr buffer number to add a buffer-local autocmd.
+ If this item is specified, then the "pattern"
+ item is ignored.
+ cmd Ex command to execute for this autocmd event
+ event autocmd event name. Refer to |autocmd-events|.
+ group autocmd group name. Refer to |autocmd-groups|.
+ 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|.
+ pattern autocmd pattern string. Refer to
+ |autocmd-patterns|. If "bufnr" item is
+ present, then this item is ignored.
+
+ Returns v:true on success and v:false on failure.
+ Examples: >
+ " Create a buffer-local autocmd for buffer 5
+ let acmd = {}
+ let acmd.group = 'MyGroup'
+ let acmd.event = 'BufEnter'
+ let acmd.bufnr = 5
+ let acmd.cmd = 'call BufEnterFunc()'
+ call autocmd_add([acmd])
+
+ Can also be used as a |method|: >
+ GetAutocmdList()->autocmd_add()
+<
+autocmd_delete({acmds}) *autocmd_delete()*
+ Deletes a List of autocmds and autocmd groups.
+
+ The {acmds} argument is a List where each item is a Dict with
+ the following optional items:
+ bufnr buffer number to delete a buffer-local autocmd.
+ If this item is specified, then the "pattern"
+ item is ignored.
+ cmd Ex command for this autocmd event
+ event autocmd event name. Refer to |autocmd-events|.
+ If '*' then all the autocmd events in this
+ group are deleted.
+ group autocmd group name. Refer to |autocmd-groups|.
+ If not specified or empty, then the default
+ group is used.
+ nested set to v:true for a nested autocmd.
+ Refer to |autocmd-nested|.
+ once set to v:true for an 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.
+
+ If only {group} is specified in a {acmds} entry and {event},
+ {pattern} and {cmd} are not specified, then that autocmd group
+ is deleted.
+
+ Returns v:true on success and v:false on failure.
+ Examples: >
+ " :autocmd! BufLeave *.vim
+ let acmd = #{event: 'BufLeave', pattern: '*.vim'}
+ call autocmd_delete([acmd]})
+ " :autocmd! MyGroup1 BufLeave
+ let acmd = #{group: 'MyGroup1', event: 'BufLeave'}
+ call autocmd_delete([acmd])
+ " :autocmd! MyGroup2 BufEnter *.c
+ let acmd = #{group: 'MyGroup2', event: 'BufEnter',
+ \ pattern: '*.c'}
+ " :autocmd! MyGroup2 * *.c
+ let acmd = #{group: 'MyGroup2', event: '*',
+ \ pattern: '*.c'}
+ call autocmd_delete([acmd])
+ " :autocmd! MyGroup3
+ let acmd = #{group: 'MyGroup3'}
+ call autocmd_delete([acmd])
+<
+ Can also be used as a |method|: >
+ GetAutocmdList()->autocmd_delete()
+
+autocmd_get([{opts}]) *autocmd_get()*
+ Returns a |List| of autocmds. If {opts} is not supplied, then
+ returns the autocmds for all the events in all the groups.
+
+ The optional {opts} Dict argument supports the following
+ items:
+ group Autocmd group name. If specified, returns only
+ the autocmds defined in this group. If the
+ specified group doesn't exist, results in an
+ error message. If set to an empty string,
+ then the default autocmd group is used.
+ event Autocmd event name. If specified, returns only
+ the autocmds defined for this event. If set
+ to "*", then returns autocmds for all the
+ events. If the specified event doesn't exist,
+ results in an error message.
+ pattern Autocmd pattern. If specified, returns only
+ the autocmds defined for this pattern.
+ A combination of the above three times can be supplied in
+ {opts}.
+
+ Each Dict in the returned List contains the following items:
+ bufnr For buffer-local autocmds, buffer number where
+ the autocmd is defined.
+ 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|.
+ 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
+ group, then separate items are returned for each command.
+
+ Examples: >
+ " :autocmd MyGroup
+ echo autocmd_get(#{group: 'Mygroup'})
+ " :autocmd G BufUnload
+ echo autocmd_get(#{group: 'G', event: 'BufUnload'})
+ " :autocmd G * *.ts
+ let acmd = #{group: 'G', event: '*', pattern: '*.ts'}
+ echo autocmd_get(acmd)
+ " :autocmd Syntax
+ echo autocmd_get(#{event: 'Syntax'})
+ " :autocmd G BufEnter *.ts
+ let acmd = #{group: 'G', event: 'BufEnter',
+ \ pattern: '*.ts'}
+ echo autocmd_get(acmd)
+<
+ Can also be used as a |method|: >
+ Getopts()->autocmd_get()
+<
balloon_gettext() *balloon_gettext()*
Return the current text in the balloon. Only for the string,
not used for the List.
diff --git a/runtime/doc/usr_41.txt b/runtime/doc/usr_41.txt
index 54af80c..162eb9d 100644
--- a/runtime/doc/usr_41.txt
+++ b/runtime/doc/usr_41.txt
@@ -925,6 +925,11 @@
reltimestr() convert reltime() result to a string
reltimefloat() convert reltime() result to a Float
+Autocmds: *autocmd-functions*
+ autocmd_add() add a list of autocmds and groups
+ autocmd_delete() delete a list of autocmds and groups
+ autocmd_get() return a list of autocmds
+
*buffer-functions* *window-functions* *arg-functions*
Buffers, windows and the argument list:
argc() number of entries in the argument list