diff options
| author | Christian Clason <c.clason@uni-graz.at> | 2022-10-27 22:31:58 +0200 |
|---|---|---|
| committer | GitHub <noreply@github.com> | 2022-10-27 22:31:58 +0200 |
| commit | f44ad753801d881f5352c9182167ced18e79e456 (patch) | |
| tree | 093d3dd32174f56736724d173b1254e1f48d7cdb | |
| parent | f3268652ab542de659270081b2b85f607a0dade4 (diff) | |
| download | rneovim-f44ad753801d881f5352c9182167ced18e79e456.tar.gz rneovim-f44ad753801d881f5352c9182167ced18e79e456.tar.bz2 rneovim-f44ad753801d881f5352c9182167ced18e79e456.zip | |
docs(api): pattern is not expanded for autocommands (#20812)
Problem: Unlike `:autocmd`, `nvim_create_autocommand()` does not expand
environment variables in the `pattern`, which is unexpected.
Solution: Add a note to the documentation explaining this and suggesting
using `expand()` explicitly.
| -rw-r--r-- | runtime/doc/api.txt | 8 | ||||
| -rw-r--r-- | src/nvim/api/autocmd.c | 9 |
2 files changed, 15 insertions, 2 deletions
diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt index b949f3016e..8928650a39 100644 --- a/runtime/doc/api.txt +++ b/runtime/doc/api.txt @@ -3267,6 +3267,12 @@ nvim_create_autocmd({event}, {*opts}) *nvim_create_autocmd()* pattern = { "*.py", "*.pyi" } < + Note: The `pattern` is passed to callbacks and commands as a literal string; environment + variables like `$HOME` and `~` are not automatically expanded as they are by |:autocmd|. Instead, + |expand()| such variables explicitly: > + pattern = vim.fn.expand("~") .. "/some/path/*.py" +< + Example values for event: > "BufWritePre" {"CursorHold", "BufWritePre", "BufWritePost"} @@ -3279,7 +3285,7 @@ nvim_create_autocmd({event}, {*opts}) *nvim_create_autocmd()* • group (string|integer) optional: the autocommand group name or id to match against. • pattern (string|array) optional: pattern or patterns to - match against |autocmd-pattern|. + match literally against |autocmd-pattern|. • buffer (integer) optional: buffer number for buffer local autocommands |autocmd-buflocal|. Cannot be used with {pattern}. diff --git a/src/nvim/api/autocmd.c b/src/nvim/api/autocmd.c index b5c695b9ce..3dfe77ba38 100644 --- a/src/nvim/api/autocmd.c +++ b/src/nvim/api/autocmd.c @@ -401,6 +401,13 @@ cleanup: /// pattern = { "*.py", "*.pyi" } /// </pre> /// +/// Note: The `pattern` is passed to callbacks and commands as a literal string; environment +/// variables like `$HOME` and `~` are not automatically expanded as they are by |:autocmd|. +/// Instead, |expand()| such variables explicitly: +/// <pre> +/// pattern = vim.fn.expand("~") .. "/some/path/*.py" +/// </pre> +/// /// Example values for event: /// <pre> /// "BufWritePre" @@ -411,7 +418,7 @@ cleanup: /// @param opts Dictionary of autocommand options: /// - group (string|integer) optional: the autocommand group name or /// id to match against. -/// - pattern (string|array) optional: pattern or patterns to match +/// - pattern (string|array) optional: pattern or patterns to match literally /// against |autocmd-pattern|. /// - buffer (integer) optional: buffer number for buffer local autocommands /// |autocmd-buflocal|. Cannot be used with {pattern}. |