nu_plugin_skim 0.31.0

An `sk` command that can handle Nushell's structured data
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
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105

# nu_plugin_skim

This is a [Nushell](https://nushell.sh/) plugin that integrates the [skim](https://github.com/lotabout/skim) fuzzy finder.

The regular `sk` executable filters lines of text, but the `sk` command added by this plugin can filter Nushell's structured data.

## Installing

Install the crate using:

```nushell
> cargo install nu_plugin_skim
```

Then register the plugin using (this must be done inside Nushell):

```nushell
> plugin add ~/.cargo/bin/nu_plugin_skim
```

## Usage

Pipe the input of any Nushell command into `sk`:

```nushell
> ps | sk --format {get name} --preview {}
```

This will open the skim TUI, allowing you to select an item from the stream:

```
                    │╭─────────┬─────────────╮            1/9
                    ││ pid     │ 4223        │
                    ││ ppid    │ 3944        │
> /usr/bin/nu       ││ name    │ /usr/bin/nu │
  nu                ││ status  │ Running     │
  nu                ││ cpu     │ 28.78       │
  nu                ││ mem     │ 37.4 MiB    │
  nu                ││ virtual │ 1.4 GiB     │
  nu                │╰─────────┴─────────────╯
  6/258         5/0 │
> 'nu               │
```

The item will be returned as the same structured Nushell type that was fed into `sk`:

```nushell
> ps | sk --format {get name} --preview {}
╭─────────┬─────────────╮
│ pid     │ 4223        │
│ ppid    │ 3944        │
│ name    │ /usr/bin/nu │
│ status  │ Running     │
│ cpu     │ 28.57       │
│ mem     │ 37.8 MiB    │
│ virtual │ 1.4 GiB     │
╰─────────┴─────────────╯
```

Of course, the result of the command can be piped into another command:

```nushell
> ps | sk --format {get name} --preview {} | kill $in.pid
```

## Notable flags

nu_plugin_skim aims to replicate skim's sytnax, but there are some differences to better integrate with Nushell:

- `--multi` / `-m` - this flag works exactly the same as in the regular skim, but unlike the regular skim that always returns text - here `sk` returns structured Nushell data, and this flag changes the type of that data. Without it, the chosen item is returned as is. With it, it gets returned as a list (even if the user only chooses a single item)

  ```nushell
  > seq 1 10 | sk | describe
  int
  > seq 1 10 | sk -m | describe
  list<int> (stream)
  ```

- `--format` - this is a flag that the regular skim does not have. It receives a Nushell closure, and pipes the items through that closure before showing them as user selectable rows. It can also receive a cell-path.

  If the closure returns a complex Nushell data type, it'll be formatted in a notation similar to [Nushell's `debug` command](http://www.nushell.sh/commands/docs/debug.html)

  Note that in skim one would use `--with-nth` for a similar purpose - but the syntax and usage are different enough to warren a different name.

- `--preview` - unlike the regular skim, where `--preview` accepts a string, here `--preview` accepts a Nushell closure. The item under the cursor will get piped into the closure and the result will be displayed inside the preview window. It can also receive a cell-path.

  If the closure returns a complex Nushell data type, it'll be formatted into a table.

  To display the item as is, use the empty closure `--preview {}`.

- `--bind` - unlike regular `sk` that recieves bindings as a comma-separated list of colon-seperated key-values (e.g. `sk --bind alt-s:down,alt-w:up`), here the bindings are given as a record (e.g. `sk --bind {alt-s: down, alt-w: up}`)

- `--expect` - unlike regular `sk` that receives actions as comma-specified list of keys (e.g. `sk --expect ctrl-v,ctrl-t,alt-s`), here the actions are given as a list of strings (e.g. `sk --expect [ctrl-v, ctrl-t, alt-s]`)

  When this flag is given (even with an empty list), the result will be a record with an `action` field that contains the action (or `null`, if regular `Return` was used) and a `selected` field that contains the selected item (or a list of them, if `-m` / `--multi` was used)

- `--tiebreak` - unlike regular `sk` that receives actions as comma-specified list of criteria, here the criteria are given as a list of strings.

- `--algo` and `--case` - in regular `sk` setting them to an unsupported value will fall back to the default. Here it'll raise an error.

- `--pre-select-items` - unlike regular `sk` where it receives a newline-seperated list, here it receives a Nushell list.

## Defaults via SKIM_DEFAULT_OPTIONS

This plugin now reads the `SKIM_DEFAULT_OPTIONS` environment variable and treats it as default skim flags (similar to the regular `sk`).