mini.nvim/doc/mini-bracketed.txt at backlog · ahillio/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<
8000
/div>

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

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

*mini.bracketed*

*MiniBracketed*

Go forward/backward with square brackets

Features:

- Configurable Lua functions to go forward/backward to a certain target.

Each function can be customized with:

- Direction. One of "forward", "backward", "first" (forward starting

from first one), "last" (backward starting from last one).

- Number of times to go.

- Whether to wrap on edges (going forward on last one goes to first).

- Some other target specific options.

- Mappings using square brackets. They are created using configurable

target suffix and can be selectively disabled.

Each mapping supports |[count]|. Mappings are created in Normal mode; for

targets which move cursor in current buffer also Visual and

Operator-pending (with dot-repeat) modes are supported.

Using `lower-suffix` and `upper-suffix` (lower and upper case suffix) for

a single target the following mappings are created:

- `[` + `upper-suffix` : go first.

- `[` + `lower-suffix` : go backward.

- `]` + `lower-suffix` : go forward.

- `]` + `upper-suffix` : go last.

- Supported targets (for more information see help for corresponding Lua

function):

`Target` `Mappings` `Lua function`

Buffer.......................... `[B` `[b` `]b` `]B` .... |MiniBracketed.buffer()|

Comment block................... `[C` `[c` `]c` `]C` .... |MiniBracketed.comment()|

Conflict marker................. `[X` `[x` `]x` `]X` .... |MiniBracketed.conflict()|

Diagnostic...................... `[D` `[d` `]d` `]D` .... |MiniBracketed.diagnostic()|

File on disk.................... `[F` `[f` `]f` `]F` .... |MiniBracketed.file()|

Indent change................... `[I` `[i` `]i` `]I` .... |MiniBracketed.indent()|

Jump from |jumplist|

inside current buffer........... `[J` `[j` `]j` `]J` .... |MiniBracketed.jump()|

Location from |location-list|..... `[L` `[l` `]l` `]L` .... |MiniBracketed.location()|

Old files....................... `[O` `[o` `]o` `]O` .... |MiniBracketed.oldfile()|

Quickfix entry from |Quickfix|.... `[Q` `[q` `]q` `]Q` .... |MiniBracketed.quickfix()|

Tree-sitter node and parents.... `[T` `[t` `]t` `]T` .... |MiniBracketed.treesitter()|

Undo states from specially

tracked linear history.......... `[U` `[u` `]u` `]U` .... |MiniBracketed.undo()|

Window in current tab........... `[W` `[w` `]w` `]W` .... |MiniBracketed.window()|

Yank selection replacing

latest put region................`[Y` `[y` `]y` `]Y` .... |MiniBracketed.yank()|

# Setup ~

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

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

which you can use for scripting or manually (with `:lua MiniBracketed.*`).

See |MiniBracketed.config| for available config settings.

You can override runtime config settings (like target options) locally

to buffer inside `vim.b.minibracketed_config` which should have same structure

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

# Comparisons ~

- 'tpope/vim-unimpaired':

- Supports buffer, conflict, file, location, and quickfix targets mostly

via built-in commands (like |:bprevious|, etc.) without configuration.

- Supports files from argument list and tags. This module does not.

- Doesn't support most other this module's targets (comment, indent, ...).

- 'mini.indentscope':

- Target |MiniBracketed.indent()| target can go to "first" and "last"

indent change. It also can go not only to line with smaller indent,

but also bigger or different one.

- Mappings from 'mini.indentscope' have more flexibility in computation of

indent scope, like how to treat empty lines near border or whether to

compute indent at cursor.

# Disabling~

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

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

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

*MiniBracketed.setup()*

`MiniBracketed.setup`({config})

Module setup

Parameters~

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

Usage~

`require('mini.bracketed').setup({})` (replace `{}` with your `config` table)

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

*MiniBracketed.config*

`MiniBracketed.config`

Module config

Default values:

MiniBracketed.config = {

-- First-level elements are tables describing behavior of a target:

-- - <suffix> - single character suffix. Used after `[` / `]` in mappings.

-- For example, with `b` creates `[B`, `[b`, `]b`, `]B` mappings.

-- Supply empty string `''` to not create mappings.

-- - <options> - table overriding target options.

-- See `:h MiniBracketed.config` for more info.

buffer = { suffix = 'b', options = {} },

comment = { suffix = 'c', options = {} },

conflict = { suffix = 'x', options = {} },

diagnostic = { suffix = 'd', options = {} },

file = { suffix = 'f', options = {} },

indent = { suffix = 'i', options = {} },

jump = { suffix = 'j', options = {} },

location = { suffix = 'l', options = {} },

oldfile = { suffix = 'o', options = {} },

quickfix = { suffix = 'q', options = {} },

treesitter = { suffix = 't', options = {} },

undo = { suffix = 'u', options = {} },

window = { suffix = 'w', options = {} },

yank = { suffix = 'y', options = {} },

}

