Add examples for some more commands (#1765)

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

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 {

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(

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(

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

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(

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

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 {

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

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(

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

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

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(

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(

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

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",
+                "the new name for the first column",
-            )
-            .rest(
-                SyntaxShape::String,
-                "Additional column name(s) to rename for",
             )
+            .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(

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

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

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(

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

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

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(

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

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(

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(