From 8ab2b924050d6e773b5d31a958d299a36f2df659 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=B6rn=20Zaefferer?= Date: Mon, 4 May 2020 23:01:31 +0200 Subject: [PATCH] docs/commands: add from.md, update subcommands (#1712) This adds a top-level document for the new `from` command, with a list of links of all the subcommands. All the from-* subcommands keep their filename, but the content is updated to use the new subcommand syntax. Needs matching update for to* Ref #1709 --- docs/commands/from-csv.md | 26 +++++++++---------- docs/commands/from-ics.md | 16 ++++++------ docs/commands/from-json.md | 12 ++++----- docs/commands/from-ods.md | 6 ++--- docs/commands/from-toml.md | 8 +++--- docs/commands/from-tsv.md | 12 ++++----- docs/commands/from-vcf.md | 16 ++++++------ docs/commands/from-xlsx.md | 6 ++--- docs/commands/from-xml.md | 10 ++++---- docs/commands/from-yaml.md | 6 ++--- docs/commands/from.md | 52 ++++++++++++++++++++++++++++++++++++++ 11 files changed, 111 insertions(+), 59 deletions(-) create mode 100644 docs/commands/from.md diff --git a/docs/commands/from-csv.md b/docs/commands/from-csv.md index cf6947c113..8f9aafcd4e 100644 --- a/docs/commands/from-csv.md +++ b/docs/commands/from-csv.md @@ -1,4 +1,4 @@ -# from-csv +# from csv Converts csv data into table. Use this when nushell cannot determine the input file extension. @@ -24,10 +24,10 @@ dog, Alfred, 10 chameleon, Linda, 1 ``` -To get a table from `pets.txt` we need to use the `from-csv` command : +To get a table from `pets.txt` we need to use the `from csv` command : ```shell -> open pets.txt | from-csv +> open pets.txt | from csv ━━━┯━━━━━━━━━━━┯━━━━━━━━━┯━━━━━━ # │ animal │ name │ age ───┼───────────┼─────────┼────── @@ -59,7 +59,7 @@ chameleon; Linda; 1 ``` ```shell -> open pets.txt | from-csv --separator ';' +> open pets.txt | from csv --separator ';' ━━━┯━━━━━━━━━━━┯━━━━━━━━━┯━━━━━━ # │ animal │ name │ age ───┼───────────┼─────────┼────── @@ -69,20 +69,20 @@ chameleon; Linda; 1 ━━━┷━━━━━━━━━━━┷━━━━━━━━━┷━━━━━━ ``` -To use this command to open a csv with separators other than a comma, use the `--raw` switch of `open` to open the csv, otherwise the csv will enter `from-csv` as a table split on commas rather than raw text. +To use this command to open a csv with separators other than a comma, use the `--raw` switch of `open` to open the csv, otherwise the csv will enter `from csv` as a table split on commas rather than raw text. ```shell > mv pets.txt pets.csv -> open pets.csv | from-csv --separator ';' +> open pets.csv | from csv --separator ';' error: Expected a string from pipeline - shell:1:16 -1 | open pets.csv | from-csv --separator ';' +1 | open pets.csv | from csv --separator ';' | ^^^^^^^^ requires string input - shell:1:0 -1 | open pets.csv | from-csv --separator ';' +1 | open pets.csv | from csv --separator ';' | value originates from here -> open pets.csv --raw | from-csv --separator ';' +> open pets.csv --raw | from csv --separator ';' ━━━┯━━━━━━━━━━━┯━━━━━━━━━┯━━━━━━ # │ animal │ name │ age ───┼───────────┼─────────┼────── @@ -99,18 +99,18 @@ Newlines '\n' are not acceptable separators. Note that separators are currently provided as strings and need to be wrapped in quotes. ```shell -> open pets.csv --raw | from-csv --separator ; +> open pets.csv --raw | from csv --separator ; - shell:1:43 -1 | open pets.csv --raw | from-csv --separator ; +1 | open pets.csv --raw | from csv --separator ; | ^ ``` It is also considered an error to use a separator greater than one char : ```shell -> open pets.txt | from-csv --separator '123' +> open pets.txt | from csv --separator '123' error: Expected a single separator char from --separator - shell:1:37 -1 | open pets.txt | from-csv --separator '123' +1 | open pets.txt | from csv --separator '123' | ^^^^^ requires a single character string input ``` diff --git a/docs/commands/from-ics.md b/docs/commands/from-ics.md index 8fa970d6ef..9c16155ec7 100644 --- a/docs/commands/from-ics.md +++ b/docs/commands/from-ics.md @@ -1,8 +1,8 @@ -# from-ics +# from ics Parse text as `.ics` and create table. -Syntax: `from-ics` +Syntax: `from ics` ## Examples @@ -20,21 +20,21 @@ UID:4l80f6dcovnriq38g57g07btid@google.com ... ``` -Pass the output of the `open` command to `from-ics` to get a correctly formatted table: +Pass the output of the `open` command to `from ics` to get a correctly formatted table: ```shell -> open calendar.txt | from-ics +> open calendar.txt | from ics ───┬────────────────┬──────────────────┬────────────────┬────────────────┬────────────────┬────────────────┬──────────────── - # │ properties │ events │ alarms │ to-Dos │ journals │ free-busys │ timezones + # │ properties │ events │ alarms │ to-Dos │ journals │ free-busys │ timezones ───┼────────────────┼──────────────────┼────────────────┼────────────────┼────────────────┼────────────────┼──────────────── 0 │ [table 0 rows] │ [table 1 row] │ [table 0 rows] │ [table 0 rows] │ [table 0 rows] │ [table 0 rows] │ [table 0 rows] ───┴────────────────┴──────────────────┴────────────────┴────────────────┴────────────────┴────────────────┴──────────────── ``` ```shell -> open calendar.txt | from-ics | get events | get properties | where name == "SUMMARY" +> open calendar.txt | from ics | get events | get properties | where name == "SUMMARY" ─────┬─────────┬───────────────────────────────────────┬──────── - # │ name │ value │ params + # │ name │ value │ params ─────┼─────────┼───────────────────────────────────────┼──────── 0 │ SUMMARY │ Basketball Game │ -``` \ No newline at end of file +``` diff --git a/docs/commands/from-json.md b/docs/commands/from-json.md index 92f920c81f..95b742b3f5 100644 --- a/docs/commands/from-json.md +++ b/docs/commands/from-json.md @@ -1,8 +1,8 @@ -# from-json +# from json Parse text as `.json` and create table. Use this when nushell cannot dertermine the input file extension. -Syntax: `from-json {flags}` +Syntax: `from json {flags}` ### Flags: @@ -16,7 +16,7 @@ Syntax: `from-json {flags}` > open command_from-json [ { - title: "from-json", + title: "from json", type: "command", flags: true } @@ -24,10 +24,10 @@ Syntax: `from-json {flags}` ``` ```shell -> open command_from-json | from-json +> open command_from-json | from json ━━━━━━━━━━━┯━━━━━━━━━┯━━━━━━━ title │ type │ flags ───────────┼─────────┼─────── - from-json │ command │ Yes + from json │ command │ Yes ━━━━━━━━━━━┷━━━━━━━━━┷━━━━━━━ -``` \ No newline at end of file +``` diff --git a/docs/commands/from-ods.md b/docs/commands/from-ods.md index 9362b1b9d3..846bfed45a 100644 --- a/docs/commands/from-ods.md +++ b/docs/commands/from-ods.md @@ -1,6 +1,6 @@ -# from-ods +# from ods -Parses OpenDocument Spreadsheet binary data into a table. `open` calls `from-ods` automatically when the file extension is `ods`. Use this command when `open` is unable to guess the file type from the extension. +Parses OpenDocument Spreadsheet binary data into a table. `open` calls `from ods` automatically when the file extension is `ods`. Use this command when `open` is unable to guess the file type from the extension. ## Examples @@ -20,7 +20,7 @@ Length: 4816 (0x12d0) bytes 12a0: 00 61 10 00 00 4d 45 54 41 2d 49 4e 46 2f 6d 61 .a...META-INF/ma 12b0: 6e 69 66 65 73 74 2e 78 6d 6c 50 4b 05 06 00 00 nifest.xmlPK.... 12c0: 00 00 06 00 06 00 5a 01 00 00 60 11 00 00 00 00 ......Z...`..... -> open abc.ods --raw | from-ods +> open abc.ods --raw | from ods ───────────────── Sheet1 ───────────────── diff --git a/docs/commands/from-toml.md b/docs/commands/from-toml.md index d3f3364c78..10520b5c48 100644 --- a/docs/commands/from-toml.md +++ b/docs/commands/from-toml.md @@ -1,4 +1,4 @@ -# from-toml +# from toml Converts toml data into table. Use this when nushell cannot dertermine the input file extension. ## Example @@ -10,14 +10,14 @@ Let's say we have the following Rust .lock file : ... ``` -The "Cargo.lock" file is actually a .toml file, but the file extension isn't .toml. That's okay, we can use the `from-toml` command : +The "Cargo.lock" file is actually a .toml file, but the file extension isn't .toml. That's okay, we can use the `from toml` command : ```shell -> open Cargo.lock | from-toml +> open Cargo.lock | from toml ━━━━━━━━━━━━━━━━┯━━━━━━━━━━━━━━━━━━━ metadata │ package ────────────────┼─────────────────── [table: 1 row] │ [table: 154 rows] ━━━━━━━━━━━━━━━━┷━━━━━━━━━━━━━━━━━━━ -``` \ No newline at end of file +``` diff --git a/docs/commands/from-tsv.md b/docs/commands/from-tsv.md index 86452de97a..14ff8b3cf9 100644 --- a/docs/commands/from-tsv.md +++ b/docs/commands/from-tsv.md @@ -1,8 +1,8 @@ -# from-tsv +# from tsv Parse text as `.tsv` and create table. -Syntax: `from-tsv {flags}` +Syntax: `from tsv {flags}` ### Flags: @@ -22,10 +22,10 @@ Li Lithium Be Beryllium ``` -If we pass the output of the `open` command to `from-tsv` we get a correct formatted table: +If we pass the output of the `open` command to `from tsv` we get a correct formatted table: ```shell -> open elements.txt | from-tsv +> open elements.txt | from tsv ━━━┯━━━━━━━━┯━━━━━━━━━━━ # │ Symbol │ Element ───┼────────┼─────────── @@ -39,7 +39,7 @@ If we pass the output of the `open` command to `from-tsv` we get a correct forma Using the `--headerless` flag has the following output: ```shell -> open elements.txt | from-tsv --headerless +> open elements.txt | from tsv --headerless ━━━━┯━━━━━━━━━┯━━━━━━━━━━━ # │ Column1 │ Column2 ────┼─────────┼─────────── @@ -49,4 +49,4 @@ Using the `--headerless` flag has the following output: 3 │ Li │ Lithium 4 │ Be │ Beryllium ━━━━┷━━━━━━━━━┷━━━━━━━━━━━ -``` \ No newline at end of file +``` diff --git a/docs/commands/from-vcf.md b/docs/commands/from-vcf.md index ce1901db25..a471d1a2f4 100644 --- a/docs/commands/from-vcf.md +++ b/docs/commands/from-vcf.md @@ -1,8 +1,8 @@ -# from-vcf +# from vcf Parse text as `.vcf` and create table. -Syntax: `from-vcf` +Syntax: `from vcf` ## Examples @@ -18,20 +18,20 @@ EMAIL;TYPE=INTERNET:john.doe99@gmail.com ... ``` -Pass the output of the `open` command to `from-vcf` to get a correctly formatted table: +Pass the output of the `open` command to `from vcf` to get a correctly formatted table: ```shell -> open contacts.txt | from-vcf +> open contacts.txt | from vcf ─────┬───────────────── - # │ properties + # │ properties ─────┼───────────────── 0 │ [table 8 rows] ``` ```shell -> open contacts.txt | from-vcf | get properties | where $it.name == "FN" | pick value +> open contacts.txt | from vcf | get properties | where $it.name == "FN" | pick value ─────┬────────────────────── - # │ value + # │ value ─────┼────────────────────── 0 │ John Doe -``` \ No newline at end of file +``` diff --git a/docs/commands/from-xlsx.md b/docs/commands/from-xlsx.md index 583dd7cf88..0ad91c204e 100644 --- a/docs/commands/from-xlsx.md +++ b/docs/commands/from-xlsx.md @@ -1,6 +1,6 @@ -# from-xlsx +# from xlsx -Parses MS Excel binary data into a table. `open` calls `from-xlsx` automatically when the file extension is `xlsx`. Use this command when `open` is unable to guess the file type from the extension. +Parses MS Excel binary data into a table. `open` calls `from xlsx` automatically when the file extension is `xlsx`. Use this command when `open` is unable to guess the file type from the extension. ## Examples @@ -20,7 +20,7 @@ Length: 6344 (0x18c8) bytes 18a0: 6b 73 68 65 65 74 73 2f 73 68 65 65 74 31 2e 78 ksheets/sheet1.x 18b0: 6d 6c 50 4b 05 06 00 00 00 00 0a 00 0a 00 7f 02 mlPK............ 18c0: 00 00 33 16 00 00 00 00 ..3..... -> open abc.xlsx --raw | from-xlsx +> open abc.xlsx --raw | from xlsx ───────────────── Sheet1 ───────────────── diff --git a/docs/commands/from-xml.md b/docs/commands/from-xml.md index d7a9e2a78d..656dcf295f 100644 --- a/docs/commands/from-xml.md +++ b/docs/commands/from-xml.md @@ -1,8 +1,8 @@ -# from-xml +# from xml Parse text as `.xml` and create table. Use this when nushell cannot dertermine the input file extension. -Syntax: `from-xml` +Syntax: `from xml` ## Examples @@ -22,13 +22,13 @@ Let's say we've got a file in `xml` format but the file extension is different s ``` -We can use `from-xml` to read the input like a `xml` file: +We can use `from xml` to read the input like a `xml` file: ```shell -> open world.txt | from-xml +> open world.txt | from xml ━━━━━━━━━━━━━━━━ world ──────────────── [table 7 rows] ━━━━━━━━━━━━━━━━ -``` \ No newline at end of file +``` diff --git a/docs/commands/from-yaml.md b/docs/commands/from-yaml.md index b8bf931e15..704570f6dd 100644 --- a/docs/commands/from-yaml.md +++ b/docs/commands/from-yaml.md @@ -1,8 +1,8 @@ -# from-yaml +# from yaml Parse text as `.yaml/.yml` and create table. Use this when nushell cannot determine the input file extension. -Syntax: `from-yaml` +Syntax: `from yaml` ## Examples @@ -14,7 +14,7 @@ flags: false ``` ```shell -> open command_from-yaml | from-yaml +> open command_from-yaml | from yaml ━━━━━━━━━━━┯━━━━━━━━━┯━━━━━━━ title │ type │ flags ───────────┼─────────┼─────── diff --git a/docs/commands/from.md b/docs/commands/from.md new file mode 100644 index 0000000000..e6b186c8e1 --- /dev/null +++ b/docs/commands/from.md @@ -0,0 +1,52 @@ +# from-csv + +Converts content (string or binary) into a table. The format is specified as a subcommand, like `from csv` or `from json`. + +Use this when nushell cannot determine the input file extension. + +## Available Subcommands + +* [from csv](from-csv.md) +* [from ics](from-ics.md) +* [from json](from-json.md) +* [from ods](from-ods.md) +* [from toml](from-toml.md) +* [from tsv](from-tsv.md) +* [from vcf](from-vcf.md) +* [from xlsx](from-csv.md) +* [from yaml](from-yaml.md) + +## Example for `from csv` + +Let's say we have the following file : + +```shell +> cat pets.txt +animal, name, age +cat, Tom, 7 +dog, Alfred, 10 +chameleon, Linda, 1 +``` + +`pets.txt` is actually a .csv file but it has the .txt extension, `open` is not able to convert it into a table : + +```shell +> open pets.txt +animal, name, age +cat, Tom, 7 +dog, Alfred, 10 +chameleon, Linda, 1 +``` + +To get a table from `pets.txt` we need to use the `from csv` command: + +```shell +> open pets.txt | from csv +━━━┯━━━━━━━━━━━┯━━━━━━━━━┯━━━━━━ + # │ animal │ name │ age +───┼───────────┼─────────┼────── + 0 │ cat │ Tom │ 7 + 1 │ dog │ Alfred │ 10 + 2 │ chameleon │ Linda │ 1 +━━━┷━━━━━━━━━━━┷━━━━━━━━━┷━━━━━━ +```