Options ~

Each entry configures target with the same name and can have data configuring

mapping suffix and target options.

Example of configuration: >

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

-- Map [N, [n, ]n, ]N for conflict marker like in 'tpope/vim-unimpaired'

conflict = { suffix = 'n' },

-- Make diagnostic advance only by errors

diagnostic = { options = { severity = vim.diagnostic.severity.ERROR } },

-- Disable creation of mappings for `indent` target (for example,

-- in favor of ones from |mini.indentscope|)

indent = { suffix = '' },

-- Disable mappings for `window` target in favor of custom ones

window = { suffix = '' },

})

-- Create custom `window` mappings

local map = vim.keymap.set

map('n', '<Leader>wH', "<Cmd>lua MiniBracketed.window('first')<CR>")

map('n', '<Leader>wh', "<Cmd>lua MiniBracketed.window('backward')<CR>")

map('n', '<Leader>wl', "<Cmd>lua MiniBracketed.window('forward')<CR>")

map('n', '<Leader>wL', "<Cmd>lua MiniBracketed.window('last')<CR>")

## Suffix ~

The `suffix` key is used to create target mappings.

Supply empty string to disable mapping creation for that particular target.

To create a completely different mapping (like with |<Leader>|) use target

function manually.

Using `lower-suffix` and `upper-suffix` (lower and upper case suffix) for

a single target the following mappings are created:

- `[` + `upper-suffix` : go first.

- `[` + `lower-suffix` : go backward.

- `]` + `lower-suffix` : go forward.

- `]` + `upper-suffix` : go last.

When supplied with a non-letter, only forward/backward mappings are created.

## Options ~

The `options` key is directly forwarded as `opts` to corresponding Lua function.

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

*MiniBracketed.buffer()*

`MiniBracketed.buffer`({direction}, {opts})

Listed buffer

Go to next/previous listed buffer. Order by their number (see |bufnr()|).

Direction "forward" increases number, "backward" - decreases.

Parameters~

{direction} `(string)` One of "first", "backward", "forward", "last".

{opts} `(table|nil)` Options. A table with fields:

- <n_times> `(number)` - Number of times to advance. Default: |v:count1|.

- <wrap> `(boolean)` - Whether to wrap around edges. Default: `true`.

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

*MiniBracketed.comment()*

`MiniBracketed.comment`({direction}, {opts})

Comment block

Go to next/previous comment block. Only linewise comments using

'commentsring' are recognized.

Direction "forward" increases line number, "backward" - decreases.

Parameters~

{direction} `(string)` One of "first", "backward", "forward", "last".

{opts} `(table|nil)` Options. A table with fields:

- <n_times> `(number)` - Number of times to advance. Default: |v:count1|.

- <wrap> `(boolean)` - Whether to wrap around edges. Default: `true`.

- <block_side> `(string)` - which side of comment block to use. One of

"near" (default; use nearest side), "start" (use first line), "end"

(use last line), "both" (use both first and last lines).

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

*MiniBracketed.conflict()*

`MiniBracketed.conflict`({direction}, {opts})

Git conflict marker

Go to next/previous lines containing Git conflict marker. That is, if it

starts with "<<<<<<< ", ">>>>>>> ", or is "=======".

Direction "forward" increases line number, "backward" - decreases.

Notes:

- Using this target in Operator-pending mode allows the following approach

at resolving merge conflicts:

- Place cursor on `=======` line.

- Execute one of these: `d]x[xdd` (choose upper part) or

`d[x]xdd` (choose lower part).

Parameters~

{direction} `(string)` One of "first", "backward", "forward", "last".

{opts} `(table|nil)` Options. A table with fields:

- <n_times> `(number)` - Number of times to advance. Default: |v:count1|.

- <wrap> `(boolean)` - Whether to wrap around edges. Default: `true`.

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

*MiniBracketed.diagnostic()*

`MiniBracketed.diagnostic`({direction}, {opts})

Diagnostic

Go to next/previous diagnostic. This is mostly similar to

|vim.diagnostic.goto_next()| and |vim.diagnostic.goto_prev()| for

current buffer which supports |[count]| and functionality to go to

first/last diagnostic entry.

Direction "forward" increases line number, "backward" - decreases.

