Skip to content

Commit c6af9c9

Browse files
NotTheDr01dsNotTheDr01ds
committed
Quick Tour chapter update
1 parent c7f8c45 commit c6af9c9

File tree

1 file changed

+193
-24
lines changed

1 file changed

+193
-24
lines changed

‎book/quick_tour.md‎

Lines changed: 193 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -1,53 +1,222 @@
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+
99+
What if we wanted to show the processes that were actively running? Just as we did with `ls` above, we can also work with the table that `ps` _outputs_:
100+
101+
```nu
102+
ps | where status == Running
103+
# => ╭───┬──────┬──────┬──────┬─────────┬──────┬──────────┬─────────╮
104+
# => │ # │ pid │ ppid │ name │ status │ cpu │ mem │ virtual │
105+
# => ├───┼──────┼──────┼──────┼─────────┼──────┼──────────┼─────────┤
106+
# => │ 0 │ 6585 │ 6584 │ nu │ Running │ 0.00 │ 31.9 MiB │ 1.2 GiB │
107+
# => ╰───┴──────┴──────┴──────┴─────────┴──────┴──────────┴─────────╯
108+
```
109+
110+
::: tip
111+
Remember above, where the `size` column from the `ls` command was a `filesize`? In this case, `status` may look like an "enum" type from some programming languages,
112+
but here it's really a normal `string`.
113+
114+
You can examine the types for the table's columns using:
115+
116+
```nu
117+
ps | describe
118+
# => table<pid: int, ppid: int, name: string, status: string, cpu: float, mem: filesize, virtual: filesize> (stream)
119+
```
120+
121+
:::
122+
123+
## Command Arguments in a Pipeline
124+
125+
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:
126+
127+
```nu:line-numbers
128+
ls
129+
| sort-by size
130+
| reverse
131+
| first
132+
| get name
133+
| cp $in ~
134+
```
135+
136+
::: tip
137+
Nushell commands can extend across multiple lines for readability. The above is the same as:
138+
139+
```nu
140+
ls | sort-by size | reverse | first | get name | cp $in ~
141+
```
142+
143+
:::
8144

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.
145+
The first three lines are the same commands we used in the second example above, so let's examine the last three:
10146

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.
147+
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.
148+
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.
149+
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"_
12150

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

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

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:
155+
```nu
156+
# help <command>
157+
help ls
158+
# Or
159+
ls --help
160+
# Also
161+
help operators
162+
help escapes
163+
```
18164

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

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:
168+
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
169+
the example will be entered at the commandline, ready to run!
22170

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

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

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:
176+
```nu
177+
help --find filesize
178+
# or
179+
help -f filesize
180+
```
28181

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

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.
184+
The Help for each command is stored as a record with:
32185

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.
186+
- Its name
187+
- Category
188+
- Type (built-in, plugin, custom)
189+
- The parameters it accepts
190+
- Signatures showing what types of data it can accept as well as output
191+
- And more
34192

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

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:
195+
```nu
196+
help commands
197+
```
38198

39-
@[code](@snippets/introduction/help_commands_get_example.nu)
199+
::: tip
200+
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).
201+
:::
40202

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.
203+
## `explore`'ing from Here
42204

43-
@[code](@snippets/introduction/help_commands_get_nested_example.nu)
205+
Of course, that `help commands` output is quite long. You could send it to a pager less `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:
44206

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:
207+
```
208+
help commands | explore
209+
```
46210

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

49-
### Getting Help
214+
::: note
215+
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).
216+
:::
50217

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>`.
218+
::: tip
219+
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.
52220

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

0 commit comments

Comments
 (0)