Merge pull request #1032 from sebastian-xyz/doc

add documentation for save, config, get, ps, from-tsv, from-xml

docs/commands/config.md

@@ -0,0 +1,47 @@
+# config
+
+Configuration management.
+
+Syntax: `config {flags}`
+
+### Flags
+
+
+    --load <file path shape>
+      load the config from the path give
+
+    --set <any shape>
+      set a value in the config, eg) --set [key value]
+
+    --set_into <member shape>
+      sets a variable from values in the pipeline
+
+    --get <any shape>
+      get a value from the config
+
+    --remove <any shape>
+      remove a value from the config
+
+    --clear
+      clear the config
+
+    --path
+      return the path to the config file
+
+### Variables
+
+| Variable        | Type           | Description  |
+| ------------- | ------------- | ----- |
+| path | table of strings | PATH to use to find binaries |
+| env | row | the environment variables to pass to external commands |
+| ctrlc_exit | boolean | whether or not to exit Nu after multiple ctrl-c presses |
+| table_mode | "light" or other | enable lightweight or normal tables |
+| edit_mode | "vi" or "emacs" | changes line editing to "vi" or "emacs" mode |
+
+## Examples
+
+```shell
+> config --set [table_mode "light"]
+```
+
+A more detailed description on how to use this command to configure Nu shell can be found in the configuration chapter of [Nu Book](https://book.nushell.sh/en/configuration).

docs/commands/format.md

@@ -0,0 +1,37 @@
+# format
+
+Format columns into a string using a simple pattern
+
+Syntax: `format <pattern>`
+
+### Parameters
+
+* `<pattern>`: the pattern to match
+
+## Example
+
+Let's say we have a table like this:
+
+```shell
+> open pets.csv
+━━━┯━━━━━━━━━━━┯━━━━━━━━┯━━━━━
+ # │ animal    │ name   │ age
+───┼───────────┼────────┼─────
+ 0 │ cat       │ Tom    │ 7
+ 1 │ dog       │ Alfred │ 10
+ 2 │ chameleon │ Linda  │ 1
+━━━┷━━━━━━━━━━━┷━━━━━━━━┷━━━━━
+```
+
+`format` allows us to convert table data into a string by following a formatting pattern. To print the value of a column we have to put the column name in curly brackets:
+
+```shell
+> open pets.csv | format "{name} is a {age} year old {animal}"
+━━━┯━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ # │ <value>
+───┼─────────────────────────────────
+ 0 │ Tom is a 7 year old cat
+ 1 │ Alfred is a 10 year old dog
+ 2 │ Linda is a 1 year old chameleon
+━━━┷━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```

docs/commands/from-tsv.md

@@ -0,0 +1,52 @@
+# from-tsv
+
+Parse text as `.tsv` and create table.
+
+Syntax: `from-tsv {flags}`
+
+### Flags:
+
+    --headerless
+      don't treat the first row as column names
+
+## Examples
+
+Let's say we have the following file which is formatted like a `tsv` file:
+
+```shell
+> open elements.txt
+Symbol        Element
+H        Hydrogen
+He        Helium
+Li        Lithium
+Be        Beryllium
+```
+
+If we pass the output of the `open` command to `from-tsv` we get a correct formatted table:
+
+```shell
+> open elements.txt | from-tsv
+━━━┯━━━━━━━━┯━━━━━━━━━━━
+ # │ Symbol │ Element
+───┼────────┼───────────
+ 0 │ H      │ Hydrogen
+ 1 │ He     │ Helium
+ 2 │ Li     │ Lithium
+ 3 │ Be     │ Beryllium
+━━━┷━━━━━━━━┷━━━━━━━━━━━
+```
+
+Using the `--headerless` flag has the following output:
+
+```shell
+> open elements.txt | from-tsv --headerless
+━━━━┯━━━━━━━━━┯━━━━━━━━━━━
+ #  │ Column1 │ Column2
+────┼─────────┼───────────
+  0 │ Symbol  │ Element
+  1 │ H       │ Hydrogen
+  2 │ He      │ Helium
+  3 │ Li      │ Lithium
+  4 │ Be      │ Beryllium
+━━━━┷━━━━━━━━━┷━━━━━━━━━━━
+```

docs/commands/from-xml.md

@@ -0,0 +1,34 @@
+# from-xml
+
+Parse text as `.xml` and create table. Use this when nushell cannot dertermine the input file extension.
+
+Syntax: `from-xml`
+
+## Examples
+
+Let's say we've got a file in `xml` format but the file extension is different so Nu can't auto-format it:
+
+```shell
+> open world.txt
+<?xml version="1.0" encoding="utf-8"?>
+<world>
+    <continent>Africa</continent>
+    <continent>Antarctica</continent>
+    <continent>Asia</continent>
+    <continent>Australia</continent>
+    <continent>Europe</continent>
+    <continent>North America</continent>
+    <continent>South America</continent>
+</world>
+```
+
+We can use `from-xml` to read the input like a `xml` file:
+
+```shell
+> open world.txt | from-xml
+━━━━━━━━━━━━━━━━
+ world
+────────────────
+ [table 7 rows]
+━━━━━━━━━━━━━━━━
+```

docs/commands/from-yaml.md

@@ -1,6 +1,6 @@
 # from-yaml
 
-Parse text as `.yaml/.yml` and create table.
+Parse text as `.yaml/.yml` and create table. Use this when nushell cannot determine the input file extension.
 
 Syntax: `from-yaml`
 

docs/commands/get.md

@@ -0,0 +1,54 @@
+# get
+
+Open given cells as text.
+
+Syntax: `get  ...args`
+
+### Parameters:
+  
+* `args`: optionally return additional data by path
+
+## Examples
+
+If we run `sys` we recieve a table which contains tables itself:
+
+```shell
+> sys
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┯━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┯━━━━━━━━━━━━━━━━┯━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┯━━━━━━━━━━━━━━━━┯━━━━━━━━━━━━━━━━┯━━━━━━━━━━━━━━━━
+ host                                   │ cpu                                │ disks          │ mem                                   │ temp           │ net            │ battery 
+────────────────────────────────────────┼────────────────────────────────────┼────────────────┼───────────────────────────────────────┼────────────────┼────────────────┼────────────────
+ [row arch hostname name release uptime │ [row cores current ghz max ghz min │ [table 7 rows] │ [row free swap free swap total total] │ [table 6 rows] │ [table 3 rows] │ [table 1 rows] 
+ users]                                 │ ghz]                               │                │                                       │                │                │  
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┷━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┷━━━━━━━━━━━━━━━━┷━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┷━━━━━━━━━━━━━━━━┷━━━━━━━━━━━━━━━━┷━━━━━━━━━━━━━━━━
+```
+
+To access one of the embeded tables we can use the `get` command
+
+```shell
+> sys | get cpu
+━━━━━━━┯━━━━━━━━━━━━━━━━━━━┯━━━━━━━━━━━━━━━━━━━━┯━━━━━━━━━━━━━━━━━━━
+ cores │ current ghz       │ min ghz            │ max ghz 
+───────┼───────────────────┼────────────────────┼───────────────────
+     4 │ 1.530000000000000 │ 0.5000000000000000 │ 3.500000000000000 
+━━━━━━━┷━━━━━━━━━━━━━━━━━━━┷━━━━━━━━━━━━━━━━━━━━┷━━━━━━━━━━━━━━━━━━━
+```
+```shell
+> sys | get battery
+━━━━━━━━┯━━━━━━━━━━┯━━━━━━━━━━━━━━━━━━
+ vendor │ model    │ mins to full 
+────────┼──────────┼──────────────────
+ SMP    │ L14M2P21 │ 16.7024000000000 
+━━━━━━━━┷━━━━━━━━━━┷━━━━━━━━━━━━━━━━━━
+```
+
+There's also the ability to pass multiple parameters to `get` which results in an output like this
+
+```shell
+sys | get cpu battery
+━━━┯━━━━━━━┯━━━━━━━━━━━━━━━━━━━┯━━━━━━━━━━━━━━━━━━━━┯━━━━━━━━━━━━━━━━━━━┯━━━━━━━━┯━━━━━━━━━━┯━━━━━━━━━━━━━━━━━━━
+ # │ cores │ current ghz       │ min ghz            │ max ghz           │ vendor │ model    │ mins to full 
+───┼───────┼───────────────────┼────────────────────┼───────────────────┼────────┼──────────┼───────────────────
+ 0 │     4 │ 1.500000000000000 │ 0.5000000000000000 │ 3.500000000000000 │        │          │  
+ 1 │       │                   │                    │                   │ SMP    │ L14M2P21 │ 16.94503000000000 
+━━━┷━━━━━━━┷━━━━━━━━━━━━━━━━━━━┷━━━━━━━━━━━━━━━━━━━━┷━━━━━━━━━━━━━━━━━━━┷━━━━━━━━┷━━━━━━━━━━┷━━━━━━━━━━━━━━━━━━━
+```

docs/commands/ps.md

@@ -0,0 +1,25 @@
+# ps
+
+This command shows information about system processes.
+
+Syntax: `ps`
+
+## Example
+
+```shell
+> ps
+...
+━━━━┯━━━━━━━┯━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┯━━━━━━━━━┯━━━━━━━━━━━━━━━━━━━
+ #  │ pid   │ name                                                               │ status  │ cpu
+────┼───────┼────────────────────────────────────────────────────────────────────┼─────────┼───────────────────
+ 50 │ 10184 │ firefox.exe                                                        │ Running │ 0.000000000000000
+ 51 │ 11584 │ WindowsTerminal.exe                                                │ Running │ 0.000000000000000
+ 52 │ 11052 │ conhost.exe                                                        │ Running │ 0.000000000000000
+ 53 │  7076 │ nu.exe                                                             │ Running │ 0.000000000000000
+   ...
+ 66 │  3000 │ Code.exe                                                           │ Running │ 0.000000000000000
+ 67 │  5388 │ conhost.exe                                                        │ Running │ 0.000000000000000
+ 68 │  6268 │ firefox.exe                                                        │ Running │ 0.000000000000000
+ 69 │  8972 │ nu_plugin_ps.exe                                                   │ Running │ 58.00986000000000
+━━━━┷━━━━━━━┷━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┷━━━━━━━━━┷━━━━━━━━━━━━━━━━━━━
+```

docs/commands/save.md

@@ -0,0 +1,30 @@
+# save
+
+This command saves the contents of the pipeline to a file. Use this in combination with the `to-json`, `to-csv`, ... commands to save the contents in the specified format.
+
+Syntax: `save (path) {flags}`
+
+### Parameters:
+
+* `(path)` the path to save contents to
+
+### Flags
+
+    --raw
+      treat values as-is rather than auto-converting based on file extension
+
+## Example
+
+You can save the name of files in a directory like this:
+
+```shell
+> ls | where type == File | pick name | save filenames.csv
+```
+
+Or you can format it in supported formats using one of the `to-*` commands:
+
+```shell
+> ls | where type == File | pick name | to-csv | save filenames
+```
+
+`filename.csv` and `filenames` are both `csv` formatted files. Nu auto-converts the format if a supported file extension is given.