From a5c5b4e7112af9312be27e6fc6bb1ce407b2f405 Mon Sep 17 00:00:00 2001 From: Corvus Corax Date: Fri, 17 Jan 2020 16:46:18 -0600 Subject: [PATCH] Add --help for commands (#1226) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * WIP --help works for PerItemCommands. * De-linting * Add more comments (#1228) * Add some more docs * More docs * More docs * More docs (#1229) * Add some more docs * More docs * More docs * Add more docs * External commands: wrap values that contain spaces in quotes (#1214) (#1220) * External commands: wrap values that contain spaces in quotes (#1214) * Add fn's argument_contains_whitespace & add_quotes (#1214) * Fix formatting with cargo fmt * Don't wrap argument in quotes when $it is already quoted (#1214) * Implement --help for internal commands * Externals now spawn independently. (#1230) This commit changes the way we shell out externals when using the `"$it"` argument. Also pipes per row to an external's stdin if no `"$it"` argument is present for external commands. Further separation of logic (preparing the external's command arguments, getting the data for piping, emitting values, spawning processes) will give us a better idea for lower level details regarding external commands until we can find the right abstractions for making them more generic and unify within the pipeline calling logic of Nu internal's and external's. * Poll externals quicker. (#1231) * WIP --help works for PerItemCommands. * De-linting * Implement --help for internal commands * Make having --help the default * Update test to include new default switch Co-authored-by: Jonathan Turner Co-authored-by: Koenraad Verheyden Co-authored-by: Andrés N. Robalino --- crates/nu-parser/src/hir.rs | 13 ++ .../nu-parser/src/hir/baseline_parse/tests.rs | 1 + crates/nu-parser/src/hir/named.rs | 4 + crates/nu-parser/src/parse_command.rs | 10 +- crates/nu-protocol/src/signature.rs | 10 +- crates/nu-protocol/src/value.rs | 7 + src/commands/command.rs | 23 ++- src/commands/help.rs | 186 ++++++++++-------- src/data/command.rs | 1 + 9 files changed, 160 insertions(+), 95 deletions(-) diff --git a/crates/nu-parser/src/hir.rs b/crates/nu-parser/src/hir.rs index 6c79d77ce..8baa36088 100644 --- a/crates/nu-parser/src/hir.rs +++ b/crates/nu-parser/src/hir.rs @@ -71,6 +71,19 @@ pub struct Call { pub span: Span, } +impl Call { + pub fn switch_preset(&self, switch: &str) -> bool { + self.named + .as_ref() + .and_then(|n| n.get(switch)) + .map(|t| match t { + NamedValue::PresentSwitch(_) => true, + _ => false, + }) + .unwrap_or(false) + } +} + impl PrettyDebugWithSource for Call { fn pretty_debug(&self, source: &str) -> DebugDocBuilder { b::delimit( diff --git a/crates/nu-parser/src/hir/baseline_parse/tests.rs b/crates/nu-parser/src/hir/baseline_parse/tests.rs index e73f1b8e6..0ed1dc69f 100644 --- a/crates/nu-parser/src/hir/baseline_parse/tests.rs +++ b/crates/nu-parser/src/hir/baseline_parse/tests.rs @@ -72,6 +72,7 @@ fn test_parse_command() { let mut map = IndexMap::new(); map.insert("full".to_string(), NamedValue::AbsentSwitch); + map.insert("help".to_string(), NamedValue::AbsentSwitch); ClassifiedCommand::Internal(InternalCommand::new( "ls".to_string(), diff --git a/crates/nu-parser/src/hir/named.rs b/crates/nu-parser/src/hir/named.rs index cc0290e57..45ca381d5 100644 --- a/crates/nu-parser/src/hir/named.rs +++ b/crates/nu-parser/src/hir/named.rs @@ -37,6 +37,10 @@ impl NamedArguments { pub fn iter(&self) -> impl Iterator { self.named.iter() } + + pub fn get(&self, name: &str) -> Option<&NamedValue> { + self.named.get(name) + } } impl NamedArguments { diff --git a/crates/nu-parser/src/parse_command.rs b/crates/nu-parser/src/parse_command.rs index ab504d6ca..0f13aea7a 100644 --- a/crates/nu-parser/src/parse_command.rs +++ b/crates/nu-parser/src/parse_command.rs @@ -31,6 +31,14 @@ pub fn parse_command_tail( named.insert_switch(name, flag); } + NamedType::Help => { + let flag = extract_switch(name, tail, context.source()); + + named.insert_switch(name, flag); + if flag.is_some() { + return Ok(Some((None, Some(named)))); + } + } NamedType::Mandatory(syntax_type) => { match extract_mandatory(config, name, tail, context.source(), command_span) { Err(err) => return Err(err), // produce a correct diagnostic @@ -242,7 +250,7 @@ impl ColorSyntax for CommandTailShape { trace!(target: "nu::color_syntax", "looking for {} : {:?}", name, kind); match &kind.0 { - NamedType::Switch => { + NamedType::Switch | NamedType::Help => { if let Some((pos, flag)) = token_nodes.extract(|t| t.as_flag(name, context.source())) { diff --git a/crates/nu-protocol/src/signature.rs b/crates/nu-protocol/src/signature.rs index 3751e73a3..117c89be8 100644 --- a/crates/nu-protocol/src/signature.rs +++ b/crates/nu-protocol/src/signature.rs @@ -13,6 +13,7 @@ pub enum NamedType { Mandatory(SyntaxShape), /// An optional flag, with associated argument. eg) `foo --optional abc` Optional(SyntaxShape), + Help, } /// The type of positional arguments @@ -135,7 +136,7 @@ impl Signature { usage: String::new(), positional: vec![], rest_positional: None, - named: IndexMap::new(), + named: indexmap::indexmap! {"help".into() => (NamedType::Help, "Display this help message".into())}, is_filter: false, yields: None, input: None, @@ -217,6 +218,13 @@ impl Signature { self } + /// Remove the default help switch + pub fn remove_help(mut self) -> Signature { + self.named.remove("help"); + + self + } + /// Set the filter flag for the signature pub fn filter(mut self) -> Signature { self.is_filter = true; diff --git a/crates/nu-protocol/src/value.rs b/crates/nu-protocol/src/value.rs index 9dcaa1d2f..ff586b481 100644 --- a/crates/nu-protocol/src/value.rs +++ b/crates/nu-protocol/src/value.rs @@ -243,6 +243,13 @@ impl Value { _ => Err(ShellError::type_error("integer", self.spanned_type_name())), } } + + pub fn as_bool(&self) -> Result { + match &self.value { + UntaggedValue::Primitive(Primitive::Boolean(p)) => Ok(*p), + _ => Err(ShellError::type_error("boolean", self.spanned_type_name())), + } + } } impl Into for &str { diff --git a/src/commands/command.rs b/src/commands/command.rs index 89d6db2e1..f04bc8f17 100644 --- a/src/commands/command.rs +++ b/src/commands/command.rs @@ -1,3 +1,4 @@ +use crate::commands::help::get_help; use crate::context::CommandRegistry; use crate::deserializer::ConfigDeserializer; use crate::evaluate::evaluate_args::evaluate_args; @@ -31,6 +32,10 @@ impl UnevaluatedCallInfo { name_tag: self.name_tag, }) } + + pub fn switch_present(&self, switch: &str) -> bool { + self.args.switch_preset(switch) + } } pub trait CallInfoExt { @@ -476,12 +481,18 @@ impl Command { } pub fn run(&self, args: CommandArgs, registry: &CommandRegistry) -> OutputStream { - match self { - Command::WholeStream(command) => match command.run(args, registry) { - Ok(stream) => stream, - Err(err) => OutputStream::one(Err(err)), - }, - Command::PerItem(command) => self.run_helper(command.clone(), args, registry.clone()), + if args.call_info.switch_present("help") { + get_help(self.name(), self.usage(), self.signature()).into() + } else { + match self { + Command::WholeStream(command) => match command.run(args, registry) { + Ok(stream) => stream, + Err(err) => OutputStream::one(Err(err)), + }, + Command::PerItem(command) => { + self.run_helper(command.clone(), args, registry.clone()) + } + } } } diff --git a/src/commands/help.rs b/src/commands/help.rs index 17b63efce..6897ac798 100644 --- a/src/commands/help.rs +++ b/src/commands/help.rs @@ -1,5 +1,6 @@ use crate::commands::PerItemCommand; use crate::data::command_dict; + use crate::prelude::*; use nu_errors::ShellError; use nu_protocol::{ @@ -72,94 +73,10 @@ impl PerItemCommand for Help { help.push_back(ReturnSuccess::value(short_desc.into_value())); } } else if let Some(command) = registry.get_command(document)? { - let mut long_desc = String::new(); - - long_desc.push_str(&command.usage()); - long_desc.push_str("\n"); - - let signature = command.signature(); - - let mut one_liner = String::new(); - one_liner.push_str(&signature.name); - one_liner.push_str(" "); - - for positional in &signature.positional { - match &positional.0 { - PositionalType::Mandatory(name, _m) => { - one_liner.push_str(&format!("<{}> ", name)); - } - PositionalType::Optional(name, _o) => { - one_liner.push_str(&format!("({}) ", name)); - } - } - } - - if signature.rest_positional.is_some() { - one_liner.push_str(" ...args"); - } - - if !signature.named.is_empty() { - one_liner.push_str("{flags} "); - } - - long_desc.push_str(&format!("\nUsage:\n > {}\n", one_liner)); - - if !signature.positional.is_empty() || signature.rest_positional.is_some() { - long_desc.push_str("\nparameters:\n"); - for positional in signature.positional { - match positional.0 { - PositionalType::Mandatory(name, _m) => { - long_desc.push_str(&format!(" <{}> {}\n", name, positional.1)); - } - PositionalType::Optional(name, _o) => { - long_desc.push_str(&format!(" ({}) {}\n", name, positional.1)); - } - } - } - - if let Some(rest_positional) = signature.rest_positional { - long_desc.push_str(&format!(" ...args: {}\n", rest_positional.1)); - } - } - if !signature.named.is_empty() { - long_desc.push_str("\nflags:\n"); - for (flag, ty) in signature.named { - match ty.0 { - NamedType::Switch => { - long_desc.push_str(&format!( - " --{}{} {}\n", - flag, - if !ty.1.is_empty() { ":" } else { "" }, - ty.1 - )); - } - NamedType::Mandatory(m) => { - long_desc.push_str(&format!( - " --{} <{}> (required parameter){} {}\n", - flag, - m.display(), - if !ty.1.is_empty() { ":" } else { "" }, - ty.1 - )); - } - NamedType::Optional(o) => { - long_desc.push_str(&format!( - " --{} <{}>{} {}\n", - flag, - o.display(), - if !ty.1.is_empty() { ":" } else { "" }, - ty.1 - )); - } - } - } - } - - help.push_back(ReturnSuccess::value( - UntaggedValue::string(long_desc).into_value(tag.clone()), - )); + return Ok( + get_help(&command.name(), &command.usage(), command.signature()).into(), + ); } - Ok(help.to_output_stream()) } _ => { @@ -182,3 +99,98 @@ You can also learn more at https://www.nushell.sh/book/"#; } } } + +pub(crate) fn get_help( + cmd_name: &str, + cmd_usage: &str, + cmd_sig: Signature, +) -> impl Into { + let mut help = VecDeque::new(); + let mut long_desc = String::new(); + + long_desc.push_str(&cmd_usage); + long_desc.push_str("\n"); + + let signature = cmd_sig; + + let mut one_liner = String::new(); + one_liner.push_str(&signature.name); + one_liner.push_str(" "); + + for positional in &signature.positional { + match &positional.0 { + PositionalType::Mandatory(name, _m) => { + one_liner.push_str(&format!("<{}> ", name)); + } + PositionalType::Optional(name, _o) => { + one_liner.push_str(&format!("({}) ", name)); + } + } + } + + if signature.rest_positional.is_some() { + one_liner.push_str(" ...args"); + } + + if !signature.named.is_empty() { + one_liner.push_str("{flags} "); + } + + long_desc.push_str(&format!("\nUsage:\n > {}\n", one_liner)); + + if !signature.positional.is_empty() || signature.rest_positional.is_some() { + long_desc.push_str("\nparameters:\n"); + for positional in signature.positional { + match positional.0 { + PositionalType::Mandatory(name, _m) => { + long_desc.push_str(&format!(" <{}> {}\n", name, positional.1)); + } + PositionalType::Optional(name, _o) => { + long_desc.push_str(&format!(" ({}) {}\n", name, positional.1)); + } + } + } + + if let Some(rest_positional) = signature.rest_positional { + long_desc.push_str(&format!(" ...args: {}\n", rest_positional.1)); + } + } + if !signature.named.is_empty() { + long_desc.push_str("\nflags:\n"); + for (flag, ty) in signature.named { + match ty.0 { + NamedType::Switch | NamedType::Help => { + long_desc.push_str(&format!( + " --{}{} {}\n", + flag, + if !ty.1.is_empty() { ":" } else { "" }, + ty.1 + )); + } + NamedType::Mandatory(m) => { + long_desc.push_str(&format!( + " --{} <{}> (required parameter){} {}\n", + flag, + m.display(), + if !ty.1.is_empty() { ":" } else { "" }, + ty.1 + )); + } + NamedType::Optional(o) => { + long_desc.push_str(&format!( + " --{} <{}>{} {}\n", + flag, + o.display(), + if !ty.1.is_empty() { ":" } else { "" }, + ty.1 + )); + } + } + } + } + + help.push_back(ReturnSuccess::value( + UntaggedValue::string(long_desc).into_value(Tag::from((0, cmd_name.len(), None))), + )); + help +} diff --git a/src/data/command.rs b/src/data/command.rs index 91c52bc0e..bec6074cf 100644 --- a/src/data/command.rs +++ b/src/data/command.rs @@ -63,6 +63,7 @@ fn signature_dict(signature: Signature, tag: impl Into) -> Value { NamedType::Mandatory(_) => sig.push_value(for_spec(name, "flag", true, &tag)), NamedType::Optional(_) => sig.push_value(for_spec(name, "flag", false, &tag)), NamedType::Switch => sig.push_value(for_spec(name, "switch", false, &tag)), + NamedType::Help => sig.push_value(for_spec("help", "switch", false, &tag)), } }