Merge pull request #1015 from sebastian-xyz/doc

Add documentation for histogram, split-column

docs/commands/from-json.md

@@ -0,0 +1,33 @@
+# from-json
+
+Parse text as `.json` and create table. Use this when nushell cannot dertermine the input file extension.
+
+Syntax: `from-json {flags}`
+
+### Flags:
+
+    --objects
+      treat each line as a separate value
+
+
+## Examples
+
+```shell
+> open command_from-json
+[
+    {
+        title: "from-json",
+        type: "command",
+        flags: true
+    }
+]
+```
+
+```shell
+> open command_from-json | from-json
+━━━━━━━━━━━┯━━━━━━━━━┯━━━━━━━
+ title     │ type    │ flags 
+───────────┼─────────┼───────
+ from-json │ command │ Yes 
+━━━━━━━━━━━┷━━━━━━━━━┷━━━━━━━
+```

docs/commands/from-yaml.md

@@ -0,0 +1,24 @@
+# from-yaml
+
+Parse text as `.yaml/.yml` and create table.
+
+Syntax: `from-yaml`
+
+## Examples
+
+```shell
+> open command_from-yaml
+title: from-yaml
+type: command
+flags: false
+```
+
+```shell
+> open command_from-yaml | from-yaml
+━━━━━━━━━━━┯━━━━━━━━━┯━━━━━━━
+ title     │ type    │ flags 
+───────────┼─────────┼───────
+ from-yaml │ command │ No 
+━━━━━━━━━━━┷━━━━━━━━━┷━━━━━━━
+
+```

docs/commands/histogram.md

@@ -0,0 +1,80 @@
+# histogram
+
+Creates a new table with a histogram based on the column name passed in.
+
+Syntax: `histogram <column_name>  ...args`
+
+### Parameters
+
+* `<column-name>`: name of the column to graph by
+* `args`: column name to give the histogram's frequency column
+
+## Examples
+
+Let's say we have this file `random_numers.csv` which contains 50 random numbers.
+
+**Note**: The input doesn't have to be numbers it works on strings too. Try it out.
+
+```shell
+> open random_numbers.csv
+open random_numbers2.csv
+━━━━┯━━━━━━━━━━━━━━━━
+ #  │ random numbers 
+────┼────────────────
+  0 │ 0 
+  1 │ 5 
+  2 │ 5 
+   ...
+ 47 │ 0 
+ 48 │ 2 
+ 49 │ 4 
+━━━━┷━━━━━━━━━━━━━━━━
+```
+
+If we now want to see how often the different numbers were generated, we can use the `histogram` function:
+
+```shell
+> open random_numbers2.csv | histogram "random numbers"
+━━━┯━━━━━━━━━━━━━━━━┯━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ # │ random numbers │ frequency 
+───┼────────────────┼──────────────────────────────────────────────────────────────────────────────────────────────────────
+ 0 │ 0              │ **************************************************************************************************** 
+ 1 │ 1              │ ****************************** 
+ 2 │ 2              │ ************************************************************* 
+ 3 │ 3              │ ********************************************************************* 
+ 4 │ 4              │ ***************************************************** 
+ 5 │ 5              │ ********************************************************************* 
+━━━┷━━━━━━━━━━━━━━━━┷━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+We can also set the name of the second column or sort the table: 
+
+```shell
+> open random_numbers2.csv | histogram "random numbers" probability
+━━━┯━━━━━━━━━━━━━━━━┯━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ # │ random numbers │ probability 
+───┼────────────────┼──────────────────────────────────────────────────────────────────────────────────────────────────────
+ 0 │ 0              │ **************************************************************************************************** 
+ 1 │ 1              │ ****************************** 
+ 2 │ 2              │ ************************************************************* 
+ 3 │ 3              │ ********************************************************************* 
+ 4 │ 4              │ ***************************************************** 
+ 5 │ 5              │ ********************************************************************* 
+━━━┷━━━━━━━━━━━━━━━━┷━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+```
+
+```shell
+> open random_numbers2.csv | histogram "random numbers" probability | sort-by probability
+━━━┯━━━━━━━━━━━━━━━━┯━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ # │ random numbers │ probability 
+───┼────────────────┼──────────────────────────────────────────────────────────────────────────────────────────────────────
+ 0 │ 1              │ ****************************** 
+ 1 │ 4              │ ***************************************************** 
+ 2 │ 2              │ ************************************************************* 
+ 3 │ 3              │ ********************************************************************* 
+ 4 │ 5              │ ********************************************************************* 
+ 5 │ 0              │ **************************************************************************************************** 
+━━━┷━━━━━━━━━━━━━━━━┷━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+```

docs/commands/history.md

@@ -0,0 +1,17 @@
+# history
+
+Displays the last 100 commands.
+
+## Example
+
+```shell
+> history
+━━━━┯━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ #  │ <value> 
+────┼───────────────────────────────────────────────────────────────────────────
+   ...
+ 97 │ ls 
+ 98 │ ls | where accessed < 1d 
+ 99 │ cd 
+━━━━┷━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```

docs/commands/nth.md

@@ -3,10 +3,13 @@
 This command returns the nth row of a table, starting from 0.  
 If the number given is less than 0 or more than the number of rows, nothing is returned.
 
-## Usage
+### Usage
 ```shell
