Skip to content

Commit 1755a91

Browse files
yegappanbrammool
yegappan
authored and
brammool
committed
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)
1 parent aaadb5b commit 1755a91

File tree

9 files changed

+801
-1
lines changed

9 files changed

+801
-1
lines changed

‎runtime/doc/autocmd.txt‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -82,6 +82,9 @@ triggered.
8282
/<start
8383
}
8484
85+
The |autocmd_add()| function can be used to add a list of autocmds and autocmd
86+
groups from a Vim script.
87+
8588
Note: The ":autocmd" command can only be followed by another command when the
8689
'|' appears where the pattern is expected. This works: >
8790
:augroup mine | au! BufRead | augroup END
@@ -146,6 +149,9 @@ prompt. When one command outputs two messages this can happen anyway.
146149
==============================================================================
147150
3. Removing autocommands *autocmd-remove*
148151

152+
In addition to the below described commands, the |autocmd_delete()| function can
153+
be used to remove a list of autocmds and autocmd groups from a Vim script.
154+
149155
:au[tocmd]! [group] {event} {aupat} [++once] [++nested] {cmd}
150156
Remove all autocommands associated with {event} and
151157
{aupat}, and add the command {cmd}.
@@ -198,6 +204,9 @@ argument behavior differs from that for defining and removing autocommands.
198204
In order to list buffer-local autocommands, use a pattern in the form <buffer>
199205
or <buffer=N>. See |autocmd-buflocal|.
200206

207+
The |autocmd_get()| function can be used from a Vim script to get a list of
208+
autocmds.
209+
201210
*:autocmd-verbose*
202211
When 'verbose' is non-zero, listing an autocommand will also display where it
203212
was last defined. Example: >

‎runtime/doc/builtin.txt‎

Lines changed: 142 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -60,6 +60,9 @@ assert_report({msg}) Number report a test failure
6060
assert_true({actual} [, {msg}]) Number assert {actual} is true
6161
atan({expr}) Float arc tangent of {expr}
6262
atan2({expr1}, {expr2}) Float arc tangent of {expr1} / {expr2}
63+
autocmd_add({acmds}) Bool add a list of autocmds and groups
64+
autocmd_delete({acmds}) Bool delete a list of autocmds and groups
65+
autocmd_get([{opts}]) List return a list of autocmds
6366
balloon_gettext() String current text in the balloon
6467
balloon_show({expr}) none show {expr} inside the balloon
6568
balloon_split({msg}) List split {msg} as used for a balloon
@@ -922,6 +925,145 @@ atan2({expr1}, {expr2}) *atan2()*
922925
<
923926
{only available when compiled with the |+float| feature}
924927

