mini.nvim/doc/mini-jump2d.txt at main · tonyrt2/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

*mini.jump2d* Jump within visible lines

*MiniJump2d*

==============================================================================

Jump within visible lines via iterative label filtering.

Features:

- Make jump by iterative filtering of possible, equally considered jump

spots until there is only one. Filtering is done by typing a label

character that is visualized at jump spot.

- Customizable (see |MiniJump2d.config|):

- Way of computing possible jump spots with opinionated default.

- Characters used to label jump spots during iterative filtering.

- Visual effects: how many steps ahead to show; dim lines with spots.

- Action hooks to be executed at certain events during jump.

- Allowed windows: current and/or not current.

- Allowed lines: whether to process blank or folded lines, lines

before/at/after cursor line, etc. Example: user can configure to look

for spots only inside current window at or after cursor line.

Example: user can configure to look for word starts only inside current

window at or after cursor line with 'j' and 'k' labels performing some

action after jump.

- Works in Visual and Operator-pending (with dot-repeat) modes.

- Preconfigured ways of computing jump spots (see |MiniJump2d.builtin_opts|):

- Starts of lines.

- Starts of words.

- Single character from user input.

- Variable length query from user input.

- Works with multibyte characters.

General overview of how jump is intended to be performed:

- Lock eyes on desired location ("spot") recognizable by future jump.

Should be within visible lines at place where cursor can be placed.

- Initiate jump. Either by custom keybinding or with a call to

|MiniJump2d.start()| (allows customization options). This will highlight

all possible jump spots with their labels (letters from "a" to "z" by

default). For more details, read |MiniJump2d.start()| and |MiniJump2d.config|.

- Type character that appeared over desired location. If its label was

unique, jump is performed. If it wasn't unique, possible jump spots are

filtered to those having the same label character.

- Repeat previous step until there is only one possible jump spot or type <CR>

to jump to first available jump spot. Typing anything else stops jumping

without moving cursor.

# Setup ~

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

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

`MiniJump2d` which you can use for scripting or manually (with

`:lua MiniJump2d.*`).

See |MiniJump2d.config| for available config settings.

You can override runtime config settings locally to buffer inside

`vim.b.minijump2d_config` which should have same structure as

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

To stop module from showing non-error feedback, set `config.silent = true`.

# Example usage ~

- Modify default jumping to use only current window at or after cursor line: >lua

require('mini.jump2d').setup({

allowed_lines = { cursor_before = false },

allowed_windows = { not_current = false },

})

- Jump to line start using combination of options supplied in

|MiniJump2d.config| and |MiniJump2d.builtin_opts.line_start|: >vim

:lua MiniJump2d.start(MiniJump2d.builtin_opts.line_start)

- Jump to a single character typed after executing this command: >vim

:lua MiniJump2d.start(MiniJump2d.builtin_opts.single_character)

- See more examples in |MiniJump2d.start| and |MiniJump2d.builtin_opts|.

# Comparisons ~

- 'phaazon/hop.nvim':

- Both are fast, customizable, and extensible (user can write their own

ways to define jump spots).

- 'hop.nvim' visualizes all steps at once. While this module can show

configurable number of steps ahead.

- Both have several builtin ways to specify type of jump (word start,

line start, one character or query based on user input). 'hop.nvim'

does that by exporting many targeted Neovim commands, while this

module has preconfigured basic options leaving others to

customization with Lua code (see |MiniJump2d.builtin_opts|).

- 'hop.nvim' computes labels (called "hints") differently. Contrary to

this module deliberately not having preference of one jump spot over

another, 'hop.nvim' uses specialized algorithm that produces sequence

of keys in a slightly biased manner: some sequences are intentionally

shorter than the others (leading to fewer average keystrokes). They

are put near cursor (by default) and highlighted differently. Final

order of sequences is based on distance to the cursor.

- 'mini.jump2d' has opinionated default algorithm of computing jump

spots. See |MiniJump2d.default_spotter|.

# Highlight groups ~

