mirror of
https://github.com/nushell/nushell.git
synced 2025-06-08 19:17:16 +02:00
e7d2717424
# Description
`recurse` command is similar to `jq`'s `recurse`/`..` command. Along
with values, it also returns their cell-paths relative to the "root"
(initial input)
By default it uses breadth-first traversal, collecting child items of
all available sibling items before starting to process those child
items. This means output is ordered in increasing depth.
With the `--depth-first` flag it uses a stack based recursive descend,
which results in output order identical to `jq`'s `recurse`.
It can be used in the following ways:
- `... | recurse`: Recursively traverses the input value, returns each
value it finds as a stream.
- `... | recurse foo.bar`: Only descend through the given cell-path.
- `... | recurse {|parent| ... }`: Produce child values with a closure.
```nushell
{
"foo": {
"egg": "X"
"spam": "Y"
}
"bar": {
"quox": ["A" "B"]
}
}
| recurse
| update item { to nuon }
# => ╭───┬──────────────┬───────────────────────────────────────────────╮
# => │ # │ path │ item │
# => ├───┼──────────────┼───────────────────────────────────────────────┤
# => │ 0 │ $. │ {foo: {egg: X, spam: Y}, bar: {quox: [A, B]}} │
# => │ 1 │ $.foo │ {egg: X, spam: Y} │
# => │ 2 │ $.bar │ {quox: [A, B]} │
# => │ 3 │ $.foo.egg │ "X" │
# => │ 4 │ $.foo.spam │ "Y" │
# => │ 5 │ $.bar.quox │ [A, B] │
# => │ 6 │ $.bar.quox.0 │ "A" │
# => │ 7 │ $.bar.quox.1 │ "B" │
# => ╰───┴──────────────┴───────────────────────────────────────────────╯
{"name": "/", "children": [
{"name": "/bin", "children": [
{"name": "/bin/ls", "children": []},
{"name": "/bin/sh", "children": []}]},
{"name": "/home", "children": [
{"name": "/home/stephen", "children": [
{"name": "/home/stephen/jq", "children": []}]}]}]}
| recurse children
| get item.name
# => ╭───┬──────────────────╮
# => │ 0 │ / │
# => │ 1 │ /bin │
# => │ 2 │ /home │
# => │ 3 │ /bin/ls │
# => │ 4 │ /bin/sh │
# => │ 5 │ /home/stephen │
# => │ 6 │ /home/stephen/jq │
# => ╰───┴──────────────────╯
{"name": "/", "children": [
{"name": "/bin", "children": [
{"name": "/bin/ls", "children": []},
{"name": "/bin/sh", "children": []}]},
{"name": "/home", "children": [
{"name": "/home/stephen", "children": [
{"name": "/home/stephen/jq", "children": []}]}]}]}
| recurse children --depth-first
| get item.name
# => ╭───┬──────────────────╮
# => │ 0 │ / │
# => │ 1 │ /bin │
# => │ 2 │ /bin/ls │
# => │ 3 │ /bin/sh │
# => │ 4 │ /home │
# => │ 5 │ /home/stephen │
# => │ 6 │ /home/stephen/jq │
# => ╰───┴──────────────────╯
2
| recurse { ({path: square item: ($in * $in)}) }
| take while { $in.item < 100 }
# => ╭───┬─────────────────┬──────╮
# => │ # │ path │ item │
# => ├───┼─────────────────┼──────┤
# => │ 0 │ $. │ 2 │
# => │ 1 │ $.square │ 4 │
# => │ 2 │ $.square.square │ 16 │
# => ╰───┴─────────────────┴──────╯
```
# User-Facing Changes
No changes other than the new command.
# Tests + Formatting
Added tests for examples. (As we can't run them directly as tests yet.)
- 🟢 `toolkit test stdlib`
# After Submitting
- Update relevant parts of
https://www.nushell.sh/cookbook/jq_v_nushell.html
- `$env.config | recurse | where ($it.item | describe -d).type not-in
[list, record, table]` can partially cover the use case of `config
flatten`, should we do something?
---------
Co-authored-by: Bahex <17417311+Bahex@users.noreply.github.com>
Welcome to the standard library of `nushell`!
The standard library is a pure-nushell collection of custom commands which
provide interactive utilities and building blocks for users writing casual scripts or complex applications.
To see what's here:
> use std
> scope commands | select name description | where name =~ "std "
#┬───────────name────────────┬───────────────────description───────────────────
0│std assert │Universal assert command
1│std assert equal │Assert $left == $right
2│std assert error │Assert that executing the code generates an error
3│std assert greater │Assert $left > $right
4│std assert greater or equal│Assert $left >= $right
... ...
─┴───────────────────────────┴─────────────────────────────────────────────────
🧰 Using the standard library in the REPL or in scripts
All commands in the standard library must be "imported" into the running environment
(the interactive read-execute-print-loop (REPL) or a .nu script) using the
use command.
You can choose to import the whole module, but then must refer to individual commands with a std prefix, e.g:
use std
std log debug "Running now"
std assert (1 == 2)
Or you can enumerate the specific commands you want to import and invoke them without the std prefix.
use std ["log debug" assert]
log debug "Running again"
assert (2 == 1)
This is probably the form of import you'll want to add to your env.nu for interactive use.
✏️ contribute to the standard library
You're invited to contribute to the standard library! See CONTRIBUTING.md for details