Add --help for commands (#1226)

* 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 <jonathandturner@users.noreply.github.com>
Co-authored-by: Koenraad Verheyden <mail@koenraadverheyden.com>
Co-authored-by: Andrés N. Robalino <andres@androbtech.com>

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(

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(),

crates/nu-parser/src/hir/named.rs

@@ -37,6 +37,10 @@ impl NamedArguments {
     pub fn iter(&self) -> impl Iterator<Item = (&String, &NamedValue)> {
         self.named.iter()
     }
+
+    pub fn get(&self, name: &str) -> Option<&NamedValue> {
+        self.named.get(name)
+    }
 }
 
 impl NamedArguments {

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()))
                     {

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;

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<bool, ShellError> {
+        match &self.value {
+            UntaggedValue::Primitive(Primitive::Boolean(p)) => Ok(*p),
+            _ => Err(ShellError::type_error("boolean", self.spanned_type_name())),
+        }
+    }
 }
 
 impl Into<UntaggedValue> for &str {

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 {
+        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()),
+                Command::PerItem(command) => {
+                    self.run_helper(command.clone(), args, registry.clone())
+                }
+            }
         }
     }
 

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,12 +73,45 @@ impl PerItemCommand for Help {
                         help.push_back(ReturnSuccess::value(short_desc.into_value()));
                     }
                 } else if let Some(command) = registry.get_command(document)? {
+                    return Ok(
+                        get_help(&command.name(), &command.usage(), command.signature()).into(),
+                    );
+                }
+                Ok(help.to_output_stream())
+            }
+            _ => {
+                let msg = r#"Welcome to Nushell.
+
+Here are some tips to help you get started.
+  * help commands - list all available commands
+  * help <command name> - display help about a particular command
+
+You can also learn more at https://www.nushell.sh/book/"#;
+
+                let mut output_stream = VecDeque::new();
+
+                output_stream.push_back(ReturnSuccess::value(
+                    UntaggedValue::string(msg).into_value(tag),
+                ));
+
+                Ok(output_stream.to_output_stream())
+            }
+        }
+    }
+}
+
+pub(crate) fn get_help(
+    cmd_name: &str,
+    cmd_usage: &str,
+    cmd_sig: Signature,
+) -> impl Into<OutputStream> {
+    let mut help = VecDeque::new();
     let mut long_desc = String::new();
 
-                    long_desc.push_str(&command.usage());
+    long_desc.push_str(&cmd_usage);
     long_desc.push_str("\n");
 
-                    let signature = command.signature();
+    let signature = cmd_sig;
 
     let mut one_liner = String::new();
     one_liner.push_str(&signature.name);
@@ -125,7 +159,7 @@ impl PerItemCommand for Help {
         long_desc.push_str("\nflags:\n");
         for (flag, ty) in signature.named {
             match ty.0 {
-                                NamedType::Switch => {
+                NamedType::Switch | NamedType::Help => {
                     long_desc.push_str(&format!(
                         "  --{}{} {}\n",
                         flag,
@@ -156,29 +190,7 @@ impl PerItemCommand for Help {
     }
 
     help.push_back(ReturnSuccess::value(
-                        UntaggedValue::string(long_desc).into_value(tag.clone()),
+        UntaggedValue::string(long_desc).into_value(Tag::from((0, cmd_name.len(), None))),
     ));
-                }
+    help
-
-                Ok(help.to_output_stream())
-            }
-            _ => {
-                let msg = r#"Welcome to Nushell.
-
-Here are some tips to help you get started.
-  * help commands - list all available commands
-  * help <command name> - display help about a particular command
-
-You can also learn more at https://www.nushell.sh/book/"#;
-
-                let mut output_stream = VecDeque::new();
-
-                output_stream.push_back(ReturnSuccess::value(
-                    UntaggedValue::string(msg).into_value(tag),
-                ));
-
-                Ok(output_stream.to_output_stream())
-            }
-        }
-    }
 }

src/data/command.rs

@@ -63,6 +63,7 @@ fn signature_dict(signature: Signature, tag: impl Into<Tag>) -> 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)),
         }
     }