From b0aa1425423a44b1c8ff7d892e50af2068913822 Mon Sep 17 00:00:00 2001
From: Jason Gedge <jason.gedge@shopify.com>
Date: Tue, 12 May 2020 11:54:29 -0400
Subject: [PATCH] Add examples for some more commands (#1765)

---
 crates/nu-cli/src/commands/get.rs       | 13 +++++++++++++
 crates/nu-cli/src/commands/group_by.rs  |  7 +++++++
 crates/nu-cli/src/commands/headers.rs   | 10 ++++++++++
 crates/nu-cli/src/commands/histogram.rs | 18 ++++++++++++++++++
 crates/nu-cli/src/commands/keep.rs      | 13 +++++++++++++
 crates/nu-cli/src/commands/kill.rs      | 13 +++++++++++++
 crates/nu-cli/src/commands/last.rs      | 13 +++++++++++++
 crates/nu-cli/src/commands/lines.rs     |  7 +++++++
 crates/nu-cli/src/commands/ls.rs        | 17 +++++++++++++++++
 crates/nu-cli/src/commands/merge.rs     |  7 +++++++
 crates/nu-cli/src/commands/mkdir.rs     |  7 +++++++
 crates/nu-cli/src/commands/mv.rs        | 17 +++++++++++++++++
 crates/nu-cli/src/commands/nth.rs       | 13 +++++++++++++
 crates/nu-cli/src/commands/parse.rs     |  7 +++++++
 crates/nu-cli/src/commands/pwd.rs       |  7 +++++++
 crates/nu-cli/src/commands/rename.rs    | 20 +++++++++++++++-----
 crates/nu-cli/src/commands/reverse.rs   |  7 +++++++
 crates/nu-cli/src/commands/rm.rs        | 13 +++++++++++++
 crates/nu-cli/src/commands/select.rs    | 13 +++++++++++++
 crates/nu-cli/src/commands/size.rs      |  7 +++++++
 crates/nu-cli/src/commands/skip.rs      |  7 +++++++
 crates/nu-cli/src/commands/sort_by.rs   | 15 ++++++++++++++-
 crates/nu-cli/src/commands/sum.rs       | 13 +++++++++++++
 crates/nu-cli/src/commands/with_env.rs  |  7 +++++++
 crates/nu-cli/src/commands/wrap.rs      | 13 +++++++++++++
 25 files changed, 278 insertions(+), 6 deletions(-)

diff --git a/crates/nu-cli/src/commands/get.rs b/crates/nu-cli/src/commands/get.rs
index 4fa8dc1bc..def162ced 100644
--- a/crates/nu-cli/src/commands/get.rs
+++ b/crates/nu-cli/src/commands/get.rs
@@ -40,6 +40,19 @@ impl WholeStreamCommand for Get {
     ) -> Result<OutputStream, ShellError> {
         args.process(registry, get)?.run()
     }
+
+    fn examples(&self) -> &[Example] {
+        &[
+            Example {
+                description: "Extract the name of files as a list",
+                example: "ls | get name",
+            },
+            Example {
+                description: "Extract the cpu list from the sys information",
+                example: "sys | get cpu",
+            },
+        ]
+    }
 }
 
 pub fn get_column_path(path: &ColumnPath, obj: &Value) -> Result<Value, ShellError> {
diff --git a/crates/nu-cli/src/commands/group_by.rs b/crates/nu-cli/src/commands/group_by.rs
index 372da74ca..2ce86f392 100644
--- a/crates/nu-cli/src/commands/group_by.rs
+++ b/crates/nu-cli/src/commands/group_by.rs
@@ -45,6 +45,13 @@ impl WholeStreamCommand for GroupBy {
     ) -> Result<OutputStream, ShellError> {
         args.process(registry, group_by)?.run()
     }
+
+    fn examples(&self) -> &[Example] {
+        &[Example {
+            description: "Group files by type",
+            example: "ls | group-by type",
+        }]
+    }
 }
 
 enum Grouper {
diff --git a/crates/nu-cli/src/commands/headers.rs b/crates/nu-cli/src/commands/headers.rs
index 9e52c977c..9e4748a1c 100644
--- a/crates/nu-cli/src/commands/headers.rs
+++ b/crates/nu-cli/src/commands/headers.rs
@@ -15,12 +15,15 @@ impl WholeStreamCommand for Headers {
     fn name(&self) -> &str {
         "headers"
     }
+
     fn signature(&self) -> Signature {
         Signature::build("headers")
     }
+
     fn usage(&self) -> &str {
         "Use the first row of the table as column names"
     }
+
     fn run(
         &self,
         args: CommandArgs,
@@ -28,6 +31,13 @@ impl WholeStreamCommand for Headers {
     ) -> Result<OutputStream, ShellError> {
         args.process(registry, headers)?.run()
     }
+
+    fn examples(&self) -> &[Example] {
+        &[Example {
+            description: "Create headers for a raw string",
+            example: "echo \"a b c|1 2 3\" | split-row \"|\" | split-column \" \" | headers",
+        }]
+    }
 }
 
 pub fn headers(
diff --git a/crates/nu-cli/src/commands/histogram.rs b/crates/nu-cli/src/commands/histogram.rs
index a5a0b7e69..b650d02d5 100644
--- a/crates/nu-cli/src/commands/histogram.rs
+++ b/crates/nu-cli/src/commands/histogram.rs
@@ -46,6 +46,24 @@ impl WholeStreamCommand for Histogram {
     ) -> Result<OutputStream, ShellError> {
         args.process(registry, histogram)?.run()
     }
+
+    fn examples(&self) -> &[Example] {
+        &[
+            Example {
+                description: "Get a histogram for the types of files",
+                example: "ls | histogram type",
+            },
+            Example {
+                description:
+                    "Get a histogram for the types of files, with frequency column named count",
+                example: "ls | histogram type count",
+            },
+            Example {
+                description: "Get a histogram for a list of numbers",
+                example: "echo [1 2 3 1 2 3 1 1 1 1 3 2 1 1 3] | wrap | histogram Column",
+            },
+        ]
+    }
 }
 
 pub fn histogram(
diff --git a/crates/nu-cli/src/commands/keep.rs b/crates/nu-cli/src/commands/keep.rs
index 73e0cbc93..982320a0c 100644
--- a/crates/nu-cli/src/commands/keep.rs
+++ b/crates/nu-cli/src/commands/keep.rs
@@ -36,6 +36,19 @@ impl WholeStreamCommand for Keep {
     ) -> Result<OutputStream, ShellError> {
         args.process(registry, keep)?.run()
     }
+
+    fn examples(&self) -> &[Example] {
+        &[
+            Example {
+                description: "Keep the first row",
+                example: "ls | keep",
+            },
+            Example {
+                description: "Keep the first four rows",
+                example: "ls | keep 4",
+            },
+        ]
+    }
 }
 
 fn keep(KeepArgs { rows }: KeepArgs, context: RunnableContext) -> Result<OutputStream, ShellError> {
diff --git a/crates/nu-cli/src/commands/kill.rs b/crates/nu-cli/src/commands/kill.rs
index bb66dcbd2..6aab7e8ef 100644
--- a/crates/nu-cli/src/commands/kill.rs
+++ b/crates/nu-cli/src/commands/kill.rs
@@ -44,6 +44,19 @@ impl WholeStreamCommand for Kill {
     ) -> Result<OutputStream, ShellError> {
         args.process(registry, kill)?.run()
     }
+
+    fn examples(&self) -> &[Example] {
+        &[
+            Example {
+                description: "Kill the pid using the most memory",
+                example: "ps | sort-by mem | last | kill $it.pid",
+            },
+            Example {
+                description: "Force kill a given pid",
+                example: "kill --force 12345",
+            },
+        ]
+    }
 }
 
 fn kill(
diff --git a/crates/nu-cli/src/commands/last.rs b/crates/nu-cli/src/commands/last.rs
index dc7411606..e914f0293 100644
--- a/crates/nu-cli/src/commands/last.rs
+++ b/crates/nu-cli/src/commands/last.rs
@@ -36,6 +36,19 @@ impl WholeStreamCommand for Last {
     ) -> Result<OutputStream, ShellError> {
         args.process(registry, last)?.run()
     }
+
+    fn examples(&self) -> &[Example] {
+        &[
+            Example {
+                description: "Get the last row",
+                example: "ls | last",
+            },
+            Example {
+                description: "Get the last three rows",
+                example: "ls | last 3",
+            },
+        ]
+    }
 }
 
 fn last(LastArgs { rows }: LastArgs, context: RunnableContext) -> Result<OutputStream, ShellError> {
diff --git a/crates/nu-cli/src/commands/lines.rs b/crates/nu-cli/src/commands/lines.rs
index 955959fca..34aa74f6d 100644
--- a/crates/nu-cli/src/commands/lines.rs
+++ b/crates/nu-cli/src/commands/lines.rs
@@ -25,6 +25,13 @@ impl WholeStreamCommand for Lines {
     ) -> Result<OutputStream, ShellError> {
         lines(args, registry)
     }
+
+    fn examples(&self) -> &[Example] {
+        &[Example {
+            description: "Split output from an external command into lines",
+            example: "^ls -l | lines",
+        }]
+    }
 }
 
 fn ends_with_line_ending(st: &str) -> bool {
diff --git a/crates/nu-cli/src/commands/ls.rs b/crates/nu-cli/src/commands/ls.rs
index 7ad6c03d7..d167c0a49 100644
--- a/crates/nu-cli/src/commands/ls.rs
+++ b/crates/nu-cli/src/commands/ls.rs
@@ -66,6 +66,23 @@ impl WholeStreamCommand for Ls {
     ) -> Result<OutputStream, ShellError> {
         args.process(registry, ls)?.run()
     }
+
+    fn examples(&self) -> &[Example] {
+        &[
+            Example {
+                description: "List all files in the current directory",
+                example: "ls",
+            },
+            Example {
+                description: "List all files in a subdirectory",
+                example: "ls subdir",
+            },
+            Example {
+                description: "List all rust files",
+                example: "ls *.rs",
+            },
+        ]
+    }
 }
 
 fn ls(args: LsArgs, context: RunnableContext) -> Result<OutputStream, ShellError> {
diff --git a/crates/nu-cli/src/commands/merge.rs b/crates/nu-cli/src/commands/merge.rs
index 172cbdb41..bd3bdcf8c 100644
--- a/crates/nu-cli/src/commands/merge.rs
+++ b/crates/nu-cli/src/commands/merge.rs
@@ -38,6 +38,13 @@ impl WholeStreamCommand for Merge {
     ) -> Result<OutputStream, ShellError> {
         Ok(args.process_raw(registry, merge)?.run())
     }
+
+    fn examples(&self) -> &[Example] {
+        &[Example {
+            description: "Merge a 1-based index column with some ls output",
+            example: "ls | select name | keep 3 | merge { echo [1 2 3] | wrap index }",
+        }]
+    }
 }
 
 fn merge(
diff --git a/crates/nu-cli/src/commands/mkdir.rs b/crates/nu-cli/src/commands/mkdir.rs
index acf7bb61f..d967e7d51 100644
--- a/crates/nu-cli/src/commands/mkdir.rs
+++ b/crates/nu-cli/src/commands/mkdir.rs
@@ -33,6 +33,13 @@ impl WholeStreamCommand for Mkdir {
     ) -> Result<OutputStream, ShellError> {
         args.process(registry, mkdir)?.run()
     }
+
+    fn examples(&self) -> &[Example] {
+        &[Example {
+            description: "Make a directory named foo",
+            example: "mkdir foo",
+        }]
+    }
 }
 
 fn mkdir(args: MkdirArgs, context: RunnableContext) -> Result<OutputStream, ShellError> {
diff --git a/crates/nu-cli/src/commands/mv.rs b/crates/nu-cli/src/commands/mv.rs
index 238d45f2c..3b2452393 100644
--- a/crates/nu-cli/src/commands/mv.rs
+++ b/crates/nu-cli/src/commands/mv.rs
@@ -44,6 +44,23 @@ impl WholeStreamCommand for Move {
     ) -> Result<OutputStream, ShellError> {
         args.process(registry, mv)?.run()
     }
+
+    fn examples(&self) -> &[Example] {
+        &[
+            Example {
+                description: "Rename a file",
+                example: "mv before.txt after.txt",
+            },
+            Example {
+                description: "Move a file into a directory",
+                example: "mv test.txt my/subdirectory",
+            },
+            Example {
+                description: "Move many files into a directory",
+                example: "mv *.txt my/subdirectory",
+            },
+        ]
+    }
 }
 
 fn mv(args: MoveArgs, context: RunnableContext) -> Result<OutputStream, ShellError> {
diff --git a/crates/nu-cli/src/commands/nth.rs b/crates/nu-cli/src/commands/nth.rs
index 49040e2a5..e1be09c83 100644
--- a/crates/nu-cli/src/commands/nth.rs
+++ b/crates/nu-cli/src/commands/nth.rs
@@ -39,6 +39,19 @@ impl WholeStreamCommand for Nth {
     ) -> Result<OutputStream, ShellError> {
         args.process(registry, nth)?.run()
     }
+
+    fn examples(&self) -> &[Example] {
+        &[
+            Example {
+                description: "Get the second row",
+                example: "echo [first second third] | get 1",
+            },
+            Example {
+                description: "Get the first and third rows",
+                example: "echo [first second third] | get 0 2",
+            },
+        ]
+    }
 }
 
 fn nth(
diff --git a/crates/nu-cli/src/commands/parse.rs b/crates/nu-cli/src/commands/parse.rs
index 5eb4e9404..0a11c2ed5 100644
--- a/crates/nu-cli/src/commands/parse.rs
+++ b/crates/nu-cli/src/commands/parse.rs
@@ -111,6 +111,13 @@ impl WholeStreamCommand for Parse {
     ) -> Result<OutputStream, ShellError> {
         args.process(registry, parse_command)?.run()
     }
+
+    fn examples(&self) -> &[Example] {
+        &[Example {
+            description: "Parse values from a string into a table",
+            example: r#"echo "data: 123" | parse "{key}: {value}""#,
+        }]
+    }
 }
 
 fn parse_command(
diff --git a/crates/nu-cli/src/commands/pwd.rs b/crates/nu-cli/src/commands/pwd.rs
index 8e80c4e14..a8330aa2f 100644
--- a/crates/nu-cli/src/commands/pwd.rs
+++ b/crates/nu-cli/src/commands/pwd.rs
@@ -25,6 +25,13 @@ impl WholeStreamCommand for Pwd {
     ) -> Result<OutputStream, ShellError> {
         pwd(args, registry)
     }
+
+    fn examples(&self) -> &[Example] {
+        &[Example {
+            description: "Print the current working directory",
+            example: "pwd",
+        }]
+    }
 }
 
 pub fn pwd(args: CommandArgs, registry: &CommandRegistry) -> Result<OutputStream, ShellError> {
diff --git a/crates/nu-cli/src/commands/rename.rs b/crates/nu-cli/src/commands/rename.rs
index 8e879afc4..f2b8f717e 100644
--- a/crates/nu-cli/src/commands/rename.rs
+++ b/crates/nu-cli/src/commands/rename.rs
@@ -23,12 +23,9 @@ impl WholeStreamCommand for Rename {
             .required(
                 "column_name",
                 SyntaxShape::String,
-                "the name of the column to rename for",
-            )
-            .rest(
-                SyntaxShape::String,
-                "Additional column name(s) to rename for",
+                "the new name for the first column",
             )
+            .rest(SyntaxShape::String, "the new name for additional columns")
     }
 
     fn usage(&self) -> &str {
@@ -42,6 +39,19 @@ impl WholeStreamCommand for Rename {
     ) -> Result<OutputStream, ShellError> {
         args.process(registry, rename)?.run()
     }
+
+    fn examples(&self) -> &[Example] {
+        &[
+            Example {
+                description: "Rename a column",
+                example: "ls | rename my_name",
+            },
+            Example {
+                description: "Rename many columns",
+                example: "echo \"{a: 1, b: 2, c: 3}\" | from json | rename spam eggs cars",
+            },
+        ]
+    }
 }
 
 pub fn rename(
diff --git a/crates/nu-cli/src/commands/reverse.rs b/crates/nu-cli/src/commands/reverse.rs
index 7243752c2..c63594af0 100644
--- a/crates/nu-cli/src/commands/reverse.rs
+++ b/crates/nu-cli/src/commands/reverse.rs
@@ -26,6 +26,13 @@ impl WholeStreamCommand for Reverse {
     ) -> Result<OutputStream, ShellError> {
         reverse(args, registry)
     }
+
+    fn examples(&self) -> &[Example] {
+        &[Example {
+            description: "Sort files in descending file size",
+            example: "ls | sort-by size | reverse",
+        }]
+    }
 }
 
 fn reverse(args: CommandArgs, registry: &CommandRegistry) -> Result<OutputStream, ShellError> {
diff --git a/crates/nu-cli/src/commands/rm.rs b/crates/nu-cli/src/commands/rm.rs
index e9a0e8e03..7550ca21b 100644
--- a/crates/nu-cli/src/commands/rm.rs
+++ b/crates/nu-cli/src/commands/rm.rs
@@ -43,6 +43,19 @@ impl WholeStreamCommand for Remove {
     ) -> Result<OutputStream, ShellError> {
         args.process(registry, rm)?.run()
     }
+
+    fn examples(&self) -> &[Example] {
+        &[
+            Example {
+                description: "Delete a file",
+                example: "rm file.txt",
+            },
+            Example {
+                description: "Move a file to the system trash",
+                example: "rm --trash file.txt",
+            },
+        ]
+    }
 }
 
 fn rm(args: RemoveArgs, context: RunnableContext) -> Result<OutputStream, ShellError> {
diff --git a/crates/nu-cli/src/commands/select.rs b/crates/nu-cli/src/commands/select.rs
index 215ec977e..015927207 100644
--- a/crates/nu-cli/src/commands/select.rs
+++ b/crates/nu-cli/src/commands/select.rs
@@ -39,6 +39,19 @@ impl WholeStreamCommand for Select {
     ) -> Result<OutputStream, ShellError> {
         args.process(registry, select)?.run()
     }
+
+    fn examples(&self) -> &[Example] {
+        &[
+            Example {
+                description: "Select just the name column",
+                example: "ls | select name",
+            },
+            Example {
+                description: "Select the name and size columns",
+                example: "ls | select name size",
+            },
+        ]
+    }
 }
 
 fn select(
diff --git a/crates/nu-cli/src/commands/size.rs b/crates/nu-cli/src/commands/size.rs
index 6dc993bea..e2e873fe4 100644
--- a/crates/nu-cli/src/commands/size.rs
+++ b/crates/nu-cli/src/commands/size.rs
@@ -25,6 +25,13 @@ impl WholeStreamCommand for Size {
     ) -> Result<OutputStream, ShellError> {
         size(args, registry)
     }
+
+    fn examples(&self) -> &[Example] {
+        &[Example {
+            description: "Count the number of words in a string",
+            example: r#"echo "There are seven words in this sentence" | size"#,
+        }]
+    }
 }
 
 fn size(args: CommandArgs, _registry: &CommandRegistry) -> Result<OutputStream, ShellError> {
diff --git a/crates/nu-cli/src/commands/skip.rs b/crates/nu-cli/src/commands/skip.rs
index beebc0ed6..7dd9c08f3 100644
--- a/crates/nu-cli/src/commands/skip.rs
+++ b/crates/nu-cli/src/commands/skip.rs
@@ -32,6 +32,13 @@ impl WholeStreamCommand for Skip {
     ) -> Result<OutputStream, ShellError> {
         args.process(registry, skip)?.run()
     }
+
+    fn examples(&self) -> &[Example] {
+        &[Example {
+            description: "Skip the first 5 rows",
+            example: "ls | skip 5",
+        }]
+    }
 }
 
 fn skip(SkipArgs { rows }: SkipArgs, context: RunnableContext) -> Result<OutputStream, ShellError> {
diff --git a/crates/nu-cli/src/commands/sort_by.rs b/crates/nu-cli/src/commands/sort_by.rs
index 7f6c6a51a..06d83644e 100644
--- a/crates/nu-cli/src/commands/sort_by.rs
+++ b/crates/nu-cli/src/commands/sort_by.rs
@@ -22,7 +22,7 @@ impl WholeStreamCommand for SortBy {
     }
 
     fn usage(&self) -> &str {
-        "Sort by the given columns."
+        "Sort by the given columns, in increasing order."
     }
 
     fn run(
@@ -32,6 +32,19 @@ impl WholeStreamCommand for SortBy {
     ) -> Result<OutputStream, ShellError> {
         args.process(registry, sort_by)?.run()
     }
+
+    fn examples(&self) -> &[Example] {
+        &[
+            Example {
+                description: "Sort output by increasing file size",
+                example: "ls | sort-by size",
+            },
+            Example {
+                description: "Sort output by type, and then by file size for each type",
+                example: "ls | sort-by type size",
+            },
+        ]
+    }
 }
 
 fn sort_by(
diff --git a/crates/nu-cli/src/commands/sum.rs b/crates/nu-cli/src/commands/sum.rs
index 1331c03d1..74e3bbda7 100644
--- a/crates/nu-cli/src/commands/sum.rs
+++ b/crates/nu-cli/src/commands/sum.rs
@@ -34,6 +34,19 @@ impl WholeStreamCommand for Sum {
             name: args.call_info.name_tag,
         })
     }
+
+    fn examples(&self) -> &[Example] {
+        &[
+            Example {
+                description: "Sum a list of numbers",
+                example: "echo [1 2 3] | sum",
+            },
+            Example {
+                description: "Get the disk usage for the current directory",
+                example: "ls --all --du | get size | sum",
+            },
+        ]
+    }
 }
 
 fn sum(RunnableContext { mut input, .. }: RunnableContext) -> Result<OutputStream, ShellError> {
diff --git a/crates/nu-cli/src/commands/with_env.rs b/crates/nu-cli/src/commands/with_env.rs
index 20ada1448..98bd41e4d 100644
--- a/crates/nu-cli/src/commands/with_env.rs
+++ b/crates/nu-cli/src/commands/with_env.rs
@@ -42,6 +42,13 @@ impl WholeStreamCommand for WithEnv {
     ) -> Result<OutputStream, ShellError> {
         Ok(args.process_raw(registry, with_env)?.run())
     }
+
+    fn examples(&self) -> &[Example] {
+        &[Example {
+            description: "Set the MYENV environment variable",
+            example: r#"with-env [MYENV "my env value"] { echo $nu.env.MYENV }"#,
+        }]
+    }
 }
 
 fn with_env(
diff --git a/crates/nu-cli/src/commands/wrap.rs b/crates/nu-cli/src/commands/wrap.rs
index 652b96ceb..820f4ad12 100644
--- a/crates/nu-cli/src/commands/wrap.rs
+++ b/crates/nu-cli/src/commands/wrap.rs
@@ -37,6 +37,19 @@ impl WholeStreamCommand for Wrap {
     ) -> Result<OutputStream, ShellError> {
         args.process(registry, wrap)?.run()
     }
+
+    fn examples(&self) -> &[Example] {
+        &[
+            Example {
+                description: "Wrap a list into a table with the default column name",
+                example: "echo [1 2 3] | wrap",
+            },
+            Example {
+                description: "Wrap a list into a table with a given column name",
+                example: "echo [1 2 3] | wrap MyColumn",
+            },
+        ]
+    }
 }
 
 fn wrap(