From 49a9107e0fd900e39618546ccbfe052f623e1daf Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jakub=20=C5=BD=C3=A1dn=C3=ADk?= Date: Mon, 8 Mar 2021 01:57:58 +0200 Subject: [PATCH] Allow composing help message from two parts (#3124) * Split help message into brief and full help Demonstrate on ansi command Brief help is printed when running `help commands` so it doesn't clutter the table. Full help is printed when normal help message is requested (e.g., `help ansi`, `ansi --help`, etc.). * Split long command descriptions Some are not split, just edited to be shorter. * Capitalize the usage of all commands * Make sure every usage ends with dot * Fix random typo --- .../nu-command/src/commands/ansi/command.rs | 6 +++-- crates/nu-command/src/commands/append.rs | 2 +- crates/nu-command/src/commands/autoenv.rs | 8 ++++-- crates/nu-command/src/commands/benchmark.rs | 2 +- .../nu-command/src/commands/build_string.rs | 2 +- crates/nu-command/src/commands/char_.rs | 2 +- crates/nu-command/src/commands/chart.rs | 2 +- crates/nu-command/src/commands/clear.rs | 2 +- crates/nu-command/src/commands/clip.rs | 2 +- crates/nu-command/src/commands/compact.rs | 2 +- .../nu-command/src/commands/date/command.rs | 4 +-- crates/nu-command/src/commands/debug.rs | 2 +- crates/nu-command/src/commands/do_.rs | 2 +- .../nu-command/src/commands/drop/command.rs | 2 +- crates/nu-command/src/commands/du.rs | 2 +- crates/nu-command/src/commands/empty.rs | 2 +- crates/nu-command/src/commands/enter.rs | 10 +++++--- crates/nu-command/src/commands/exec.rs | 2 +- crates/nu-command/src/commands/exit.rs | 2 +- crates/nu-command/src/commands/from.rs | 4 +-- .../nu-command/src/commands/hash_/command.rs | 2 +- crates/nu-command/src/commands/headers.rs | 2 +- crates/nu-command/src/commands/help.rs | 4 +-- crates/nu-command/src/commands/into_int.rs | 2 +- .../nu-command/src/commands/keep/command.rs | 2 +- .../nu-command/src/commands/math/command.rs | 6 ++--- crates/nu-command/src/commands/nth.rs | 2 +- crates/nu-command/src/commands/nu/plugin.rs | 2 +- crates/nu-command/src/commands/open.rs | 10 +++++--- .../nu-command/src/commands/path/command.rs | 4 +-- crates/nu-command/src/commands/prepend.rs | 2 +- .../nu-command/src/commands/random/command.rs | 4 +-- crates/nu-command/src/commands/range.rs | 2 +- crates/nu-command/src/commands/reduce.rs | 7 ++++-- crates/nu-command/src/commands/rm.rs | 2 +- .../nu-command/src/commands/roll/command.rs | 2 +- crates/nu-command/src/commands/seq.rs | 2 +- crates/nu-command/src/commands/sleep.rs | 2 +- .../nu-command/src/commands/split/command.rs | 4 +-- .../nu-command/src/commands/str_/command.rs | 2 +- crates/nu-command/src/commands/to.rs | 2 +- crates/nu-command/src/commands/touch.rs | 2 +- crates/nu-command/src/commands/uniq.rs | 2 +- .../nu-command/src/commands/url_/command.rs | 4 +-- crates/nu-command/src/commands/version.rs | 2 +- crates/nu-command/src/commands/with_env.rs | 2 +- crates/nu-command/src/prelude.rs | 2 +- crates/nu-engine/src/documentation.rs | 25 +++++++++++++++++-- crates/nu-engine/src/lib.rs | 2 +- crates/nu-engine/src/whole_stream_command.rs | 8 ++++-- crates/nu_plugin_fetch/src/nu/mod.rs | 2 +- crates/nu_plugin_match/src/nu/mod.rs | 2 +- 52 files changed, 110 insertions(+), 72 deletions(-) diff --git a/crates/nu-command/src/commands/ansi/command.rs b/crates/nu-command/src/commands/ansi/command.rs index 9f91df2c42..dff6db4d52 100644 --- a/crates/nu-command/src/commands/ansi/command.rs +++ b/crates/nu-command/src/commands/ansi/command.rs @@ -42,9 +42,11 @@ impl WholeStreamCommand for Command { } fn usage(&self) -> &str { - r#"Output ANSI codes to change color + "Output ANSI codes to change color." + } -For escape sequences: + fn extra_usage(&self) -> &str { + r#"For escape sequences: Escape: '\x1b[' is not required for --escape parameter Format: #(;#)m Example: 1;31m for bold red or 2;37;41m for dimmed white fg with red bg diff --git a/crates/nu-command/src/commands/append.rs b/crates/nu-command/src/commands/append.rs index 7924405aa8..20ca99c7dc 100644 --- a/crates/nu-command/src/commands/append.rs +++ b/crates/nu-command/src/commands/append.rs @@ -25,7 +25,7 @@ impl WholeStreamCommand for Command { } fn usage(&self) -> &str { - "Append a row to the table" + "Append a row to the table." } async fn run(&self, args: CommandArgs) -> Result { diff --git a/crates/nu-command/src/commands/autoenv.rs b/crates/nu-command/src/commands/autoenv.rs index c5eb7d26ba..c2fb974674 100644 --- a/crates/nu-command/src/commands/autoenv.rs +++ b/crates/nu-command/src/commands/autoenv.rs @@ -51,8 +51,12 @@ impl WholeStreamCommand for Autoenv { "autoenv" } fn usage(&self) -> &str { + "Manage directory specific environment variables and scripts." + } + + fn extra_usage(&self) -> &str { // "Mark a .nu-env file in a directory as trusted. Needs to be re-run after each change to the file or its filepath." - r#"Manage directory specific environment variables and scripts. Create a file called .nu-env in any directory and run 'autoenv trust' to let nushell read it when entering the directory. + r#"Create a file called .nu-env in any directory and run 'autoenv trust' to let nushell read it when entering the directory. The file can contain several optional sections: env: environment variables to set when visiting the directory. The variables are unset after leaving the directory and any overwritten values are restored. scriptvars: environment variables that should be set to the return value of a script. After they have been set, they behave in the same way as variables set in the env section. @@ -64,7 +68,7 @@ The file can contain several optional sections: } async fn run(&self, args: CommandArgs) -> Result { Ok(OutputStream::one(ReturnSuccess::value( - UntaggedValue::string(get_help(&Autoenv, &args.scope)).into_value(Tag::unknown()), + UntaggedValue::string(get_full_help(&Autoenv, &args.scope)).into_value(Tag::unknown()), ))) } diff --git a/crates/nu-command/src/commands/benchmark.rs b/crates/nu-command/src/commands/benchmark.rs index bfbb63b8e6..85e0e9741e 100644 --- a/crates/nu-command/src/commands/benchmark.rs +++ b/crates/nu-command/src/commands/benchmark.rs @@ -45,7 +45,7 @@ impl WholeStreamCommand for Benchmark { } fn usage(&self) -> &str { - "Runs a block and returns the time it took to execute it" + "Runs a block and returns the time it took to execute it." } async fn run(&self, args: CommandArgs) -> Result { diff --git a/crates/nu-command/src/commands/build_string.rs b/crates/nu-command/src/commands/build_string.rs index 90ba76ec0a..4b02f5fb41 100644 --- a/crates/nu-command/src/commands/build_string.rs +++ b/crates/nu-command/src/commands/build_string.rs @@ -24,7 +24,7 @@ impl WholeStreamCommand for BuildString { } fn usage(&self) -> &str { - "Builds a string from the arguments" + "Builds a string from the arguments." } async fn run(&self, args: CommandArgs) -> Result { diff --git a/crates/nu-command/src/commands/char_.rs b/crates/nu-command/src/commands/char_.rs index 6c5aa1e672..33ff0b3a47 100644 --- a/crates/nu-command/src/commands/char_.rs +++ b/crates/nu-command/src/commands/char_.rs @@ -29,7 +29,7 @@ impl WholeStreamCommand for Char { } fn usage(&self) -> &str { - "Output special characters (eg. 'newline')" + "Output special characters (eg. 'newline')." } fn examples(&self) -> Vec { diff --git a/crates/nu-command/src/commands/chart.rs b/crates/nu-command/src/commands/chart.rs index d5d697fd23..4e84542334 100644 --- a/crates/nu-command/src/commands/chart.rs +++ b/crates/nu-command/src/commands/chart.rs @@ -28,7 +28,7 @@ impl WholeStreamCommand for Chart { } Ok(OutputStream::one(Ok(ReturnSuccess::Value( - UntaggedValue::string(get_help(&Chart, &args.scope)).into_value(Tag::unknown()), + UntaggedValue::string(get_full_help(&Chart, &args.scope)).into_value(Tag::unknown()), )))) } } diff --git a/crates/nu-command/src/commands/clear.rs b/crates/nu-command/src/commands/clear.rs index 86ab539cf4..8c8208e5fc 100644 --- a/crates/nu-command/src/commands/clear.rs +++ b/crates/nu-command/src/commands/clear.rs @@ -17,7 +17,7 @@ impl WholeStreamCommand for Clear { } fn usage(&self) -> &str { - "Clears the terminal" + "Clears the terminal." } async fn run(&self, _: CommandArgs) -> Result { diff --git a/crates/nu-command/src/commands/clip.rs b/crates/nu-command/src/commands/clip.rs index ac1f290ad2..60fbbce43e 100644 --- a/crates/nu-command/src/commands/clip.rs +++ b/crates/nu-command/src/commands/clip.rs @@ -19,7 +19,7 @@ impl WholeStreamCommand for Clip { } fn usage(&self) -> &str { - "Copy the contents of the pipeline to the copy/paste buffer" + "Copy the contents of the pipeline to the copy/paste buffer." } async fn run(&self, args: CommandArgs) -> Result { diff --git a/crates/nu-command/src/commands/compact.rs b/crates/nu-command/src/commands/compact.rs index c75d21522e..cc99b7301b 100644 --- a/crates/nu-command/src/commands/compact.rs +++ b/crates/nu-command/src/commands/compact.rs @@ -24,7 +24,7 @@ impl WholeStreamCommand for Compact { } fn usage(&self) -> &str { - "Creates a table with non-empty rows" + "Creates a table with non-empty rows." } async fn run(&self, args: CommandArgs) -> Result { diff --git a/crates/nu-command/src/commands/date/command.rs b/crates/nu-command/src/commands/date/command.rs index 6ebce001c8..3503cf627e 100644 --- a/crates/nu-command/src/commands/date/command.rs +++ b/crates/nu-command/src/commands/date/command.rs @@ -16,12 +16,12 @@ impl WholeStreamCommand for Command { } fn usage(&self) -> &str { - "Apply date function" + "Apply date function." } async fn run(&self, args: CommandArgs) -> Result { Ok(OutputStream::one(ReturnSuccess::value( - UntaggedValue::string(get_help(&Command, &args.scope)).into_value(Tag::unknown()), + UntaggedValue::string(get_full_help(&Command, &args.scope)).into_value(Tag::unknown()), ))) } } diff --git a/crates/nu-command/src/commands/debug.rs b/crates/nu-command/src/commands/debug.rs index 085c1b5fd7..aad906971c 100644 --- a/crates/nu-command/src/commands/debug.rs +++ b/crates/nu-command/src/commands/debug.rs @@ -21,7 +21,7 @@ impl WholeStreamCommand for Debug { } fn usage(&self) -> &str { - "Print the Rust debug representation of the values" + "Print the Rust debug representation of the values." } async fn run(&self, args: CommandArgs) -> Result { diff --git a/crates/nu-command/src/commands/do_.rs b/crates/nu-command/src/commands/do_.rs index 138a275b7a..ae7a1c10c4 100644 --- a/crates/nu-command/src/commands/do_.rs +++ b/crates/nu-command/src/commands/do_.rs @@ -29,7 +29,7 @@ impl WholeStreamCommand for Do { } fn usage(&self) -> &str { - "Runs a block, optionally ignoring errors" + "Runs a block, optionally ignoring errors." } async fn run(&self, args: CommandArgs) -> Result { diff --git a/crates/nu-command/src/commands/drop/command.rs b/crates/nu-command/src/commands/drop/command.rs index 289899a74f..543a762566 100644 --- a/crates/nu-command/src/commands/drop/command.rs +++ b/crates/nu-command/src/commands/drop/command.rs @@ -26,7 +26,7 @@ impl WholeStreamCommand for Command { } fn usage(&self) -> &str { - "Remove the last number of rows. If you want to remove columns, try 'drop column'." + "Remove the last number of rows or columns." } async fn run(&self, args: CommandArgs) -> Result { diff --git a/crates/nu-command/src/commands/du.rs b/crates/nu-command/src/commands/du.rs index 2907d5a476..cb89b0948e 100644 --- a/crates/nu-command/src/commands/du.rs +++ b/crates/nu-command/src/commands/du.rs @@ -68,7 +68,7 @@ impl WholeStreamCommand for Du { } fn usage(&self) -> &str { - "Find disk usage sizes of specified items" + "Find disk usage sizes of specified items." } async fn run(&self, args: CommandArgs) -> Result { diff --git a/crates/nu-command/src/commands/empty.rs b/crates/nu-command/src/commands/empty.rs index 491573847e..96334349f3 100644 --- a/crates/nu-command/src/commands/empty.rs +++ b/crates/nu-command/src/commands/empty.rs @@ -32,7 +32,7 @@ impl WholeStreamCommand for Command { } fn usage(&self) -> &str { - "Check for empty values" + "Check for empty values." } async fn run(&self, args: CommandArgs) -> Result { diff --git a/crates/nu-command/src/commands/enter.rs b/crates/nu-command/src/commands/enter.rs index 76308b3610..405a8c61bb 100644 --- a/crates/nu-command/src/commands/enter.rs +++ b/crates/nu-command/src/commands/enter.rs @@ -39,14 +39,16 @@ impl WholeStreamCommand for Enter { } fn usage(&self) -> &str { - r#"Create a new shell and begin at this path. - -Multiple encodings are supported for reading text files by using + "Create a new shell and begin at this path." + } + + fn extra_usage(&self) -> &str { + r#"Multiple encodings are supported for reading text files by using the '--encoding ' parameter. Here is an example of a few: big5, euc-jp, euc-kr, gbk, iso-8859-1, utf-16, cp1252, latin5 For a more complete list of encodings please refer to the encoding_rs -documentation link at https://docs.rs/encoding_rs/0.8.23/encoding_rs/#statics"# +documentation link at https://docs.rs/encoding_rs/0.8.28/encoding_rs/#statics"# } async fn run(&self, args: CommandArgs) -> Result { diff --git a/crates/nu-command/src/commands/exec.rs b/crates/nu-command/src/commands/exec.rs index 8e2841ee6d..524e0734b2 100644 --- a/crates/nu-command/src/commands/exec.rs +++ b/crates/nu-command/src/commands/exec.rs @@ -29,7 +29,7 @@ impl WholeStreamCommand for Exec { } fn usage(&self) -> &str { - "Execute command" + "Execute command." } async fn run(&self, args: CommandArgs) -> Result { diff --git a/crates/nu-command/src/commands/exit.rs b/crates/nu-command/src/commands/exit.rs index 475abb849c..3d68e484c3 100644 --- a/crates/nu-command/src/commands/exit.rs +++ b/crates/nu-command/src/commands/exit.rs @@ -21,7 +21,7 @@ impl WholeStreamCommand for Exit { } fn usage(&self) -> &str { - "Exit the current shell (or all shells)" + "Exit the current shell (or all shells)." } async fn run(&self, args: CommandArgs) -> Result { diff --git a/crates/nu-command/src/commands/from.rs b/crates/nu-command/src/commands/from.rs index 0dcec25172..8cdafb9b19 100644 --- a/crates/nu-command/src/commands/from.rs +++ b/crates/nu-command/src/commands/from.rs @@ -16,12 +16,12 @@ impl WholeStreamCommand for From { } fn usage(&self) -> &str { - "Parse content (string or binary) as a table (input format based on subcommand, like csv, ini, json, toml)" + "Parse content (string or binary) as a table (input format based on subcommand, like csv, ini, json, toml)." } async fn run(&self, args: CommandArgs) -> Result { Ok(OutputStream::one(ReturnSuccess::value( - UntaggedValue::string(get_help(&From, &args.scope)).into_value(Tag::unknown()), + UntaggedValue::string(get_full_help(&From, &args.scope)).into_value(Tag::unknown()), ))) } } diff --git a/crates/nu-command/src/commands/hash_/command.rs b/crates/nu-command/src/commands/hash_/command.rs index d19f5d7f4a..a89282d977 100644 --- a/crates/nu-command/src/commands/hash_/command.rs +++ b/crates/nu-command/src/commands/hash_/command.rs @@ -24,7 +24,7 @@ impl WholeStreamCommand for Command { async fn run(&self, args: CommandArgs) -> Result { Ok(OutputStream::one(ReturnSuccess::value( - UntaggedValue::string(get_help(&Command, &args.scope)).into_value(Tag::unknown()), + UntaggedValue::string(get_full_help(&Command, &args.scope)).into_value(Tag::unknown()), ))) } } diff --git a/crates/nu-command/src/commands/headers.rs b/crates/nu-command/src/commands/headers.rs index 12b4697592..156b5585cb 100644 --- a/crates/nu-command/src/commands/headers.rs +++ b/crates/nu-command/src/commands/headers.rs @@ -19,7 +19,7 @@ impl WholeStreamCommand for Headers { } fn usage(&self) -> &str { - "Use the first row of the table as column names" + "Use the first row of the table as column names." } async fn run(&self, args: CommandArgs) -> Result { diff --git a/crates/nu-command/src/commands/help.rs b/crates/nu-command/src/commands/help.rs index 053fc74b89..d196f681b2 100644 --- a/crates/nu-command/src/commands/help.rs +++ b/crates/nu-command/src/commands/help.rs @@ -161,7 +161,7 @@ async fn help(args: CommandArgs) -> Result { let command_name = format!("{} {}", rest[0].item, rest[1].item); if let Some(command) = scope.get_command(&command_name) { Ok(OutputStream::one(ReturnSuccess::value( - UntaggedValue::string(get_help(command.stream_command(), &scope)) + UntaggedValue::string(get_full_help(command.stream_command(), &scope)) .into_value(Tag::unknown()), ))) } else { @@ -169,7 +169,7 @@ async fn help(args: CommandArgs) -> Result { } } else if let Some(command) = scope.get_command(&rest[0].item) { Ok(OutputStream::one(ReturnSuccess::value( - UntaggedValue::string(get_help(command.stream_command(), &scope)) + UntaggedValue::string(get_full_help(command.stream_command(), &scope)) .into_value(Tag::unknown()), ))) } else { diff --git a/crates/nu-command/src/commands/into_int.rs b/crates/nu-command/src/commands/into_int.rs index 73e0a8784e..e784137b6b 100644 --- a/crates/nu-command/src/commands/into_int.rs +++ b/crates/nu-command/src/commands/into_int.rs @@ -23,7 +23,7 @@ impl WholeStreamCommand for IntoInt { } fn usage(&self) -> &str { - "Convert value to integer" + "Convert value to integer." } async fn run(&self, args: CommandArgs) -> Result { diff --git a/crates/nu-command/src/commands/keep/command.rs b/crates/nu-command/src/commands/keep/command.rs index 84d561cf86..ec5c33df45 100644 --- a/crates/nu-command/src/commands/keep/command.rs +++ b/crates/nu-command/src/commands/keep/command.rs @@ -26,7 +26,7 @@ impl WholeStreamCommand for Command { } fn usage(&self) -> &str { - "Keep the number of rows only" + "Keep the number of rows only." } async fn run(&self, args: CommandArgs) -> Result { diff --git a/crates/nu-command/src/commands/math/command.rs b/crates/nu-command/src/commands/math/command.rs index 843a1b4655..8c3ea1fef1 100644 --- a/crates/nu-command/src/commands/math/command.rs +++ b/crates/nu-command/src/commands/math/command.rs @@ -16,12 +16,12 @@ impl WholeStreamCommand for Command { } fn usage(&self) -> &str { - "Use mathematical functions as aggregate functions on a list of numbers or tables" + "Use mathematical functions as aggregate functions on a list of numbers or tables." } async fn run(&self, args: CommandArgs) -> Result { Ok(OutputStream::one(Ok(ReturnSuccess::Value( - UntaggedValue::string(get_help(&Command, &args.scope)).into_value(Tag::unknown()), + UntaggedValue::string(get_full_help(&Command, &args.scope)).into_value(Tag::unknown()), )))) } } @@ -154,7 +154,7 @@ mod tests { "col2".to_owned() => table(&[int(5), int(6), int(7), int(8)]) ]), Ok(row![ - "col1".to_owned() => decimal(BigDecimal::from_str("1.118033988749894848204586834365638117720309179805762862135448622705260462818902449707207204189391137").expect("Could not convert to decimal from string")), + "col1".to_owned() => decimal(BigDecimal::from_str("1.118033988749894848204586834365638117720309179805762862135448622705260462818902449707207204189391137").expect("Could not convert to decimal from string")), "col2".to_owned() => decimal(BigDecimal::from_str("1.118033988749894848204586834365638117720309179805762862135448622705260462818902449707207204189391137").expect("Could not convert to decimal from string")) ]), Ok(row!["col1".to_owned() => int(10), "col2".to_owned() => int(26)]), diff --git a/crates/nu-command/src/commands/nth.rs b/crates/nu-command/src/commands/nth.rs index 528cb144c8..a7550e35df 100644 --- a/crates/nu-command/src/commands/nth.rs +++ b/crates/nu-command/src/commands/nth.rs @@ -31,7 +31,7 @@ impl WholeStreamCommand for Nth { } fn usage(&self) -> &str { - "Return or skip only the selected rows" + "Return or skip only the selected rows." } async fn run(&self, args: CommandArgs) -> Result { diff --git a/crates/nu-command/src/commands/nu/plugin.rs b/crates/nu-command/src/commands/nu/plugin.rs index 3fb76d8ab5..1c5d53683a 100644 --- a/crates/nu-command/src/commands/nu/plugin.rs +++ b/crates/nu-command/src/commands/nu/plugin.rs @@ -101,7 +101,7 @@ impl WholeStreamCommand for SubCommand { } Ok(OutputStream::one(ReturnSuccess::value( - UntaggedValue::string(get_help(&SubCommand, &scope)).into_value(Tag::unknown()), + UntaggedValue::string(get_full_help(&SubCommand, &scope)).into_value(Tag::unknown()), ))) } } diff --git a/crates/nu-command/src/commands/open.rs b/crates/nu-command/src/commands/open.rs index 1ceaa434f0..27e3d8dcbb 100644 --- a/crates/nu-command/src/commands/open.rs +++ b/crates/nu-command/src/commands/open.rs @@ -46,14 +46,16 @@ impl WholeStreamCommand for Open { } fn usage(&self) -> &str { - r#"Load a file into a cell, convert to table if possible (avoid by appending '--raw'). - -Multiple encodings are supported for reading text files by using + "Load a file into a cell, convert to table if possible (avoid by appending '--raw')." + } + + fn extra_usage(&self) -> &str { + r#"Multiple encodings are supported for reading text files by using the '--encoding ' parameter. Here is an example of a few: big5, euc-jp, euc-kr, gbk, iso-8859-1, utf-16, cp1252, latin5 For a more complete list of encodings please refer to the encoding_rs -documentation link at https://docs.rs/encoding_rs/0.8.23/encoding_rs/#statics"# +documentation link at https://docs.rs/encoding_rs/0.8.28/encoding_rs/#statics"# } async fn run(&self, args: CommandArgs) -> Result { diff --git a/crates/nu-command/src/commands/path/command.rs b/crates/nu-command/src/commands/path/command.rs index 539793f4c6..bc96a8346e 100644 --- a/crates/nu-command/src/commands/path/command.rs +++ b/crates/nu-command/src/commands/path/command.rs @@ -16,12 +16,12 @@ impl WholeStreamCommand for Path { } fn usage(&self) -> &str { - "Explore and manipulate paths" + "Explore and manipulate paths." } async fn run(&self, args: CommandArgs) -> Result { Ok(OutputStream::one(ReturnSuccess::value( - UntaggedValue::string(get_help(&Path, &args.scope)).into_value(Tag::unknown()), + UntaggedValue::string(get_full_help(&Path, &args.scope)).into_value(Tag::unknown()), ))) } } diff --git a/crates/nu-command/src/commands/prepend.rs b/crates/nu-command/src/commands/prepend.rs index 7a6c476546..932511293b 100644 --- a/crates/nu-command/src/commands/prepend.rs +++ b/crates/nu-command/src/commands/prepend.rs @@ -25,7 +25,7 @@ impl WholeStreamCommand for Prepend { } fn usage(&self) -> &str { - "Prepend the given row to the front of the table" + "Prepend the given row to the front of the table." } async fn run(&self, args: CommandArgs) -> Result { diff --git a/crates/nu-command/src/commands/random/command.rs b/crates/nu-command/src/commands/random/command.rs index f11b1fb707..7b0bdc87b3 100644 --- a/crates/nu-command/src/commands/random/command.rs +++ b/crates/nu-command/src/commands/random/command.rs @@ -16,12 +16,12 @@ impl WholeStreamCommand for Command { } fn usage(&self) -> &str { - "Generate random values" + "Generate random values." } async fn run(&self, args: CommandArgs) -> Result { Ok(OutputStream::one(Ok(ReturnSuccess::Value( - UntaggedValue::string(get_help(&Command, &args.scope)).into_value(Tag::unknown()), + UntaggedValue::string(get_full_help(&Command, &args.scope)).into_value(Tag::unknown()), )))) } } diff --git a/crates/nu-command/src/commands/range.rs b/crates/nu-command/src/commands/range.rs index a556fd133f..7a980f4598 100644 --- a/crates/nu-command/src/commands/range.rs +++ b/crates/nu-command/src/commands/range.rs @@ -27,7 +27,7 @@ impl WholeStreamCommand for Range { } fn usage(&self) -> &str { - "Return only the selected rows" + "Return only the selected rows." } async fn run(&self, args: CommandArgs) -> Result { diff --git a/crates/nu-command/src/commands/reduce.rs b/crates/nu-command/src/commands/reduce.rs index ebb3c215be..d4cfd8cb05 100644 --- a/crates/nu-command/src/commands/reduce.rs +++ b/crates/nu-command/src/commands/reduce.rs @@ -42,8 +42,11 @@ impl WholeStreamCommand for Reduce { } fn usage(&self) -> &str { - "Aggregate a list table to a single value using an accumulator block. Block must be - (A, A) -> A unless --fold is selected, in which case it may be A, B -> A." + "Aggregate a list table to a single value using an accumulator block." + } + + fn extra_usage(&self) -> &str { + "Block must be (A, A) -> A unless --fold is selected, in which case it may be A, B -> A." } async fn run(&self, args: CommandArgs) -> Result { diff --git a/crates/nu-command/src/commands/rm.rs b/crates/nu-command/src/commands/rm.rs index aa08b0991a..6fc7df6432 100644 --- a/crates/nu-command/src/commands/rm.rs +++ b/crates/nu-command/src/commands/rm.rs @@ -30,7 +30,7 @@ impl WholeStreamCommand for Remove { } fn usage(&self) -> &str { - "Remove file(s)" + "Remove file(s)." } async fn run(&self, args: CommandArgs) -> Result { diff --git a/crates/nu-command/src/commands/roll/command.rs b/crates/nu-command/src/commands/roll/command.rs index 03581ec8ac..c4de00ad55 100644 --- a/crates/nu-command/src/commands/roll/command.rs +++ b/crates/nu-command/src/commands/roll/command.rs @@ -24,7 +24,7 @@ impl WholeStreamCommand for Command { } fn usage(&self) -> &str { - "Rolls the table rows" + "Rolls the table rows." } async fn run(&self, args: CommandArgs) -> Result { diff --git a/crates/nu-command/src/commands/seq.rs b/crates/nu-command/src/commands/seq.rs index f7cd72f03c..0735f9c37c 100644 --- a/crates/nu-command/src/commands/seq.rs +++ b/crates/nu-command/src/commands/seq.rs @@ -45,7 +45,7 @@ impl WholeStreamCommand for Seq { } fn usage(&self) -> &str { - "print sequences of numbers" + "Print sequences of numbers." } async fn run(&self, args: CommandArgs) -> Result { diff --git a/crates/nu-command/src/commands/sleep.rs b/crates/nu-command/src/commands/sleep.rs index df26003983..49de864c83 100644 --- a/crates/nu-command/src/commands/sleep.rs +++ b/crates/nu-command/src/commands/sleep.rs @@ -36,7 +36,7 @@ impl WholeStreamCommand for Sleep { } fn usage(&self) -> &str { - "Delay for a specified amount of time" + "Delay for a specified amount of time." } async fn run(&self, args: CommandArgs) -> Result { diff --git a/crates/nu-command/src/commands/split/command.rs b/crates/nu-command/src/commands/split/command.rs index 270d9b197e..90278e2912 100644 --- a/crates/nu-command/src/commands/split/command.rs +++ b/crates/nu-command/src/commands/split/command.rs @@ -17,12 +17,12 @@ impl WholeStreamCommand for Command { } fn usage(&self) -> &str { - "split contents across desired subcommand (like row, column) via the separator." + "Split contents across desired subcommand (like row, column) via the separator." } async fn run(&self, args: CommandArgs) -> Result { Ok(OutputStream::one(Ok(ReturnSuccess::Value( - UntaggedValue::string(get_help(&Command, &args.scope)).into_value(Tag::unknown()), + UntaggedValue::string(get_full_help(&Command, &args.scope)).into_value(Tag::unknown()), )))) } } diff --git a/crates/nu-command/src/commands/str_/command.rs b/crates/nu-command/src/commands/str_/command.rs index fb3ebb61e7..060eee9015 100644 --- a/crates/nu-command/src/commands/str_/command.rs +++ b/crates/nu-command/src/commands/str_/command.rs @@ -24,7 +24,7 @@ impl WholeStreamCommand for Command { async fn run(&self, args: CommandArgs) -> Result { Ok(OutputStream::one(ReturnSuccess::value( - UntaggedValue::string(get_help(&Command, &args.scope)).into_value(Tag::unknown()), + UntaggedValue::string(get_full_help(&Command, &args.scope)).into_value(Tag::unknown()), ))) } } diff --git a/crates/nu-command/src/commands/to.rs b/crates/nu-command/src/commands/to.rs index 4018bd0203..fd43e3ad1a 100644 --- a/crates/nu-command/src/commands/to.rs +++ b/crates/nu-command/src/commands/to.rs @@ -22,7 +22,7 @@ impl WholeStreamCommand for To { async fn run(&self, args: CommandArgs) -> Result { Ok(OutputStream::one(ReturnSuccess::value( - UntaggedValue::string(get_help(&To, &args.scope)).into_value(Tag::unknown()), + UntaggedValue::string(get_full_help(&To, &args.scope)).into_value(Tag::unknown()), ))) } } diff --git a/crates/nu-command/src/commands/touch.rs b/crates/nu-command/src/commands/touch.rs index 4dcce74d91..f0594ece45 100644 --- a/crates/nu-command/src/commands/touch.rs +++ b/crates/nu-command/src/commands/touch.rs @@ -29,7 +29,7 @@ impl WholeStreamCommand for Touch { .rest(SyntaxShape::FilePath, "additional files to create") } fn usage(&self) -> &str { - "creates one or more files" + "Creates one or more files." } async fn run(&self, args: CommandArgs) -> Result { touch(args).await diff --git a/crates/nu-command/src/commands/uniq.rs b/crates/nu-command/src/commands/uniq.rs index 6f4ce5d716..cb54c09d52 100644 --- a/crates/nu-command/src/commands/uniq.rs +++ b/crates/nu-command/src/commands/uniq.rs @@ -16,7 +16,7 @@ impl WholeStreamCommand for Uniq { } fn usage(&self) -> &str { - "Return the unique rows" + "Return the unique rows." } async fn run(&self, args: CommandArgs) -> Result { diff --git a/crates/nu-command/src/commands/url_/command.rs b/crates/nu-command/src/commands/url_/command.rs index 10f851791c..2de6681a1c 100644 --- a/crates/nu-command/src/commands/url_/command.rs +++ b/crates/nu-command/src/commands/url_/command.rs @@ -16,12 +16,12 @@ impl WholeStreamCommand for Url { } fn usage(&self) -> &str { - "Apply url function" + "Apply url function." } async fn run(&self, args: CommandArgs) -> Result { Ok(OutputStream::one(ReturnSuccess::value( - UntaggedValue::string(get_help(&Url, &args.scope)).into_value(Tag::unknown()), + UntaggedValue::string(get_full_help(&Url, &args.scope)).into_value(Tag::unknown()), ))) } } diff --git a/crates/nu-command/src/commands/version.rs b/crates/nu-command/src/commands/version.rs index 6217bf2f5e..12f90d775d 100644 --- a/crates/nu-command/src/commands/version.rs +++ b/crates/nu-command/src/commands/version.rs @@ -21,7 +21,7 @@ impl WholeStreamCommand for Version { } fn usage(&self) -> &str { - "Display Nu version" + "Display Nu version." } async fn run(&self, args: CommandArgs) -> Result { diff --git a/crates/nu-command/src/commands/with_env.rs b/crates/nu-command/src/commands/with_env.rs index 044b0266f6..1a2c3c6a79 100644 --- a/crates/nu-command/src/commands/with_env.rs +++ b/crates/nu-command/src/commands/with_env.rs @@ -35,7 +35,7 @@ impl WholeStreamCommand for WithEnv { } fn usage(&self) -> &str { - "Runs a block with an environment set. Eg) with-env [NAME 'foo'] { echo $nu.env.NAME }" + "Runs a block with an environment variable set." } async fn run(&self, args: CommandArgs) -> Result { diff --git a/crates/nu-command/src/prelude.rs b/crates/nu-command/src/prelude.rs index 5d2f005006..10463028e0 100644 --- a/crates/nu-command/src/prelude.rs +++ b/crates/nu-command/src/prelude.rs @@ -59,7 +59,7 @@ pub(crate) use nu_engine::Example; pub(crate) use nu_engine::Host; pub(crate) use nu_engine::RawCommandArgs; pub(crate) use nu_engine::ShellManager; -pub(crate) use nu_engine::{get_help, CommandArgs, Scope, WholeStreamCommand}; +pub(crate) use nu_engine::{get_full_help, CommandArgs, Scope, WholeStreamCommand}; pub(crate) use nu_parser::ParserScope; pub(crate) use nu_protocol::{out, row}; pub(crate) use nu_source::{AnchorLocation, PrettyDebug, Span, SpannedItem, Tag, TaggedItem, Text}; diff --git a/crates/nu-engine/src/documentation.rs b/crates/nu-engine/src/documentation.rs index 1256921697..40f8ad862f 100644 --- a/crates/nu-engine/src/documentation.rs +++ b/crates/nu-engine/src/documentation.rs @@ -11,6 +11,7 @@ const COMMANDS_DOCS_DIR: &str = "docs/commands"; pub struct DocumentationConfig { no_subcommands: bool, no_color: bool, + brief: bool, } impl Default for DocumentationConfig { @@ -18,6 +19,7 @@ impl Default for DocumentationConfig { DocumentationConfig { no_subcommands: false, no_color: false, + brief: false, } } } @@ -49,6 +51,7 @@ fn generate_doc(name: &str, scope: &Scope) -> IndexMap { &DocumentationConfig { no_subcommands: true, no_color: true, + brief: false, }, )) .into_untagged_value(), @@ -70,7 +73,7 @@ pub fn generate_docs(scope: &Scope) -> Value { if cmap.contains_key(*parent_name) { let sub_names = cmap .get_mut(*parent_name) - .expect("Expected a entry for parent"); + .expect("Expected an entry for parent"); sub_names.push(name.to_owned()); } } else { @@ -135,6 +138,12 @@ pub fn get_documentation( long_desc.push_str("\n\n"); } + let extra_usage = if config.brief { "" } else { &cmd.extra_usage() }; + if !extra_usage.is_empty() { + long_desc.push_str(extra_usage); + long_desc.push_str("\n\n"); + } + let mut subcommands = vec![]; if !config.no_subcommands { for name in scope.get_command_names() { @@ -296,6 +305,18 @@ fn get_flags_section(signature: &Signature) -> String { long_desc } -pub fn get_help(cmd: &dyn WholeStreamCommand, scope: &Scope) -> String { +pub fn get_brief_help(cmd: &dyn WholeStreamCommand, scope: &Scope) -> String { + get_documentation( + cmd, + scope, + &DocumentationConfig { + no_subcommands: false, + no_color: false, + brief: true, + }, + ) +} + +pub fn get_full_help(cmd: &dyn WholeStreamCommand, scope: &Scope) -> String { get_documentation(cmd, scope, &DocumentationConfig::default()) } diff --git a/crates/nu-engine/src/lib.rs b/crates/nu-engine/src/lib.rs index 3bb9ff910a..c6c8f031ec 100644 --- a/crates/nu-engine/src/lib.rs +++ b/crates/nu-engine/src/lib.rs @@ -21,7 +21,7 @@ pub use crate::call_info::UnevaluatedCallInfo; pub use crate::command_args::{ CommandArgs, EvaluatedCommandArgs, EvaluatedWholeStreamCommandArgs, RawCommandArgs, }; -pub use crate::documentation::{generate_docs, get_documentation, get_help}; +pub use crate::documentation::{generate_docs, get_brief_help, get_documentation, get_full_help}; pub use crate::env::environment::Env; pub use crate::env::host::FakeHost; pub use crate::env::host::Host; diff --git a/crates/nu-engine/src/whole_stream_command.rs b/crates/nu-engine/src/whole_stream_command.rs index 62c99630f3..e05e9185d4 100644 --- a/crates/nu-engine/src/whole_stream_command.rs +++ b/crates/nu-engine/src/whole_stream_command.rs @@ -1,5 +1,5 @@ use crate::command_args::CommandArgs; -use crate::documentation::get_help; +use crate::documentation::get_full_help; use crate::evaluate::block::run_block; use crate::evaluation_context::EvaluationContext; use crate::example::Example; @@ -22,6 +22,10 @@ pub trait WholeStreamCommand: Send + Sync { fn usage(&self) -> &str; + fn extra_usage(&self) -> &str { + "" + } + async fn run(&self, args: CommandArgs) -> Result; fn is_binary(&self) -> bool { @@ -210,7 +214,7 @@ impl Command { if args.call_info.switch_present("help") { let cl = self.0.clone(); Ok(OutputStream::one(Ok(ReturnSuccess::Value( - UntaggedValue::string(get_help(&*cl, &args.scope)).into_value(Tag::unknown()), + UntaggedValue::string(get_full_help(&*cl, &args.scope)).into_value(Tag::unknown()), )))) } else { self.0.run(args).await diff --git a/crates/nu_plugin_fetch/src/nu/mod.rs b/crates/nu_plugin_fetch/src/nu/mod.rs index b891cce727..8ac4fdccab 100644 --- a/crates/nu_plugin_fetch/src/nu/mod.rs +++ b/crates/nu_plugin_fetch/src/nu/mod.rs @@ -9,7 +9,7 @@ use crate::Fetch; impl Plugin for Fetch { fn config(&mut self) -> Result { Ok(Signature::build("fetch") - .desc("Load from a URL into a cell, convert to table if possible (avoid by appending '--raw')") + .desc("Load from a URL into a cell, convert to table if possible (avoid by appending '--raw').") .required( "URL", SyntaxShape::String, diff --git a/crates/nu_plugin_match/src/nu/mod.rs b/crates/nu_plugin_match/src/nu/mod.rs index 887044f107..5bf7abaad9 100644 --- a/crates/nu_plugin_match/src/nu/mod.rs +++ b/crates/nu_plugin_match/src/nu/mod.rs @@ -10,7 +10,7 @@ use regex::Regex; impl Plugin for Match { fn config(&mut self) -> Result { Ok(Signature::build("match") - .desc("Filter rows by Regex pattern") + .desc("Filter rows by Regex pattern.") .required("member", SyntaxShape::String, "the column name to match") .required("regex", SyntaxShape::String, "the regex to match with") .switch("insensitive", "case-insensitive search", Some('i'))