Add example for command n,g,p and grid, update date now examples (#4622)

crates/nu-command/src/date/now.rs

@@ -35,10 +35,22 @@ impl Command for SubCommand {
     }
 
     fn examples(&self) -> Vec<Example> {
-        vec![Example {
+        vec![
-            description: "Get the current date and display it in a given format string.",
+            Example {
-            example: r#"date now | date format "%Y-%m-%d %H:%M:%S""#,
+                description: "Get the current date and display it in a given format string.",
-            result: None,
+                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,
+            },
+        ]
     }
 }

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<Example> {
+        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,
+            },
+        ]
+    }
 }

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<Example> {
+        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,
+            },
+        ]
+    }
 }

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<Example> {
+        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,
+            },
+        ]
+    }
 }

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,
+    Category, Config, Example, IntoPipelineData, PipelineData, ShellError, Signature, Span,
-    Value,
+    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<Example> {
+        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

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
+```

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
+```

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
+```

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
+```

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
+```

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];
+    ["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]
+    [          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];
+    ["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]
+    [          37,            0,            0,            0,           37,            0,            0]
 ] | update cells -c ["2021-11-18", "2021-11-17"] {|value|
         if $value == 0 {
           ""