Skip to content

Commit

Permalink
Update DOC.md section structure
Browse files Browse the repository at this point in the history 
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.
  • Loading branch information
@kylefhartzenberg
kylefhartzenberg authored Aug 18, 2023
1 parent ef5b521 commit 91ad6b5
Showing 1 changed file with 84 additions and 80 deletions.
164 changes: 84 additions & 80 deletions DOC.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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`
Expand All @@ -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("<luasnip-filetype>", { "<collection-filetype>" })
```

* **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

Expand Down Expand Up @@ -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

<a id="troubleshooting-adding-snippets-loaders"></a>
### 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("<luasnip-filetype>", { "<collection-filetype>" })
```

* **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")`:
Expand Down

0 comments on commit 91ad6b5

Please sign in to comment.