8000 mini.nvim/doc/mini-bracketed.txt at main · yurihbm/mini.nvim · GitHub
[go: up one dir, main page]
Skip to content

mini-bracketed.txt

Latest commit

 

History

History
622 lines (497 loc) · 27.7 KB

mini-bracketed.txt

File metadata and controls

622 lines (497 loc) · 27.7 KB
Raw
`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|): >lua
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})
Register "latest put region"
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:
0