mini.nvim/doc/mini-snippets.txt at main · yilisharcs/mini.nvim

Repository navigation

<
8000
div data-line-number="59" class="react-line-number react-code-text" style="padding-right:16px">59

*mini.snippets* Manage and expand snippets

------------------------------------------------------------------------------

*MiniSnippets*

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.

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

- `LuaSnip` 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|:

- 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 featu 8000 res 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 ~

*MiniSnippets-hl-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.

# Using in other plugins ~

*MiniSnippets-in-other-plugins*

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

ensures that user explicitly set up the module.

- 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 })

------------------------------------------------------------------------------

*MiniSnippets-glossary*

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.

------------------------------------------------------------------------------

*MiniSnippets-overview*

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 platform

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.

------------------------------------------------------------------------------

*MiniSnippets-examples*

# 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', }

au_opts.callback = function()

while MiniSnippets.session.get() do

MiniSnippets.session.stop()

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)

------------------------------------------------------------------------------

*MiniSnippets.setup()*

`MiniSnippets.setup`({config})

Module setup

Parameters ~

{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.config*

`MiniSnippets.config`

Defaults ~

>lua

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,

}

# 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.expand()*

`MiniSnippets.expand`({opts})

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.

Parameters ~

{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 })

FilesExpand file tree

mini-snippets.txt

Latest commit

History

mini-snippets.txt

File metadata and controls