Update #4455, Regenerate all commands' docs (#4557)

docs/commands/alias.md

@@ -15,3 +15,10 @@ Alias a command (with optional flags) to a new name
  -  `name`: name of the alias
  -  `initial_value`: equals sign followed by value
 
+## Examples
+
+Alias ll to ls -l
+```shell
+> alias ll = ls -l
+```
+

docs/commands/benchmark.md

@@ -14,3 +14,10 @@ Time the running time of a block
 
  -  `block`: the block to run
 
+## Examples
+
+Benchmarks a command within a block
+```shell
+> benchmark { sleep 500ms }
+```
+

docs/commands/cd.md

@@ -14,3 +14,10 @@ Change directory.
 
  -  `path`: the path to change to
 
+## Examples
+
+Change to your home directory
+```shell
+> cd ~
+```
+

docs/commands/cp.md

@@ -16,3 +16,15 @@ Copy files.
  -  `destination`: the place to copy to
  -  `--recursive`: copy recursively through subdirectories
 
+## Examples
+
+Copy myfile to dir_b
+```shell
+> cp myfile dir_b
+```
+
+Recursively copy dir_a to dir_b
+```shell
+> cp -r dir_a dir_b
+```
+

docs/commands/date_format.md

@@ -4,29 +4,35 @@ layout: command
 version: 0.59.0
 ---
 
-Format a given date using the given format string.
+Format a given date using a format string.
 
 ## Signature
 
-```> date format (format string)```
+```> date format (format string) --list```
 
 ## Parameters
 
  -  `format string`: the desired date format
+ -  `--list`: lists strftime cheatsheet
 
 ## Examples
 
-Format a given date using the given format string.
+Format a given date using the default format (RFC 2822).
+```shell
+> "2021-10-22 20:00:12 +01:00" | date format
+```
+
+Format a given date using a given format string.
 ```shell
 > date format '%Y-%m-%d'
 ```
 
-Format a given date using the given format string.
+Format a given date using a given format string.
 ```shell
 > date format "%Y-%m-%d %H:%M:%S"
 ```
 
-Format a given date using the given format string.
+Format a given date using a given format string.
 ```shell
 > "2021-10-22 20:00:12 +01:00" | date format "%Y-%m-%d"
 ```

docs/commands/date_list-timezone.md

@@ -10,3 +10,10 @@ List supported time zones.
 
 ```> date list-timezone ```
 
+## Examples
+
+Show timezone(s) that contains 'Shanghai'
+```shell
+> date list-timezone | where timezone =~ Shanghai
+```
+

docs/commands/date_now.md

@@ -10,3 +10,10 @@ Get the current date.
 
 ```> date now ```
 
+## Examples
+
+Get the current date and display it in a given format string.
+```shell
+> date now | date format "%Y-%m-%d %H:%M:%S"
+```
+

docs/commands/def.md

@@ -16,3 +16,15 @@ Define a custom command
  -  `params`: parameters
  -  `block`: body of the definition
 
+## Examples
+
+Define a command and run it
+```shell
+> def say-hi [] { echo 'hi' }; say-hi
+```
+
+Define a command and run it with parameter(s)
+```shell
+> def say-sth [sth: string] { echo $sth }; say-sth hi
+```
+

docs/commands/detect_columns.md

@@ -8,10 +8,22 @@ splits contents across multiple columns via the separator.
 
 ## Signature
 
-```> detect columns --skip --no_headers```
+```> detect columns --skip --no-headers```
 
 ## Parameters
 
  -  `--skip {int}`: number of rows to skip before detecting
- -  `--no_headers`: don't detect headers
+ -  `--no-headers`: don't detect headers
+
+## Examples
+
+Splits string across multiple columns
+```shell
+> echo 'a b c' | detect columns -n
+```
+
+Splits a multi-line string into columns with headers detected
+```shell
+> echo $'c1 c2 c3(char nl)a b c' | detect columns
+```
 

docs/commands/dfr_aggregate.md

@@ -8,11 +8,11 @@ Performs an aggregation operation on a dataframe and groupby object
 
 ## Signature
 
-```> dfr aggregate (operation-name) --quantile --explicit```
+```> dfr aggregate (operation_name) --quantile --explicit```
 
 ## Parameters
 
- -  `operation-name`: 
+ -  `operation_name`: 
 	Dataframes: mean, sum, min, max, quantile, median, var, std
 	GroupBy: mean, sum, min, max, first, last, nunique, quantile, median, var, std, count
  -  `--quantile {number}`: quantile value for quantile operation

docs/commands/dfr_drop-duplicates.md

