From d6141881f228889561cf360a7b4355db577478db Mon Sep 17 00:00:00 2001
From: Antoine Stevan <44101798+amtoine@users.noreply.github.com>
Date: Sun, 5 Mar 2023 10:56:06 +0100
Subject: [PATCH] FEATURE: add the example results to the scope (#8319)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

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 :relieved:

# 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
- :heavy_check_mark: `cargo fmt --all`
- :heavy_check_mark: `cargo clippy --workspace -- -D warnings -D
clippy::unwrap_used -A clippy::needless_collect`
- :heavy_check_mark: `cargo test --workspace` (~~currently running~~)

# After Submitting
the documentation would have to be regenerated!
---
 crates/nu-engine/src/scope.rs | 7 ++++++-
 1 file changed, 6 insertions(+), 1 deletion(-)

diff --git a/crates/nu-engine/src/scope.rs b/crates/nu-engine/src/scope.rs
index edcd851101..284719bf51 100644
--- a/crates/nu-engine/src/scope.rs
+++ b/crates/nu-engine/src/scope.rs
@@ -166,7 +166,7 @@ impl<'e, 's> ScopeData<'e, 's> {
                         .examples()
                         .into_iter()
                         .map(|x| Value::Record {
-                            cols: vec!["description".into(), "example".into()],
+                            cols: vec!["description".into(), "example".into(), "result".into()],
                             vals: vec![
                                 Value::String {
                                     val: x.description.to_string(),
@@ -176,6 +176,11 @@ impl<'e, 's> ScopeData<'e, 's> {
                                     val: x.example.to_string(),
                                     span,
                                 },
+                                if let Some(result) = x.result {
+                                    result
+                                } else {
+                                    Value::Nothing { span }
+                                },
                             ],
                             span,
                         })