Skip to content

Commit 61adb5c

Browse files
NotTheDr01dsNotTheDr01ds
authored
Quick Tour chapter update (#1662)
* Quick Tour chapter update * Minor additions * Typo * Changes from review * Additional changes from review * Fix missing language specifier * One more * List consistency
1 parent eee5970 commit 61adb5c

File tree

1 file changed

+213
-24
lines changed

1 file changed

+213
-24
lines changed

‎book/quick_tour.md‎

Lines changed: 213 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -1,53 +1,242 @@
11
# Quick Tour
22

3+
[[toc]]
4+
5+
## Nushell Commands Output _Data_
6+
37
The easiest way to see what Nu can do is to start with some examples, so let's dive in.
48

59
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.
610

7-
@[code](@snippets/introduction/ls_example.sh)
11+
```nu:no-line-numbers
12+
ls
13+
# => ╭────┬─────────────────────┬──────┬───────────┬──────────────╮
14+
# => │ # │ name │ type │ size │ modified │
15+
# => ├────┼─────────────────────┼──────┼───────────┼──────────────┤
16+
# => │ 0 │ CITATION.cff │ file │ 812 B │ 2 months ago │
17+
# => │ 1 │ CODE_OF_CONDUCT.md │ file │ 3.4 KiB │ 9 months ago │
18+
# => │ 2 │ CONTRIBUTING.md │ file │ 11.0 KiB │ 5 months ago │
19+
# => │ 3 │ Cargo.lock │ file │ 194.9 KiB │ 15 hours ago │
20+
# => │ 4 │ Cargo.toml │ file │ 9.2 KiB │ 15 hours ago │
21+
# => │ 5 │ Cross.toml │ file │ 666 B │ 6 months ago │
22+
# => │ 6 │ LICENSE │ file │ 1.1 KiB │ 9 months ago │
23+
# => │ 7 │ README.md │ file │ 12.0 KiB │ 15 hours ago │
24+
# => ...
25+
```
26+
27+
This table does more than just format the output nicely. Like a spreadsheet, it allows us to work with the data _interactively_.
28+
29+
## Acting on Data
30+
31+
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.
32+
33+
```nu:no-line-numbers
34+
ls | sort-by size | reverse
35+
# => ╭───┬─────────────────┬──────┬───────────┬──────────────╮
36+
# => │ # │ name │ type │ size │ modified │
37+
# => ├───┼─────────────────┼──────┼───────────┼──────────────┤
38+
# => │ 0 │ Cargo.lock │ file │ 194.9 KiB │ 15 hours ago │
39+
# => │ 1 │ toolkit.nu │ file │ 20.0 KiB │ 15 hours ago │
40+
# => │ 2 │ README.md │ file │ 12.0 KiB │ 15 hours ago │
41+
# => │ 3 │ CONTRIBUTING.md │ file │ 11.0 KiB │ 5 months ago │
42+
# => │ 4 │ ... │ ... │ ... │ ... │
43+
# => │ 5 │ LICENSE │ file │ 1.1 KiB │ 9 months ago │
44+
# => │ 6 │ CITATION.cff │ file │ 812 B │ 2 months ago │
45+
# => │ 7 │ Cross.toml │ file │ 666 B │ 6 months ago │
46+
# => │ 8 │ typos.toml │ file │ 513 B │ 2 months ago │
47+
# => ╰───┴─────────────────┴──────┴───────────┴──────────────╯
48+
```
49+
50+
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`.
51+
52+
::: tip Cool!
53+
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).
54+
:::
55+
56+
# Finding Data Using the `where` Command
57+
58+
Nu provides many commands that can operate on the structured output of the previous command. These are usually categorized as "Filters" in Nushell.
59+
60+
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:
61+
62+
```nu
63+
ls | where size > 10kb
64+
# => ╭───┬─────────────────┬──────┬───────────┬───────────────╮
65+
# => │ # │ name │ type │ size │ modified │
66+
# => ├───┼─────────────────┼──────┼───────────┼───────────────┤
67+
# => │ 0 │ CONTRIBUTING.md │ file │ 11.0 KiB │ 5 months ago │
68+
# => │ 1 │ Cargo.lock │ file │ 194.6 KiB │ 2 minutes ago │
69+
# => │ 2 │ README.md │ file │ 12.0 KiB │ 16 hours ago │
70+
# => │ 3 │ toolkit.nu │ file │ 20.0 KiB │ 16 hours ago │
71+
# => ╰───┴─────────────────┴──────┴───────────┴───────────────╯
72+
```
73+
74+
## More Than Just Directories
75+
76+
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.
77+
78+
Let's look at a different command:
79+
80+
```nu:no-line-numbers
81+
ps
82+
# => ╭───┬──────┬──────┬───────────────┬──────────┬──────┬───────────┬─────────╮
83+
# => │ # │ pid │ ppid │ name │ status │ cpu │ mem │ virtual │
84+
# => ├───┼──────┼──────┼───────────────┼──────────┼──────┼───────────┼─────────┤
85+
# => │ 0 │ 1 │ 0 │ init(void) │ Sleeping │ 0.00 │ 1.2 MiB │ 2.2 MiB │
86+
# => │ 1 │ 8 │ 1 │ init │ Sleeping │ 0.00 │ 124.0 KiB │ 2.3 MiB │
87+
# => │ 2 │ 6565 │ 1 │ SessionLeader │ Sleeping │ 0.00 │ 108.0 KiB │ 2.2 MiB │
88+
# => │ 3 │ 6566 │ 6565 │ Relay(6567) │ Sleeping │ 0.00 │ 116.0 KiB │ 2.2 MiB │
89+
# => │ 4 │ 6567 │ 6566 │ nu │ Running │ 0.00 │ 28.4 MiB │ 1.1 GiB │
90+
# => ╰───┴──────┴──────┴───────────────┴──────────┴──────┴───────────┴─────────╯
91+
```
92+
93+
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.
94+
95+
::: note
96+
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.
97+
98+
Normally, running `ps` in Nushell uses its **_internal_**, cross-platform command. However, it is still possible to run the **_external_**, system-dependent version on Unix/Linux platforms by prefacing it with the _caret sigil_. For example:
99+
100+
```nu
101+
^ps aux # run the Unix ps command with all processes in user-oriented form
102+
```
103+
104+
See [Running External System Commands](./running_externals.md) for more details.
105+
:::
106+
107+
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_:
108+
109+
```nu
110+
ps | where status == Running
111+
# => ╭───┬──────┬──────┬──────┬─────────┬──────┬──────────┬─────────╮
112+
# => │ # │ pid │ ppid │ name │ status │ cpu │ mem │ virtual │
113+
# => ├───┼──────┼──────┼──────┼─────────┼──────┼──────────┼─────────┤
114+
# => │ 0 │ 6585 │ 6584 │ nu │ Running │ 0.00 │ 31.9 MiB │ 1.2 GiB │
115+
# => ╰───┴──────┴──────┴──────┴─────────┴──────┴──────────┴─────────╯
116+
```
117+
118+
::: tip
119+
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.
120+
121+
You can examine the types for the table's columns using:
122+
123+
```nu
124+
ps | describe
125+
# => table<pid: int, ppid: int, name: string, status: string, cpu: float, mem: filesize, virtual: filesize> (stream)
126+
```
127+
128+
The [`describe` command](/commands/docs/describe.md) can be used to display the output type of any command or expression.
129+
130+
:::
131+
132+
## Command Arguments in a Pipeline
133+
134+
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:
135+
136+
```nu:line-numbers
137+
ls
138+
| sort-by size
139+
| reverse
140+
| first
141+
| get name
142+
| cp $in ~
143+
```
144+
145+
::: tip Nushell Design Note
146+
Whenever possible, Nushell commands are designed to act on pipeline _input_. However, some commands, like `cp` in this example, have two (or more)
147+
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
148+
more ergonomic with two _positional parameters_.
149+
:::
150+
151+
::: tip
152+
Nushell commands can extend across multiple lines for readability. The above is the same as:
153+
154+
```nu
155+
ls | sort-by size | reverse | first | get name | cp $in ~
156+
```
157+
158+
:::
159+
160+
The first three lines are the same commands we used in the second example above, so let's examine the last three:
8161

9-
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.
162+
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.
163+
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.
164+
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"_
10165

11-
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.
166+
::: tip
167+
[`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
168+
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.
169+
:::
12170

13-
@[code](@snippets/introduction/ls_sort_by_reverse_example.sh)
171+
## Getting Help
14172

15-
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).
173+
Nushell provides an extensive, in-shell Help system. For example
16174