* `MiniJump2dSpot` - highlighting of jump spot's next step. By default it

uses label with highest contrast while not being too visually demanding:

white on black for dark 'background', black on white for light. If it

doesn't suit your liking, try couple of these alternatives (or choose

your own, of course): >lua

-- Reverse underlying colors (mostly *very* visible in any colorscheme)

vim.api.nvim_set_hl(0, 'MiniJump2dSpot', { reverse = true })

-- Bold italic

vim.api.nvim_set_hl(0, 'MiniJump2dSpot', { bold = true, italic = true })

-- Red undercurl

vim.api.nvim_set_hl(0, 'MiniJump2dSpot', { sp = 'Red', undercurl = true })

* `MiniJump2dSpotUnique` - highlighting of jump spot's next step if it has

unique label. By default links to `MiniJump2dSpot`.

* `MiniJump2dSpotAhead` - highlighting of jump spot's future steps. By default

similar to `MiniJump2dSpot` but with less contrast and visibility.

* `MiniJump2dDim` - highlighting of lines with at least one jump spot.

Make it non-bright in order for jump spot labels to be more visible.

By default linked to `Comment` highlight group.

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

# Disabling ~

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

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

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

*MiniJump2d.setup()*

`MiniJump2d.setup`({config})

Module setup

Parameters ~

{config} `(table|nil)` Module config table. See |MiniJump2d.config|.

Usage ~

>lua

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

-- OR

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

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

*MiniJump2d.config*

`MiniJump2d.config`

Module config

Default values:

>lua

