extern/nushell
1
0
Fork 1
mirror of https://github.com/nushell/nushell.git synced 2025-07-13 12:56:22 +02:00
Code Issues Packages Projects Releases Wiki Activity

refactor the ansi help page (#8713)

Browse Source 
# Description
i've always found the `ansi --help` extra usage hard to read and
understand...
i decided to give it a shot today, so here is what i came up 😋 

- make the extra usage structured with `nushell` tables
- make the examples clearer with variables and comments

one change that might appear strange is the following last two commits
```diff
diff --git a/crates/nu-command/src/platform/ansi/ansi_.rs b/crates/nu-command/src/platform/ansi/ansi_.rs
index 4746d27fa..ba3e597c4 100644
--- a/crates/nu-command/src/platform/ansi/ansi_.rs
+++ b/crates/nu-command/src/platform/ansi/ansi_.rs
@@ -507,10 +507,7 @@ impl Command for AnsiCommand {
 
     fn signature(&self) -> Signature {
         Signature::build("ansi")
-            .input_output_types(vec![
-                (Type::Nothing, Type::String),
-                (Type::List(Box::new(Type::String)), Type::String),
-            ])
+            .input_output_types(vec![(Type::Nothing, Type::String)])
             .optional(
                 "code",
                 SyntaxShape::Any,
```
`ansi` is never used on `list` inputs, as can be seen in the `Ansi.run`
function: `_input: PipelineData` is never used.
this broke the tests (see [this
action](https://github.com/nushell/nushell/actions/runs/4589552235/jobs/8104520078#step:4:1392))
for no real reason...

# User-Facing Changes
hopefully an easier to read `help ansi` page.

# Tests + Formatting
- 🟢 `toolkit fmt`
- 🟢 `toolkit clippy`
- 🟢 `toolkit test`
- 🟢 `toolkit test stdlib`

# After Submitting

If your PR had any user-facing changes, update [the
documentation](https://github.com/nushell/nushell.github.io) after the
PR is merged, if necessary. This will help us keep the docs up to date.
This commit is contained in:
Antoine Stevan
2023-04-05 20:16:36 +02:00
committed by GitHub
parent 65c90d5b45
commit caf1432dc7
1 changed files with 73 additions and 57 deletions
Download Patch File Download Diff File Expand all files Collapse all files

130
crates/nu-command/src/platform/ansi/ansi_.rs
View File

@ -507,10 +507,7 @@ impl Command for AnsiCommand {
fn signature(&self) -> Signature { fn signature(&self) -> Signature {
Signature::build("ansi") Signature::build("ansi")
.input_output_types(vec![ .input_output_types(vec![(Type::Nothing, Type::String)])
(Type::Nothing, Type::String),
(Type::List(Box::new(Type::String)), Type::String),
])
.optional( .optional(
"code", "code",
SyntaxShape::Any, SyntaxShape::Any,
@ -518,12 +515,12 @@ impl Command for AnsiCommand {
) )
.switch( .switch(
"escape", // \x1b[ "escape", // \x1b[
"escape sequence without the escape character(s)", r#"escape sequence without the escape character(s) ('\x1b[' is not required)"#,
Some('e'), Some('e'),
) )
.switch( .switch(
"osc", // \x1b] "osc", // \x1b]
"operating system command (ocs) escape sequence without the escape character(s)", r#"operating system command (osc) escape sequence without the escape character(s) ('\x1b]' is not required)"#,
Some('o'), Some('o'),
) )
.switch("list", "list available ansi code names", Some('l')) .switch("list", "list available ansi code names", Some('l'))
@ -531,58 +528,72 @@ impl Command for AnsiCommand {
} }
fn usage(&self) -> &str { fn usage(&self) -> &str {
"Output ANSI codes to change color." "Output ANSI codes to change color and style of text."
} }
fn extra_usage(&self) -> &str { fn extra_usage(&self) -> &str {
r#"For escape sequences: "An introduction to what ANSI escape sequences are can be found in the
Escape: '\x1b[' is not required for --escape parameter [*ANSI escape code*](https://en.wikipedia.org/wiki/ANSI_escape_code) Wikipedia page.
Format: #(;#)m
Example: 1;31m for bold red or 2;37;41m for dimmed white fg with red bg
There can be multiple text formatting sequence numbers
separated by a ; and ending with an m where the # is of the
following values:
attribute_number, abbreviation, description
0 reset / normal display
1 b bold or increased intensity
2 d faint or decreased intensity
3 i italic on (non-mono font)
4 u underline on
5 l slow blink on
6 fast blink on
7 r reverse video on
8 h nondisplayed (invisible) on
9 s strike-through on
foreground/bright colors background/bright colors Escape sequences usual values:
30/90 black 40/100 black ╭────┬────────────┬────────┬────────┬─────────╮
31/91 red 41/101 red │ # │ type │ normal │ bright │ name │
32/92 green 42/102 green ├────┼────────────┼────────┼────────┼─────────┤
33/93 yellow 43/103 yellow │ 0 │ foreground │ 30 │ 90 │ black │
34/94 blue 44/104 blue │ 1 │ foreground │ 31 │ 91 │ red │
35/95 magenta 45/105 magenta │ 2 │ foreground │ 32 │ 92 │ green │
36/96 cyan 46/106 cyan │ 3 │ foreground │ 33 │ 93 │ yellow │
37/97 white 47/107 white │ 4 │ foreground │ 34 │ 94 │ blue │
39 default 49 default │ 5 │ foreground │ 35 │ 95 │ magenta │
https://en.wikipedia.org/wiki/ANSI_escape_code │ 6 │ foreground │ 36 │ 96 │ cyan │
│ 7 │ foreground │ 37 │ 97 │ white │
│ 8 │ foreground │ 39 │ │ default │
│ 9 │ background │ 40 │ 100 │ black │
│ 10 │ background │ 41 │ 101 │ red │
│ 11 │ background │ 42 │ 102 │ green │
│ 12 │ background │ 43 │ 103 │ yellow │
│ 13 │ background │ 44 │ 104 │ blue │
│ 14 │ background │ 45 │ 105 │ magenta │
│ 15 │ background │ 46 │ 106 │ cyan │
│ 16 │ background │ 47 │ 107 │ white │
│ 17 │ background │ 49 │ │ default │
╰────┴────────────┴────────┴────────┴─────────╯
OSC: '\x1b]' is not required for --osc parameter Escape sequences attributes:
Example: echo [(ansi -o '0') 'some title' (char bel)] | str join ╭───┬────┬──────────────┬──────────────────────────────╮
Format: # │ # │ id │ abbreviation │ description │
0 Set window title and icon name ├───┼────┼──────────────┼──────────────────────────────┤
1 Set icon name │ 0 │ 0 │ │ reset / normal display │
2 Set window title │ 1 │ 1 │ b │ bold or increased intensity │
4 Set/read color palette │ 2 │ 2 │ d │ faint or decreased intensity │
9 iTerm2 Grown notifications │ 3 │ 3 │ i │ italic on (non-mono font) │
10 Set foreground color (x11 color spec) │ 4 │ 4 │ u │ underline on │
11 Set background color (x11 color spec) │ 5 │ 5 │ l │ slow blink on │
... others"# │ 6 │ 6 │ │ fast blink on │
│ 7 │ 7 │ r │ reverse video on │
│ 8 │ 8 │ h │ nondisplayed (invisible) on │
│ 9 │ 9 │ s │ strike-through on │
╰───┴────┴──────────────┴──────────────────────────────╯
Operating system commands:
╭───┬─────┬───────────────────────────────────────╮
│ # │ id │ description │
├───┼─────┼───────────────────────────────────────┤
│ 0 │ 0 │ Set window title and icon name │
│ 1 │ 1 │ Set icon name │
│ 2 │ 2 │ Set window title │
│ 3 │ 4 │ Set/read color palette │
│ 4 │ 9 │ iTerm2 Grown notifications │
│ 5 │ 10 │ Set foreground color (x11 color spec) │
│ 6 │ 11 │ Set background color (x11 color spec) │
│ 7 │ ... │ others │
╰───┴─────┴───────────────────────────────────────╯"
} }
fn examples(&self) -> Vec<Example> { fn examples(&self) -> Vec<Example> {
vec![ vec![
Example { Example {
description: "Change color to green", description: "Change color to green (see how the next example text will be green!)",
example: r#"ansi green"#, example: r#"ansi green"#,
result: Some(Value::test_string("\u{1b}[32m")), result: Some(Value::test_string("\u{1b}[32m")),
}, },
@ -592,23 +603,28 @@ Format: #
result: Some(Value::test_string("\u{1b}[0m")), result: Some(Value::test_string("\u{1b}[0m")),
}, },
Example { Example {
description: description: "Use different colors and styles in the same text",
"Use ansi to color text (rb = red bold, gb = green bold, pb = purple bold)", example: r#"$'(ansi red_bold)Hello(ansi reset) (ansi green_dimmed)Nu(ansi reset) (ansi purple_italic)World(ansi reset)'"#,
example: r#"$'(ansi rb)Hello (ansi gb)Nu (ansi pb)World(ansi reset)'"#,
result: Some(Value::test_string( result: Some(Value::test_string(
"\u{1b}[1;31mHello \u{1b}[1;32mNu \u{1b}[1;35mWorld\u{1b}[0m", "\u{1b}[1;31mHello\u{1b}[0m \u{1b}[2;32mNu\u{1b}[0m \u{1b}[3;35mWorld\u{1b}[0m",
)), )),
}, },
Example { Example {
description: "Use ansi to color text (italic bright yellow on red 'Hello' with green bold 'Nu' and purple bold 'World')", description: "The same example as above with short names",
example: r#"[(ansi -e '3;93;41m') Hello (ansi reset) " " (ansi gb) Nu " " (ansi pb) World (ansi reset)] | str join"#, example: r#"$'(ansi rb)Hello(ansi reset) (ansi gd)Nu(ansi reset) (ansi pi)World(ansi reset)'"#,
result: Some(Value::test_string( result: Some(Value::test_string(
"\u{1b}[3;93;41mHello\u{1b}[0m \u{1b}[1;32mNu \u{1b}[1;35mWorld\u{1b}[0m", "\u{1b}[1;31mHello\u{1b}[0m \u{1b}[2;32mNu\u{1b}[0m \u{1b}[3;35mWorld\u{1b}[0m",
)), )),
}, },
Example { Example {
description: "Use ansi to color text with a style (blue on red in bold)", description: "Use escape codes, without the '\\x1b['",
example: r#"$"(ansi -e { fg: '#0000ff' bg: '#ff0000' attr: b })Hello Nu World(ansi reset)""#, example: r#"$"(ansi -e '3;93;41m')Hello(ansi reset)" # italic bright yellow on red background"#,
result: Some(Value::test_string("\u{1b}[3;93;41mHello\u{1b}[0m")),
},
Example {
description: "Use structured escape codes",
example: r#"let bold_blue_on_red = { fg: '#0000ff' bg: '#ff0000' attr: b }
$"(ansi -e $bold_blue_on_red)Hello Nu World(ansi reset)""#,
result: Some(Value::test_string( result: Some(Value::test_string(
"\u{1b}[1;48;2;255;0;0;38;2;0;0;255mHello Nu World\u{1b}[0m", "\u{1b}[1;48;2;255;0;0;38;2;0;0;255mHello Nu World\u{1b}[0m",
)), )),