Skip to content

Commit 4b8030e

Browse files
IanManskeIanManske
committed
Rework structured data examples
1 parent 5048dd2 commit 4b8030e

File tree

5 files changed

+52
-24
lines changed

5 files changed

+52
-24
lines changed

‎book/quick_tour.md

Lines changed: 10 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -28,40 +28,26 @@ What if we wanted to show the processes that were actively using the CPU? Just l
2828

2929
@[code](@snippets/introduction/ps_where_example.sh)
3030

31-
So far, we've been using [`ls`](/commands/docs/ls.md) and [`ps`](/commands/docs/ps.md) to list files and processes. Nu also offers other commands that can create tables of useful information. Next, let's explore [`date`](/commands/docs/date.md) and [`sys`](/commands/docs/sys.md).
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.
3232

33-
Running [`date now`](/commands/docs/date_now.md) gives us information about the current day and time:
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.
3434

35-
@[code](@snippets/introduction/date_example.sh)
35+
@[code](@snippets/introduction/help_commands_each_example.nu)
3636

37-
To get the date as a table we can feed it into [`date to-table`](/commands/docs/date_to-table.md)
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:
3838

39-
@[code](@snippets/introduction/date_table_example.sh)
39+
@[code](@snippets/introduction/help_commands_get_example.nu)
4040

41-
Running [`sys host`](/commands/docs/sys_host.md) gives information about the system that Nu is running on:
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.
4242

43-
@[code](@snippets/introduction/sys_host_example.sh)
43+
@[code](@snippets/introduction/help_commands_get_nested_example.nu)
4444

45-
This is a bit different than the tables we saw before. The [`sys host`](/commands/docs/sys.md) command gives us a [record](/book/types_of_data.html#records), which is set of key-value pairs. Note that the "sessions" column in the record happens to contain a table instead of a simple value. To take a look at this data, we need to _get_ the column to view:
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:
4646

47-
@[code](@snippets/introduction/sys_get_example.sh)
48-
49-
The [`get`](/commands/docs/get.md) command lets us jump into the contents of structured data (a table, record, or list). Here, we're looking into the "sessions" column, which contains a table of the users on the system and their groups. Let's get the names of the users:
50-
51-
@[code](@snippets/introduction/sys_get_nested_example.sh)
52-
53-
Right now, there's just one user on the system named "sophiajt". You'll notice that we can pass nested columns (the `sessions.name` part) and not just the name of the column. These 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 the table.
54-
55-
You might have noticed something else that's different. Rather than having a table of data, we have just a single element: the string "sophiajt". Nu works with both tables of data as well as strings. Strings are an important part of working with commands outside of Nu.
56-
57-
Let's see how strings work outside of Nu in action. We'll take our example from before and run the external [`echo`](/commands/docs/echo.md) command (the `^` tells Nu to not use the built-in [`echo`](/commands/docs/echo.md) command):
58-
59-
@[code](@snippets/introduction/sys_get_external_echo_example.sh)
60-
61-
If this looks very similar to what we had before, you have a keen eye! It is similar, but with one important difference: we've called `^echo` with the value we saw earlier. This allows us to pass data out of Nu into [`echo`](/commands/docs/echo.md) (or any command outside of Nu, like `git` for example).
47+
@[code](@snippets/introduction/help_commands_get_cell_path_example.nu)
6248

6349
### Getting Help
6450

65-
Help text for any of Nu's built-in commands can be discovered with the [`help`](/commands/docs/help.md) command. To see all commands, run [`help commands`](/commands/docs/help_commands.md). You can also search for a topic by doing `help -f <topic>`.
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>`.
6652

6753
@[code](@snippets/introduction/help_example.sh)

‎snippets/introduction/help_commands_each_example.nu

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
> help commands | where name == each | first
2+
╭──────────────┬────────────────────────────────────────────────────────────────────────────────────────────────╮
3+
│ name │ each │
4+
│ category │ filters │
5+
│ command_type │ built-in │
6+
│ usage │ Run a closure on each row of the input list, creating a new list with the results. │
7+
│ │ ╭───┬──────────────────┬──────────────┬──────────┬───────────────────────────────────────────╮ │
8+
│ params │ │ # │ name │ type │ required │ description │ │
9+
│ │ ├───┼──────────────────┼──────────────┼──────────┼───────────────────────────────────────────┤ │
10+
│ │ │ 0 │ closure │ closure(any) │ true │ The closure to run. │ │
11+
│ │ │ 1 │ --help(-h) │ switch │ false │ Display the help message for this command │ │
12+
│ │ │ 2 │ --keep-empty(-k) │ switch │ false │ keep empty result cells │ │
13+
│ │ ╰───┴──────────────────┴──────────────┴──────────┴───────────────────────────────────────────╯ │
14+
│ │ ╭───┬───────────┬───────────╮ │
15+
│ input_output │ │ # │ input │ output │ │
16+
│ │ ├───┼───────────┼───────────┤ │
17+
│ │ │ 0 │ list<any> │ list<any> │ │
18+
│ │ │ 1 │ table │ list<any> │ │
19+
│ │ │ 2 │ any │ any │ │
20+
│ │ ╰───┴───────────┴───────────╯ │
21+
│ search_terms │ for, loop, iterate, map │
22+
╰──────────────┴────────────────────────────────────────────────────────────────────────────────────────────────╯

‎snippets/introduction/help_commands_get_cell_path_example.nu

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
> help commands | where name == each | get 0.params.name
2+
╭───┬──────────────────╮
3+
│ 0 │ closure │
4+
│ 1 │ --help(-h) │
5+
│ 2 │ --keep-empty(-k) │
6+
╰───┴──────────────────╯

‎snippets/introduction/help_commands_get_example.nu

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
> help commands | where name == each | first | get params
2+
╭───┬──────────────────┬──────────────┬──────────┬───────────────────────────────────────────╮
3+
│ # │ name │ type │ required │ description │
4+
├───┼──────────────────┼──────────────┼──────────┼───────────────────────────────────────────┤
5+
│ 0 │ closure │ closure(any) │ true │ The closure to run. │
6+
│ 1 │ --help(-h) │ switch │ false │ Display the help message for this command │
7+
│ 2 │ --keep-empty(-k) │ switch │ false │ keep empty result cells │
8+
╰───┴──────────────────┴──────────────┴──────────┴───────────────────────────────────────────╯

‎snippets/introduction/help_commands_get_nested_example.nu

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
> help commands | where name == each | first | get params.name
2+
╭───┬──────────────────╮
3+
│ 0 │ closure │
4+
│ 1 │ --help(-h) │
5+
│ 2 │ --keep-empty(-k) │
6+
╰───┴──────────────────╯

0 commit comments

Comments
 (0)