Notes:

- Using `severity` option, this target can be used in mappings like "go to

next/previous error" (), etc. Using code similar to this: >

local severity_error = vim.diagnostic.severity.ERROR

-- Use these inside custom mappings

MiniBracketed.diagnostic('forward', { severity = severity_error })

MiniBracketed.diagnostic('backward', { severity = severity_error })

Parameters~

{direction} `(string)` One of "first", "backward", "forward", "last".

{opts} `(table|nil)` Options. A table with fields:

- <n_times> `(number)` - Number of times to advance. Default: |v:count1|.

- <wrap> `(boolean)` - Whether to wrap around edges. Default: `true`.

- <float> `(boolean|table)` - control floating window after movement.

For available values see |vim.diagnostic.goto_next()|.

- <severity> `(string|table)` - which severity to use.

For available values see |diagnostic-severity|.

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

*MiniBracketed.file()*

`MiniBracketed.file`({direction}, {opts})

File on disk

Go to next/previous file on disk alphabetically. Files are taken from

directory of file in current buffer (or current working directory if buffer

doesn't contain a readable file). Only first-level files are used, i.e. it

doesn't go inside subdirectories.

Direction "forward" goes forward alphabetically, "backward" - backward.

Parameters~

{direction} `(string)` One of "first", "backward", "forward", "last".

{opts} `(table|nil)` Options. A table with fields:

- <n_times> `(number)` - Number of times to advance. Default: |v:count1|.

- <wrap> `(boolean)` - Whether to wrap around edges. Default: `true`.

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

*MiniBracketed.indent()*

`MiniBracketed.indent`({direction}, {opts})

Indent change

Go to next/previous line with different indent (see |indent()|).

Can be used to go to lines with smaller, bigger, or different indent.

Notes:

- Directions "first" and "last" work differently from most other targets

for performance reasons. They are essentially "backward" and "forward"

with very big `n_times` option.

- For similar reasons, `wrap` is not supported.

- Blank line inherit indent from near non-blank line in direction of movement.

Direction "forward" increases line number, "backward" - decreases.

Parameters~

{direction} `(string)` One of "first", "backward", "forward", "last".

{opts} `(table|nil)` Options. A table with fields:

- <n_times> `(number)` - Number of times to advance. Default: |v:count1|.

- <change_type> `(string)` - which type of indent change to use.

One of "less" (default; smaller indent), "more" (bigger indent),

"diff" (different indent).

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

*MiniBracketed.jump()*

`MiniBracketed.jump`({direction}, {opts})

Jump inside current buffer

Go to next/previous jump from |jumplist| which is inside current buffer.

Notes:

- There are no Visual mode mappings due to implementation problems.

Direction "forward" increases jump number, "backward" - decreases.

Parameters~

{direction} `(string)` One of "first", "backward", "forward", "last".

{opts} `(table|nil)` Options. A table with fields:

- <n_times> `(number)` - Number of times to advance. Default: |v:count1|.

- <wrap> `(boolean)` - Whether to wrap around edges. Default: `true`.

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

*MiniBracketed.location()*

`MiniBracketed.location`({direction}, {opts})

Location from location list

Go to next/previous location from |location-list|. This is similar to

wrapping around edges and |[count]| for "first"/"last" direction.

Direction "forward" increases location number, "backward" - decreases.

Parameters~

{direction} `(string)` One of "first", "backward", "forward", "last".

{opts} `(table|nil)` Options. A table with fields:

- <n_times> `(number)` - Number of times to advance. Default: |v:count1|.

- <wrap> `(boolean)` - Whether to wrap around edges. Default: `true`.

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

*MiniBracketed.oldfile()*

`MiniBracketed.oldfile`({direction}, {opts})

Old files from previous and current sessions

Go to older/newer readable file either from previous session (see |v:oldfiles|)

or the current one (updated automatically after |MiniBracketed.setup()| call).

Direction "forward" goes to more recent files, "backward" - to older.

Notes:

- In current session it tracks only normal buffers (see |'buftype'|) for

some readable file.

- No new file is tracked when advancing this target. Only after buffer

change is done not through this target (like with |MiniBracketed.buffer()|),

it updates recency of last advanced and new buffers.

Parameters~

{direction} `(string)` One of "first", "backward", "forward", "last".

{opts} `(table|nil)` Options. A table with fields:

- <n_times> `(number)` - Number of times to advance. Default: |v:count1|.

- <wrap> `(boolean)` - Whether to wrap around edges. Default: `true`.

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

*MiniBracketed.quickfix()*

`MiniBracketed.quickfix`({direction}, {opts})

Quickfix from quickfix list

Go to next/previous entry from |quickfix| list. This is similar to

wrapping around edges and |[count]| for "first"/"last" direction.

Direction "forward" increases location number, "backward" - decreases.

Parameters~

{direction} `(string)` One of "first", "backward", "forward", "last".

{opts} `(table|nil)` Options. A table with fields:

- <n_times> `(number)` - Number of times to advance. Default: |v:count1|.

- <wrap> `(boolean)` - Whether to wrap around edges. Default: `true`.

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

*MiniBracketed.treesitter()*

`MiniBracketed.treesitter`({direction}, {opts})

Tree-sitter node

Go to end/start of current tree-sitter node and its parents (except root).

Notes:

- Requires |get_node_at_pos()| from |lua-treesitter| (present in Neovim=0.8)

or |vim.treesitter.get_node()| (present in Neovim>=0.9) along with loaded

tree-sitter parser in current buffer.

- Directions "first" and "last" work differently from most other targets

for performance reasons. They are essentially "backward" and "forward"

with very big `n_times` option.

- For similar reasons, `wrap` is not supported.

Direction "forward" moves cursor forward to node's end, "backward" - backward

to node's start.

Parameters~

{direction} `(string)` One of "first", "backward", "forward", "last".

{opts} `(table|nil)` Options. A table with fields:

- <n_times> `(number)` - Number of times to advance. Default: |v:count1|.

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

*MiniBracketed.undo()*

`MiniBracketed.undo`({direction}, {opts})

Undo along a tracked linear history

In a nutshell:

- Keys |u| and |<C-R>| (although remapped) can be used as usual, but every

their execution new state is recorded in this module's linear undo history.

- Advancing this target goes along linear undo history revealing undo states

**in order they actually appeared**.

- One big difference with built-in methods is that tracked linear history

can repeat undo states (not consecutively, though).

Neovim's default way of managing undo history is through branches (see

|undo-branches|). Basically it means that if you undo several changes and then

