From c3979ef1cf2610d271cad0b1be00cf7a579cc673 Mon Sep 17 00:00:00 2001 From: Justin Ma Date: Thu, 24 Feb 2022 20:17:05 +0800 Subject: [PATCH] Add example for command n,g,p and grid, update date now examples (#4622) --- crates/nu-command/src/date/now.rs | 22 ++++++++--- crates/nu-command/src/shells/g.rs | 19 ++++++++- crates/nu-command/src/shells/n.rs | 17 +++++++- crates/nu-command/src/shells/p.rs | 17 +++++++- crates/nu-command/src/viewers/griddle.rs | 49 +++++++++++++++++++++++- docs/commands/date_now.md | 10 +++++ docs/commands/g.md | 12 ++++++ docs/commands/grid.md | 27 +++++++++++++ docs/commands/n.md | 12 ++++++ docs/commands/p.md | 12 ++++++ docs/commands/update_cells.md | 8 ++-- 11 files changed, 191 insertions(+), 14 deletions(-) diff --git a/crates/nu-command/src/date/now.rs b/crates/nu-command/src/date/now.rs index cc5f92325d..b1c602de76 100644 --- a/crates/nu-command/src/date/now.rs +++ b/crates/nu-command/src/date/now.rs @@ -35,10 +35,22 @@ impl Command for SubCommand { } fn examples(&self) -> Vec { - vec![Example { - description: "Get the current date and display it in a given format string.", - example: r#"date now | date format "%Y-%m-%d %H:%M:%S""#, - result: None, - }] + vec![ + Example { + description: "Get the current date and display it in a given format string.", + example: r#"date now | date format "%Y-%m-%d %H:%M:%S""#, + result: None, + }, + Example { + description: "Get the time duration from 2019-04-30 to now", + example: r#"(date now) - 2019-05-01"#, + result: None, + }, + Example { + description: "Get the time duration since a more accurate time", + example: r#"(date now) - 2019-05-01T04:12:05.20+08:00"#, + result: None, + }, + ] } } diff --git a/crates/nu-command/src/shells/g.rs b/crates/nu-command/src/shells/g.rs index c9f5f27052..763a7ed524 100644 --- a/crates/nu-command/src/shells/g.rs +++ b/crates/nu-command/src/shells/g.rs @@ -1,7 +1,9 @@ use nu_engine::{current_dir, CallExt}; use nu_protocol::ast::Call; use nu_protocol::engine::{Command, EngineState, Stack}; -use nu_protocol::{Category, PipelineData, ShellError, Signature, Spanned, SyntaxShape, Value}; +use nu_protocol::{ + Category, Example, PipelineData, ShellError, Signature, Spanned, SyntaxShape, Value, +}; /// Source a file for environment variables. #[derive(Clone)] @@ -75,4 +77,19 @@ impl Command for GotoShell { Ok(PipelineData::new(call.head)) } + + fn examples(&self) -> Vec { + vec![ + Example { + description: "Make two directories and enter new shells for them, use `g` to jump to the specific shell", + example: r#"mkdir foo bar; enter foo; enter ../bar; g 1"#, + result: None, + }, + Example { + description: "Use `shells` to show all the opened shells and run `g 2` to jump to the third one", + example: r#"shells; g 2"#, + result: None, + }, + ] + } } diff --git a/crates/nu-command/src/shells/n.rs b/crates/nu-command/src/shells/n.rs index 9354c7595c..94e8f70f34 100644 --- a/crates/nu-command/src/shells/n.rs +++ b/crates/nu-command/src/shells/n.rs @@ -1,7 +1,7 @@ use nu_engine::current_dir; use nu_protocol::ast::Call; use nu_protocol::engine::{Command, EngineState, Stack}; -use nu_protocol::{Category, PipelineData, ShellError, Signature, Value}; +use nu_protocol::{Category, Example, PipelineData, ShellError, Signature, Value}; /// Source a file for environment variables. #[derive(Clone)] @@ -76,4 +76,19 @@ impl Command for NextShell { Ok(PipelineData::new(call.head)) } + + fn examples(&self) -> Vec { + vec![ + Example { + description: "Make two directories and enter new shells for them, use `n` to jump to the next shell", + example: r#"mkdir foo bar; enter foo; enter ../bar; n"#, + result: None, + }, + Example { + description: "Run `n` several times and note the changes of current directory", + example: r#"n"#, + result: None, + }, + ] + } } diff --git a/crates/nu-command/src/shells/p.rs b/crates/nu-command/src/shells/p.rs index bd04b82b74..696bb91fe4 100644 --- a/crates/nu-command/src/shells/p.rs +++ b/crates/nu-command/src/shells/p.rs @@ -1,7 +1,7 @@ use nu_engine::current_dir; use nu_protocol::ast::Call; use nu_protocol::engine::{Command, EngineState, Stack}; -use nu_protocol::{Category, PipelineData, ShellError, Signature, Value}; +use nu_protocol::{Category, Example, PipelineData, ShellError, Signature, Value}; /// Source a file for environment variables. #[derive(Clone)] @@ -76,4 +76,19 @@ impl Command for PrevShell { Ok(PipelineData::new(call.head)) } + + fn examples(&self) -> Vec { + vec![ + Example { + description: "Make two directories and enter new shells for them, use `p` to jump to the previous shell", + example: r#"mkdir foo bar; enter foo; enter ../bar; p"#, + result: None, + }, + Example { + description: "Run `p` several times and note the changes of current directory", + example: r#"p"#, + result: None, + }, + ] + } } diff --git a/crates/nu-command/src/viewers/griddle.rs b/crates/nu-command/src/viewers/griddle.rs index ddd9bbf75a..62c62875b5 100644 --- a/crates/nu-command/src/viewers/griddle.rs +++ b/crates/nu-command/src/viewers/griddle.rs @@ -8,8 +8,8 @@ use nu_engine::CallExt; use nu_protocol::{ ast::{Call, PathMember}, engine::{Command, EngineState, Stack}, - Category, Config, IntoPipelineData, PipelineData, ShellError, Signature, Span, SyntaxShape, - Value, + Category, Config, Example, IntoPipelineData, PipelineData, ShellError, Signature, Span, + SyntaxShape, Value, }; use nu_term_grid::grid::{Alignment, Cell, Direction, Filling, Grid, GridOptions}; use terminal_size::{Height, Width}; @@ -131,6 +131,51 @@ prints out the list properly."# } } } + + fn examples(&self) -> Vec { + vec![ + Example { + description: "Render a simple list to a grid", + example: "[1 2 3 a b c] | grid", + result: Some(Value::String { + val: "1 │ 2 │ 3 │ a │ b │ c".to_string(), + span: Span::test_data(), + }), + }, + Example { + description: "The above example is the same as:", + example: "[1 2 3 a b c] | wrap name | grid", + result: Some(Value::String { + val: "1 │ 2 │ 3 │ a │ b │ c".to_string(), + span: Span::test_data(), + }), + }, + Example { + description: "Render a record to a grid", + example: "{name: 'foo', b: 1, c: 2} | grid", + result: Some(Value::String { + val: "foo".to_string(), + span: Span::test_data(), + }), + }, + Example { + description: "Render a list of records to a grid", + example: "[{name: 'A', v: 1} {name: 'B', v: 2} {name: 'C', v: 3}] | grid", + result: Some(Value::String { + val: "A │ B │ C".to_string(), + span: Span::test_data(), + }), + }, + Example { + description: "Render a table with 'name' column in it to a grid", + example: "[[name patch]; [0.1.0 $false] [0.1.1 $true] [0.2.0 $false]] | grid", + result: Some(Value::String { + val: "0.1.0 │ 0.1.1 │ 0.2.0".to_string(), + span: Span::test_data(), + }), + }, + ] + } } /// Removes ANSI escape codes and some ASCII control characters diff --git a/docs/commands/date_now.md b/docs/commands/date_now.md index 0d7bb378d1..17146ff344 100644 --- a/docs/commands/date_now.md +++ b/docs/commands/date_now.md @@ -16,3 +16,13 @@ Get the current date and display it in a given format string. ```shell > date now | date format "%Y-%m-%d %H:%M:%S" ``` + +Get the time duration from 2019-04-30 to now +```shell +> (date now) - 2019-05-01 +``` + +Get the time duration since a more accurate time +```shell +> (date now) - 2019-05-01T04:12:05.20+08:00 +``` diff --git a/docs/commands/g.md b/docs/commands/g.md index f401242b9a..cbfead0fd6 100644 --- a/docs/commands/g.md +++ b/docs/commands/g.md @@ -13,3 +13,15 @@ Switch to a given shell. ## Parameters - `shell_number`: shell number to change to + +## Examples + +Make two directories and enter new shells for them, use `g` to jump to the specific shell +```shell +> mkdir foo bar; enter foo; enter ../bar; g 1 +``` + +Use `shells` to show all the opened shells and run `g 2` to jump to the third one +```shell +> shells; g 2 +``` diff --git a/docs/commands/grid.md b/docs/commands/grid.md index 85415c99a5..0e96f2472c 100644 --- a/docs/commands/grid.md +++ b/docs/commands/grid.md @@ -15,3 +15,30 @@ Renders the output to a textual terminal grid. - `--width {int}`: number of terminal columns wide (not output columns) - `--color`: draw output with color - `--separator {string}`: character to separate grid with + +## Examples + +Render a simple list to a grid +```shell +> [1 2 3 a b c] | grid +``` + +The above example is the same as: +```shell +> [1 2 3 a b c] | wrap name | grid +``` + +Render a record to a grid +```shell +> {name: 'foo', b: 1, c: 2} | grid +``` + +Render a list of records to a grid +```shell +> [{name: 'A', v: 1} {name: 'B', v: 2} {name: 'C', v: 3}] | grid +``` + +Render a table with 'name' column in it to a grid +```shell +> [[name patch]; [0.1.0 $false] [0.1.1 $true] [0.2.0 $false]] | grid +``` diff --git a/docs/commands/n.md b/docs/commands/n.md index ae7d7ec833..74a4ae3638 100644 --- a/docs/commands/n.md +++ b/docs/commands/n.md @@ -9,3 +9,15 @@ Switch to the next shell. ## Signature ```> n ``` + +## Examples + +Make two directories and enter new shells for them, use `n` to jump to the next shell +```shell +> mkdir foo bar; enter foo; enter ../bar; n +``` + +Run `n` several times and note the changes of current directory +```shell +> n +``` diff --git a/docs/commands/p.md b/docs/commands/p.md index 750419827c..3bb92301a9 100644 --- a/docs/commands/p.md +++ b/docs/commands/p.md @@ -9,3 +9,15 @@ Switch to the previous shell. ## Signature ```> p ``` + +## Examples + +Make two directories and enter new shells for them, use `p` to jump to the previous shell +```shell +> mkdir foo bar; enter foo; enter ../bar; p +``` + +Run `p` several times and note the changes of current directory +```shell +> p +``` diff --git a/docs/commands/update_cells.md b/docs/commands/update_cells.md index 3dd946d8f8..60c638dea2 100644 --- a/docs/commands/update_cells.md +++ b/docs/commands/update_cells.md @@ -20,8 +20,8 @@ Update the table cells. Update the zero value cells to empty strings. ```shell > [ - [2021-04-16, 2021-06-10, 2021-09-18, 2021-10-15, 2021-11-16, 2021-11-17, 2021-11-18]; - [ 37, 0, 0, 0, 37, 0, 0] + ["2021-04-16", "2021-06-10", "2021-09-18", "2021-10-15", "2021-11-16", "2021-11-17", "2021-11-18"]; + [ 37, 0, 0, 0, 37, 0, 0] ] | update cells {|value| if $value == 0 { "" @@ -34,8 +34,8 @@ Update the zero value cells to empty strings. Update the zero value cells to empty strings in 2 last columns. ```shell > [ - [2021-04-16, 2021-06-10, 2021-09-18, 2021-10-15, 2021-11-16, 2021-11-17, 2021-11-18]; - [ 37, 0, 0, 0, 37, 0, 0] + ["2021-04-16", "2021-06-10", "2021-09-18", "2021-10-15", "2021-11-16", "2021-11-17", "2021-11-18"]; + [ 37, 0, 0, 0, 37, 0, 0] ] | update cells -c ["2021-11-18", "2021-11-17"] {|value| if $value == 0 { ""