From 91ad6b514e971085816ee693a06360c87ad82666 Mon Sep 17 00:00:00 2001 From: Kyle F Hartzenberg <113495179+kylefhartzenberg@users.noreply.github.com> Date: Fri, 18 Aug 2023 00:10:15 +0000 Subject: [PATCH] Update DOC.md section structure Moved the recently added Troubleshooting section to between the Config-Options and API sections. In-place of the removed Troubleshooting section, a sentence was added referring readers to the Troubleshooting-Adding Snippets-Loaders section to see solutions to potential snippet adding/loading issues. --- DOC.md | 164 +++++++++++++++++++++++++++++---------------------------- 1 file changed, 84 insertions(+), 80 deletions(-) diff --git a/DOC.md b/DOC.md index b30a622b4..f0dfc8807 100644 --- a/DOC.md +++ b/DOC.md @@ -2300,16 +2300,17 @@ own filetype (vscode via `scope`, lua via the underlying `filetype`-option for snippets). These snippet-specific filetypes are not considered when determining which files to `lazy_load` for some filetype, this is exclusively determined by the `language` associated with a file in vscodes' `package.json`, and the -file/directory-name in lua. -This can be resolved relatively easily in vscode, where the `language` -advertised in `package.json` can just be a superset of the `scope`s in the file. -Another simplistic solution is to set the language to `all` (in lua, it might -make sense to create a directory `luasnippets/all/*.lua` to group these files -together). -Another approach is to modify `load_ft_func` to load a custom filetype if the -snippets should be activated, and store the snippets in a file for that -filetype. This can be used to group snippets by e.g. framework, and load them -once a file belonging to such a framework is edited. +file/directory-name in lua. + + * This can be resolved relatively easily in vscode, where the `language` + advertised in `package.json` can just be a superset of the `scope`s in the file. + * Another simplistic solution is to set the language to `all` (in lua, it might + make sense to create a directory `luasnippets/all/*.lua` to group these files + together). + * Another approach is to modify `load_ft_func` to load a custom filetype if the + snippets should be activated, and store the snippets in a file for that + filetype. This can be used to group snippets by e.g. framework, and load them + once a file belonging to such a framework is edited. **Example**: `react.lua` @@ -2333,76 +2334,8 @@ load_ft_func = function(bufnr) end ``` - -# Troubleshooting - -## Adding Snippets - -### Loaders - -* **Filetypes**. LuaSnip uses `all` as the global filetype. As most snippet - collections don't explicitly target LuaSnip, they may not provide global - snippets for this filetype, but another, like `_` (`honza/vim-snippets`). - In these cases, it's necessary to extend LuaSnip's global filetype with - the collection's global filetype: - ```lua - ls.filetype_extend("all", { "_" }) - ``` - - In general, if some snippets don't show up when loading a collection, a good - first step is checking the filetype LuaSnip is actually looking into (print - them for the current buffer via `:lua - print(vim.inspect(require("luasnip").get_snippet_filetypes()))`), against the - one the missing snippet is provided for (in the collection). - If there is indeed a mismatch, `filetype_extend` can be used to also search - the collection's filetype: - ```lua - ls.filetype_extend("", { "" }) - ``` - -* **Non-default `ft_func` loading**. As we only load `lazy_load`ed snippets on - some events, `lazy_load` will probably not play nice when a non-default - `ft_func` is used: if it depends on e.g. the cursor position, only the - filetypes for the cursor position when the `lazy_load` events are triggered - will be loaded. Check [Extras-Filetype-Function](#filetype-functions)'s - `extend_load_ft` for a solution. - -### General - -* **Snippets sharing triggers**. If multiple snippets could be triggered at - the current buffer-position, the snippet that was defined first in one's - configuration will be expanded first. As a small, real-world LaTeX math - example, given the following two snippets with triggers `.ov` and `ov`: - - ```lua - postfix( -- Insert over-line command to text via post-fix - { trig = ".ov", snippetType = "autosnippet" }, - { - f(function(_, parent) - return "\\overline{" .. parent.snippet.env.POSTFIX_MATCH .. "}" - end, {}), - } - ), - s( -- Insert over-line command - { trig = "ov", snippetType="autosnippet" }, - fmt( - [[\overline{<>}]], - { i(1) }, - { delimiters = "<>" } - ) - ), - ``` - - If one types `x` followed by `.ov`, the postfix snippet expands producing - `\overline{x}`. However, if the `postfix` snippet above is defined *after* - the normal snippet `s`, then the same key press sequence produces - `x.\overline{}`. - This behaviour can be overridden by explicitly providing a priority to - such snippets. For example, in the above code, if the `postfix` snippet - was defined after the normal snippet `s`, then adding `priority=1001` to the - `postfix` snippet will cause it to expand as if it were defined before - the normal snippet `s`. Snippet `priority` is discussed in the - [Snippets section](https://github.com/L3MON4D3/LuaSnip/blob/master/DOC.md#snippets) of the documentation. +See the [Troubleshooting-Adding Snippets-Loaders](#troubleshooting-adding-snippets-loaders) +section if one is having issues adding snippets via loaders. ## VS-Code @@ -3294,6 +3227,77 @@ These are the settings you can provide to `luasnip.setup()`: [Extras-Snippet-Location](#snippet-location), but also entails slightly increased memory consumption (and load-time, but it's not really noticeable). +# Troubleshooting + +## Adding Snippets + + +### Loaders + +* **Filetypes**. LuaSnip uses `all` as the global filetype. As most snippet + collections don't explicitly target LuaSnip, they may not provide global + snippets for this filetype, but another, like `_` (`honza/vim-snippets`). + In these cases, it's necessary to extend LuaSnip's global filetype with + the collection's global filetype: + ```lua + ls.filetype_extend("all", { "_" }) + ``` + + In general, if some snippets don't show up when loading a collection, a good + first step is checking the filetype LuaSnip is actually looking into (print + them for the current buffer via `:lua + print(vim.inspect(require("luasnip").get_snippet_filetypes()))`), against the + one the missing snippet is provided for (in the collection). + If there is indeed a mismatch, `filetype_extend` can be used to also search + the collection's filetype: + ```lua + ls.filetype_extend("", { "" }) + ``` + +* **Non-default `ft_func` loading**. As we only load `lazy_load`ed snippets on + some events, `lazy_load` will probably not play nice when a non-default + `ft_func` is used: if it depends on e.g. the cursor position, only the + filetypes for the cursor position when the `lazy_load` events are triggered + will be loaded. Check [Extras-Filetype-Function](#filetype-functions)'s + `extend_load_ft` for a solution. + +### General + +* **Snippets sharing triggers**. If multiple snippets could be triggered at + the current buffer-position, the snippet that was defined first in one's + configuration will be expanded first. As a small, real-world LaTeX math + example, given the following two snippets with triggers `.ov` and `ov`: + + ```lua + postfix( -- Insert over-line command to text via post-fix + { trig = ".ov", snippetType = "autosnippet" }, + { + f(function(_, parent) + return "\\overline{" .. parent.snippet.env.POSTFIX_MATCH .. "}" + end, {}), + } + ), + s( -- Insert over-line command + { trig = "ov", snippetType="autosnippet" }, + fmt( + [[\overline{<>}]], + { i(1) }, + { delimiters = "<>" } + ) + ), + ``` + + If one types `x` followed by `.ov`, the postfix snippet expands producing + `\overline{x}`. However, if the `postfix` snippet above is defined *after* + the normal snippet `s`, then the same key press sequence produces + `x.\overline{}`. + This behaviour can be overridden by explicitly providing a priority to + such snippets. For example, in the above code, if the `postfix` snippet + was defined after the normal snippet `s`, then adding `priority=1001` to the + `postfix` snippet will cause it to expand as if it were defined before + the normal snippet `s`. Snippet `priority` is discussed in the + [Snippets section](https://github.com/L3MON4D3/LuaSnip/blob/master/DOC.md#snippets) of the documentation. + # API `require("luasnip")`: