mini.nvim/lua/mini/completion.lua at main · skoch13/mini.nvim

Repository navigation

History

100

101

102

103

104

105

106

107

108

109

110

111

112

113

114

115

116

117

118

119

120

121

122

123

124

125

126

127

128

129

130

131

132

133

134

135

136

137

138

139

140

141

142

143

144

145

146

147

148

149

150

151

152

153

154

155

156

157

158

159

160

161

162

163

164

165

166

167

168

169

170

171

172

173

174

175

176

177

178

179

180

181

182

183

184

185

186

187

188

189

190

191

192

193

194

195

196

197

198

199

200

201

202

203

204

205

206

207

208

209

210

211

212

213

214

215

216

217

218

219

220

221

222

223

224

225

226

227

228

229

230

231

232

233

234

235

236

237

238

239

240

241

242

243

244

245

246

247

248

249

250

251

252

253

254

255

256

257

258

259

260

261

262

263

264

265

266

267

268

269

270

271

272

273

274

275

276

277

278

279

280

281

282

283

284

285

286

287

288

289

290

291

292

293

294

295

296

297

298

299

300

301

302

303

304

305

306

307

308

309

310

311

312

313

314

315

316

317

318

319

320

321

322

323

324

325

326

327

328

329

330

331

332

333

334

335

336

337

338

339

340

341

342

343

344

345

346

347

348

349

350

351

352

353

354

355

356

357

358

359

360

361

362

363

364

365

366

367

368

369

370

371

372

373

374

375

376

377

378

379

380

381

382

383

384

385

386

387

388

389

390

391

392

393

394

395

396

397

398

399

400

401

402

403

404

405

406

407

408

409

410

411

412

413

414

415

416

417

418

419

420

421

422

423

424

425

426

427

428

429

430

431

432

433

434

435

436

437

438

439

440

441

442

443

444

445

446

447

448

449

450

451

452

453

454

455

456

457

458

459

460

461

462

463

464

465

466

467

468

469

470

471

472

473

474

475

476

477

478

479

480

481

482

483

484

485

486

487

488

489

490

491

492

493

494

495

496

497

498

499

500

501

502

503

504

505

506

507

508

509

510

511

512

513

514

515

516

517

518

519

520

521

522

523

524

525

526

527

528

529

530

531

532

533

534

535

536

537

538

539

540

541

542

543

544

545

546

547

548

549

550

551

552

553

554

555

556

557

558

559

560

561

562

563

564

565

566

567

568

569

570

571

572

573

574

575

576

577

578

579

580

581

582

583

584

585

586

587

588

589

590

591

592

593

594

595

596

597

598

599

600

601

602

603

604

605

606

607

608

609

610

611

612

613

614

615

616

617

618

619

620

621

622

623

624

625

626

627

628

629

630

631

632

633

634

635

636

637

638

639

640

641

642

643

644

645

646

647

648

649

650

651

652

653

654

655

656

657

658

659

660

661

662

663

664

665

666

667

668

669

670

671

672

673

674

675

676

677

678

679

680

681

682

683

684

685

686

687

688

689

690

691

692

693

694

695

696

697

698

699

700

701

702

703

704

705

706

707

708

709

710

711

712

713

714

715

716

717

718

719

720

721

722

723

724

725

726<
8000
/div>

--- *mini.completion* Completion and signature help

--- *MiniCompletion*

---

--- ==============================================================================

---

--- Key design ideas:

--- - Have an async (with customizable "debounce" delay) "two-stage chain

--- completion": first try to get completion items from LSP client (if set

--- up) and if no result, fallback to custom action.

---

--- - Managing completion is done as much with Neovim's built-in tools as

--- possible. |popupmenu-completion| is used to show completion suggestions.

8000

---

--- Features:

--- - Two-stage chain completion:

--- - First stage is an LSP completion implemented via

--- |MiniCompletion.completefunc_lsp()|. It should be set up as either

--- |completefunc| or |omnifunc|. It tries to get completion items from

--- LSP client (via 'textDocument/completion' request). Custom

--- preprocessing of response items is possible (with

--- `MiniCompletion.config.lsp_completion.process_items`), for example

--- with fuzzy matching. By default items directly starting with completed

--- word are kept and are sorted according to LSP specification.

--- Supports `additionalTextEdits`, like auto-import and others (see 'Notes'),

--- and snippet items (best results require |mini.snippets| dependency).

--- - If first stage is not set up or resulted into no candidates, fallback

--- action is executed. The most tested actions are Neovim's built-in

--- insert completion (see |ins-completion|).

---

--- - Automatic display in floating window of completion item info (via

--- 'completionItem/resolve' request) and signature help (with highlighting

--- of active parameter if LSP server provides such information).

--- Signature help is shown if character to cursor's left is a dedicated trigger

--- character (configured in `signatureHelpProvider.triggerCharacters` of LSP

--- server capabilities) and updated without delay if is currently opened.

--- Already shown window for signature help is fixed and is closed when there

--- is nothing to show, its text is different, or when leaving Insert mode.

--- Scroll in either info/signature window with `<C-f>` / `<C-b>` (by default).

---

--- - Automatic actions are done after some configurable amount of delay. This

--- reduces computational load and allows fast typing (completion and

--- signature help) and item selection (item info)

---

--- - Force two-stage/fallback completion (`<C-Space>` / `<A-Space>` by default).

---

--- - LSP kind highlighting ("Function", "Keyword", etc.). Requires Neovim>=0.11.

--- By default uses "lsp" category of |MiniIcons| (if enabled). Can be customized

--- via `config.lsp_completion.process_items` by adding field <kind_hlgroup>

--- (same meaning as in |complete-items|) to items.

---

--- What it doesn't do:

--- - Many configurable sources.

--- - Automatic mapping of `<CR>`, `<Tab>`, etc. Those tend to have highly

--- variable user expectations. See 'Helpful mappings' for suggestions or

--- use |MiniKeymap.map_multistep()| with `"pmenu_*"` built-in steps.

---

--- # Dependencies ~

---

--- Suggested dependencies (provide extra functionality, will work without them):

---

--- - Enabled |MiniIcons| module to highlight LSP kind (requires Neovim>=0.11).

--- If absent, |MiniCompletion.default_process_items()| does not add highlighting.

--- Also take a look at |MiniIcons.tweak_lsp_kind()|.

--- - Enabled |MiniSnippets| module for better snippet handling (much recommended).

--- If absent and custom snippet insert is not configured, |vim.snippet.expand()|

--- is used on Neovim>=0.10 (nothing extra is done on earlier versions).

--- See |MiniCompletion.default_snippet_insert()|.

---

--- # Setup ~

---

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

--- (replace `{}` with your `config` table). It will create global Lua table

--- `MiniCompletion` which you can use for scripting or manually (with

--- `:lua MiniCompletion.*`).

---

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

---

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

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

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

---

--- # Suggested option values ~

---

--- Some options are set automatically (if not set before |MiniCompletion.setup()|):

--- - 'completeopt' is set to "menuone,noselect" for less intrusive popup.

--- To enable fuzzy matching, manually set to "menuone,noselect,fuzzy".

--- - 'shortmess' is appended with "c" flag for silent <C-n> fallback.

---

--- # Snippets ~

---

--- As per LSP specification, some completion items can be supplied in the form of

--- snippet - a template with both pre-defined text and places (called "tabstops")

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

---

--- In 'mini.completion' items that will insert snippet have "S" symbol shown in

--- the popup (as part of `menu` in |complete-items|). To actually insert a snippet:

--- - Select an item via <C-n> / <C-p>. This will insert item's label (usually not

--- full snippet) first to reduce visual flicker. The full snippet text will be

--- shown in info window if LSP server doesn't provide its own info for an item.

--- - Press <C-y> (|complete_CTRL-Y|) or attempt inserting a non-keyword character

--- (like <CR>; new character will be removed). It will clear text from previous

--- step, set cursor, and call `lsp_completion.snippet_insert` with snippet text.

--- - Press <C-e> (|complete_CTRL-E|) to cancel snippet insert and properly end

--- completion.

---

--- See |MiniCompletion.default_snippet_insert()| for overview of how to work with

--- inserted snippets.

---

--- Notes:

--- - To stop LSP server from suggesting snippets, disable (set to `false`) the

--- following capability during LSP server start:

--- `textDocument.completion.completionItem.snippetSupport`.

--- - If snippet body doesn't contain tabstops, `lsp_completion.snippet_insert`

--- is not called and text is inserted as is.

---

--- # Notes ~

---

--- - A more appropriate (albeit slightly advanced) LSP completion setup is to set

--- it not on every |BufEnter| event (default), but on every attach of LSP client.

--- To do that:

--- - Use in |MiniCompletion.setup()| config: >lua

---

--- lsp_completion = { source_func = 'omnifunc', auto_setup = false }

--- <

--- - Set 'omnifunc' option to exactly `v:lua.MiniCompletion.completefunc_lsp`

--- for every client attach in an |LspAttach| event. Like this: >lua

---

--- local on_attach = function(args)

--- vim.bo[args.buf].omnifunc = 'v:lua.MiniCompletion.completefunc_lsp'

--- end

--- vim.api.nvim_create_autocmd('LspAttach', { callback = on_attach })

--- <

--- This setup is not default to allow simultaneous usage of filetype-specific

--- 'omnifunc' (with manual |i_CTRL-X_CTRL-O|) and automated LSP completion.

---

--- - Use |MiniCompletion.get_lsp_capabilities()| to get/set information about part

--- of LSP specification supported by module. See its help for usability notes.

---

--- - Uses `vim.lsp.protocol.CompletionItemKind` map in LSP step to show a readable

--- version of item's kind. Modify it directly to change what is displayed.

--- If you have |mini.icons| enabled, take a look at |MiniIcons.tweak_lsp_kind()|.

---

--- - If you have trouble using custom (overridden) |vim.ui.input|, disable

--- 'mini.completion' for input buffer (usually based on its 'filetype').

---

--- # Comparisons ~

---

--- - 'hrsh7th/nvim-cmp':

--- - Implements own popup menu to show completion candidates, while this

--- module reuses |ins-completion-menu|.

--- - Has more complex design which allows multiple sources, each in a form of

--- a separate plugin. This module has two built-in: LSP and fallback.

--- - Requires separate plugin for automated signature help.

--- - Implements own "ghost text" feature, while this module does not.

---

--- - 'Saghen/blink.cmp':

--- - Mostly similar to 'nvim-cmp' comparison: provides more features at the

--- cost of more code and config complexity, while this module is designed

--- to provide only a handful of "enough" features while relying on Neovim's

--- built-in capabilities as much as possible.

--- - Both provide automated signature help out of the box.

---

--- # Helpful mappings ~

---

--- If there is |mini.keymap| available, prefer using |MiniKeymap.map_multistep()|

--- with `"pmenu_*"` built-in steps. See |MiniKeymap-examples| for examples.

---

--- To use `<Tab>` and `<S-Tab>` for navigation through completion list, make

--- these mappings: >lua

---

--- local imap_expr = function(lhs, rhs)