make new ones, it creates new undo branch while usually (see |'undolevels'|)

saving previous buffer states in another branch. While there are commands

to navigate by time of undo state creation (like |:earlier| and |:later|),

there is no intuitive way to cycle through them. Existing |g-| and |g+|

cycle through undo states **based on their creation time**, which often

gets confusing really guickly in extensively edited buffer.

This `undo()` target provides a way to cycle through linear undo history

**in order states actually appeared**. It does so by registering any new undo

states plus every time |MiniBracketed.register_undo_state()| is called. To have

more "out of the box" experience, |u| and |<C-R>| are remapped to call it after

they perform their undo/redo.

Example ~

To show more clearly the difference between advancing this target and using

built-in functionality, here is an example:

- Create undo history in a new buffer (|:new|):

- Enter `one two three` text.

- Delete first word with `daw` and undo the change with `u`.

- Delete second word with `daw` and undo the change with `u`.

- Delete third word with `daw` and undo the change with `u`.

- Now try one of the following (each one after performing previous steps in

separate new buffer):

- Press `u`. It goes back to empty buffer. Press `<C-R>` twice and it

goes to the latest change (`one two`). No way to get to other states

(like `two three` or `one three`) with these two keys.

- Press `g-`. It goes to an empty buffer. Press `g+` 4 times. It cycles

through all available undo states **in order they were created**.

- Finally, press `[u`. It goes back to `one two` - state which was

**previously visited** by the user. Another `[u` restores `one two three`.

Use `]U` to go to latest visited undo state.

Parameters~

{direction} `(string)` One of "first", "backward", "forward", "last".

{opts} `(table|nil)` Options. A table with fields:

- <n_times> `(number)` - Number of times to advance. Default: |v:count1|.

- <wrap> `(boolean)` - Whether to wrap around edges. Default: `true`.

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

*MiniBracketed.register_undo_state()*

`MiniBracketed.register_undo_state`()

Use this function to add current undo state to this module's linear undo

history. It is used in |MiniBracketed.setup()| to remap |u| and |<C-R>| keys to add

their new state to linear undo history.

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

*MiniBracketed.window()*

`MiniBracketed.window`({direction}, {opts})

Normal window

Go to next/previous normal window. Order by their number (see |winnr()|).

Direction "forward" increases window number, "backward" - decreases.

Only normal (non-floating) windows are used.

Parameters~

{direction} `(string)` One of "first", "backward", "forward", "last".

{opts} `(table|nil)` Options. A table with fields:

- <n_times> `(number)` - Number of times to advance. Default: |v:count1|.