@@ -0,0 +1,24 @@
+---
+title: dfr drop-duplicates
+layout: command
+version: 0.59.0
+---
+
+Drops duplicate values in dataframe
+
+## Signature
+
+```> dfr drop-duplicates (subset) --maintain```
+
+## Parameters
+
+ -  `subset`: subset of columns to drop duplicates
+ -  `--maintain`: maintain order
+
+## Examples
+
+drop duplicates
+```shell
+> [[a b]; [1 2] [3 4] [1 2]] | dfr to-df | dfr drop-duplicates
+```
+

docs/commands/dfr_pivot.md

@@ -8,12 +8,12 @@ Performs a pivot operation on a groupby object
 
 ## Signature
 
-```> dfr pivot (pivot-column) (value-column) (operation)```
+```> dfr pivot (pivot_column) (value_column) (operation)```
 
 ## Parameters
 
- -  `pivot-column`: pivot column to perform pivot
- -  `value-column`: value column to perform pivot
+ -  `pivot_column`: pivot column to perform pivot
+ -  `value_column`: value column to perform pivot
  -  `operation`: aggregate operation
 
 ## Examples

docs/commands/do.md

@@ -16,3 +16,15 @@ Run a block
  -  `...rest`: the parameter(s) for the block
  -  `--ignore-errors`: ignore errors as the block runs
 
+## Examples
+
+Run the block
+```shell
+> do { echo hello }
+```
+
+Run the block and ignore errors
+```shell
+> do -i { thisisnotarealcommand }
+```
+

docs/commands/drop_column.md

@@ -14,3 +14,10 @@ Remove the last number of columns. If you want to remove columns by name, try 'r
 
  -  `columns`: starting from the end, the number of columns to remove
 
+## Examples
+
+Remove the last column of a table
+```shell
+> echo [[lib, extension]; [nu-lib, rs] [nu-core, rb]] | drop column
+```
+

docs/commands/each_group.md

@@ -19,6 +19,6 @@ Runs a block on groups of `group_size` rows of a table at a time.
 
 Echo the sum of each pair
 ```shell
-> echo [1 2 3 4] | each group 2 { $it.0 + $it.1 }
+> echo [1 2 3 4] | each group 2 { |it| $it.0 + $it.1 }
 ```
 

docs/commands/each_window.md

@@ -20,7 +20,7 @@ Runs a block on window groups of `window_size` that slide by n rows.
 
 A sliding window of two elements
 ```shell
-> echo [1 2 3 4] | each window 2 { $it.0 + $it.1 }
+> echo [1 2 3 4] | each window 2 { |it| $it.0 + $it.1 }
 ```
 
 A sliding window of two elements, with a stride of 3

docs/commands/empty.md

@@ -29,6 +29,6 @@ more than one column
 
 use a block if setting the empty cell contents is wanted
 ```shell
-> [[2020/04/16 2020/07/10 2020/11/16]; ['' [27] [37]]] | empty? 2020/04/16 -b { [33 37] }
+> [[2020/04/16 2020/07/10 2020/11/16]; ['' [27] [37]]] | empty? 2020/04/16 -b { |_| [33 37] }
 ```
 

docs/commands/env.md

@@ -10,3 +10,20 @@ Display current environment variables
 
 ```> env ```
 
+## Examples
+
+Display current path environment variable
+```shell
+> env | where name == PATH
+```
+
+Check whether the env variable `MY_ENV_ABC` exists
+```shell
+> env | any? name == MY_ENV_ABC
+```
+
+Another way to check whether the env variable `PATH` exists
+```shell
+> 'PATH' in (env).name
+```
+

docs/commands/error_make.md

@@ -8,11 +8,11 @@ Create an error.
 
 ## Signature
 
-```> error make (error-struct)```
+```> error make (error_struct)```
 
 ## Parameters
 
- -  `error-struct`: the error to create
+ -  `error_struct`: the error to create
 
 ## Examples
 

docs/commands/exit.md

@@ -8,10 +8,22 @@ Runs a script file in the current context.
 
 ## Signature
 
-```> exit (exit-code) --now```
+```> exit (exit_code) --now```
 
 ## Parameters
 
- -  `exit-code`: Exit code to return immediately with
+ -  `exit_code`: Exit code to return immediately with
  -  `--now`: Exit out of the shell immediately
 
+## Examples
+
+Exit the current shell
+```shell
+> exit
+```
+
+Exit all shells (exiting Nu)
+```shell
+> exit --now
+```
+

docs/commands/find.md

