FEATURE: add the example results to the scope (#8319)

Related to #8189.
Should close #8302.

Important to:
- have a complete `$nu` structure with all available information
- generate an accurate website, because the `make_docs.nu` script of
`nushell.github.io` uses `$nu.scope.command` to generate the pages of
https://nushell.sh/commands/

> **Note**
> i was looking for "scope" in the source of `nushell` to augment
`$nu.scope` and i found `crates/nu-engine/src/scope.rs` that defines
`nu_engine::scope::create_scope` which lead me to
`nu_engine::scope::ScopeData.collect_commands`.
> i hope this is the right file 😌 

# Description
this PR slightly modifies
`nu_engine::scope::ScopeData.collect_commands`:
- add the "result" column to `$nu.scope.commands.examples`
- put the result of the example when a valid `Option(Value)`
- put a `Value::Nothing` when the result is set to `None` in the source
of the command

# User-Facing Changes
users can now access the results of all examples in
```bash
$nu.scope.commands | where name == <command> | get examples.0.result
```

## example...
### ...with a command that defines examples: `merge`
```bash
>_ $nu.scope.commands | where name == merge | get examples.0 | reject description | table --expand
╭───┬────────────────────────────────────────────────────────┬───────────────────────────╮
│ # │                        example                         │          result           │
├───┼────────────────────────────────────────────────────────┼───────────────────────────┤
│ 0 │ [a b c] | wrap name | merge ( [1 2 3] | wrap index )   │ ╭───┬──────╮              │
│   │                                                        │ │ # │ name │              │
│   │                                                        │ ├───┼──────┤              │
│   │                                                        │ │ 1 │ a    │              │
│   │                                                        │ │ 2 │ b    │              │
│   │                                                        │ │ 3 │ c    │              │
│   │                                                        │ ╰───┴──────╯              │
│ 1 │ {a: 1, b: 2} | merge {c: 3}                            │ ╭───┬───╮                 │
│   │                                                        │ │ a │ 1 │                 │
│   │                                                        │ │ b │ 2 │                 │
│   │                                                        │ │ c │ 3 │                 │
│   │                                                        │ ╰───┴───╯                 │
│ 2 │ [{columnA: A0 columnB: B0}] | merge [{columnA: 'A0*'}] │ ╭───┬─────────┬─────────╮ │
│   │                                                        │ │ # │ columnA │ columnB │ │
│   │                                                        │ ├───┼─────────┼─────────┤ │
│   │                                                        │ │ 0 │ A0*     │ B0      │ │
│   │                                                        │ ╰───┴─────────┴─────────╯ │
╰───┴────────────────────────────────────────────────────────┴───────────────────────────╯
```
and we can check that these are "true" results and not just string, e.g.
```bash
>_ $nu.scope.commands | where name == merge | get examples.0.result.0 | describe
table<name: string, index: int>
```
### ...with a command without any example: `open`
```bash
>_ $nu.scope.commands | where name == open | get examples.0 | reject description | table --expand
╭───┬──────────────────────────────────────┬────────╮
│ # │               example                │ result │
├───┼──────────────────────────────────────┼────────┤
│ 0 │ open myfile.json                     │        │
│ 1 │ open myfile.json --raw               │        │
│ 2 │ 'myfile.txt' | open                  │        │
│ 3 │ open myfile.txt --raw | decode utf-8 │        │
╰───┴──────────────────────────────────────┴────────╯
```
and same thing, we can check that there is `$nothing` in this last
command
```bash
>_ $nu.scope.commands | where name == open | get examples.0.result.0 | describe
table<name: string, index: int>
```

# Tests + Formatting
- ✔️ `cargo fmt --all`
- ✔️ `cargo clippy --workspace -- -D warnings -D
clippy::unwrap_used -A clippy::needless_collect`
- ✔️ `cargo test --workspace` (~~currently running~~)

# After Submitting
the documentation would have to be regenerated!
This commit is contained in:
Antoine Stevan 2023-03-05 10:56:06 +01:00 committed by GitHub
parent f93033c20b
commit d6141881f2
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23

View file

@ -166,7 +166,7 @@ impl<'e, 's> ScopeData<'e, 's> {
.examples() .examples()
.into_iter() .into_iter()
.map(|x| Value::Record { .map(|x| Value::Record {
cols: vec!["description".into(), "example".into()], cols: vec!["description".into(), "example".into(), "result".into()],
vals: vec![ vals: vec![
Value::String { Value::String {
val: x.description.to_string(), val: x.description.to_string(),
@ -176,6 +176,11 @@ impl<'e, 's> ScopeData<'e, 's> {
val: x.example.to_string(), val: x.example.to_string(),
span, span,
}, },
if let Some(result) = x.result {
result
} else {
Value::Nothing { span }
},
], ],
span, span,
}) })