- <wrap> `(boolean)` - Whether to wrap around edges. Default: `true`.

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

*MiniBracketed.yank()*

`MiniBracketed.yank`({direction}, {opts})

Replace "latest put region" with yank history entry

After |MiniBracketed.setup()| is called, on every yank/delete/change operation

(technically, every trigger of |TextYankPost| event) the object of operation

is added to yank history. Advancing this target will replace the region of

latest put operation with entry from yank history.

By default works best if called **right after** text paste (like with |p| or |P|).

To better detect "latest put region", use |MiniBracketed.register_put_region()|

as described later.

Direction "forward" goes to newer yank history entry, "backward" - to older.

Example ~

- Type `one two three`.

- Yank each word with `yiw`.

- Create new line and press `p`. This should paste `three`.

- Type `[y`. This should replace latest `three` with `two`.

Latest put region ~

"Latest put region" is (in order of decreasing priority):

- The one from latest advance of this target.

- The one registered by user with |MiniBracketed.register_put_region()|.

- The one taken from |`[| and |`]| marks.

For users there are these approaches to manage which region will be used:

- Do nothing. In this case region between `[` / `]` marks will always be used

for first `yank` advance.

Although doable, this has several drawbacks: it will use latest yanked or

changed region or the entire buffer if marks are not set.

If remember to advance this target only after recent put operation, this

should work as expected.

- Remap common put operations to use |MiniBracketed.register_put_region()|.

After that, only regions from mapped put operations will be used for first

advance. Example of custom mappings (note use of |:map-expression|): >

local put_keys = { 'p', 'P' }

for _, lhs in ipairs(put_keys) do

local rhs = 'v:lua.MiniBracketed.register_put_region("' .. lhs .. '")'

vim.keymap.set({ 'n', 'x' }, lhs, rhs, { expr = true })

end

Parameters~

{direction} `(string)` One of "first", "backward", "forward", "last".

{opts} `(table|nil)` Options. A table with fields:

- <n_times> `(number)` - Number of times to advance. Default: |v:count1|.

- <wrap> `(boolean)` - Whether to wrap around edges. Default: `true`.

- <operators> `(table)` - array of operator names ("c", "d", or "y") for

which yank entry should be used to advance. For example, use `{ "y" }`

to advance only by entries actually resulted from yank operation with |y|.

Default: `{ 'c', 'd', 'y' }`.

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

*MiniBracketed.register_put_region()*

`MiniBracketed.register_put_region`({put_key})

This function should be called after put register becomes relevant

(|v:register| is appropriately set) but before put operation takes place

(|`[| and |`]| marks become relevant).

Designed to be used in a user-facing expression mapping (see |:map-expression|).

For mapping examples see |MiniBracketed.yank()|.

Parameters~

{put_key} `(string)` Put keys to be remapped.

Return~

`(string)` Returns `put_key` for a better usage inside expression mappings.

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

*MiniBracketed.advance()*

`MiniBracketed.advance`({iterator}, {direction}, {opts})

Advance iterator

This is the main function which performs any forward/backward/first/last

advance in this module. Its basic idea is to take iterator (object containing

information about current state and how to go to next/previous one) and go

in certain direction until needed/allowed.

Notes:

- Directions "first" and "last" are convenience wrappers for "forward" and

"backward" with pre-setting initial state to `start_edge` and `end_edge`.

- Iterators `next()` and `prev()` methods should be able to handle `nil` as input.

- This function only returns new state and doesn't modify `iterator.state`.

Parameters~

{iterator} `(table)` Table:

- Methods:

- <next> - given state, return state in forward direction (no wrap).

- <prev> - given state, return state in backward direction (no wrap).

- Fields:

- <state> - object describing current state.

- <start_edge> (optional) - object with `forward(start_edge)` describing

first state. If `nil`, can't wrap forward or use direction "first".

- <end_edge> (optional) - object with `backward(end_edge)` describing

last state. If `nil`, can't wrap backward or use direction "last".

{direction} `(string)` Direction. One of "first", "backward", "forward", "last".

{opts} `(table|nil)` Options with the following keys:

- <n_times> `(number)` - number of times to go in input direction.

Default: `v:count1`.

- <wrap> `(boolean)` - whether to wrap around edges when `next()` or

`prev()` return `nil`. Default: `true`.

Return~

`(any)` Result state. If `nil`, could not reach any valid result state.

vim:tw=78:ts=8:noet:ft=help:norl:

FilesExpand file tree

mini-bracketed.txt

Latest commit

History

mini-bracketed.txt

File metadata and controls