@@ -39,11 +39,11 @@ Search a char in a list of string
 
 Find the first odd value
 ```shell
-> echo [2 4 3 6 5 8] | find --predicate { ($it mod 2) == 1 }
+> echo [2 4 3 6 5 8] | find --predicate { |it| ($it mod 2) == 1 }
 ```
 
 Find if a service is not running
 ```shell
-> echo [[version patch]; [0.1.0 $false] [0.1.1 $true] [0.2.0 $false]] | find -p { $it.patch }
+> echo [[version patch]; [0.1.0 $false] [0.1.1 $true] [0.2.0 $false]] | find -p { |it| $it.patch }
 ```
 

docs/commands/g.md

@@ -8,9 +8,9 @@ Switch to a given shell.
 
 ## Signature
 
-```> g (shell-number)```
+```> g (shell_number)```
 
 ## Parameters
 
- -  `shell-number`: shell number to change to
+ -  `shell_number`: shell number to change to
 

docs/commands/hash_base64.md

@@ -8,12 +8,12 @@ base64 encode or decode a value
 
 ## Signature
 
-```> hash base64 ...rest --character_set --encode --decode```
+```> hash base64 ...rest --character-set --encode --decode```
 
 ## Parameters
 
  -  `...rest`: optionally base64 encode / decode data by column paths
- -  `--character_set {string}`: specify the character rules for encoding the input.
+ -  `--character-set {string}`: specify the character rules for encoding the input.
 	Valid values are 'standard', 'standard-no-padding', 'url-safe', 'url-safe-no-padding','binhex', 'bcrypt', 'crypt'
  -  `--encode`: encode the input as base64. This is the default behavior if not specified.
  -  `--decode`: decode the input from base64

docs/commands/length.md

@@ -14,3 +14,15 @@ Count the number of elements in the input.
 
  -  `--column`: Show the number of columns in a table
 
+## Examples
+
+Count the number of entries in a list
+```shell
+> echo [1 2 3 4 5] | length
+```
+
+Count the number of columns in the calendar table
+```shell
+> cal | length -c
+```
+

docs/commands/let-env.md

@@ -15,3 +15,10 @@ Create an environment variable and give it a value.
  -  `var_name`: variable name
  -  `initial_value`: equals sign followed by value
 
+## Examples
+
+Create an environment variable and display it
+```shell
+> let-env MY_ENV_VAR = 1; $env.MY_ENV_VAR
+```
+

docs/commands/let.md

@@ -27,3 +27,8 @@ Set a variable to the result of an expression
 > let x = 10 + 100
 ```
 
+Set a variable based on the condition
+```shell
+> let x = if $false { -1 } else { 1 }
+```
+

docs/commands/lines.md

@@ -14,3 +14,10 @@ Converts input to lines
 
  -  `--skip-empty`: skip empty lines
 
+## Examples
+
+Split multi-line string into lines
+```shell
+> echo $'two(char nl)lines' | lines
+```
+

docs/commands/ls.md

@@ -19,3 +19,20 @@ List the files in a directory.
  -  `--full-paths`: display paths as absolute paths
  -  `--du`: Display the apparent directory size in place of the directory metadata size
 
+## Examples
+
+List all files in the current directory
+```shell
+> ls
+```
+
+List all files in a subdirectory
+```shell
+> ls subdir
+```
+
+List all rust files
+```shell
+> ls *.rs
+```
+

docs/commands/mkdir.md

@@ -15,3 +15,15 @@ Make directories, creates intermediary directories as required.
  -  `...rest`: the name(s) of the path(s) to create
  -  `--show-created-paths`: show the path(s) created.
 
+## Examples
+
+Make a directory named foo
+```shell
+> mkdir foo
+```
+
+Make multiple directories and show the paths created
+```shell
+> mkdir -s foo/bar foo2
+```
+

docs/commands/mv.md

@@ -15,3 +15,20 @@ Move files or directories.
  -  `source`: the location to move files/directories from
  -  `destination`: the location to move files/directories to
 
+## Examples
+
+Rename a file
+```shell
+> mv before.txt after.txt
+```
+
+Move a file into a directory
+```shell
+> mv test.txt my/subdirectory
+```
+
+Move many files into a directory
+```shell
+> mv *.txt my/subdirectory
+```
+

docs/commands/post.md

@@ -1,20 +1,35 @@
-# post
-Post content to a URL and retrieve data as a table if possible.
+---
+title: post
+layout: command
+version: 0.59.0
+---
 
-## Usage
-```shell
-> post <path> <body> {flags} 
- ```
+Post a body to a URL (HTTP POST operation).
+
+## Signature
+
+```> post (path) (body) --user --password --content-type --content-length --raw --insecure```
 
 ## Parameters
-* `<path>` the URL to post to
-* `<body>` the contents of the post body
 
-## Flags
-* -h, --help: Display this help message
-* -u, --user <any>: the username when authenticating
-* -p, --password <any>: the password when authenticating
-* -t, --content-type <any>: the MIME type of content to post
-* -l, --content-length <any>: the length of the content being posted
-* -r, --raw: return values as a string instead of a table
+ -  `path`: the URL to post to
+ -  `body`: the contents of the post body
+ -  `--user {any}`: the username when authenticating
+ -  `--password {any}`: the password when authenticating
+ -  `--content-type {any}`: the MIME type of content to post
+ -  `--content-length {any}`: the length of the content being posted
+ -  `--raw`: return values as a string instead of a table
+ -  `--insecure`: allow insecure server connections when using SSL
+
+## Examples
+
+Post content to url.com
+```shell
+> post url.com 'body'
+```
+
+Post content to url.com, with username and password
+```shell
+> post -u myuser -p mypass url.com 'body'
+```
 

docs/commands/print.md

@@ -0,0 +1,28 @@
+---
+title: print
+layout: command
+version: 0.59.0
+---
+
+Prints the values given
+
+## Signature
+
+```> print ...rest```
+
+## Parameters
+
+ -  `...rest`: the values to print
+
+## Examples
+
+Print 'hello world'
+```shell
+> print "hello world"
+```
+
+Print the sum of 2 and 3
+```shell
+> print (2 + 3)
+```
+

docs/commands/reduce.md

@@ -20,26 +20,26 @@ Aggregate a list table to a single value using an accumulator block.
 
 Sum values of a list (same as 'math sum')
 ```shell