--- vim.keymap.set('i', lhs, rhs, { expr = true })

--- end

--- imap_expr('<Tab>', [[pumvisible() ? "\<C-n>" : "\<Tab>"]])

--- imap_expr('<S-Tab>', [[pumvisible() ? "\<C-p>" : "\<S-Tab>"]])

--- <

--- To get more consistent behavior of `<CR>`, you can use this template in

--- your 'init.lua' to make customized mapping: >lua

---

--- _G.cr_action = function()

--- -- If there is selected item in popup, accept it with <C-y>

--- if vim.fn.complete_info()['selected'] ~= -1 then return '\25' end

--- -- Fall back to plain `<CR>`. You might want to customize according

--- -- to other plugins. For example if 'mini.pairs' is set up, replace

--- -- next line with `return MiniPairs.cr()`

--- return '\r'

--- end

---

--- vim.keymap.set('i', '<CR>', 'v:lua.cr_action()', { expr = true })

--- <

--- # Highlight groups ~

---

--- * `MiniCompletionActiveParameter` - signature active parameter.

--- * `MiniCompletionInfoBorderOutdated` - info window border when text is outdated

--- due to explicit delay during fast movement through candidates.

---

--- To change any highlight group, modify it directly with |:highlight|.

---

--- # Disabling ~

---

--- To disable, set `vim.g.minicompletion_disable` (globally) or