928+
929+
autocmd_add({acmds}) *autocmd_add()*
930+
Adds a List of autocmds and autocmd groups.
931+
932+
The {acmds} argument is a List where each item is a Dict with
933+
the following optional items:
934+
bufnr buffer number to add a buffer-local autocmd.
935+
If this item is specified, then the "pattern"
936+
item is ignored.
937+
cmd Ex command to execute for this autocmd event
938+
event autocmd event name. Refer to |autocmd-events|.
939+
group autocmd group name. Refer to |autocmd-groups|.
940+
If this group doesn't exist then it is
941+
created. If not specified or empty, then the
942+
default group is used.
943+
nested set to v:true to add a nested autocmd.
944+
Refer to |autocmd-nested|.
945+
once set to v:true to add a autocmd which executes
946+
only once. Refer to |autocmd-once|.
947+
pattern autocmd pattern string. Refer to
948+
|autocmd-patterns|. If "bufnr" item is
949+
present, then this item is ignored.
950+
951+
Returns v:true on success and v:false on failure.
952+
Examples: >
953+
" Create a buffer-local autocmd for buffer 5
954+
let acmd = {}
955+
let acmd.group = 'MyGroup'
956+
let acmd.event = 'BufEnter'
957+
let acmd.bufnr = 5
958+
let acmd.cmd = 'call BufEnterFunc()'
959+
call autocmd_add([acmd])
960+
961+
Can also be used as a |method|: >
962+
GetAutocmdList()->autocmd_add()
963+
<
964+
autocmd_delete({acmds}) *autocmd_delete()*
965+
Deletes a List of autocmds and autocmd groups.
966+
967+
The {acmds} argument is a List where each item is a Dict with
968+
the following optional items:
969+
bufnr buffer number to delete a buffer-local autocmd.
970+
If this item is specified, then the "pattern"
971+
item is ignored.
972+
cmd Ex command for this autocmd event
973+
event autocmd event name. Refer to |autocmd-events|.
974+
If '*' then all the autocmd events in this
975+
group are deleted.
976+
group autocmd group name. Refer to |autocmd-groups|.
977+
If not specified or empty, then the default
978+
group is used.
979+
nested set to v:true for a nested autocmd.
980+
Refer to |autocmd-nested|.
981+
once set to v:true for an autocmd which executes
982+
only once. Refer to |autocmd-once|.
983+
pattern autocmd pattern string. Refer to
984+
|autocmd-patterns|. If "bufnr" item is
985+
present, then this item is ignored.
986+
987+
If only {group} is specified in a {acmds} entry and {event},
988+
{pattern} and {cmd} are not specified, then that autocmd group
989+
is deleted.
990+
991+
Returns v:true on success and v:false on failure.
992+
Examples: >
993+
" :autocmd! BufLeave *.vim
994+
let acmd = #{event: 'BufLeave', pattern: '*.vim'}
995+
call autocmd_delete([acmd]})
996+
" :autocmd! MyGroup1 BufLeave
997+
let acmd = #{group: 'MyGroup1', event: 'BufLeave'}
998+
call autocmd_delete([acmd])
999+
" :autocmd! MyGroup2 BufEnter *.c
1000+
let acmd = #{group: 'MyGroup2', event: 'BufEnter',
1001+
\ pattern: '*.c'}
1002+
" :autocmd! MyGroup2 * *.c
1003+
let acmd = #{group: 'MyGroup2', event: '*',
1004+
\ pattern: '*.c'}
1005+
call autocmd_delete([acmd])
1006+
" :autocmd! MyGroup3
1007+
let acmd = #{group: 'MyGroup3'}
1008+
call autocmd_delete([acmd])
1009+
<
1010+
Can also be used as a |method|: >
1011+
GetAutocmdList()->autocmd_delete()
1012+
1013+
autocmd_get([{opts}]) *autocmd_get()*
1014+
Returns a |List| of autocmds. If {opts} is not supplied, then
1015+
returns the autocmds for all the events in all the groups.
1016+
1017+
The optional {opts} Dict argument supports the following
1018+
items:
1019+
group Autocmd group name. If specified, returns only
1020+
the autocmds defined in this group. If the
1021+
specified group doesn't exist, results in an
1022+
error message. If set to an empty string,
1023+
then the default autocmd group is used.
1024+
event Autocmd event name. If specified, returns only
1025+
the autocmds defined for this event. If set
1026+
to "*", then returns autocmds for all the
1027+
events. If the specified event doesn't exist,
1028+
results in an error message.
1029+
pattern Autocmd pattern. If specified, returns only
1030+
the autocmds defined for this pattern.
1031+
A combination of the above three times can be supplied in
1032+
{opts}.
1033+
1034+
Each Dict in the returned List contains the following items:
1035+
bufnr For buffer-local autocmds, buffer number where
1036+
the autocmd is defined.
1037+
cmd Command executed for this autocmd.
1038+
event Autocmd event name.
1039+
group Autocmd group name.
1040+
nested Set to v:true for a nested autocmd. See
1041+
|autocmd-nested|.
1042+
once Set to v:true, if the autocmd will be executed
1043+
only once. See |autocmd-once|.
1044+
pattern Autocmd pattern. For a buffer-local
1045+
autocmd, this will be of the form "<buffer=n>".
1046+
If there are multiple commands for an autocmd event in a
1047+
group, then separate items are returned for each command.
1048+
1049+
Examples: >
1050+
" :autocmd MyGroup
1051+
echo autocmd_get(#{group: 'Mygroup'})
1052+
" :autocmd G BufUnload
1053+
echo autocmd_get(#{group: 'G', event: 'BufUnload'})
1054+
" :autocmd G * *.ts
1055+
let acmd = #{group: 'G', event: '*', pattern: '*.ts'}
1056+
echo autocmd_get(acmd)
1057+
" :autocmd Syntax
1058+
echo autocmd_get(#{event: 'Syntax'})
1059+
" :autocmd G BufEnter *.ts
1060+
let acmd = #{group: 'G', event: 'BufEnter',
1061+
\ pattern: '*.ts'}
1062+
echo autocmd_get(acmd)
1063+
<
1064+
Can also be used as a |method|: >
1065+
Getopts()->autocmd_get()
1066+
<
9251067
balloon_gettext() *balloon_gettext()*
9261068
Return the current text in the balloon. Only for the string,
9271069
not used for the List.

‎runtime/doc/usr_41.txt‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -925,6 +925,11 @@ Date and Time: *date-functions* *time-functions*
925925
reltimestr() convert reltime() result to a string
926926
reltimefloat() convert reltime() result to a Float
927927

928+
Autocmds: *autocmd-functions*
929+
autocmd_add() add a list of autocmds and groups
930+
autocmd_delete() delete a list of autocmds and groups
931+
autocmd_get() return a list of autocmds
932+
928933
*buffer-functions* *window-functions* *arg-functions*
929934
Buffers, windows and the argument list:
930935
argc() number of entries in the argument list

0 commit comments

Comments
 (0)