From 427db0d101d0c1cebf97f2ab7da5b80f53f8c95a Mon Sep 17 00:00:00 2001
From: Antoine Stevan <44101798+amtoine@users.noreply.github.com>
Date: Wed, 5 Apr 2023 23:14:39 +0200
Subject: [PATCH] FEATURE: better `ansi -e` error (#8709)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Should close #8704.

# Description
this PR
- makes the error thrown by things like `ansi -e {invalid: "invalid"}`
more explicit
- makes the `ansi -e` example more explicit about valid / invalid keys

# User-Facing Changes
the error
```bash
> ansi -e {invalid: "invalid"}
Error: nu::shell::incompatible_parameters

  × Incompatible parameters.
   ╭─[entry #1:1:1]
 1 │ ansi -e {invalid: "invalid"}
   ·         ──────────┬─────────
   ·                   ╰── unknown ANSI format key: expected one of ['fg', 'bg', 'attr'], found 'invalid'
   ╰────
```

the new `ansi -e` example
```bash
  Use structured escape codes
  > let bold_blue_on_red = {  # `fg`, `bg`, `attr` are the acceptable keys, all other keys are considered invalid and will throw errors.
        fg: '#0000ff'
        bg: '#ff0000'
        attr: b
    }
    $"(ansi -e $bold_blue_on_red)Hello Nu World(ansi reset)"
  Hello Nu World
```

# Tests + Formatting
- :green_circle: `toolkit fmt`
- :green_circle: `toolkit clippy`
- :black_circle: `toolkit test`
- :black_circle: `toolkit test stdlib`

# After Submitting
```
$nothing
```
---
 crates/nu-command/src/platform/ansi/ansi_.rs | 8 ++++++--
 1 file changed, 6 insertions(+), 2 deletions(-)

diff --git a/crates/nu-command/src/platform/ansi/ansi_.rs b/crates/nu-command/src/platform/ansi/ansi_.rs
index ffb6ad5c90..2981be1745 100644
--- a/crates/nu-command/src/platform/ansi/ansi_.rs
+++ b/crates/nu-command/src/platform/ansi/ansi_.rs
@@ -623,7 +623,11 @@ Operating system commands:
             },
             Example {
                 description: "Use structured escape codes",
-                example: r#"let bold_blue_on_red = { fg: '#0000ff' bg: '#ff0000' attr: b }
+                example: r#"let bold_blue_on_red = {  # `fg`, `bg`, `attr` are the acceptable keys, all other keys are considered invalid and will throw errors.
+        fg: '#0000ff'
+        bg: '#ff0000'
+        attr: b
+    }
     $"(ansi -e $bold_blue_on_red)Hello Nu World(ansi reset)""#,
                 result: Some(Value::test_string(
                     "\u{1b}[1;48;2;255;0;0;38;2;0;0;255mHello Nu World\u{1b}[0m",
@@ -761,7 +765,7 @@ Operating system commands:
                     "attr" => nu_style.attr = Some(v.as_string()?),
                     _ => {
                         return Err(ShellError::IncompatibleParametersSingle {
-                            msg: format!("problem with key: {k}"),
+                            msg: format!("unknown ANSI format key: expected one of ['fg', 'bg', 'attr'], found '{k}'"),
                             span: code.expect_span(),
                         })
                     }