--- `vim.b.minicompletion_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.

-- Overall implementation design:

-- - Completion:

-- - On `InsertCharPre` event try to start auto completion. If needed,

-- start timer which after delay will start completion process. Stop this

-- timer if it is not needed.

-- - When timer is activated, first execute LSP source (if set up and there

-- is an active LSP client) by calling built-in complete function

-- (`completefunc` or `omnifunc`) which tries LSP completion by

-- asynchronously sending LSP 'textDocument/completion' request to all

-- LSP clients. When all are done, execute callback which processes

-- results, stores them in LSP cache and reruns built-in complete

-- function which produces completion popup.

-- - If previous step didn't result into any completion, execute (in Insert

-- mode and if no popup) fallback action.

-- - Documentation:

-- - On `CompleteChanged` start auto info with similar to completion timer

-- pattern.

-- - If timer is activated, try these sources of item info:

-- - 'info' field of completion item (see `:h complete-items`).

-- - 'documentation' field of LSP's previously returned result.

-- - 'documentation' field in result of asynchronous

-- 'completeItem/resolve' LSP request.

-- - If info doesn't consist only from whitespace, show floating window

-- with its content. Its dimensions and position are computed based on

-- current state of Neovim's data and content itself (which will be

-- displayed wrapped with `linebreak` option).

-- - Signature help (similar to item info):

-- - On `CursorMovedI` start auto signature (if there is any active LSP

-- client) with similar to completion timer pattern. Better event might

-- be `InsertCharPre` but there are issues with 'autopair-type' plugins.

-- Update immediately if already shown or after delay if character to the

-- left is signature help trigger (after delay has passed).

-- - If timer is activated, send 'textDocument/signatureHelp' request to

-- all LSP clients. On callback, process their results. Window is opened

-- if not already with the same text (its characteristics are computed

-- similar to item info). For every LSP client it shows only active

-- signature (in case there are many). If LSP response has data about

-- active parameter, it is highlighted with

-- `MiniCompletionActiveParameter` highlight group.

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

local MiniCompletion = {}

local H = {}

--- Module setup

---

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

---

---@usage >lua

--- require('mini.completion').setup() -- use default config

--- -- OR

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

--- <

MiniCompletion.setup = function(config)

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

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

vim.notify(

'(mini.completion) Neovim<0.9 is soft deprecated (module works but not supported).'

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

.. ' Please update your Neovim version.'

)

end

-- Export module

_G.MiniCompletion = MiniCompletion

-- Setup config

config = H.setup_config(config)

-- Apply config

H.apply_config(config)

-- Define behavior

H.create_autocommands(config)

-- Create default highlighting

H.create_default_hl()

end

--- Module config

---

--- Default values:

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

MiniCompletion.config = {

-- Delay (debounce type, in ms) between certain Neovim event and action.

-- This can be used to (virtually) disable certain automatic actions by

-- setting very high delay time (like 10^7).

delay = { completion = 100, info = 100, signature = 50 },

-- Configuration for action windows:

-- - `height` and `width` are maximum dimensions.

-- - `border` defines border (as in `nvim_open_win()`; default "single").

window = {

info = { height = 25, width = 80, border = nil },

signature = { height = 25, width = 80, border = nil },

-- Way of how module does LSP completion

lsp_completion = {

-- `source_func` should be one of 'completefunc' or 'omnifunc'.

source_func = 'completefunc',

-- `auto_setup` should be boolean indicating if LSP completion is set up

-- on every `BufEnter` event.

auto_setup = true,

-- A function which takes LSP 'textDocument/completion' response items

-- (each with `client_id` field for item's server) and word to complete.

-- Output should be a table of the same nature as input. Common use case

-- is custom filter/sort. Default: `default_process_items`

process_items = nil,

-- A function which takes a snippet as string and inserts it at cursor.

-- Default: `default_snippet_insert` which tries to use 'mini.snippets'

-- and falls back to `vim.snippet.expand` (on Neovim>=0.10).

snippet_insert = nil,

-- Fallback action as function/string. Executed in Insert mode.

-- To use built-in completion (`:h ins-completion`), set its mapping as

-- string. Example: set '<C-x><C-l>' for 'whole lines' completion.

fallback_action = '<C-n>',

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

-- might conflict with system mappings.

mappings = {

-- Force two-step/fallback completions

force_twostep = '<C-Space>',

force_fallback = '<A-Space>',

-- Scroll info/signature window down/up. When overriding, check for

-- conflicts with built-in keys for popup menu (like `<C-u>`/`<C-o>`

-- for 'completefunc'/'omnifunc' source function; or `<C-n>`/`<C-p>`).

scroll_down = '<C-f>',

scroll_up = '<C-b>',

}

--minidoc_afterlines_end

-- Module functionality =======================================================

--- Run two-stage completion

---

---@param fallback boolean|nil Whether to use fallback completion. Default: `true`.

---@param force boolean|nil Whether to force update of completion popup.

--- Default: `true`.

MiniCompletion.complete_twostage = function(fallback, force)

if H.is_disabled() then return end

if fallback == nil then fallback = true end

if force == nil then force = true end

H.stop_completion()

H.completion.fallback, H.completion.force = fallback, force

H.trigger_twostep()

end

--- Run fallback completion

MiniCompletion.complete_fallback = function()

if H.is_disabled() then return end

H.stop_completion()

H.completion.fallback, H.completion.force = true, true

H.trigger_fallback()

end

--- Scroll in info/signature window

---

--- Designed to be used in |:map-<expr>|.

--- Scrolling is done as if |CTRL-F| and |CTRL-B| is pressed inside target window.

--- Used in default `config.mappings.scroll_xxx` mappings.

---

---@param direction string One of `"down"` or `"up"`.

---

---@return boolean Whether scroll is scheduled to be done.

MiniCompletion.scroll = function(direction)

if not (direction == 'down' or direction == 'up') then H.error('`direction` should be one of "up" or "down"') end

local win_id = H.is_valid_win(H.info.win_id) and H.info.win_id

or (H.is_valid_win(H.signature.win_id) and H.signature.win_id or nil)

if win_id == nil then return false end

-- Schedule execution as scrolling is not allowed in expression mappings

local key = direction == 'down' and '\6' or '\2'

vim.schedule(function()

if not H.is_valid_win(win_id) then return end

vim.api.nvim_win_call(win_id, function() vim.cmd('noautocmd normal! ' .. key) end)

end)

return true

end

--- Stop actions

---

--- This stops currently active (because of module delay or LSP answer delay)

--- actions.

---

--- Designed to be used with |autocmd|. No need to use it directly, everything

--- is setup in |MiniCompletion.setup|.

---

---@param actions table|nil Array containing any of 'completion', 'info', or

--- 'signature' string. Default: array containing all of them.

MiniCompletion.stop = function(actions)

actions = actions or { 'completion', 'info', 'signature' }

for _, n in pairs(actions) do

H.stop_actions[n]()

end

--- Module's |complete-function|

---

--- This is the main function which enables two-stage completion. It should be

--- set as one of |completefunc| or |omnifunc|.

---

--- No need to use it directly, everything is setup in |MiniCompletion.setup|.

MiniCompletion.completefunc_lsp = function(findstart, base)

-- Early return

if not H.has_lsp_clients('completionProvider') or H.completion.lsp.status == 'sent' then

return findstart == 1 and -3 or {}

end

-- NOTE: having code for request inside this function enables its use

-- directly with `<C-x><...>` and as a reaction to `<BS>`.

if H.completion.lsp.status ~= 'received' then

-- NOTE: it is CRUCIAL to make LSP request on the first call to

-- 'complete-function' (as in Vim's help). This is due to the fact that

-- cursor line and position are different on the first and second calls to

-- 'complete-function'. For example, when calling this function at the end

-- of the line ' he', cursor position on the first call will be

-- (<linenum>, 4) and line will be ' he' but on the second call -

-- (<linenum>, 2) and ' ' (because 2 is a column of completion start).

-- This request is not executed on second call because it returns `-3` on

-- first call (which means cancel and leave completion mode).

H.make_completion_request()

-- End completion and wait for LSP callback to re-trigger this

return findstart == 1 and -3 or {}

else

if findstart == 1 then

H.completion.start_pos = H.get_completion_start(H.completion.lsp.result)

return H.completion.start_pos[2]

end

local is_incomplete = false

local all_items = H.process_lsp_response(H.completion.lsp.result, function(response, client_id)

is_incomplete = is_incomplete or (response.isIncomplete == true)

-- Response can be `CompletionList` with 'items' field plus their

-- defaults or `CompletionItem[]`

local items = H.table_get(response, { 'items' }) or response

if type(items) ~= 'table' then return {} end

items = H.apply_item_defaults(items, response.itemDefaults)

for _, item in ipairs(items) do

item.client_id = client_id

end

return items

end)

-- Process items

local process_items = H.get_config().lsp_completion.process_items or MiniCompletion.default_process_items

all_items = process_items(all_items, base)

local candidates = H.lsp_completion_response_items_to_complete_items(all_items)

H.completion.lsp.status = 'done'

H.completion.lsp.is_incomplete = is_incomplete

-- Maybe trigger fallback action

if vim.tbl_isempty(candidates) and H.completion.fallback then return H.trigger_fallback() end

-- Track from which source is current popup

H.completion.source = 'lsp'

return candidates

end

--- Default processing of LSP items

---

--- Steps:

--- - Filter and sort items according to supplied method.

--- - Arrange items further by completion item kind according to their priority.

--- - If |MiniIcons| is enabled, add <kind_hlgroup> based on the "lsp" category.

---

--- Example of forcing fuzzy matching, filtering out `Text` items, and putting

--- `Snippet` items last: >lua

---

--- local kind_priority = { Text = -1, Snippet = 99 }

--- local opts = { filtersort = 'fuzzy', kind_priority = kind_priority }

--- local process_items = function(items, base)

--- return MiniCompletion.default_process_items(items, base, opts)

--- end

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

--- lsp_completion = { process_items = process_items },

--- })

--- <

---@param items table Array of items from LSP response.

---@param base string Base for which completion is done. See |complete-functions|.

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

--- - <filtersort> `(string|function)` - method of filtering and sorting items.

--- If string, should be one of the following:

--- - `'prefix'` - filter out items not starting with `base`, sort according

--- to LSP specification. Use `filterText` and `sortText` respectively with

--- fallback to `label`.

--- - `'fuzzy'` - filter and sort with |matchfuzzy()| using `filterText`.

--- - `'none'` - no filter and no sort.

--- If callable, should take `items` and `base` arguments and return items array.

--- Default: `'fuzzy'` if 'completeopt' contains "fuzzy", `'prefix'` otherwise.

--- - <kind_priority> `(table)` - map of completion item kinds (like `Variable`,

--- `Snippet`; see string keys of `vim.lsp.protocol.CompletionItemKind`) to

--- their numerical priority. It will be used after applying <filtersort> to

--- arrange by completion item kind: items with negative priority kinds will

--- be filtered out, the rest are sorted by decreasing priority (preserving

--- order in case of same priority).

--- Priorities can be any number, only matters how they compare to each other.

--- Value 100 is used for missing kinds (i.e. not all can be supplied).

--- Default: `{}` (all equal priority).

---

---@return table Array of processed items from LSP response.

MiniCompletion.default_process_items = function(items, base, opts)

opts = opts or {}

-- Filter+sort (important with frequent `isIncomplete`)

local fs = opts.filtersort or (vim.o.completeopt:find('fuzzy') ~= nil and 'fuzzy' or 'prefix')

if type(fs) == 'string' then fs = H.filtersort_methods[fs] end

if not vim.is_callable(fs) then H.error('`filtersort` should be callable or one of "prefix", "fuzzy", "none"') end

local res = fs(items, base)

-- Arrange by kind

if opts.kind_priority ~= nil then res = H.lsp_arrange_by_kind(res, opts.kind_priority) end

-- Possibly add "kind" highlighting

if _G.MiniIcons == nil then return res end

local add_kind_hlgroup = H.make_add_kind_hlgroup()

for _, item in ipairs(res) do

add_kind_hlgroup(item)

end

return res

end

--- Default snippet insert

---

--- Order of preference:

--- - Use |MiniSnippets| if set up (i.e. there is `require('mini.snippets').setup()`).

--- - Use |vim.snippet.expand()| on Neovim>=0.10

--- - Add snippet text at cursor as is.

---

--- After snippet is inserted, user is expected to navigate/jump between dedicated

--- places (tabstops) to adjust inserted text as needed:

--- - |MiniSnippets| by default uses <C-l> / <C-h> to jump to next/previous tabstop.

--- Can be adjusted in `mappings` of |MiniSnippets.config|.

--- - |vim.snippet| on Neovim=0.10 requires manually created mappings for jumping

--- between tabstops (see |vim.snippet.jump()|). Neovim>=0.11 sets them up

--- automatically to <Tab> / <S-Tab> (if not overridden by user).

---

--- End session by navigating all the way to the last tabstop. In 'mini.snippets':

--- - Also make any text edit or exit Insert mode to end the session. This allows

--- smoother navigation to previous tabstops in case of a lately spotted typo.

--- - Press `<C-c>` to force session stop.

---

---@param snippet string Snippet body to insert at cursor.

---

---@seealso |MiniSnippets-session| if 'mini.snippets' is set up.

--- |vim.snippet| for Neovim's built-in snippet engine.

MiniCompletion.default_snippet_insert = function(snippet)

if _G.MiniSnippets then

local insert = MiniSnippets.config.expand.insert or MiniSnippets.default_insert

return insert({ body = snippet })

end

if vim.fn.has('nvim-0.10') == 1 then return vim.snippet.expand(snippet) end

local pos, lines = vim.api.nvim_win_get_cursor(0), vim.split(snippet, '\n')

vim.api.nvim_buf_set_text(0, pos[1] - 1, pos[2], pos[1] - 1, pos[2], lines)

local n = #lines

local new_pos = n == 1 and { pos[1], pos[2] + lines[n]:len() } or { pos[1] + n - 1, lines[n]:len() }

vim.api.nvim_win_set_cursor(0, new_pos)

end

--- Get client LSP capabilities

---

--- Possible usages:

--- - On Neovim>=0.11 via |vim.lsp.config()|: >lua

---

--- vim.lsp.config('*', {capabilities = MiniCompletion.get_lsp_capabilities()})

--- <

--- - Together with |vim.lsp.protocol.make_client_capabilities()| to get the full

--- client capabilities (use |vim.tbl_deep_extend()| to merge tables).

---

--- - Manually execute `:=MiniCompletion.get_lsp_capabilities()` to see the info.

---

--- Notes:

--- - It declares completion resolve support for `'additionalTextEdits'` (usually

--- used for something like auto-import feature), as it is usually a more robust

--- choice for various LSP servers. As a consequence, this requires selecting

--- completion item and waiting for `config.delay.info` milliseconds plus server

--- response time (i.e. until information window shows relevant text).

--- To not have to wait after an item selection and if the server handles absent

--- `'additionalTextEdits'` well, set `opts.resolve_additional_text_edits = false`.

---

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

--- - <resolve_additional_text_edits> `(boolean)` - whether to declare

--- `'additionalTextEdits'` as possible to resolve in `'completionitem/resolve'`

--- requrest. See above "Notes" section.

--- Default: `true`.

---

---@return table Data about LSP capabilities supported by 'mini.completion'. Has same

--- structure as relevant parts of |vim.lsp.protocol.make_client_capabilities()|.

---

---@seealso Structures of `completionClientCapabilities` and `signatureHelpClientCapabilities`

--- at https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification

MiniCompletion.get_lsp_capabilities = function(opts)

opts = vim.tbl_extend('force', { resolve_additional_text_edits = true }, opts or {})

local resolve_support = { 'detail', 'documentation' }

if opts.resolve_additional_text_edits then table.insert(resolve_support, 1, 'additionalTextEdits') end

return {

textDocument = {

-- https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#completionClientCapabilities

completion = {

dynamicRegistration = false,

completionItem = {

snippetSupport = true,

commitCharactersSupport = false,

documentationFormat = { 'markdown', 'plaintext' },

deprecatedSupport = false,

preselectSupport = false,

tagSupport = { valueSet = {} },

insertReplaceSupport = true,

resolveSupport = { properties = resolve_support },

insertTextModeSupport = { valueSet = { 1 } },

labelDetailsSupport = true,

completionItemKind = {

valueSet = { 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25 },

contextSupport = true,

insertTextMode = 1,

completionList = {

itemDefaults = { 'commitCharacters', 'editRange', 'insertTextFormat', 'insertTextMode', 'data' },

-- https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#signatureHelpClientCapabilities

signatureHelp = {

dynamicRegistration = false,

signatureInformation = {

documentationFormat = { 'markdown', 'plaintext' },

parameterInformation = {

labelOffsetSupport = true,

activeParameterSupport = true,

contextSupport = false,

}

end

-- Helper data ================================================================

-- Module default config

H.default_config = vim.deepcopy(MiniCompletion.config)

-- Track Insert mode changes

H.text_changed_id = 0

-- Namespace for highlighting

H.ns_id = vim.api.nvim_create_namespace('MiniCompletion')

-- Commonly used key sequences

H.keys = {

completefunc = vim.api.nvim_replace_termcodes('<C-x><C-u>', true, false, true),

omnifunc = vim.api.nvim_replace_termcodes('<C-x><C-o>', true, false, true),

ctrl_n = vim.api.nvim_replace_termcodes('<C-g><C-g><C-n>', true, false, true),

}

-- Caches for different actions -----------------------------------------------

-- Field `lsp` is a table describing state of all used LSP requests. It has the

-- following structure:

-- - id: identifier (consecutive numbers).

-- - status: one of 'sent', 'received', 'done', 'canceled'

-- - is_incomplete: whether request was incomplete and require recomputing

-- - result: result of request.

-- - cancel_fun: function which cancels current request.

-- Cache for completion

H.completion = {

fallback = true,

force = false,

source = nil,

text_changed_id = 0,

timer = vim.loop.new_timer(),

lsp = { id = 0, status = nil, is_incomplete = false, result = nil, resolved = {}, cancel_fun = nil, context = nil },

start_pos = {},

}

-- Cache for completion item info

H.info = {

bufnr = nil,

event = nil,

id = 0,

timer = vim.loop.new_timer(),

win_id = nil,

lsp = { id = 0, status = nil, result = nil, cancel_fun = nil },

}

-- Cache for signature help

H.signature = {

bufnr = nil,

text = nil,

timer = vim.loop.new_timer(),

win_id = nil,

lsp = { id = 0, status = nil, result = nil, cancel_fun = nil },

}

-- Helper functionality =======================================================

-- Settings -------------------------------------------------------------------

H.setup_config = function(config)

H.check_type('config', config, 'table', true)

config = vim.tbl_deep_extend('force', vim.deepcopy(H.default_config), config or {})

H.check_type('delay', config.delay, 'table')

H.check_type('window', config.window, 'table')

H.check_type('lsp_completion', config.lsp_completion, 'table')

if not (type(config.fallback_action) == 'function' or type(config.fallback_action) == 'string') then

H.error('`fallback_action` should be function or string, not ' .. type(config.fallback_action))

end

H.check_type('mappings', config.mappings, 'table')

H.check_type('delay.completion', config.delay.completion, 'number')

H.check_type('delay.info', config.delay.info, 'number')

H.check_type('delay.signature', config.delay.signature, 'number')

H.check_type('window.info', config.window.info, 'table')

H.check_type('window.signature', config.window.signature, 'table')

if not (config.lsp_completion.source_func == 'completefunc' or config.lsp_completion.source_func == 'omnifunc') then

H.error('`lsp_completion.source_func` should be one of "completefunc" or "omnifunc"')

end

H.check_type('lsp_completion.auto_setup', config.lsp_completion.auto_setup, 'boolean')

H.check_type('lsp_completion.process_items', config.lsp_completion.process_items, 'callable', true)

H.check_type('lsp_completion.snippet_insert', config.lsp_completion.snippet_insert, 'callable', true)

H.check_type('mappings.force_twostep', config.mappings.force_twostep, 'string')

H.check_type('mappings.force_fallback', config.mappings.force_fallback, 'string')

H.check_type('mappings.scroll_down', config.mappings.scroll_down, 'string')

H.check_type('mappings.scroll_up', config.mappings.scroll_up, 'string')

local is_string_or_array = function(x) return type(x) == 'string' or H.islist(x) end

H.check_type('window.info.height', config.window.info.height, 'number')

H.check_type('window.info.width', config.window.info.width, 'number')

if not is_string_or_array(config.window.info.border or 'single') then

H.error('`config.window.info.border` should be either string or array, not ' .. type(config.window.info.border))

end

H.check_type('window.signature.height', config.window.signature.height, 'number')

H.check_type('window.signature.width', config.window.signature.width, 'number')

if not is_string_or_array(config.window.signature.border or 'single') then

H.error(

'`config.window.signature.border` should be either string or array, not ' .. type(config.window.signature.border)

)

end

return config

end

H.apply_config = function(config)

MiniCompletion.config = config

H.map('i', config.mappings.force_twostep, MiniCompletion.complete_twostage, { desc = 'Complete with two-stage' })

H.map('i', config.mappings.force_fallback, MiniCompletion.complete_fallback, { desc = 'Complete with fallback' })

local map_scroll = function(lhs, direction)

local rhs = function() return MiniCompletion.scroll(direction) and '' or lhs end

H.map('i', lhs, rhs, { expr = true, desc = 'Scroll info/signature ' .. direction })

end

map_scroll(config.mappings.scroll_down, 'down')

map_scroll(config.mappings.scroll_up, 'up')

-- Try setting suggested option values

-- TODO: use `nvim_get_option_info2` after Neovim=0.8 support is dropped

-- - More common completion behavior

local was_set = vim.api.nvim_get_option_info('completeopt').was_set

if not was_set then vim.o.completeopt = 'menuone,noselect' end

-- - Don't show ins-completion-menu messages ("C" is default on Neovim>=0.10)

local shortmess_flags = 'c' .. ((vim.fn.has('nvim-0.9') == 1 and vim.fn.has('nvim-0.10') == 0) and 'C' or '')

was_set = vim.api.nvim_get_option_info('shortmess').was_set

if not was_set then vim.opt.shortmess:append(shortmess_flags) end

end

H.create_autocommands = function(config)

local gr = vim.api.nvim_create_augroup('MiniCompletion', {})

local au = function(event, pattern, callback, desc)

vim.api.nvim_create_autocmd(event, { group = gr, pattern = pattern, callback = callback, desc = desc })

end

au('InsertCharPre', '*', H.auto_completion, 'Auto show completion')

au('CompleteChanged', '*', H.auto_info, 'Auto show info')

au('CursorMovedI', '*', H.auto_signature, 'Auto show signature')

au('ModeChanged', 'i*:[^i]*', function() MiniCompletion.stop() end, 'Stop completion')

au('CompleteDonePre', '*', H.on_completedonepre, 'On CompleteDonePre')

au('TextChangedI', '*', H.on_text_changed_i, 'On TextChangedI')

au('TextChangedP', '*', H.on_text_changed_p, 'On TextChangedP')

if config.lsp_completion.auto_setup then

local source_func = config.lsp_completion.source_func

local callback = function() vim.bo[source_func] = 'v:lua.MiniCompletion.completefunc_lsp' end

au('BufEnter', '*', callback, 'Set completion function')

end

au('ColorScheme', '*', H.create_default_hl, 'Ensure colors')

au('FileType', 'TelescopePrompt', function() vim.b.minicompletion_disable = true end, 'Disable locally')

end

H.create_default_hl = function()

vim.api.nvim_set_hl(0, 'MiniCompletionActiveParameter', { default = true, link = 'LspSignatureActiveParameter' })

vim.api.nvim_set_hl(0, 'MiniCompletionInfoBorderOutdated', { default = true, link = 'DiagnosticFloatingWarn' })

end

H.is_disabled = function() return vim.g.minicompletion_disable == true or vim.b.minicompletion_disable == true end

H.get_config = function(config)

return vim.tbl_deep_extend('force', MiniCompletion.config, vim.b.minicompletion_config or {}, config or {})

end

-- Autocommands ---------------------------------------------------------------

H.auto_completion = function()

if H.is_disabled() then return end

H.completion.timer:stop()

local is_incomplete = H.completion.lsp.is_incomplete

local is_trigger = H.is_lsp_trigger(vim.v.char, 'completion')

local force = is_trigger or is_incomplete

if force then

-- Force fresh LSP completion if needed. Check before checking pumvisible

-- because it should be forced even if there are visible candidates.

-- Keep positive `is_incomplete` to allow fast typing and not "forget" that

-- list was incomplete after the second fast key press. This will force LSP

-- completion until `isIncomplete=false` response or general `stop()`.

H.stop_completion(false, is_incomplete)

elseif H.pumvisible() then

-- Do nothing if popup is visible. `H.pumvisible()` might be `true` even if

-- there is no popup. It is common when manually typing candidate followed

-- by an LSP trigger (like ".").

-- Keep completion source as it is needed all time when popup is visible.

-- Keep resolved candidates because they should be relevant in this route.

return H.stop_completion(true, false, true)

elseif not H.is_char_keyword(vim.v.char) then

-- Stop everything if inserted character is not appropriate. Check this

-- after popup check to allow completion candidates to have bad characters.

return H.stop_completion(false)

end

-- Start non-forced completion with fallback or forced LSP source for trigger

H.completion.fallback, H.completion.force = not force, force

-- Cache id of Insert mode "text changed" event for a later tracking (reduces

-- false positive delayed triggers). The intention is to trigger completion

-- after the delay only if text wasn't changed during waiting. Using only

-- `InsertCharPre` is not enough though, as not every Insert mode change

-- triggers `InsertCharPre` event (notable example - hitting `<CR>`).

-- Also, using `+ 1` here because it is a `Pre` event and needs to cache

-- after inserting character.

H.completion.text_changed_id = H.text_changed_id + 1

-- If completion was requested after 'lsp' source exhausted itself (there

-- were matches on typing start, but they disappeared during filtering), call

-- fallback immediately.

if H.completion.source == 'lsp' then return H.trigger_fallback() end

-- Set completion context with information about how it was triggered

-- Prefer manual `TriggerCharacter` over automated `...ForIncomplete...`.

local trigger_kind_name = is_trigger and 'TriggerCharacter'

or (is_incomplete and 'TriggerForIncompleteCompletions' or 'Invoked')

local trigger_kind = vim.lsp.protocol.CompletionTriggerKind[trigger_kind_name]

local trigger_char = trigger_kind_name == 'TriggerCharacter' and vim.v.char or nil

H.completion.lsp.context = { triggerKind = trigger_kind, triggerCharacter = trigger_char }

-- Debounce delay improves experience (can type fast without many popups)

-- Request right away if improving incomplete suggestions (less flickering),

-- but still with `vim.schedule` because line is still not up to date during

-- `InsertCharPre` event.

local delay = is_incomplete and 0 or H.get_config().delay.completion

H.completion.timer:start(delay, 0, vim.schedule_wrap(H.trigger_twostep))

end

H.auto_info = function()

if H.is_disabled() then return end

-- Stop current LSP request that tries to get already not current data

H.cancel_lsp({ H.info })

-- Update metadata before leaving to register a `CompleteChanged` event

H.info.timer:stop()

H.info.event = vim.v.event

H.info.id = H.info.id + 1

-- Stop showing window if no candidate is selected

local completed_item = H.info.event.completed_item

if completed_item.word == nil then return vim.schedule(function() H.close_action_window(H.info, true) end) end

-- Show info content without delay for visited and resolved LSP item.

-- Otherwise delay to not spam LSP requests on up/down navigation.

local item_id = H.table_get(completed_item, { 'user_data', 'lsp', 'item_id' })

local is_resolved = H.completion.lsp.resolved[item_id] ~= nil

local delay = is_resolved and 0 or H.get_config().delay.info

-- Mark visually that currently shown content will be outdated for a while

local win_id = H.info.win_id

if H.is_valid_win(win_id) and delay > 0 then

vim.wo[win_id].winhighlight = vim.wo[win_id].winhighlight .. ',FloatBorder:MiniCompletionInfoBorderOutdated'

end

H.info.timer:start(delay, 0, vim.schedule_wrap(H.show_info_window))

end

H.auto_signature = function()

if H.is_disabled() then return end

H.signature.timer:stop()

if not H.has_lsp_clients('signatureHelpProvider') then return end

local is_shown = H.is_valid_win(H.signature.win_id)

local left_char_is_trigger = H.is_lsp_trigger(H.get_left_char(), 'signature')

if not (is_shown or left_char_is_trigger) then return end

local delay = is_shown and 0 or H.get_config().delay.signature

H.signature.timer:start(delay, 0, vim.schedule_wrap(H.show_signature_window))

end

H.on_completedonepre = function()

-- Do nothing if it is triggered inside `trigger_lsp()` as a result of

-- emulating 'completefunc'/'omnifunc' keys. This can happen if popup is

-- visible and pressing keys first hides it with 'CompleteDonePre' event.

if H.completion.lsp.status == 'received' then return end

-- Do extra actions for LSP completion items

local lsp_data = H.table_get(vim.v.completed_item, { 'user_data', 'lsp' })

if lsp_data ~= nil then H.make_lsp_extra_actions(lsp_data) end

-- Stop processes

MiniCompletion.stop({ 'completion', 'info' })

end

H.on_text_changed_i = function()

-- Track Insert mode changes

H.text_changed_id = H.text_changed_id + 1

-- Stop 'info' processes in case no completion event is triggered but popup

-- is not visible. See https://github.com/neovim/neovim/issues/15077

H.stop_info()

end

H.on_text_changed_p = function()

-- Track Insert mode changes

H.text_changed_id = H.text_changed_id + 1

end

-- Completion triggers --------------------------------------------------------

H.trigger_twostep = function()

-- Trigger only in Insert mode and if text didn't change after trigger

-- request, unless completion is forced

-- NOTE: check for `text_changed_id` equality is still not 100% solution as

-- there are cases when, for example, `<CR>` is hit just before this check.

-- Because of asynchronous id update and this function call (called after

-- delay), these still match.

local allow_trigger = (vim.fn.mode() == 'i')

and (H.completion.force or (H.completion.text_changed_id == H.text_changed_id))

if not allow_trigger then return end

if H.has_lsp_clients('completionProvider') and H.has_lsp_completion() then

H.trigger_lsp()

elseif H.completion.fallback then

H.trigger_fallback()

end

H.trigger_lsp = function()

-- Check for popup visibility is needed to reduce flickering.

-- Possible issue timeline (with 100ms delay with set up LSP):

-- 0ms: Key is pressed.

-- 100ms: LSP is triggered from first key press.

-- 110ms: Another key is pressed.

-- 200ms: LSP callback is processed, triggers complete-function which

-- processes "received" LSP request.

-- 201ms: LSP request is processed, completion is (should be almost

-- immediately) provided, request is marked as "done".

-- 210ms: LSP is triggered from second key press. As previous request is

-- "done", it will once make whole LSP request. Having check for visible

-- popup should prevent here the call to complete-function.

-- Do not trigger if not needed and/or allowed

if vim.fn.mode() ~= 'i' or (H.pumvisible() and not H.completion.force) then return end

-- Overall idea: first make LSP request and re-trigger this same function

-- inside its callback to take the "received" route. This reduces flickering

View remainder of file in raw view

FilesExpand file tree

completion.lua

Latest commit

History

completion.lua

File metadata and controls