From f7f8b0dbff5bfe0e8c59c340e4cfe78f8f672027 Mon Sep 17 00:00:00 2001 From: JT <547158+jntrnr@users.noreply.github.com> Date: Sun, 28 Nov 2021 07:16:20 +1300 Subject: [PATCH] A few help cleanups (#372) --- crates/nu-command/src/core_commands/if_.rs | 46 ++++++++++++++++++--- crates/nu-command/src/core_commands/let_.rs | 29 ++++++++++++- crates/nu-engine/src/documentation.rs | 34 ++++++++++++--- crates/nu-parser/src/flatten.rs | 2 +- 4 files changed, 99 insertions(+), 12 deletions(-) diff --git a/crates/nu-command/src/core_commands/if_.rs b/crates/nu-command/src/core_commands/if_.rs index 9de1bb1769..df91d7537e 100644 --- a/crates/nu-command/src/core_commands/if_.rs +++ b/crates/nu-command/src/core_commands/if_.rs @@ -2,7 +2,7 @@ use nu_engine::{eval_block, eval_expression}; use nu_protocol::ast::Call; use nu_protocol::engine::{Command, EngineState, Stack}; use nu_protocol::{ - Category, IntoPipelineData, PipelineData, ShellError, Signature, SyntaxShape, Value, + Category, Example, IntoPipelineData, PipelineData, ShellError, Signature, SyntaxShape, Value, }; #[derive(Clone)] @@ -19,12 +19,16 @@ impl Command for If { fn signature(&self) -> nu_protocol::Signature { Signature::build("if") - .required("cond", SyntaxShape::Expression, "condition") - .required("then_block", SyntaxShape::Block(Some(vec![])), "then block") + .required("cond", SyntaxShape::Expression, "condition to check") + .required( + "then_block", + SyntaxShape::Block(Some(vec![])), + "block to run if check succeeds", + ) .optional( - "else", + "else_expression", SyntaxShape::Keyword(b"else".to_vec(), Box::new(SyntaxShape::Expression)), - "optional else followed by else block", + "expression or block to run if check fails", ) .category(Category::Core) } @@ -74,4 +78,36 @@ impl Command for If { )), } } + + fn examples(&self) -> Vec { + vec![ + Example { + description: "Output a value if a condition matches, otherwise return nothing", + example: "if 2 < 3 { 'yes!' }", + result: Some(Value::test_string("yes!")), + }, + Example { + description: "Output a value if a condition matches, else return another value", + example: "if 5 < 3 { 'yes!' } else { 'no!' }", + result: Some(Value::test_string("no!")), + }, + Example { + description: "Chain multiple if's together", + example: "if 5 < 3 { 'yes!' } else if 4 < 5 { 'no!' } else { 'okay!' }", + result: Some(Value::test_string("no!")), + }, + ] + } +} + +#[cfg(test)] +mod test { + use super::*; + + #[test] + fn test_examples() { + use crate::test_examples; + + test_examples(If {}) + } } diff --git a/crates/nu-command/src/core_commands/let_.rs b/crates/nu-command/src/core_commands/let_.rs index 5742f1a233..10bfacd1c0 100644 --- a/crates/nu-command/src/core_commands/let_.rs +++ b/crates/nu-command/src/core_commands/let_.rs @@ -1,7 +1,7 @@ use nu_engine::eval_expression; use nu_protocol::ast::Call; use nu_protocol::engine::{Command, EngineState, Stack}; -use nu_protocol::{Category, PipelineData, Signature, SyntaxShape}; +use nu_protocol::{Category, Example, PipelineData, Signature, SyntaxShape}; #[derive(Clone)] pub struct Let; @@ -48,4 +48,31 @@ impl Command for Let { stack.add_var(var_id, rhs); Ok(PipelineData::new(call.head)) } + + fn examples(&self) -> Vec { + vec![ + Example { + description: "Set a variable to a value", + example: "let x = 10", + result: None, + }, + Example { + description: "Set a variable to the result of an expression", + example: "let x = 10 + 100", + result: None, + }, + ] + } +} + +#[cfg(test)] +mod test { + use super::*; + + #[test] + fn test_examples() { + use crate::test_examples; + + test_examples(Let {}) + } } diff --git a/crates/nu-engine/src/documentation.rs b/crates/nu-engine/src/documentation.rs index caa6af50b6..a921f351ac 100644 --- a/crates/nu-engine/src/documentation.rs +++ b/crates/nu-engine/src/documentation.rs @@ -1,5 +1,7 @@ use itertools::Itertools; -use nu_protocol::{engine::EngineState, Example, Signature, Span, Value}; +use nu_protocol::{ + engine::EngineState, Example, PositionalArg, Signature, Span, SyntaxShape, Value, +}; use std::collections::HashMap; const COMMANDS_DOCS_DIR: &str = "docs/commands"; @@ -171,10 +173,10 @@ pub fn get_documentation( one_liner.push(' '); for positional in &sig.required_positional { - one_liner.push_str(&format!("<{}> ", positional.name)); + one_liner.push_str(&get_positional_short_name(positional, true)); } for positional in &sig.optional_positional { - one_liner.push_str(&format!("({}) ", positional.name)); + one_liner.push_str(&get_positional_short_name(positional, false)); } if sig.rest_positional.is_some() { @@ -204,10 +206,13 @@ pub fn get_documentation( { long_desc.push_str("\nParameters:\n"); for positional in &sig.required_positional { - long_desc.push_str(&format!(" <{}> {}\n", positional.name, positional.desc)); + long_desc.push_str(&format!(" {}: {}\n", positional.name, positional.desc)); } for positional in &sig.optional_positional { - long_desc.push_str(&format!(" ({}) {}\n", positional.name, positional.desc)); + long_desc.push_str(&format!( + " (optional) {}: {}\n", + positional.name, positional.desc + )); } if let Some(rest_positional) = &sig.rest_positional { @@ -241,6 +246,25 @@ pub fn get_documentation( long_desc } +fn get_positional_short_name(arg: &PositionalArg, is_required: bool) -> String { + match &arg.shape { + SyntaxShape::Keyword(name, ..) => { + if is_required { + format!("{} <{}> ", String::from_utf8_lossy(name), arg.name) + } else { + format!("({} <{}>) ", String::from_utf8_lossy(name), arg.name) + } + } + _ => { + if is_required { + format!("<{}> ", arg.name) + } else { + format!("({}) ", arg.name) + } + } + } +} + fn get_flags_section(signature: &Signature) -> String { let mut long_desc = String::new(); long_desc.push_str("\nFlags:\n"); diff --git a/crates/nu-parser/src/flatten.rs b/crates/nu-parser/src/flatten.rs index d9a23b18e1..dffef0c7e7 100644 --- a/crates/nu-parser/src/flatten.rs +++ b/crates/nu-parser/src/flatten.rs @@ -194,7 +194,7 @@ pub fn flatten_expression( output } Expr::Keyword(_, span, expr) => { - let mut output = vec![(*span, FlatShape::Operator)]; + let mut output = vec![(*span, FlatShape::InternalCall)]; output.extend(flatten_expression(working_set, expr)); output }