MiniJump2d.config = {

-- Function producing jump spots (byte indexed) for a particular line.

-- For more information see |MiniJump2d.start|.

-- If `nil` (default) - use |MiniJump2d.default_spotter|

spotter = nil,

-- Characters used for labels of jump spots (in supplied order)

labels = 'abcdefghijklmnopqrstuvwxyz',

-- Options for visual effects

view = {

-- Whether to dim lines with at least one jump spot

dim = false,

-- How many steps ahead to show. Set to big number to show all steps.

n_steps_ahead = 0,

-- Which lines are used for computing spots

allowed_lines = {

blank = true, -- Blank line (not sent to spotter even if `true`)

cursor_before = true, -- Lines before cursor line

cursor_at = true, -- Cursor line

cursor_after = true, -- Lines after cursor line

fold = true, -- Start of fold (not sent to spotter even if `true`)

-- Which windows from current tabpage are used for visible lines

allowed_windows = {

current = true,

not_current = true,

-- Functions to be executed at certain events

hooks = {

before_start = nil, -- Before jump start

after_jump = nil, -- After jump was actually done

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

mappings = {

start_jumping = '<CR>',

-- Whether to disable showing non-error feedback

-- This also affects (purely informati 8000 onal) helper messages shown after

-- idle time if user input is required.

silent = false,

}

# Options ~

## Spotter function ~

Actual computation of possible jump spots is done through spotter function.

It should have the following arguments:

- `line_num` is a line number inside buffer.

- `args` - table with additional arguments:

- {win_id} - identifier of a window where input line number is from.

- {win_id_init} - identifier of a window which was current when

`MiniJump2d.start()` was called.

Its output is a list of byte-indexed positions that should be considered as

possible jump spots for this particular line in this particular window.

Note: for a more aligned visualization this list should be (but not

strictly necessary) sorted increasingly.

Note: spotter function is always called with `win_id` window being

"temporary current" (see |nvim_win_call|). This allows using builtin

Vimscript functions that operate only inside current window.

## View ~

Option `view.n_steps_ahead` controls how many steps ahead to show along

with the currently required label. Those future steps are shown with

different (less visible) highlight group ("MiniJump2dSpotAhead"). Usually

it is a good idea to use this with a spotter which doesn't result into many

jump spots (like, for example, |MiniJump2d.builtin_opts.word_start|).

Default is 0 to not show anything ahead as it reduces visual noise.

Option `view.dim` controls whether to dim lines with at least one jump spot.

Dimming is done by applying "MiniJump2dDim" highlight group to the whole line.

## Allowed lines ~

Option `allowed_lines` controls which lines will be used for computing

possible jump spots:

- If `blank` or `fold` is `true`, it is possible to jump to first column of blank

line (determined by |prevnonblank|) or first folded one (determined by

|foldclosed|) respectively. Otherwise they are skipped. These lines are

not processed by spotter function even if the option is `true`.

- If `cursor_before`, (`cursor_at`, `cursor_after`) is `true`, lines before

(at, after) cursor line of all processed windows are forwarded to spotter

function. Otherwise, they don't. This allows control of jump "direction".

## Hooks ~

Following hook functions can be used to further tweak jumping experience:

- `before_start` - called without arguments first thing when jump starts.

One of the possible use cases is to ask for user input and update spotter

function with it.

- `after_jump` - called after jump was actually done. Useful to make

post-adjustments (like move cursor to first non-whitespace character).

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

*MiniJump2d.start()*

`MiniJump2d.start`({opts})

Start jumping

Compute possible jump spots, visualize them and wait for iterative filtering.

First computation of possible jump spots ~

- Process allowed windows (current and/or not current; controlled by

`allowed_windows` option) by visible lines from top to bottom. For each

one see if it is allowed (controlled by `allowed_lines` option). If not

allowed, then do nothing. If allowed and should be processed by

`spotter`, process it.

- Apply spotter function from `spotter` option for each appropriate line

and concatenate outputs. This means that eventual order of jump spots

aligns with lexicographical order within "window id" - "line number" -

"position in `spotter` output" tuples.

- For each possible jump compute its label: a single character from

`labels` option used to filter jump spots. Each possible label character

might be used more than once to label several "consecutive" jump spots.

It is done in an optimal way under assumption of no preference of one

spot over another. Basically, it means "use all labels at each step of

iterative filtering as equally as possible".

Visualization ~

Current label for each possible jump spot is shown at that position

overriding everything underneath it.

Iterative filtering ~

Labels of possible jump spots are computed in order to use them as equally

as possible.

Example:

- With `abc` as `labels` option, initial labels for 10 possible jumps

are "aaaabbbccc". As there are 10 spots which should be "coded" with 3

symbols, at least 2 symbols need 3 steps to filter them out. With current

implementation those are always the "first ones".

- After typing `a`, it filters first four jump spots and recomputes its

labels to be "aabc".

- After typing `a` again, it filters first two spots and recomputes its

labels to be "ab".

- After typing either `a` or `b` it filters single spot and makes jump.

With default 26 labels for most real-world cases 2 steps is enough for

default spotter function. Rarely 3 steps are needed with several windows.

Parameters ~

{opts} `(table|nil)` Configuration of jumping, overriding global and buffer

local values. Has the same structure as |MiniJump2d.config|

without <mappings> field. Extra allowed fields:

- <hl_group> - highlight group for first step.

Default: `"MiniJump2dSpot"`.

- <hl_group_ahead> - highlight group for second and later steps.

Default: `"MiniJump2dSpotAhead"`.

- <hl_group_dim> - highlight group for dimming used lines.

Default: `"MiniJump2dDim"`.

- <hl_group_unique> - highlight group for unique next step.

Default: `"MiniJump2dSpotUnique"`.

Usage ~

>lua

-- Start default jumping

MiniJump2d.start()

-- Jump to word start

MiniJump2d.start(MiniJump2d.builtin_opts.word_start)

-- Jump to single character from user input (follow by typing one character)

MiniJump2d.start(MiniJump2d.builtin_opts.single_character)

-- Jump to first character of punctuation group only inside current window

-- which is placed at cursor line; visualize with `Search`

MiniJump2d.start({

spotter = MiniJump2d.gen_spotter.pattern('%p+'),

allowed_lines = { cursor_before = false, cursor_after = false },

allowed_windows = { not_current = false },

hl_group = 'Search'

})

FilesExpand file tree

mini-jump2d.txt

Latest commit

History

mini-jump2d.txt

File metadata and controls