-> [input-command] | nth [row-number]
+> [input-command] | nth <row number>  ...args
 ```
+### Parameters:
+* `<row number>` the number of the row to return
+* `args`: Optionally return more rows
 
 ## Examples
 ```shell
@@ -21,11 +24,19 @@ If the number given is less than 0 or more than the number of rows, nothing is r
 ━━━┷━━━━━━━━━━━━┷━━━━━━━━━━━┷━━━━━━━━━━┷━━━━━━━━┷━━━━━━━━━━━━━━━┷━━━━━━━━━━━━━━━
 
 > ls | nth 0
-━━━━━━━━━━━━┯━━━━━━┯━━━━━━━━━━┯━━━━━━━━┯━━━━━━━━━━━━━━━┯━━━━━━━━━━━━━━━
- name       │ type │ readonly │ size   │ accessed      │ modified 
-────────────┼──────┼──────────┼────────┼───────────────┼───────────────
- Cargo.toml │ File │          │ 239 B  │ 2 minutes ago │ 2 minutes ago 
-━━━━━━━━━━━━┷━━━━━━┷━━━━━━━━━━┷━━━━━━━━┷━━━━━━━━━━━━━━━┷━━━━━━━━━━━━━━━
+━━━┯━━━━━━━━━━━━┯━━━━━━━━━━━┯━━━━━━━━━━┯━━━━━━━━┯━━━━━━━━━━━━━━━┯━━━━━━━━━━━━━━━
+ # │ name       │ type      │ readonly │ size   │ accessed      │ modified 
+───┼────────────┼───────────┼──────────┼────────┼───────────────┼───────────────
+ 0 │ Cargo.toml │ File      │          │ 239 B  │ 2 minutes ago │ 2 minutes ago 
+━━━┷━━━━━━━━━━━━┷━━━━━━━━━━━┷━━━━━━━━━━┷━━━━━━━━┷━━━━━━━━━━━━━━━┷━━━━━━━━━━━━━━━
+
+> ls | nth 0 2
+━━━┯━━━━━━━━━━━━┯━━━━━━━━━━━┯━━━━━━━━━━┯━━━━━━━━┯━━━━━━━━━━━━━━━┯━━━━━━━━━━━━━━━
+ # │ name       │ type      │ readonly │ size   │ accessed      │ modified 
+───┼────────────┼───────────┼──────────┼────────┼───────────────┼───────────────
+ 0 │ Cargo.toml │ File      │          │ 239 B  │ 2 minutes ago │ 2 minutes ago 
+ 2 │ .gitignore │ File      │          │  19 B  │ 2 minutes ago │ 2 minutes ago 
+━━━┷━━━━━━━━━━━━┷━━━━━━━━━━━┷━━━━━━━━━━┷━━━━━━━━┷━━━━━━━━━━━━━━━┷━━━━━━━━━━━━━━━
 
 > ls | nth 5
 ```

docs/commands/sort-by.md

@@ -1,5 +1,5 @@
 
-# env
+# sort-by
 
 The `sort-by` command sorts the table being displayed in the terminal by a chosen column(s). 
 

docs/commands/split-column.md

@@ -0,0 +1,72 @@
+# split-column
+
+Split row contents across multiple columns via the separator.
+
+Syntax: `split-column <separator>  ...args{flags}`
+
+### Parameters
+
+* `<seperator>`: string that denotes what separates columns
+* `args`: column names to give the new columns. If not specified they will be set to `Column1` `Column2` ...
+
+### Flags
+
+    --collapse-empty
+      Removes empty columns
+
+## Examples
+
+If we have file structured like this:
+
+```shell
+0.12643678160919541 | 0.6851851851851852 | 0.273972602739726
+0.28735632183908044 | 0.09259259259259259 | 0.6986301369863014
+0.8045977011494253 | 0.8148148148148148 | 0.7397260273972602
+0.28735632183908044 | 0.09259259259259259 | 0.547945205479452
+0.6896551724137931 | 0.7037037037037037 | 1.2465753424657535
+0.6896551724137931 | 0.8333333333333334 | 0.4657534246575342
+0.9080459770114943 | 1.3333333333333333 | 0.4931506849315068
+0.9310344827586207 | 1.1296296296296295 | 0.7123287671232876
+0.3448275862068966 | 0.018518518518518517 | 0.6575342465753424
+1.0459770114942528 | 1.0925925925925926 | 0.6164383561643836
+```
+
+We can build a table from it using the `split-column` command
+
+```shell
+> open coordinates.txt | lines | split-column " | "
+━━━┯━━━━━━━━━━━━━━━━━━━━━┯━━━━━━━━━━━━━━━━━━━━━━┯━━━━━━━━━━━━━━━━━━━━
+ # │ Column1             │ Column2              │ Column3 
+───┼─────────────────────┼──────────────────────┼────────────────────
+ 0 │ 0.12643678160919541 │ 0.6851851851851852   │ 0.273972602739726 
+ 1 │ 0.28735632183908044 │ 0.09259259259259259  │ 0.6986301369863014 
+ 2 │ 0.8045977011494253  │ 0.8148148148148148   │ 0.7397260273972602 
+ 3 │ 0.28735632183908044 │ 0.09259259259259259  │ 0.547945205479452 
+ 4 │ 0.6896551724137931  │ 0.7037037037037037   │ 1.2465753424657535 
+ 5 │ 0.6896551724137931  │ 0.8333333333333334   │ 0.4657534246575342 
+ 6 │ 0.9080459770114943  │ 1.3333333333333333   │ 0.4931506849315068 
+ 7 │ 0.9310344827586207  │ 1.1296296296296295   │ 0.7123287671232876 
+ 8 │ 0.3448275862068966  │ 0.018518518518518517 │ 0.6575342465753424 
+ 9 │ 1.0459770114942528  │ 1.0925925925925926   │ 0.6164383561643836 
+━━━┷━━━━━━━━━━━━━━━━━━━━━┷━━━━━━━━━━━━━━━━━━━━━━┷━━━━━━━━━━━━━━━━━━━━
+```
+
+And give names to the columns
+
+```shell
+> open coordinates.txt | lines | split-column " | " x y z
+━━━┯━━━━━━━━━━━━━━━━━━━━━┯━━━━━━━━━━━━━━━━━━━━━━┯━━━━━━━━━━━━━━━━━━━━
+ # │ x                   │ y                    │ z 
+───┼─────────────────────┼──────────────────────┼────────────────────
+ 0 │ 0.12643678160919541 │ 0.6851851851851852   │ 0.273972602739726 
+ 1 │ 0.28735632183908044 │ 0.09259259259259259  │ 0.6986301369863014 
+ 2 │ 0.8045977011494253  │ 0.8148148148148148   │ 0.7397260273972602 
+ 3 │ 0.28735632183908044 │ 0.09259259259259259  │ 0.547945205479452 
+ 4 │ 0.6896551724137931  │ 0.7037037037037037   │ 1.2465753424657535 
+ 5 │ 0.6896551724137931  │ 0.8333333333333334   │ 0.4657534246575342 
+ 6 │ 0.9080459770114943  │ 1.3333333333333333   │ 0.4931506849315068 
+ 7 │ 0.9310344827586207  │ 1.1296296296296295   │ 0.7123287671232876 
+ 8 │ 0.3448275862068966  │ 0.018518518518518517 │ 0.6575342465753424 
+ 9 │ 1.0459770114942528  │ 1.0925925925925926   │ 0.6164383561643836 
+━━━┷━━━━━━━━━━━━━━━━━━━━━┷━━━━━━━━━━━━━━━━━━━━━━┷━━━━━━━━━━━━━━━━━━━━
+```

docs/commands/split-row.md

@@ -0,0 +1,34 @@
+# split-row
+
+Split row contents over multiple rows via the separator.
+
+Syntax: `split-row <separator>`
+
+### Parameters:
+* `<separator>` the character that denotes what separates rows
+
+## Examples
+
+We can build a table from a file that looks like this
+
+```shell
+> open table.txt
+4, 0, 2, 0, 7, 8
+
+```
+
+using the `split-row` command.
+
+```shell
+open table.txt | split-row ", "
+━━━┯━━━━━━━━━
+ # │ <value> 
+───┼─────────
+ 0 │ 4 
+ 1 │ 0 
+ 2 │ 2 
+ 3 │ 0 
+ 4 │ 7 
+ 5 │ 8 
+━━━┷━━━━━━━━━
+```