:toc:
:nofooter:
:!webfonts:
= kakutils-rs
Sort by regular expression or lexicographically, find uniqes, shuffle, or evaluate rust selections without spawning a new command for each selection.
image::https://asciinema.org/a/dIQh9NtLRkzVEENxmij5qBaai.svg[link="https://asciinema.org/a/dIQh9NtLRkzVEENxmij5qBaai"]
== Example
Sort stages by step number:
++++
1|stage("Make") { # Step 100
2| 1+ 2+ 3+ 4+ 5+ 6+ 7+ 8+ 9+ 10
3|}
4|
5|stage("Compile") { # Step 5
6| math::log2(8)
7|}
8|
9|stage("Build") { # Step 1
10| 8+3
11|}
12|
13|stage("Assemble") { # Step 10
14| 2^9+math::log2(10)
15|}
~
~
~
~
~
~
~
:utils sort \d+ *scratch* 15:2 [scratch] prompt - client0@[616]
++++
After `sort \d+`:
++++
1|stage("Build") { # Step 1
2| 8+3
3|}
4|
5|stage("Compile") { # Step 5
6| math::log2(8)
7|}
8|
9|stage("Assemble") { # Step 10
10| 2^9+math::log2(10)
11|}
12|
13|stage("Make") { # Step 100
14| 1+ 2+ 3+ 4+ 5+ 6+ 7+ 8+ 9+ 10
15|}
~
~
~
~
~
~
~
Sorted 4 selections *scratch* 15:2 [scratch] 4 sels (4) - client0@[616]
++++
Evaluate all math expressions:
++++
1|stage("Build") { # Step 1
2| 8+3
3|}
4|
5|stage("Compile") { # Step 5
6| math::log2(8)
7|}
8|
9|stage("Assemble") { # Step 10
10| 2^9+math::log2(10)
11|}
12|
13|stage("Make") { # Step 100
14| 1+ 2+ 3+ 4+ 5+ 6+ 7+ 8+ 9+ 10
15|}
~
~
~
~
~
~
~
:utils bc *scratch* 14:33 [scratch] prompt - client0@[616]
++++
After `bc`
++++
1|stage("Build") { # Step 1
2| 11
3|}
4|
5|stage("Compile") { # Step 5
6| 3
7|}
8|
9|stage("Assemble") { # Step 10
10| 515.3219280948873
11|}
12|
13|stage("Make") { # Step 100
14| 55
15|}
~
~
~
~
~
~
~
Processed 4 selections *scratch* 14:6 [scratch] 4 sels (4) - client0@[616]
++++
== Configuration
[source,sh,title='sh']
----
cargo install --git https://github.com/austenadler/kakutils-rs
----
[source,title='kakrc']
----
define-command utils -params .. -shell-script-candidates %{
# use kak_token_to_complete;
kakutils-rs shell-script-candidates "$@"
} %{
eval -save-regs '"' %{
eval %sh{
# use kak_command_fifo kak_response_fifo;
kakutils-rs "$@"
}
}
}
----
== Commands
=== box
Creates a box with corners on each selection's cursor and anchor
* `-b`/`--bounding-box` - Create only one box with corners on the left/bottom/right/top-most cursor or anchor
.Example
[%collapsible]
====
Before:
++++
1|*** this is a *scratch* buffer which won't be automatically saved ***
2|*** use it for notes or open a file buffer with the :edit command ***
3|*** this is a *scratch* buffer which won't be automatically saved ***
4|*** use it for notes or open a file buffer with the :edit command ***
5|*** this is a *scratch* buffer which won't be automatically saved ***
6|*** use it for notes or open a file buffer with the :edit command ***
7|*** this is a *scratch* buffer which won't be automatically saved ***
8|*** use it for notes or open a file buffer with the :edit command ***
~
~
~
~
~
~
~
~
~
~
~
~
~
~
*scratch* 7:36 [scratch] 4 sels (4) - client0@[616]
++++
After `box`:
++++
1|*** this is a *scratch* buffer which won't be automatically saved ***
2|*** use it for notes or open a file buffer with the :edit command ***
3|*** this is a *scratch* buffer which won't be automatically saved ***
4|*** use it for notes or open a file buffer with the :edit command ***
5|*** this is a *scratch* buffer which won't be automatically saved ***
6|*** use it for notes or open a file buffer with the :edit command ***
7|*** this is a *scratch* buffer which won't be automatically saved ***
8|*** use it for notes or open a file buffer with the :edit command ***
~
~
~
~
~
~
~
~
~
~
~
~
~
~
Boxed 8 selection(s) *scratch* 1:9 [scratch] 8 sels (1) - client0@[616]
++++
====
=== invert
Selects anything not already selected
* Aliases: `inverse`
* `-n`/`--no-newline` - Do not include newlines
* `-l`/`--line` - Invert by line instead of by entire document
.Example
[%collapsible]
====
Before:
++++
1|*** this is a *scratch* buffer which won't be automatically saved ***
2|*** use it for notes or open a file buffer with the :edit command ***
3|*** this is a *scratch* buffer which won't be automatically saved ***
4|*** use it for notes or open a file buffer with the :edit command ***
5|*** this is a *scratch* buffer which won't be automatically saved ***
6|*** use it for notes or open a file buffer with the :edit command ***
7|*** this is a *scratch* buffer which won't be automatically saved ***
8|*** use it for notes or open a file buffer with the :edit command ***
~
~
~
~
~
~
~
~
~
~
~
~
~
~
*scratch* 7:36 [scratch] 4 sels (4) - client0@[616]
++++
After `invert`:
++++
1|*** this is a *scratch* buffer which won't be automatically saved ***
2|*** use it for notes or open a file buffer with the :edit command ***
3|*** this is a *scratch* buffer which won't be automatically saved ***
4|*** use it for notes or open a file buffer with the :edit command ***
5|*** this is a *scratch* buffer which won't be automatically saved ***
6|*** use it for notes or open a file buffer with the :edit command ***
7|*** this is a *scratch* buffer which won't be automatically saved ***
8|*** use it for notes or open a file buffer with the :edit command ***
~
~
~
~
~
~
~
~
~
~
~
~
~
~
Inverted 7 selections *scratch* 1:2 [scratch] 5 sels (1) - client0@[616]
++++
After `invert -nl`.
Notice newlines are not selected and nothing is selected on a line that didn't already have a selection:
++++
1|*** this is a *scratch* buffer which won't be automatically saved ***
2|*** use it for notes or open a file buffer with the :edit command ***
3|*** this is a *scratch* buffer which won't be automatically saved ***
4|*** use it for notes or open a file buffer with the :edit command ***
5|*** this is a *scratch* buffer which won't be automatically saved ***
6|*** use it for notes or open a file buffer with the :edit command ***
7|*** this is a *scratch* buffer which won't be automatically saved ***
8|*** use it for notes or open a file buffer with the :edit command ***
~
~
~
~
~
~
~
~
~
~
~
~
~
~
Inverted 7 selections *scratch* 1:2 [scratch] 7 sels (1) - client0@[616]
++++
====
=== math-eval
Evaluates each selection as a math expression.
Note that this is similar to `|bc`, but does not spawn a new process for each selection.
Uses link:https://docs.rs/evalexpr/latest/evalexpr/[evalexpr^] to evaluate expressions.
* Aliases: `bc`
.Example
[%collapsible]
====
Before:
++++
1|*** this is a *scratch* buffer which won't be automatically saved ***
2|*** use it for notes or open a file buffer with the :edit command ***
3|
4|2 * 4
5|
6|8/3
7|
8|.123^8
9|
10|math::sin(3.14)
11|
12|math::ln(1000)
~
~
~
~
~
~
~
~
~
~
*scratch* 12:14 [scratch] 5 sels (5) - client0@[616]
++++
After `bc`:
++++
1|*** this is a *scratch* buffer which won't be automatically saved ***
2|*** use it for notes or open a file buffer with the :edit command ***
3|
4|8
5|
6|2
7|
8|0.00000005238909442826287
9|
10|0.0015926529164868282
11|
12|6.907755278982137
~
~
~
~
~
~
~
~
~
~
Processed 5 selections *scratch* 12:17 [scratch] 5 sels (5) - client0@[616]
++++
====
=== set
Performs set operations on selections with registers.
This requires at least one register to contain selections (`"xZ` where `x` is the one-letter register name).
* First argument is the register and operation
** For example `a-b` or `a&b` or `_?b`
* Operations
** `&` - Set intersection
** `-`/`\\` - Set subtraction (order matters)
** `+` - Set union
** `?`/`=` - Set comparison (order matters)
This will open a new scratch buffer comparing the selection counts and content
* Registers
** Any register `a-z`/`A-Z` works
** `_` is treated as the current selection, and does not require you to manually set a register
*** For example, `a-_` will return the set of selections in `a` that are not currently selected in the editor
.Example
[%collapsible]
====
`x` register (`"xZ`) content:
++++
1|a a
2|b f
3|c b
4|d d
5|e h
6|f
7|g
8|h
~
~
~
~
~
~
~
~
~
~
~
~
~
~
Saved 5 selections to register 'x' …ch* 5:3 [scratch] 5 sels (5) - client0@[616]
++++
Before:
++++
1|a a
2|b f
3|c b
4|d d
5|e h
6|f
7|g
8|h
~
~
~
~
~
~
~
~
~
~
~
~
~
~
*scratch* 8:1 [scratch] 8 sels (8) - client0@[616]
++++
After `set \x` or `set _-x`:
++++
1|a a
2|b f
3|c b
4|d d
5|e h
6|f
7|g
8|h
~
~
~
~
~
~
~
~
~
~
~
~
~
~
_-x returned 3 selections *scratch* 3:1 [scratch] 3 sels (1) - client0@[616]
++++
After `set &x` or `set _&x`:
++++
1|a a
2|b f
3|c b
4|d d
5|e h
6|f
7|g
8|h
~
~
~
~
~
~
~
~
~
~
~
~
~
~
_&x returned 5 selections *scratch* 1:1 [scratch] 5 sels (1) - client0@[616]
++++
After `set ?x` or `set _=x`:
++++
1|? _ a selection
2|= 1 1 a
3|= 1 1 b
4|= 1 1 d
5|= 1 1 f
6|= 1 1 h
7|> 0 1 c
8|> 0 1 e
9|> 0 1 g
~
~
~
~
~
~
~
~
~
~
~
~
~
Compared 8 selections *kakplugin-set* 2:7 [scratch] 8 sels (1) - client0@[616]
++++
====
=== shuf
Shuffle selections randomly
.Example
[%collapsible]
====
Before:
++++
1|0 1 2 3 4 5 6 7 8 9 random words
~
~
~
~
~
~
~
~
~
~
~
~
~
~
~
~
~
~
~
~
~
*scratch* 1:32 [scratch] 12 sels (12) - client0@[616]
++++
After `shuf`:
++++
1|4 1 9 3 words random 6 5 2 0 8 7
~
~
~
~
~
~
~
~
~
~
~
~
~
~
~
~
~
~
~
~
~
Shuf 12 selections *scratch* 1:32 [scratch] 12 sels (12) - client0@[616]
++++
====
=== sort
Sort selections by regular expression or content
* `-S`/`--no-skip-whitespace` - Do not treat trimmed value of selections when sorting (by default, surrounding selection whitespace is trimmed before comparison)
* `-L`/`--no-lexicographic-sort` - Do not sort numbers lexicographically (`10 < 2` when `-L` is passed)
* `-r`/`--reverse` - Reverse sorting
* `-i`/`--ignore-case` - Ignore case when sorting
* `[REGEX]` - Optional regex comparison key
.Example
[%collapsible]
====
Before:
++++
1|*** this is a *scratch* buffer which won't be automatically saved ***
2|*** use it for notes or open a file buffer with the :edit command ***
3|
4|block 3 {
5| #
6|}
7|
8|section 1 {
9| //
10|}
11|
12|region 2 {
13| --
14|}
~
~
~
~
~
~
~
~
*scratch* 2:69 [scratch] 27 sels (27) - client0@[616]
++++
After `sort`:
++++
1|*** *** *** *** *scratch* :edit a a automatically be buffer buffer
2|command file for is it notes open or saved the this use which with won't
3|
4|block 3 {
5| #
6|}
7|
8|section 1 {
9| //
10|}
11|
12|region 2 {
13| --
14|}
~
~
~
~
~
~
~
~
Sorted 27 selections *scratch* 2:72 [scratch] 27 sels (27) - client0@[616]
++++
Before:
++++
1|*** this is a *scratch* buffer which won't be automatically saved ***
2|*** use it for notes or open a file buffer with the :edit command ***
3|
4|block 3 {
5| #
6|}
7|
8|section 1 {
9| //
10|}
11|
12|region 2 {
13| --
14|}
~
~
~
~
~
~
~
~
*scratch* 4:1 [scratch] 3 sels (1) - client0@[616]
++++
After `sort` (Sort alphabetically):
++++
1|*** this is a *scratch* buffer which won't be automatically saved ***
2|*** use it for notes or open a file buffer with the :edit command ***
3|
4|block 3 {
5| #
6|}
7|
8|region 2 {
9| --
10|}
11|
12|section 1 {
13| //
14|}
~
~
~
~
~
~
~
~
Sorted 3 selections *scratch* 4:1 [scratch] 3 sels (1) - client0@[616]
++++
After `sort \d+` (Sort by first digit in selection)
++++
1|*** this is a *scratch* buffer which won't be automatically saved ***
2|*** use it for notes or open a file buffer with the :edit command ***
3|
4|section 1 {
5| //
6|}
7|
8|region 2 {
9| --
10|}
11|
12|block 3 {
13| #
14|}
~
~
~
~
~
~
~
~
Sorted 3 selections *scratch* 4:1 [scratch] 3 sels (1) - client0@[616]
++++
====
=== uniq
Select only unique selections
* `-S`/`--no-skip-whitespace` - Do not treat trimmed value of selections when comparing (by default, surrounding selection whitespace is trimmed before comparison)
* `-i`/`--ignore-case` - Ignore case
* `[REGEX]` - Optional regex comparison key
.Example
[%collapsible]
====
Before:
++++
1|*** this is a *scratch* buffer which won't be automatically saved ***
2|*** use it for notes or open a file buffer with the :edit command ***
~
~
~
~
~
~
~
~
~
~
~
~
~
~
~
~
~
~
~
~
*scratch* 2:69 [scratch] 27 sels (27) - client0@[616]
++++
After `uniq`:
++++
1|*** this is a *scratch* buffer which won't be automatically saved
2| use it for notes or open file with the :edit command
~
~
~
~
~
~
~
~
~
~
~
~
~
~
~
~
~
~
~
~
22 unique selections out of 27 …ratch* 1:3 [scratch] 22 sels (1) - client0@[616]
++++
====
=== incr/decr
Increment or decrement selections
* `[AMOUNT]` - Optional increment/decrement count (default: `1`)
.Example
[%collapsible]
====
Before:
++++
++++
After `incr 3`:
++++
++++
====