17-
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:
175+
```nu
176+
# help <command>
177+
help ls
178+
# Or
179+
ls --help
180+
# Also
181+
help operators
182+
help escapes
183+
```
18184

19-
@[code](@snippets/introduction/ls_where_example.sh)
185+
::: tip Cool!
186+
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_!
20187

21-
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:
188+
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
189+
the example will be entered at the commandline, ready to run!
22190

23-
@[code](@snippets/introduction/ps_example.sh)
191+
This can be a great way to explore and learn about the extensive set of Nushell commands.
192+
:::
24193

25-
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.
194+
The Help system also has a "search" feature:
26195

27-
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:
196+
```nu
197+
help --find filesize
198+
# or
199+
help -f filesize
200+
```
28201

29-
@[code](@snippets/introduction/ps_where_example.sh)
202+
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.
30203

31-
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.
204+
The Help for each command is stored as a record with the:
32205

33-
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.
206+
- Name
207+
- Category
208+
- Type (built-in, plugin, custom)
209+
- Parameters it accepts
210+
- Signatures showing what types of data it can accept as well as output
211+
- And more
34212

35-
@[code](@snippets/introduction/help_commands_each_example.nu)
213+
You can view _all_ commands (other than externals) as a single large table using:
36214

37-
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:
215+
```nu
216+
help commands
217+
```
38218

39-
@[code](@snippets/introduction/help_commands_get_example.nu)
219+
::: tip
220+
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).
221+
:::
40222

41-
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.
223+
## `explore`'ing from Here
42224

43-
@[code](@snippets/introduction/help_commands_get_nested_example.nu)
225+
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:
44226

45-
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:
227+
```nu
228+
help commands | explore
229+
```
46230

47-
@[code](@snippets/introduction/help_commands_get_cell_path_example.nu)
231+
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
232+
telescope in to the complete list of parameters available to the `cp` command.
48233

49-
### Getting Help
234+
::: note
235+
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).
236+
:::
50237

51-
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>`.
238+
::: tip
239+
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.
52240

53-
@[code](@snippets/introduction/help_example.sh)
241+
Try `$env.config | explore` for fun!
242+
:::

0 commit comments

Comments
 (0)