diff options
author | Yegappan Lakshmanan <yegappan@yahoo.com> | 2022-05-19 10:31:47 +0100 |
---|---|---|
committer | Bram Moolenaar <Bram@vim.org> | 2022-05-19 10:31:47 +0100 |
commit | 1755a91851f7022fdd3eecfbd2cc0b508a2f2a8f (patch) | |
tree | d0b3e630953275b71ee1a97a9bdfa55912b19415 /runtime | |
parent | aaadb5b6f76ea03e5eb460121f3dbf46ad04ce50 (diff) |
patch 8.2.4981: it is not possible to manipulate autocommandsv8.2.4981
Problem: It is not possible to manipulate autocommands.
Solution: Add functions to add, get and set autocommands. (Yegappan
Lakshmanan, closes #10291)
Diffstat (limited to 'runtime')
-rw-r--r-- | runtime/doc/autocmd.txt | 9 | ||||
-rw-r--r-- | runtime/doc/builtin.txt | 142 | ||||
-rw-r--r-- | runtime/doc/usr_41.txt | 5 |
3 files changed, 156 insertions, 0 deletions
diff --git a/runtime/doc/autocmd.txt b/runtime/doc/autocmd.txt index 0bbfd34a72..fb4532fc4e 100644 --- a/runtime/doc/autocmd.txt +++ b/runtime/doc/autocmd.txt @@ -82,6 +82,9 @@ triggered. /<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 @@ prompt. When one command outputs two messages this can happen anyway. ============================================================================== 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 @@ argument behavior differs from that for defining and removing autocommands. 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 538f099cb4..44997f32a7 100644 --- a/runtime/doc/builtin.txt +++ b/runtime/doc/builtin.txt @@ -60,6 +60,9 @@ assert_report({msg}) Number report a test failure 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 @@ atan2({expr1}, {expr2}) *atan2()* < {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 54af80cb3f..162eb9d3cd 100644 --- a/runtime/doc/usr_41.txt +++ b/runtime/doc/usr_41.txt @@ -925,6 +925,11 @@ Date and Time: *date-functions* *time-functions* 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 |