-> [ 1 2 3 4 ] | reduce { $it.acc + $it.item }
+> [ 1 2 3 4 ] | reduce {|it, acc| $it + $acc }
 ```
 
 Sum values with a starting value (fold)
 ```shell
-> [ 1 2 3 4 ] | reduce -f 10 { $it.acc + $it.item }
+> [ 1 2 3 4 ] | reduce -f 10 {|it, acc| $acc + $it }
 ```
 
 Replace selected characters in a string with 'X'
 ```shell
-> [ i o t ] | reduce -f "Arthur, King of the Britons" { $it.acc | str find-replace -a $it.item "X" }
+> [ i o t ] | reduce -f "Arthur, King of the Britons" {|it, acc| $acc | str find-replace -a $it "X" }
 ```
 
 Find the longest string and its index
 ```shell
-> [ one longest three bar ] | reduce -n {
-        if ($it.item | str length) > ($it.acc | str length) {
+> [ one longest three bar ] | reduce -n { |it, acc|
+        if ($it.item | str length) > ($acc | str length) {
             $it.item
         } else {
-            $it.acc
+            $acc
         }
     }
 ```

docs/commands/reject.md

@@ -14,3 +14,15 @@ Remove the given columns from the table. If you want to remove rows, try 'drop'.
 
  -  `...rest`: the names of columns to remove from the table
 
+## Examples
+
+Lists the files in a directory without showing the modified column
+```shell
+> ls | reject modified
+```
+
+Reject the specified field in a record
+```shell
+> echo {a: 1, b: 2} | reject a
+```
+

docs/commands/rm.md

@@ -19,3 +19,25 @@ Remove file(s).
  -  `--force`: suppress error when no file
  -  `--quiet`: supress output showing files deleted
 
+## Examples
+
+Delete or move a file to the system trash (depending on 'rm_always_trash' config option)
+```shell
+> rm file.txt
+```
+
+Move a file to the system trash
+```shell
+> rm --trash file.txt
+```
+
+Delete a file permanently
+```shell
+> rm --permanent file.txt
+```
+
+Delete a file, and suppress errors if no file is found
+```shell
+> rm --force file.txt
+```
+

docs/commands/run-external.md

@@ -0,0 +1,17 @@
+---
+title: run-external
+layout: command
+version: 0.59.0
+---
+
+Runs external command
+
+## Signature
+
+```> run-external ...rest --last-expression```
+
+## Parameters
+
+ -  `...rest`: external command to run
+ -  `--last-expression`: last-expression
+

docs/commands/split_column.md

@@ -16,3 +16,15 @@ splits contents across multiple columns via the separator.
  -  `...rest`: column names to give the new columns
  -  `--collapse-empty`: remove empty columns
 
+## Examples
+
+Split a string into columns by the specified separator
+```shell
+> echo 'a--b--c' | split column '--'
+```
+
+Split a string into columns of char and remove the empty columns
+```shell
+> echo 'abc' | split column -c ''
+```
+

docs/commands/split_row.md

@@ -14,3 +14,15 @@ splits contents over multiple rows via the separator.
 
  -  `separator`: the character that denotes what separates rows
 
+## Examples
+
+Split a string into rows of char
+```shell
+> echo 'abc' | split row ''
+```
+
+Split a string into rows by the specified separator
+```shell
+> echo 'a--b--c' | split row '--'
+```
+

docs/commands/str_to-datetime.md

@@ -0,0 +1,12 @@
+---
+title: str to-datetime
+layout: command
+version: 0.59.0
+---
+
+Deprecated command
+
+## Signature
+
+```> str to-datetime ```
+

docs/commands/sys.md

@@ -17,3 +17,13 @@ Show info about the system
 > sys
 ```
 
+Show the os system name with get
+```shell
+> (sys).host | get name
+```
+
+Show the os system name
+```shell
+> (sys).host.name
+```
+

docs/commands/table.md

@@ -8,9 +8,9 @@ Render the table.
 
 ## Signature
 
-```> table --start_number```
+```> table --start-number```
 
 ## Parameters
 
- -  `--start_number {int}`: row number to start viewing from
+ -  `--start-number {int}`: row number to start viewing from
 

docs/commands/to_html.md

@@ -8,12 +8,12 @@ Convert table into simple HTML
 
 ## Signature
 
-```> to html --html_color --no_color --dark --partial --theme --list```
+```> to html --html-color --no-color --dark --partial --theme --list```
 
 ## Parameters
 
- -  `--html_color`: change ansi colors to html colors
- -  `--no_color`: remove all ansi colors in output
+ -  `--html-color`: change ansi colors to html colors
+ -  `--no-color`: remove all ansi colors in output
  -  `--dark`: indicate your background color is a darker color
  -  `--partial`: only output the html for the content itself
  -  `--theme {string}`: the name of the theme to use (github, blulocolight, ...)

docs/commands/touch.md

@@ -15,3 +15,15 @@ Creates one or more files.
  -  `filename`: the path of the file you want to create
  -  `...rest`: additional files to create
 
+## Examples
+
+Creates "fixture.json"
+```shell
+> touch fixture.json
+```
+
+Creates files a, b and c
+```shell
+> touch a b c
+```
+

docs/commands/transpose.md

@@ -16,3 +16,20 @@ Transposes the table contents so rows become columns and columns become rows.
  -  `--header-row`: treat the first row as column names
  -  `--ignore-titles`: don't transpose the column names into values
 
+## Examples
+
+Transposes the table contents with default column names
+```shell
+> echo [[c1 c2]; [1 2]] | transpose
+```
+
+Transposes the table contents with specified column names
+```shell
+> echo [[c1 c2]; [1 2]] | transpose key val
+```
+
+Transposes the table without column names and specify a new column name
+```shell
+> echo [[c1 c2]; [1 2]] | transpose -i val
+```
+

docs/commands/update.md

@@ -22,6 +22,11 @@ Update a column value
 > echo {'name': 'nu', 'stars': 5} | update name 'Nushell'
 ```
 
+Use in block form for more involved updating logic
+```shell
+> echo [[count fruit]; [1 'apple']] | update count {|f| $f.count + 1}
+```
+
 Use in block form for more involved updating logic
 ```shell
 > echo [[project, authors]; ['nu', ['Andrés', 'JT', 'Yehuda']]] | update authors { get authors | str collect ',' }

docs/commands/where.md

@@ -14,3 +14,25 @@ Filter values based on a condition.
 
  -  `cond`: condition
 
+## Examples
+
+List all files in the current directory with sizes greater than 2kb
+```shell
+> ls | where size > 2kb
+```
+
+List only the files in the current directory
+```shell
+> ls | where type == file
+```
+
+List all files with names that contain "Car"
+```shell
+> ls | where name =~ "Car"
+```
+
+List all files that were modified in the last two weeks
+```shell
+> ls | where modified <= 2wk
+```
+

docs/commands/with-env.md

@@ -34,6 +34,6 @@ Set by single row table
 
 Set by row(e.g. `open x.json` or `from json`)
 ```shell
-> echo '{"X":"Y","W":"Z"}'|from json|with-env $it { echo $env.X $env.W }
+> echo '{"X":"Y","W":"Z"}'|from json|with-env $in { echo $env.X $env.W }
 ```
 

docs/commands/wrap.md

@@ -14,3 +14,10 @@ Wrap the value into a column.
 
  -  `name`: the name of the column
 
+## Examples
+
+Wrap a list into a table with a given column name
+```shell
+> echo [1 2 3] | wrap num
+```
+