Quick Tour chapter update

book/quick_tour.md

@@ -1,53 +1,233 @@
 # Quick Tour
 
+[[toc]]
+
+## Nushell Commands Output _Data_
+
 The easiest way to see what Nu can do is to start with some examples, so let's dive in.
 
 The first thing you'll notice when you run a command like [`ls`](/commands/docs/ls.md) is that instead of a block of text coming back, you get a structured table.
 
-@[code](@snippets/introduction/ls_example.sh)
+```nu:no-line-numbers
+ls
+# => ╭────┬─────────────────────┬──────┬───────────┬──────────────╮
+# => │  # │        name         │ type │   size    │   modified   │
+# => ├────┼─────────────────────┼──────┼───────────┼──────────────┤
+# => │  0 │ CITATION.cff        │ file │     812 B │ 2 months ago │
+# => │  1 │ CODE_OF_CONDUCT.md  │ file │   3.4 KiB │ 9 months ago │
+# => │  2 │ CONTRIBUTING.md     │ file │  11.0 KiB │ 5 months ago │
+# => │  3 │ Cargo.lock          │ file │ 194.9 KiB │ 15 hours ago │
+# => │  4 │ Cargo.toml          │ file │   9.2 KiB │ 15 hours ago │
+# => │  5 │ Cross.toml          │ file │     666 B │ 6 months ago │
+# => │  6 │ LICENSE             │ file │   1.1 KiB │ 9 months ago │
+# => │  7 │ README.md           │ file │  12.0 KiB │ 15 hours ago │
+# => ...
+```
+
+This table does more than just format the output nicely. Like a spreadsheet, it allows us to work with the data _interactively_.
+
+## Acting on Data
+
+Next, let's sort this table by each file's size. To do this, we'll take the output from [`ls`](/commands/docs/ls.md) and feed it into a command that can sort tables based on the _values_ in a column.
+
+```nu:no-line-numbers
+ls | sort-by size | reverse
+# => ╭───┬─────────────────┬──────┬───────────┬──────────────╮
+# => │ # │      name       │ type │   size    │   modified   │
+# => ├───┼─────────────────┼──────┼───────────┼──────────────┤
+# => │ 0 │ Cargo.lock      │ file │ 194.9 KiB │ 15 hours ago │
+# => │ 1 │ toolkit.nu      │ file │  20.0 KiB │ 15 hours ago │
+# => │ 2 │ README.md       │ file │  12.0 KiB │ 15 hours ago │
+# => │ 3 │ CONTRIBUTING.md │ file │  11.0 KiB │ 5 months ago │
+# => │ 4 │ ...             │ ...  │ ...       │ ...          │
+# => │ 5 │ LICENSE         │ file │   1.1 KiB │ 9 months ago │
+# => │ 6 │ CITATION.cff    │ file │     812 B │ 2 months ago │
+# => │ 7 │ Cross.toml      │ file │     666 B │ 6 months ago │
+# => │ 8 │ typos.toml      │ file │     513 B │ 2 months ago │
+# => ╰───┴─────────────────┴──────┴───────────┴──────────────╯
+```
+
+Notice that we didn't pass commandline arguments or switches to [`ls`](/commands/docs/ls.md). Instead, we used Nushell's built-in [`sort-by`](/commands/docs/sort-by.md) command to sort the _output_ of the `ls` command. Then, to see the largest files on top, we used [`reverse`](/commands/docs/reverse.md) on the _output_ of `sort-by`.
+
+::: tip Cool!
+If you compare the sort order closely, you might realize that the data isn't sorted alphabetically. It's not even sorted by the _numerical_ values. Instead, since the `size` column is a [`filesize` type](./types_of_data.md#file-sizes), Nushell knows that `1.1 KiB` (kibibytes) is larger than `812 B` (bytes).
+:::
+
+# Finding Data Using the `where` Command
+
+Nu provides many commands that can operate on the structured output of the previous command. These are usually categorized as "Filters" in Nushell.
+
+For example, we can use [`where`](/commands/docs/where.md) to filter the contents of the table so that it only shows files over 10 kilobytes:
+
+```nu
+ls | where size > 10kb
+# => ╭───┬─────────────────┬──────┬───────────┬───────────────╮
+# => │ # │      name       │ type │   size    │   modified    │
+# => ├───┼─────────────────┼──────┼───────────┼───────────────┤
+# => │ 0 │ CONTRIBUTING.md │ file │  11.0 KiB │ 5 months ago  │
+# => │ 1 │ Cargo.lock      │ file │ 194.6 KiB │ 2 minutes ago │
+# => │ 2 │ README.md       │ file │  12.0 KiB │ 16 hours ago  │
+# => │ 3 │ toolkit.nu      │ file │  20.0 KiB │ 16 hours ago  │
+# => ╰───┴─────────────────┴──────┴───────────┴───────────────╯
+```
+
+## More Than Just Directories
+
+Of course, this isn't limited to the `ls` command. Nushell follows the Unix philosophy where each command does one thing well and you can typically expect the output of one command to become the input of another. This allows us to mix-and-match commands in many different combinations.
+
+Let's look at a different command:
+
+```nu:no-line-numbers
+ps
+# => ╭───┬──────┬──────┬───────────────┬──────────┬──────┬───────────┬─────────╮
+# => │ # │ pid  │ ppid │     name      │  status  │ cpu  │    mem    │ virtual │
+# => ├───┼──────┼──────┼───────────────┼──────────┼──────┼───────────┼─────────┤
+# => │ 0 │    1 │    0 │ init(void)    │ Sleeping │ 0.00 │   1.2 MiB │ 2.2 MiB │
+# => │ 1 │    8 │    1 │ init          │ Sleeping │ 0.00 │ 124.0 KiB │ 2.3 MiB │
+# => │ 2 │ 6565 │    1 │ SessionLeader │ Sleeping │ 0.00 │ 108.0 KiB │ 2.2 MiB │
+# => │ 3 │ 6566 │ 6565 │ Relay(6567)   │ Sleeping │ 0.00 │ 116.0 KiB │ 2.2 MiB │
+# => │ 4 │ 6567 │ 6566 │ nu            │ Running  │ 0.00 │  28.4 MiB │ 1.1 GiB │
+# => ╰───┴──────┴──────┴───────────────┴──────────┴──────┴───────────┴─────────╯
+```
+
+You may be familiar with the Linux/Unix `ps` command. It provides a list of all of the current processes running in the system along with their current status. As with `ls`, Nushell provides a cross-platform, built-in [`ps` command](/commands/docs/ps.md) that returns its results as structured data.
+
+::: note
+The traditional Unix `ps` only shows the current process and its parents by default. Nushell's implementation shows all of the processes on the system by default.
+:::
+
+What if we wanted to just show the processes that are actively running? As with `ls` above, we can also work with the table that `ps` _outputs_:
+
+```nu
+ps | where status == Running
+# => ╭───┬──────┬──────┬──────┬─────────┬──────┬──────────┬─────────╮
+# => │ # │ pid  │ ppid │ name │ status  │ cpu  │   mem    │ virtual │
+# => ├───┼──────┼──────┼──────┼─────────┼──────┼──────────┼─────────┤
+# => │ 0 │ 6585 │ 6584 │ nu   │ Running │ 0.00 │ 31.9 MiB │ 1.2 GiB │
+# => ╰───┴──────┴──────┴──────┴─────────┴──────┴──────────┴─────────╯
+```
+
+::: tip
+Remember above, where the `size` column from the `ls` command was a `filesize`? Here, `status` is really just a string, and
+you can use all the normal string operations and commands with it, including (as above) the `==` comparison.
+
+You can examine the types for the table's columns using:
+
+```nu
+ps | describe
+# => table<pid: int, ppid: int, name: string, status: string, cpu: float, mem: filesize, virtual: filesize> (stream)
+```
+
+:::
+
+## Command Arguments in a Pipeline
+
+Sometimes, a command takes an _argument_ instead of pipeline _input_. For this scenario, Nushell provides the [`$in` variable](./pipelines.md#pipeline-input-and-the-special-in-variable) that let's you use the previous command's output in variable-form. For example:
+
+```nu:line-numbers
+ls
+| sort-by size
+| reverse
+| first
+| get name
+| cp $in ~
+```
+
+::: tip Nushell Design Note
+Whenever possible, Nushell commands are designed to act on pipeline _input_. However, some commands, like `cp` in this example, have two (or more)
+arguments with different meanings. In this case, `cp` needs to know both the path to _copy_ as well as the _target_ path. As a result, this command is
+more ergonomic with two _positional parameters_.
+:::
+
+::: tip
+Nushell commands can extend across multiple lines for readability. The above is the same as:
+
+```nu
+ls | sort-by size | reverse | first | get name | cp $in ~
+```
+
+:::
+
+The first three lines are the same commands we used in the second example above, so let's examine the last three:
 
-The table does more than show the directory in a different way. Just like tables in a spreadsheet, this table allows us to work with the data more interactively.
+4. The [`first` command](/commands/docs/first.md) simply returns the first value from the table. In this case, that means the file with the largest size. That's the `Cargo.lock` file if using the directory listing from the second example above. This "file" is a [`record`](./types_of_data.md#records) from the table which still contains its `name`, `type`, `size`, and `modified` columns/fields.
+5. `get name` returns the _value_ of the `name` field from the previous command, so `"Cargo.lock"` (a string). This is also a simple example of a [`cell-path`](./types_of_data.md#cell-paths) that can be used to navigate and isolate structured data.
+6. The last line uses the `$in` variable to reference the output of line 5. The result is a command that says _"Copy 'Cargo.lock' to the home directory"_
 
-The first thing we'll do is to sort our table by size. To do this, we'll take the output from [`ls`](/commands/docs/ls.md) and feed it into a command that can sort tables based on the contents of a column.
+::: tip
+[`get`](/commands/docs/get.md) and its counterpart [`select`](/commands/docs/select.md) are two of the most used filters in Nushell, but it might not be easy to
+spot the difference between them at first glance. When you're ready to start using them more extensively, see [Using `get` and `select`](./navigating_structured_data.md#using-get-and-select) for a guide.
+:::
 
-@[code](@snippets/introduction/ls_sort_by_reverse_example.sh)
+## Getting Help
 
-You can see that to make this work we didn't pass commandline arguments to [`ls`](/commands/docs/ls.md). Instead, we used the [`sort-by`](/commands/docs/sort-by.md) command that Nu provides to do the sorting of the output of the [`ls`](/commands/docs/ls.md) command. To see the biggest files on top, we also used [`reverse`](/commands/docs/reverse.md).
+Nushell provides an extensive, in-shell Help system. For example
 
-Nu provides many commands that can work on tables. For example, we could use [`where`](/commands/docs/where.md) to filter the contents of the [`ls`](/commands/docs/ls.md) table so that it only shows files over 1 kilobyte:
+```nu
+# help <command>
+help ls
+# Or
+ls --help
+# Also
+help operators
+help escapes
+```
 
-@[code](@snippets/introduction/ls_where_example.sh)
+::: tip Cool!
+Press the <kbd>F1</kbd> key to access the Help [menu](./line_editor.md#menus). Search for the `ps` command here, but _don't press <kbd>Enter</kbd> just yet_!
 
-Just as in the Unix philosophy, being able to have commands talk to each other gives us ways to mix-and-match in many different combinations. Let's look at a different command:
+Instead, press the <kbd>Down Arrow</kbd> key, and notice that you are scrolling through the Examples section. Highlight an example, _then_ press <kbd>Enter</kbd> and
+the example will be entered at the commandline, ready to run!
 
-@[code](@snippets/introduction/ps_example.sh)
+This can be a great way to explore and learn about the extensive set of Nushell commands.
+:::
 
-You may be familiar with the [`ps`](/commands/docs/ps.md) command if you've used Linux. With it, we can get a list of all the current processes that the system is running, what their status is, and what their name is. We can also see the CPU load for the processes.
+The Help system also has a "search" feature:
 
-What if we wanted to show the processes that were actively using the CPU? Just like we did with the [`ls`](/commands/docs/ls.md) command earlier, we can also work with the table that the [`ps`](/commands/docs/ps.md) command gives back to us:
+```nu
+help --find filesize
+# or
+help -f filesize
+```
 
-@[code](@snippets/introduction/ps_where_example.sh)
+It may not surprise you by now that the Help system itself is based on structured data! Notice that the output of `help -f filesize` is a table.
 
-So far, we've been using [`ls`](/commands/docs/ls.md) and [`ps`](/commands/docs/ps.md) to list files and processes in the form of a simple table. But data in Nu is structured and can be arbitrarily nested. As an example, let's now explore the [`help commands`](/commands/docs/help_commands.md) command.
+The Help for each command is stored as a record with:
 
-Running [`help commands`](/commands/docs/help_commands.md) gives us information for all Nushell commands as a table. However, the output will be quite large, so let's get the row for the `each` command only.
+- Its name
+- Category
+- Type (built-in, plugin, custom)
+- The parameters it accepts
+- Signatures showing what types of data it can accept as well as output
+- And more
 
-@[code](@snippets/introduction/help_commands_each_example.nu)
+You can view _all_ commands (other than externals) as a single large table using:
 
-This is a bit different than the tables we saw before. Retrieving a single row from a table gives us a [record](/book/types_of_data.html#records), which is set of key-value pairs. Note that the "params" and "input_output" columns happen to contain tables instead of a simple values. To view only one of those columns, we can use the [`get`](/commands/docs/get.md) command to retrieve it:
+```nu
+help commands
+```
 
-@[code](@snippets/introduction/help_commands_get_example.nu)
+::: tip
+Notice that the `params` and `input_output` columns of the output above are _nested_ tables. Nushell allows [arbitrarily nested data structures](./navigating_structured_data.md#background).
+:::
 
-The [`get`](/commands/docs/get.md) command lets us jump into the contents of structured data (a table, record, or list). We can even pass it nested columns to access data at any depth.
+## `explore`'ing from Here
 
-@[code](@snippets/introduction/help_commands_get_nested_example.nu)
+That `help commands` output is quite long. You could send it to a pager like `less` or `bat`, but Nushell includes a built-in `explore` command that lets you not only scroll, but also telescope-in to nested data. Try:
 
-These nested columns are called [cell paths](/book/types_of_data.html#cell-paths). Nu will take the cell path and go to the corresponding bit of data in a table, record, or list. Cell paths also support row numbers, so we could have rewritten the above pipeline as:
+```
+help commands | explore
+```
 
-@[code](@snippets/introduction/help_commands_get_cell_path_example.nu)
+Then press the <kbd>Enter</kbd> key to access the data itself. Use the arrow keys to scroll to the `cp` command, and over to the `params` column. Hit <kbd>Enter</kbd> again to
+telescope in to the complete list of parameters available to the `cp` command.
 
-### Getting Help
+::: note
+Pressing <kbd>Esc</kbd> one time returns from Scroll-mode to the View; Pressing it a second time returns to the previous view (or exits, if already at the top view level).
+:::
 
-You can see the help text for any of Nu's built-in commands by using the [`help`](/commands/docs/help.md) command or by passing the `--help` flag to a command. You can also search for a topic by doing `help -f <topic>`.
+::: tip
+You can, of course, use the `explore` command on _any_ structured data in Nushell. This might include JSON data coming from a Web API, a spreadsheet or CVS file, YAML, or anything that can be represented as structured data in Nushell.
 
-@[code](@snippets/introduction/help_example.sh)
+Try `$env.config | explore` for fun!
+:::