--- *mini.snippets* Manage and expand snippets

---

--- MIT License Copyright (c) 2024 Evgeni Chasnovski

--- Snippet is a template for a frequently used text. Typical workflow is to type

--- snippet's (configurable) prefix and expand it into a snippet session.

---

--- The template usually contains both pre-defined text and places (called

--- "tabstops") for user to interactively change/add text during snippet session.

---

--- This module supports (only) snippet syntax defined in LSP specification (with

--- small deviations). See |MiniSnippets-syntax-specification|.

---

--- Features:

--- - Manage snippet collection by adding it explicitly or with a flexible set of

--- performant built-in loaders. See |MiniSnippets.gen_loader|.

---

--- - Configured snippets are efficiently resolved before every expand based on

--- current local context. This, for example, allows using different snippets

--- in different local tree-sitter languages (like in markdown code blocks).

--- See |MiniSnippets.default_prepare()|.

---

--- - Match which snippet to insert based on the currently typed text.

--- Supports both exact and fuzzy matching. See |MiniSnippets.default_match()|.

---

--- - Select from several matched snippets via `vim.ui.select()`.

--- See |MiniSnippets.default_select()|.

---

--- - Start specialized in-process LSP server to show loaded snippets inside

--- (auto)completion engines (like |mini.completion|).

--- See |MiniSnippets.start_lsp_server()|.

---

--- - Insert, jump, and edit during snippet session in a configurable manner:

--- - Configurable mappings for jumping and stopping.

--- - Jumping wraps around the tabstops for easier navigation.

--- - Easy to reason rules for when session automatically stops.

--- - Text synchronization of linked tabstops preserving relative indent.

--- - Dynamic tabstop state visualization (current/visited/unvisited, etc.)

--- - Inline visualization of empty tabstops (requires Neovim>=0.10).

--- - Works inside comments by preserving comment leader on new lines.

--- - Supports nested sessions (expand snippet while there is an active one).

--- See |MiniSnippets.default_insert()|.

---

--- - Exported function to parse snippet body into easy-to-reason data structure.

--- See |MiniSnippets.parse()|.

---

--- Notes:

--- - It does not set up any snippet collection by default. Explicitly populate

--- `config.snippets` to have snippets to match from.

--- - It does not come with a built-in snippet collection. It is expected from

--- users to add their own snippets, manually or with dedicated plugin(s).

--- - It does not support variable/tabstop transformations in default snippet

--- session. This requires ECMAScript Regular Expression parser which can not

--- be implemented concisely.

---

--- Sources with more details:

--- - |MiniSnippets-glossary|

--- - |MiniSnippets-overview|

--- - |MiniSnippets-examples|

--- - |MiniSnippets-in-other-plugins| (for plugin authors)

---

--- # Dependencies ~

---

--- This module doesn't come with snippet collection. Either create it manually

--- or install a dedicated plugin. For example,

--- [rafamadriz/friendly-snippets](https://github.com/rafamadriz/friendly-snippets).

---

--- # Setup ~

---

--- This module needs a setup with `require('mini.snippets').setup({})` (replace `{}`

--- with your `config` table). It will create global Lua table `MiniSnippets` which

--- you can use for scripting or manually (with `:lua MiniSnippets.*`).

---

--- See |MiniSnippets.config| for `config` structure and default values.

---

--- You can override runtime config settings locally to buffer inside

--- `vim.b.minisnippets_config` which should have same structure as

--- `MiniSnippets.config`. See |mini.nvim-buffer-local-config| for more details.

---

--- # Comparisons ~

---

--- - [L3MON4D3/LuaSnip](https://github.com/L3MON4D3/LuaSnip):

--- - Both contain functionality to load snippets from file system.

--- This module provides several common loader generators while 'LuaSnip'

--- contains a more elaborate loading setup.

--- Also both require explicit opt-in for which snippets to load.

--- - Both support LSP snippet format. 'LuaSnip' also provides own more

--- elaborate snippet format which is out of scope for this module.

--- - 'LuaSnip' can autoexpand snippets, while this module always requires

--- an explicit user action to expand (by design).

--- - Both contain snippet expand functionality which differs in some aspects:

--- - 'LuaSnip' has an elaborate dynamic tabstop visualization config.

--- This module provides a handful of dedicated highlight groups.

--- - This module provides configurable visualization of empty tabstops.

--- - 'LusSnip' implements nested sessions by essentially merging them

--- into one. This module treats each nested session separately (to not

--- visually overload) while storing them in stack (first in last out).

--- - 'LuaSnip' uses |Select-mode| to power replacing current tabstop,

--- while this module always stays in |Insert-mode|. This enables easier

--- mapping understanding and more targeted highlighting.

--- - This module implements jumping which wraps after final tabstop

--- for more flexible navigation (enhanced with by a more flexible

--- autostopping rules), while 'LuaSnip' autostops session once

--- jumping reached the final tabstop.

---

--- - Built-in |vim.snippet| (on Neovim>=0.10):

--- - Does not contain functionality to load or match snippets (by design),

--- while this module does.

--- - Both contain expand functionality based on LSP snippet format.

--- Differences in how snippet sessions are handled are similar to

--- comparison with 'LuaSnip'.

---

--- - [rafamadriz/friendly-snippets](https://github.com/rafamadriz/friendly-snippets):

--- - A snippet collection plugin without features to manage or expand them.

--- This module is designed with 'friendly-snippets' compatibility in mind.

---

--- - [abeldekat/cmp-mini-snippets](https://github.com/abeldekat/cmp-mini-snippets):

--- - A source for [hrsh7th/nvim-cmp](https://github.com/hrsh7th/nvim-cmp)

--- that integrates 'mini.snippets'.

---

--- # Highlight groups ~

---

--- - `MiniSnippetsCurrent` - current tabstop.

--- - `MiniSnippetsCurrentReplace` - current tabstop, placeholder is to be replaced.

--- - `MiniSnippetsFinal` - special `$0` tabstop.

--- - `MiniSnippetsUnvisited` - not yet visited tabstop(s).

--- - `MiniSnippetsVisited` - visited tabstop(s).

---

--- To change any highlight group, set it directly with |nvim_set_hl()|.

---

--- # Disabling ~

---

--- To disable core functionality, set `vim.g.minisnippets_disable` (globally) or

--- `vim.b.minisnippets_disable` (for a buffer) to `true`. Considering high number

--- of different scenarios and customization intentions, writing exact rules

--- for disabling module's functionality is left to user. See

--- |mini.nvim-disabling-recipes| for common recipes.

---@tag MiniSnippets

--- POSITION ~

--- Table representing position in a buffer. Fields:

--- - <line> `(number)` - line number (starts at 1).

--- - <col> `(number)` - column number (starts at 1).

---

--- REGION ~

--- Table representing region in a buffer.

--- Fields: <from> and <to> for inclusive start/end POSITIONs.

---

--- SNIPPET ~

--- Data about template to insert. Should contain fields:

--- - <prefix> - string snippet identifier.

--- - <body> - string snippet content with appropriate syntax.

--- - <desc> - string snippet description in human readable form.

---

--- Can also be used to mean snippet body if distinction is clear.

---

--- SNIPPET SESSION ~

--- Interactive state for user to adjust inserted snippet.

---

--- MATCHED SNIPPET ~

--- Snippet which contains <region> field with region that matched it.

--- Usually region needs to be removed.

---

--- SNIPPET NODE ~

--- Unit of parsed snippet body. See |MiniSnippets.parse()|.

---

--- TABSTOP ~

--- Dedicated places in snippet body for users to interactively adjust.

--- Specified in snippet body with `$` followed by digit(s).

---

--- LINKED TABSTOPS ~

--- Different nodes assigned the same tabstop. Updated in sync.

---

--- REFERENCE NODE ~

--- First (from left to right) node of linked tabstops. Used to determine

--- synced text and cursor placement after jump.

---

--- EXPAND ~

--- Action to start snippet session based on currently typed text.

--- Always done in current buffer at cursor. Executed steps:

--- - `PREPARE` - resolve raw config snippets at context.

--- - `MATCH` - match resolved snippets at cursor position.

--- - `SELECT` - possibly choose among matched snippets.

--- - `INSERT` - insert selected snippet and start snippet session.

---@tag MiniSnippets-glossary

--- Snippet is a template for a frequently used text. Typical workflow is to type

--- snippet's (configurable) prefix and expand it into a snippet session: add some

--- pre-defined text and allow user to interactively change/add at certain places.

---

--- This overview assumes default config for mappings and expand.

--- See |MiniSnippets.config| and |MiniSnippets-examples| for more details.

---

--- # Snippet structure ~

---

--- Snippet consists from three parts:

--- - `Prefix` - identifier used to match against current text.

--- - `Body` - actually inserted content with appropriate syntax.

--- - `Desc` - description in human readable form.

---

--- Example: `{ prefix = 'tis', body = 'This is snippet', desc = 'Snip' }`

--- Typing `tis` and pressing "expand" mapping (<C-j> by default) will remove "tis",

--- add "This is snippet", and place cursor at the end in Insert mode.

---

--- # Syntax ~

--- *MiniSnippets-syntax-specification*

---

--- Inserting just text after typing smaller prefix is already powerful enough.

--- For more flexibility, snippet body can be formatted in a special way to

--- provide extra features. This module implements support for syntax defined

--- in LSP specification (with small deviations). See this link for reference:

--- https://microsoft.github.io/language-server-protocol/specifications/lsp/3.18/specification/#snippet_syntax

---

--- A quick overview of basic syntax features:

---

--- - Tabstops are snippet parts meant for interactive editing at their location.

--- They are denoted as `$1`, `$2`, etc.

--- Navigating between them is called "jumping" and is done in numerical order

--- of tabstop identifiers by pressing special keys: <C-l> and <C-h> to jump

--- to next and previous tabstop respectively.

--- Special tabstop `$0` is called "final tabstop": it is used to decide when

--- snippet session is automatically stopped and is visited last during jumping.

---

--- Example: `T1=$1 T2=$2 T0=$0` is expanded as `T1= T2= T0=` with three tabstops.

---

--- - Tabstop can have placeholder: a text used if tabstop is not yet edited.

--- Text is preserved if no editing is done. It follows this same syntax, which

--- means it can itself contain tabstops with placeholders (i.e. be nested).

--- Tabstop with placeholder is denoted as `${1:placeholder}` (`$1` is `${1:}`).

---

--- Example: `T1=${1:text} T2=${2:<$1>}` is expanded as `T1=text T2=<text>`;

--- typing `x` at first placeholder results in `T1=x T2=<x>`;

--- jumping once and typing `y` results in `T1=x T2=y`.

---

--- - There can be several tabstops with same identifier. They are linked and

--- updated in sync during text editing. Can also have different placeholders;

--- they are forced to be the same as in the first (from left to right) tabstop.

---

--- Example: `T1=${1:text} T1=$1` is expanded as `T1=text T1=text`;

--- typing `x` at first placeholder results in `T1=x T1=x`.

---

--- - Tabstop can also have choices: suggestions about tabstop text. It is denoted

--- as `${1|a,b,c|}`. First choice is used as placeholder.

---

--- Example: `T1=${1|left,right|}` is expanded as `T1=left`.

---

--- - Variables can be used to automatically insert text without user interaction.

--- As tabstops, each one can have a placeholder which is used if variable is

--- not defined. There is a special set of variables describing editor state.

---

--- Example: `V1=$TM_FILENAME V2=${NOTDEFINED:placeholder}` is expanded as

--- `V1=current-file-basename V2=placeholder`.

---

--- What's different from LSP specification:

--- - Special set of variables is wider and is taken from VSCode specification:

--- https://code.visualstudio.com/docs/editor/userdefinedsnippets#_variables

--- Exceptions are `BLOCK_COMMENT_START` and `BLOCK_COMMENT_END` as Neovim doesn't

--- provide this information.

--- - Variable `TM_SELECTED_TEXT` is resolved as contents of |quote_quote| register.

--- It assumes that text is put there prior to expanding. For example, visually

--- select, press |c|, type prefix, and expand.

--- See |MiniSnippets-examples| for how to adjust this.

--- - Environment variables are recognized and supported: `V1=$VIMRUNTIME` will

--- use an actual value of |$VIMRUNTIME|.

--- - Variable transformations are not supported during snippet session. It would

--- require interacting with ECMAScript-like regular expressions for which there

--- is no easy way in Neovim. It may change in the future.

--- Transformations are recognized during parsing, though, with some exceptions:

--- - The `}` inside `if` of `${1:?if:else}` needs escaping (for technical reasons).

---

--- There is a |MiniSnippets.parse()| function for programmatically parsing

--- snippet body into a comprehensible data structure.

---

--- # Expand ~

---

--- Using snippets is done via what is called "expanding". It goes like this:

--- - Type snippet prefix or its recognizable part.

--- - Press <C-j> to expand. It will perform the following steps:

--- - Prepare available snippets in current context (buffer + local language).

--- This allows snippet setup to have general function loaders which return

--- different snippets in different contexts.

--- - Match text to the left of cursor with available prefixes. It first tries

--- to do exact match and falls back to fuzzy matching.

--- - If there are several matches, use `vim.ui.select()` to choose one.

--- - Insert single matching snippet. If snippet contains tabstops, start

--- snippet session.

---

--- For more details about each step see:

--- - |MiniSnippets.default_prepare()|

--- - |MiniSnippets.default_match()|

--- - |MiniSnippets.default_select()|

--- - |MiniSnippets.default_insert()|

---

--- Snippet session allows interactive editing at tabstop locations:

---

--- - All tabstop locations are visualized depending on tabstop "state" (whether

--- it is current/visited/unvisited/final and whether it was already edited).

--- Empty tabstops are visualized with inline virtual text ("•"/"∎" for

--- regular/final tabstops). It is removed after session is stopped.

---

--- - Start session at first tabstop. Type text to replace placeholder.

--- When finished with current tabstop, jump to next with <C-l>. Repeat.

--- If changed mind about some previous tabstop, jump back with <C-h>.

--- Jumping also wraps around the edge (first tabstop is next after final).

---

--- - If tabstop has choices, use <C-n> / <C-p> to select next / previous item.

---

--- - Starting another snippet session while there is an active one is allowed.

--- This creates nested sessions: suspend current, start the new one.

--- After newly created is stopped, resume the suspended one.

---

--- - Stop session manually by pressing <C-c> or make it stop automatically:

--- if final tabstop is current either make a text edit or exit to Normal mode.

--- If snippet doesn't explicitly define final tabstop, it is added at the end

--- of the snippet.

---

--- For more details about snippet session see |MiniSnippets-session|.

---

--- To select and insert snippets via completion engine (that supports LSP

--- completion; like |mini.completion| or |lsp-autocompletion|),

--- call |MiniSnippets.start_lsp_server()| after |MiniSnippets.setup()|. This sets up

--- an LSP server that matches and provides snippets loaded with 'mini.snippets'.

--- To match with completion engine, use `start_lsp_server({ match = false })`.

---

--- # Management ~

---

--- Out of the box 'mini.snippets' doesn't load any snippets, it should be done

--- explicitly inside |MiniSnippets.setup()| following |MiniSnippets.config|.

---

--- The suggested approach to snippet management is to create dedicated files with

--- snippet data and load them through function loaders in `config.snippets`.

--- See |MiniSnippets-examples| for basic (yet capable) snippet management config.

---

--- ## File specification ~

--- *MiniSnippets-file-specification*

---

--- General idea of supported files is to have at least out of the box experience

--- with common snippet collections. Namely "rafamadriz/friendly-snippets".

--- The following files are supported:

---

--- - Extensions:

--- - Read/decoded as JSON object (|vim.json.decode()|): `*.json`, `*.code-snippets`

--- - Executed as Lua file (|dofile()|) and uses returned value: `*.lua`

---

--- - Content:

--- - Dict-like: object in JSON; returned table in Lua; no order guarantees.

--- - Array-like: array in JSON; returned array table in Lua; preserves order.

---

--- Example of file content with a single snippet:

--- - Lua dict-like: `return { name = { prefix = 't', body = 'Text' } }`

--- - Lua array-like: `return { { prefix = 't', body = 'Text', desc = 'name' } }`

--- - JSON dict-like: `{ "name": { "prefix": "t", "body": "Text" } }`

--- - JSON array-like: `[ { "prefix": "t", "body": "Text", "desc": "name" } ]`

---

--- Notes:

--- - There is no built-in support for VSCode-like "package.json" files. Define

--- structure manually in |MiniSnippets.setup()| via built-in or custom loaders.

--- - There is no built-in support for `scope` field of snippet data. Snippets are

--- expected to be manually separated into smaller files and loaded on demand.

---

--- For supported snippet syntax see |MiniSnippets-syntax-specification|.

---

--- ## General advice ~

---

--- - Put files in "snippets" subdirectory of any path in 'runtimepath' (like

--- '`$XDG_CONFIG_HOME`/nvim/snippets/global.json').

--- This is compatible with |MiniSnippets.gen_loader.from_runtime()| and

--- example from |MiniSnippets-examples|.

--- - Prefer `*.json` files with dict-like content if you want more cross platfrom

--- setup. Otherwise use `*.lua` files with array-like content.

--- - To implement "dynamic snippet" that changes data (usually <body>) depending

--- on the context, use `*.lua` file with function returning snippet data.

--- It should be an element in the output table (dict or array like).

---

--- # Demo ~

---

--- The best way to grasp the design of snippet management and expansion is to

--- try them out yourself. Here are steps for a basic demo:

--- - Create 'snippets/global.json' file in the config directory with the content: >json

---

--- {

--- "Basic": { "prefix": "ba", "body": "T1=$1 T2=$2 T0=$0" },

--- "Placeholders": { "prefix": "pl", "body": "T1=${1:aa}\nT2=${2:<$1>}" },

--- "Choices": { "prefix": "ch", "body": "T1=${1|a,b|} T2=${2|c,d|}" },

--- "Linked": { "prefix": "li", "body": "T1=$1\n\tT1=$1" },

--- "Variables": { "prefix": "va", "body": "Runtime: $VIMRUNTIME\n" },

--- "Complex": {

--- "prefix": "co",

--- "body": [ "T1=${1:$RANDOM}", "T3=${3:$1_${2:$1}}", "T2=$2" ]

--- }

--- }

--- <

--- - Set up 'mini.snippets' as recommended in |MiniSnippets-examples|.

--- - Open Neovim. Type each snippet prefix and press <C-j> (even if there is

--- still active session). Explore from there.

---@tag MiniSnippets-overview

--- # Basic snippet management config ~

---

--- Example of snippet management setup that should cover most cases: >lua

---

--- -- Setup

--- local gen_loader = require('mini.snippets').gen_loader

--- require('mini.snippets').setup({

--- snippets = {

--- -- Load custom file with global snippets first

--- gen_loader.from_file('~/.config/nvim/snippets/global.json'),

---

--- -- Load snippets based on current language by reading files from

--- -- "snippets/" subdirectories from 'runtimepath' directories.

--- gen_loader.from_lang(),

--- },

--- })

--- <

--- This setup allows having single file with custom "global" snippets (will be

--- present in every buffer) and snippets which will be loaded based on the local

--- language (see |MiniSnippets.gen_loader.from_lang()|).

---

--- Create language snippets manually (by creating and populating

--- '`$XDG_CONFIG_HOME`/nvim/snippets/lua.json' file) or by installing dedicated

--- snippet collection plugin (like 'rafamadriz/friendly-snippets').

---

--- Note: all built-in loaders and |MiniSnippets.read_file()| cache their output

--- by default. It means that after a file is first read, changing it won't have

--- effect during current Neovim session. See |MiniSnippets.gen_loader| about how

--- to reset cache if necessary.

---

--- # Select from all available snippets in current context ~

---

--- With |MiniSnippets.default_match()|, expand snippets (<C-j> by default) at line

--- start or after whitespace. To be able to always select from all current

--- context snippets, make mapping similar to the following: >lua

---

--- local rhs = function() MiniSnippets.expand({ match = false }) end

--- vim.keymap.set('i', '<C-g><C-j>', rhs, { desc = 'Expand all' })

--- <

--- # "Supertab"-like <Tab> / <S-Tab> mappings ~

---

--- This module intentionally by default uses separate keys to expand and jump as

--- it enables cleaner use of nested sessions. Here is an example of setting up

--- custom <Tab> to "expand or jump" and <S-Tab> to "jump to previous": >lua

---

--- local snippets = require('mini.snippets')

--- local match_strict = function(snips)

--- -- Do not match with whitespace to cursor's left

--- return snippets.default_match(snips, { pattern_fuzzy = '%S+' })

--- end

--- snippets.setup({

--- -- ... Set up snippets ...

--- mappings = { expand = '', jump_next = '', jump_prev = '' },

--- expand = { match = match_strict },

--- })

--- local expand_or_jump = function()

--- local can_expand = #MiniSnippets.expand({ insert = false }) > 0

--- if can_expand then vim.schedule(MiniSnippets.expand); return '' end

--- local is_active = MiniSnippets.session.get() ~= nil

--- if is_active then MiniSnippets.session.jump('next'); return '' end

--- return '\t'

--- end

--- local jump_prev = function() MiniSnippets.session.jump('prev') end

--- vim.keymap.set('i', '<Tab>', expand_or_jump, { expr = true })

--- vim.keymap.set('i', '<S-Tab>', jump_prev)

--- <

--- # Stop session immediately after jumping to final tabstop ~

---

--- Utilize a dedicated |MiniSnippets-events|: >lua

---

--- local fin_stop = function(args)

--- if args.data.tabstop_to == '0' then MiniSnippets.session.stop() end

--- end

--- local au_opts = { pattern = 'MiniSnippetsSessionJump', callback = fin_stop }

--- vim.api.nvim_create_autocmd('User', au_opts)

--- <

--- # Stop all sessions on Normal mode exit ~

---

--- Use |ModeChanged| and |MiniSnippets-events| events: >lua

---

--- local make_stop = function()

--- local au_opts = { pattern = '*:n', once = true }

--- au_opts.callback = function()

--- while MiniSnippets.session.get() do

--- MiniSnippets.session.stop()

--- end

--- end

--- vim.api.nvim_create_autocmd('ModeChanged', au_opts)

--- end

--- local opts = { pattern = 'MiniSnippetsSessionStart', callback = make_stop }

--- vim.api.nvim_create_autocmd('User', opts)

--- <

--- # Customize variable evaluation ~

---

--- Create environment variables and `config.expand.insert` wrapper: >lua

---

--- -- Use evnironment variables with value is same for all snippet sessions

--- vim.loop.os_setenv('USERNAME', 'user')

---

--- -- Compute custom lookup for variables with dynamic values

--- local insert_with_lookup = function(snippet)

--- local lookup = {

--- TM_SELECTED_TEXT = table.concat(vim.fn.getreg('a', true, true), '\n'),

--- }

--- return MiniSnippets.default_insert(snippet, { lookup = lookup })

--- end

---

--- require('mini.snippets').setup({

--- -- ... Set up snippets ...

--- expand = { insert = insert_with_lookup },

--- })

--- <

--- # Using Neovim's built-ins to insert snippet ~

---

--- Define custom `expand.insert` in |MiniSnippets.config| and mappings: >lua

---

--- require('mini.snippets').setup({

--- -- ... Set up snippets ...

--- expand = {

--- insert = function(snippet, _) vim.snippet.expand(snippet.body) end

--- }

--- })

--- -- Make jump mappings or skip to use built-in <Tab>/<S-Tab> in Neovim>=0.11

--- local jump_next = function()

--- if vim.snippet.active({direction = 1}) then return vim.snippet.jump(1) end

--- end

--- local jump_prev = function()

--- if vim.snippet.active({direction = -1}) then vim.snippet.jump(-1) end

--- end

--- vim.keymap.set({ 'i', 's' }, '<C-l>', jump_next)

--- vim.keymap.set({ 'i', 's' }, '<C-h>', jump_prev)

--- <

--- # Using 'mini.snippets' in other plugins ~

--- *MiniSnippets-in-other-plugins*

---

--- - Perform a `_G.MiniSnippets ~= nil` check before using any feature. This

--- ensures that user explicitly set up 'mini.snippets'.

---

--- - To insert snippet given its body (like |vim.snippet.expand()|), use: >lua

---

--- -- Use configured `insert` method with falling back to default

--- local insert = MiniSnippets.config.expand.insert

--- or MiniSnippets.default_insert

--- -- Insert at cursor

--- insert({ body = snippet })

--- <

--- - To get available snippets, use: >lua

---

--- -- Get snippets matched at cursor

--- MiniSnippets.expand({ insert = false })

---

--- -- Get all snippets available at cursor context

--- MiniSnippets.expand({ match = false, insert = false })

--- <

---@tag MiniSnippets-examples

---@alias __minisnippets_cache_opt <cache> `(boolean)` - whether to use cached output. Default: `true`.

---@alias __minisnippets_silent_opt <silent> `(boolean)` - whether to hide non-error messages. Default: `false`.

---@alias __minisnippets_loader_return function Snippet loader.

---@diagnostic disable:undefined-field

---@diagnostic disable:discard-returns

---@diagnostic disable:unused-local

-- Module definition ==========================================================

local MiniSnippets = {}

local H = {}

--- Module setup

---

---@param config table|nil Module config table. See |MiniSnippets.config|.

---

---@usage >lua

--- require('mini.snippets').setup({}) -- replace {} with your config table

--- -- needs `snippets` field present

--- <

MiniSnippets.setup = function(config)

-- TODO: Remove after Neovim=0.9 support is dropped

if vim.fn.has('nvim-0.10') == 0 then

vim.notify(

'(mini.snippets) Neovim<0.10 is soft deprecated (module works but is not supported).'

.. " It will be deprecated after the next 'mini.nvim' release (module might not work)."

.. ' Please update your Neovim version.'

)

end

-- Export module

_G.MiniSnippets = MiniSnippets

-- Setup config

config = H.setup_config(config)

-- Apply config

H.apply_config(config)

-- Define behavior

H.create_autocommands()

-- Create default highlighting

H.create_default_hl()

end

--- Defaults ~

---@eval return MiniDoc.afterlines_to_code(MiniDoc.current.eval_section)

---@text # Loaded snippets ~

---

--- `config.snippets` is an array containing snippet data which can be: snippet

--- table, function loader, or (however deeply nested) array of snippet data.

---

--- Snippet is a table with the following fields:

---

--- - <prefix> `(string|table|nil)` - string used to match against current text.

--- If array, all strings should be used as separate prefixes.

--- - <body> `(string|table|nil)` - content of a snippet which should follow

--- the |MiniSnippets-syntax-specification|. Array is concatenated with `"\n"`.

--- - <desc> `(string|table|nil)` - description of snippet. Can be used to display

--- snippets in a more human readable form. Array is concatenated with `"\n"`.

---

--- Function loaders are expected to be called with single `context` table argument

--- (containing any data about current context) and return same as `config.snippets`

--- data structure.

---

--- `config.snippets` is resolved with `config.prepare` on every expand.

--- See |MiniSnippets.default_prepare()| for how it is done by default.

---

--- For a practical example see |MiniSnippets-examples|.

--- Here is an illustration of `config.snippets` customization capabilities: >lua

---

--- local gen_loader = require('mini.snippets').gen_loader

--- require('mini.snippets').setup({

--- snippets = {

--- -- Load custom file with global snippets first (order matters)

--- gen_loader.from_file('~/.config/nvim/snippets/global.json'),

---

--- -- Or add them here explicitly

--- { prefix='cdate', body='$CURRENT_YEAR-$CURRENT_MONTH-$CURRENT_DATE' },

---

--- -- Load snippets based on current language by reading files from

--- -- "snippets/" subdirectories from 'runtimepath' directories.

--- gen_loader.from_lang(),

---

--- -- Load project-local snippets with `gen_loader.from_file()`

--- -- and relative path (file doesn't have to be present)

--- gen_loader.from_file('.vscode/project.code-snippets'),

---

--- -- Custom loader for language-specific project-local snippets

--- function(context)

--- local rel_path = '.vscode/' .. context.lang .. '.code-snippets'

--- if vim.fn.filereadable(rel_path) == 0 then return end

--- return MiniSnippets.read_file(rel_path)

--- end,

---

--- -- Ensure that some prefixes are not used (as there is no `body`)

--- { prefix = { 'bad', 'prefix' } },

--- }

--- })

--- <

--- # Mappings ~

---

--- `config.mappings` describes which mappings are automatically created.

---

--- `mappings.expand` is created globally in Insert mode and is used to expand

--- snippet at cursor. Use |MiniSnippets.expand()| for custom mappings.

---

--- `mappings.jump_next`, `mappings.jump_prev`, and `mappings.stop` are created for

--- the duration of active snippet session(s) from |MiniSnippets.default_insert()|.

--- Used to jump to next/previous tabstop and stop active session respectively.

--- Use |MiniSnippets.session.jump()| and |MiniSnippets.session.stop()| for custom

--- Insert mode mappings.

--- Note: do not use `"<C-n>"` or `"<C-p>"` for any action as they conflict with

--- built-in completion: it forces them to mean "change focus to next/previous

--- completion item". This matters more frequently than when there is a tabstop

--- with choices due to how this module handles built-in completion during jumps.

---

--- # Expand ~

---

--- `config.expand` defines expand steps (see |MiniSnippets-glossary|), either after

--- pressing `mappings.expand` or starting manually via |MiniSnippets.expand()|.

---

--- `expand.prepare` is a function that takes `raw_snippets` in the form of

--- `config.snippets` and should return a plain array of snippets (as described

--- in |MiniSnippets-glossary|). Will be called on every |MiniSnippets.expand()| call.

--- If returns second value, it will be used as context for warning messages.

--- Default: |MiniSnippets.default_prepare()|.

---

--- `expand.match` is a function that takes `expand.prepare` output and returns

--- an array of matched snippets: one or several snippets user might intend to

--- eventually insert. Should sort matches in output from best to worst.

--- Entries can contain `region` field with current buffer region used to do

--- the match; usually it needs to be removed (similar to how |ins-completion|

--- and |abbreviations| work).

--- Default: |MiniSnippets.default_match()|

---

--- `expand.select` is a function that takes output of `expand.match` and function

--- that inserts snippet (and also ensures Insert mode and removes snippet's match

--- region). Should allow user to perform interactive snippet selection and

--- insert the chosen one. Designed to be compatible with |vim.ui.select()|.

--- Called for any non-empty `expand.match` output (even with single entry).

--- Default: |MiniSnippets.default_select()|

---

--- `expand.insert` is a function that takes single snippet table as input and

--- inserts snippet at cursor position. This is a main entry point for adding

--- text template to buffer and starting a snippet session.

--- If called inside |MiniSnippets.expand()| (which is a usual interactive case),

--- all it has to do is insert snippet at cursor position. Ensuring Insert mode

--- and removing matched snippet region is done beforehand.

--- Default: |MiniSnippets.default_insert()|

---

--- Illustration of `config.expand` customization: >lua

---

--- -- Supply extra data as context

--- local my_p = function(raw_snippets)

--- local _, cont = MiniSnippets.default_prepare({})

--- cont.cursor = vim.api.nvim_win_get_cursor()

--- return MiniSnippets.default_prepare(raw_snippets, { context = cont })

--- end

--- -- Perform fuzzy match based only on alphanumeric characters

--- local my_m = function(snippets)

--- return MiniSnippets.default_match(snippets, { pattern_fuzzy = '%w*' })

--- end

--- -- Always insert the best matched snippet

--- local my_s = function(snippets, insert) return insert(snippets[1]) end

--- -- Use different string to show empty tabstop as inline virtual text

--- local my_i = function(snippet)

--- return MiniSnippets.default_insert(snippet, { empty_tabstop = '$' })

--- end

---

--- require('mini.snippets').setup({

--- -- ... Set up snippets ...

--- expand = { prepare = my_p, match = my_m, select = my_s, insert = my_i }

--- })

--- <

MiniSnippets.config = {

-- Array of snippets and loaders (see |MiniSnippets.config| for details).

-- Nothing is defined by default. Add manually to have snippets to match.

snippets = {},

-- Module mappings. Use `''` (empty string) to disable one.

mappings = {

-- Expand snippet at cursor position. Created globally in Insert mode.

expand = '<C-j>',

-- Interact with default `expand.insert` session.

-- Created for the duration of active session(s)

jump_next = '<C-l>',

jump_prev = '<C-h>',

stop = '<C-c>',

},

-- Functions describing snippet expansion. If `nil`, default values

-- are `MiniSnippets.default_<field>()`.

expand = {

-- Resolve raw config snippets at context

prepare = nil,

-- Match resolved snippets at cursor position

match = nil,

-- Possibly choose among matched snippets

select = nil,

-- Insert selected snippet

insert = nil,

},

}

--minidoc_afterlines_end

--- Expand snippet at cursor position

---

--- Perform expand steps (see |MiniSnippets-glossary|).

--- Initial raw snippets are taken from `config.snippets` in current buffer.

--- Snippets from `vim.b.minisnippets_config` are appended to global snippet array.

---

---@param opts table|nil Options. Same structure as `expand` in |MiniSnippets.config|

--- and uses its values as default. There are differences in allowed values:

--- - Use `match = false` to have all buffer snippets as matches.

--- - Use `select = false` to always expand the best match (if any).

--- - Use `insert = false` to return all matches without inserting.

---

--- Note: `opts.insert` is called after ensuring Insert mode, removing snippet's

--- match region, and positioning cursor.

---

---@return table|nil If `insert` is `false`, an array of matched snippets (`expand.match`

--- output). Otherwise `nil`.

---

---@usage >lua

--- -- Match, maybe select, and insert

--- MiniSnippets.expand()

---

--- -- Match and force expand the best match (if any)

--- MiniSnippets.expand({ select = false })

---

--- -- Use all current context snippets as matches

--- MiniSnippets.expand({ match = false })

---

--- -- Get all matched snippets

--- local matches = MiniSnippets.expand({ insert = false })

---

--- -- Get all current context snippets

--- local all = MiniSnippets.expand({ match = false, insert = false })

--- <

---

---@seealso |MiniSnippets.start_lsp_server()| to instead show loaded snippets

--- in (auto)completion engines (like |mini.completion|).

MiniSnippets.expand = function(opts)

if H.is_disabled() then return end

local config = H.get_config()

opts = vim.tbl_extend('force', config.expand, opts or {})

-- Validate

local prepare = opts.prepare or MiniSnippets.default_prepare

if not vim.is_callable(prepare) then H.error('`opts.prepare` should be callable') end

local match = false

if opts.match ~= false then match = opts.match or MiniSnippets.default_match end

if not (match == false or vim.is_callable(match)) then H.error('`opts.match` should be `false` or callable') end

local select = false

if opts.select ~= false then select = opts.select or MiniSnippets.default_select end

if not (select == false or vim.is_callable(select)) then H.error('`opts.select` should be `false` or callable') end

local insert = false

if opts.insert ~= false then insert = opts.insert or MiniSnippets.default_insert end

if not (insert == false or vim.is_callable(insert)) then H.error('`opts.insert` should be `false` or callable') end

-- Match

local all_snippets, context = prepare(config.snippets)

if not H.is_array_of(all_snippets, H.is_snippet) then H.error('`prepare` should return array of snippets') end

local matches = match == false and all_snippets or match(all_snippets)

if not H.is_array_of(matches, H.is_snippet) then H.error('`match` should return array of snippets') end

-- Act

if insert == false then return matches end

if #all_snippets == 0 then return H.notify('No snippets in context:\n' .. vim.inspect(context), 'WARN') end

if #matches == 0 then return H.notify('No matches in context:\n' .. vim.inspect(context), 'WARN') end

local insert_ext = H.make_extended_insert(insert)

if select == false then return insert_ext(matches[1]) end

select(matches, insert_ext)

end

--- Generate snippet loader

---

--- This is a table with function elements. Call to actually get a loader.

---

--- Common features for all produced loaders:

--- - Designed to work with |MiniSnippets-file-specification|.

--- - Cache output by default, i.e. second and later calls with same input value

--- don't read file system. Different loaders from same generator share cache.

--- Disable by setting `opts.cache` to `false`.

--- To clear all cache, call |MiniSnippets.setup()|. For example:

--- `MiniSnippets.setup(MiniSnippets.config)`

--- - Use |vim.notify()| to show problems during loading while trying to load as

--- much correctly defined snippet data as possible.

--- Disable by setting `opts.silent` to `true`.

MiniSnippets.gen_loader = {}

--- Generate language loader

---

--- Output loads files from "snippets/" subdirectories of 'runtimepath' matching

--- configured language patterns.

--- See |MiniSnippets.gen_loader.from_runtime()| for runtime loading details.

---

--- Language is taken from <lang> field (if present with string value) of `context`

--- argument used in loader calls during "prepare" stage.

--- This is compatible with |MiniSnippets.default_prepare()| and most snippet

--- collection plugins.

---

---@param opts table|nil Options. Possible values:

--- - <lang_patterns> `(table)` - map from language to array of runtime patterns

--- used to find snippet files, as in |MiniSnippets.gen_loader.from_runtime()|.

--- Patterns will be processed in order. With |MiniSnippets.default_prepare()|

--- it means if snippets have same prefix, data from later patterns is used.

--- To interactively check the current language with default context, execute

--- `:=MiniSnippets.default_prepare({})` and see data in the second table.

---

--- Default pattern array (for non-empty language) is constructed as to read

--- `*.json` and `*.lua` files that are:

--- - Inside "snippets/" subdirectory named as language (files can be however

--- deeply nested).

--- - Named as language and is in "snippets/" directory (however deep).

--- Example for "lua" language: >lua

--- { 'lua/**/*.json', 'lua/**/*.lua', '**/lua.json', '**/lua.lua' }

--- <

--- Add entry for `""` (empty string) as language to be sourced when `lang`

--- context is empty string (which is usually temporary scratch buffers).

---

--- - __minisnippets_cache_opt

--- Note: caching is done per used runtime pattern, not `lang` value to allow

--- different `from_lang()` loaders to share cache.

--- - __minisnippets_silent_opt

---

---@return __minisnippets_loader_return

---

---@usage >lua

--- -- Adjust language patterns

--- local latex_patterns = { 'latex/**/*.json', '**/latex.json' }

--- local lang_patterns = {

--- tex = latex_patterns, plaintex = latex_patterns,

--- -- Recognize special injected language of markdown tree-sitter parser

--- markdown_inline = { 'markdown.json' },

--- }

--- local gen_loader = require('mini.snippets').gen_loader

--- require('mini.snippets').setup({

--- snippets = {

--- gen_loader.from_lang({ lang_patterns = lang_patterns }),

--- },

--- })

--- <

MiniSnippets.gen_loader.from_lang = function(opts)

opts = vim.tbl_extend('force', { lang_patterns = {}, cache = true, silent = false }, opts or {})

for lang, tbl in pairs(opts.lang_patterns) do

if type(lang) ~= 'string' then H.error('Keys of `opts.lang_patterns` should be string language names') end

if not H.is_array_of(tbl, H.is_string) then H.error('Values of `opts.lang_patterns` should be string arrays') end

end

local loaders, loader_opts = {}, { cache = opts.cache, silent = opts.silent }

return function(context)

local lang = (context or {}).lang

if type(lang) ~= 'string' then return {} end

local patterns = opts.lang_patterns[lang]

if patterns == nil and lang == '' then return {} end

-- NOTE: Don't use `{json,lua}` for better compatibility, as it seems that

-- its support might depend on the shell (and might not work on Windows).

-- Which is shame because fewer patterns used mean fewer calls to cache.

patterns = patterns

or { lang .. '/**/*.json', lang .. '/**/*.lua', '**/' .. lang .. '.json', '**/' .. lang .. '.lua' }

local res = {}

for _, pat in ipairs(patterns) do

local loader = loaders[pat] or MiniSnippets.gen_loader.from_runtime(pat, loader_opts)

loaders[pat] = loader

table.insert(res, loader(context))

end

return res

end

end

--- Generate runtime loader

---

--- Output loads files which match `pattern` inside "snippets/" directories from

--- 'runtimepath'. This is useful to simultaneously read several similarly

--- named files from different sources. Order from 'runtimepath' is preserved.

---

--- Typical case is loading snippets for a language from files like `xxx.{json,lua}`

--- but located in different "snippets/" directories inside 'runtimepath'.

--- - `<config>`/snippets/lua.json - manually curated snippets in user config.

--- - `<path/to/installed/plugin>`/snippets/lua.json - from installed plugin.

--- - `<config>`/after/snippets/lua.json - used to adjust snippets from plugins.

--- For example, remove some snippets by using prefixes and no body.

---

---@param pattern string Pattern of files to read. Can have wildcards as described

--- in |nvim_get_runtime_file()|. Example for "lua" language: `'lua.{json,lua}'`.

---@param opts table|nil Options. Possible fields:

--- - <all> `(boolean)` - whether to load from all matching runtime files.

--- Default: `true`.

--- - __minisnippets_cache_opt

--- Note: caching is done per `pattern` value, which assumes that both

--- 'runtimepath' value and snippet files do not change during Neovim session.

--- Caching this way gives significant speed improvement by reducing the need

--- to traverse file system on every snippet expand.

--- - __minisnippets_silent_opt

---

---@return __minisnippets_loader_return

MiniSnippets.gen_loader.from_runtime = function(pattern, opts)

if type(pattern) ~= 'string' then H.error('`pattern` should be string') end

opts = vim.tbl_extend('force', { all = true, cache = true, silent = false }, opts or {})

pattern = 'snippets/' .. pattern

local cache, read_opts = opts.cache, { cache = opts.cache, silent = opts.silent }

local read = function(p) return MiniSnippets.read_file(p, read_opts) end

return function()

if cache and H.cache.runtime[pattern] ~= nil then return vim.deepcopy(H.cache.runtime[pattern]) end

local res = vim.tbl_map(read, vim.api.nvim_get_runtime_file(pattern, opts.all))

if cache then H.cache.runtime[pattern] = vim.deepcopy(res) end

return res

end

end

--- Generate single file loader

---

--- Output is a thin wrapper around |MiniSnippets.read_file()| which will skip

--- warning if file is absent (other messages are still shown). Use it to load

--- file which is not guaranteed to exist (like project-local snippets).

---

---@param path string Same as in |MiniSnippets.read_file()|.

---@param opts table|nil Same as in |MiniSnippets.read_file()|.

---

---@return __minisnippets_loader_return

MiniSnippets.gen_loader.from_file = function(path, opts)

if type(path) ~= 'string' then H.error('`path` should be string') end

opts = vim.tbl_extend('force', { cache = true, silent = false }, opts or {})

return function()

local full_path = vim.fn.fnamemodify(path, ':p')

if vim.fn.filereadable(full_path) ~= 1 then return {} end

return MiniSnippets.read_file(full_path, opts) or {}

end

end

--- Read file with snippet data

---