Skip to content

Commit 6504b17

Browse files
NotTheDr01dsNotTheDr01ds
authored
Lang guide refactor (#1403)
* Refactor monolithic Language Guide into smaller files * Removed old lang-ref file; additional minor fixes
1 parent a9622d1 commit 6504b17

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

54 files changed

+1803
-1584
lines changed

‎.vuepress/configs/sidebar/en.ts

Lines changed: 90 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -157,7 +157,96 @@ export const sidebarEn: SidebarConfig = {
157157
text: 'Language Reference Guide',
158158
link: '/lang-guide/README.md',
159159
collapsible: false,
160-
children: ['/lang-guide/README.md', '/lang-guide/lang-guide.md'],
160+
children: [
161+
'/lang-guide/README.md',
162+
{
163+
text: 'Types in the Nu Language',
164+
link: '/lang-guide/chapters/types/00_types_overview.md',
165+
collapsible: true,
166+
children: [
167+
{
168+
text: 'Basic Types',
169+
link: '/lang-guide/chapters/types/basic_types/00_basic_types.md',
170+
collapsible: true,
171+
children: [
172+
'/lang-guide/chapters/types/basic_types/any.md',
173+
'/lang-guide/chapters/types/basic_types/bool.md',
174+
'/lang-guide/chapters/types/basic_types/int.md',
175+
'/lang-guide/chapters/types/basic_types/float.md',
176+
'/lang-guide/chapters/types/basic_types/filesize.md',
177+
'/lang-guide/chapters/types/basic_types/duration.md',
178+
'/lang-guide/chapters/types/basic_types/date.md',
179+
'/lang-guide/chapters/types/basic_types/range.md',
180+
'/lang-guide/chapters/types/basic_types/string.md',
181+
'/lang-guide/chapters/types/basic_types/record.md',
182+
'/lang-guide/chapters/types/basic_types/list.md',
183+
'/lang-guide/chapters/types/basic_types/table.md',
184+
'/lang-guide/chapters/types/basic_types/closure.md',
185+
'/lang-guide/chapters/types/basic_types/nothing.md',
186+
'/lang-guide/chapters/types/basic_types/binary.md',
187+
'/lang-guide/chapters/types/basic_types/glob.md',
188+
'/lang-guide/chapters/types/basic_types/cellpath.md',
189+
],
190+
},
191+
{
192+
text: 'Other Data Types',
193+
collapsible: true,
194+
children: [
195+
{
196+
text: 'Types that cannot be used to declare variables',
197+
link: '/lang-guide/chapters/types/other_types/00_not_assignable.md',
198+
children: ['/lang-guide/chapters/types/other_types/path.md'],
199+
},
200+
{
201+
text: 'Types which are not declarable',
202+
link: '/lang-guide/chapters/types/other_types/01_not_declarable.md',
203+
children: [
204+
'/lang-guide/chapters/types/other_types/lazy_record.md',
205+
'/lang-guide/chapters/types/other_types/error.md',
206+
'/lang-guide/chapters/types/other_types/custom_value.md',
207+
'/lang-guide/chapters/types/other_types/block.md',
208+
],
209+
},
210+
],
211+
},
212+
'/lang-guide/chapters/types/type_signatures.md',
213+
'/lang-guide/chapters/types/related_commands.md',
214+
],
215+
},
216+
'/lang-guide/chapters/operators.md',
217+
{
218+
text: 'Flow control',
219+
link: '/lang-guide/chapters/flow_control/00_flow_control_overview.md',
220+
collapsible: true,
221+
children: [
222+
'/lang-guide/chapters/flow_control/if-else.md',
223+
'/lang-guide/chapters/flow_control/loop.md',
224+
'/lang-guide/chapters/flow_control/while.md',
225+
'/lang-guide/chapters/flow_control/match.md',
226+
'/lang-guide/chapters/flow_control/try-catch.md',
227+
'/lang-guide/chapters/flow_control/break.md',
228+
'/lang-guide/chapters/flow_control/return.md',
229+
'/lang-guide/chapters/flow_control/continue.md',
230+
],
231+
},
232+
{
233+
text: 'Filters',
234+
link: '/lang-guide/chapters/filters/00_filters_overview.md',
235+
collapsible: true,
236+
children: [
237+
'/lang-guide/chapters/filters/each-par-each.md',
238+
'/lang-guide/chapters/filters/selecting_data.md',
239+
'/lang-guide/chapters/filters/where-filter.md',
240+
'/lang-guide/chapters/filters/select-get.md',
241+
],
242+
},
243+
'/lang-guide/chapters/custom_commands.md',
244+
'/lang-guide/chapters/declarations.md',
245+
'/lang-guide/chapters/variable_scope.md',
246+
'/lang-guide/chapters/strings_and_text.md',
247+
'/lang-guide/chapters/helpers_and_debugging.md',
248+
'/lang-guide/chapters/pipelines.md',
249+
],
161250
},
162251
],
163252
};

‎lang-guide/chapters/custom_commands.md

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
# Custom Commands
2+
3+
## Defining Custom Commands
4+
5+
## Calling Custom Commands
6+
7+
## Function Scope
8+
9+
## Closures
10+
11+
## Arguments & Parameters

‎lang-guide/chapters/declarations.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
# Declarations
2+
3+
TODO - `let`, `mut`, `const` and others

‎lang-guide/chapters/filters/00_filters_overview.md

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
# Filters
2+
3+
A primary goal of Nushell is the ability to easily handle structured data in the pipeline. Nushell contains an extensive set of commands known as "filters" designed to meet these needs.
4+
5+
A sample of filter commands is listed in this Guide below. For the current list of commands categorized as filters, you can run:
6+
7+
```nu
8+
help commands | where category == filters
9+
```
10+
11+
## Filters vs. Flow Control Statements
12+
13+
While it's certainly possible to modify structured data using "traditional" flow control statements like `for` or `while`, filters are usually more convenient and (often far) more performant.
14+
15+
For example:
16+
17+
- Using a `for` statement to create a list of 50,000 random numbers:
18+
19+
```nu
20+
timeit {
21+
mut randoms = []
22+
for _ in 1..50_000 {
23+
$randoms = ($randoms | append (random int))
24+
}
25+
}
26+
```
27+
28+
Result: 1min 4sec 191ms 135µs 90ns
29+
30+
- Using `each` to do the same:
31+
32+
```nu
33+
timeit {
34+
let randoms = (1..50_000 | each {random int})
35+
}
36+
```
37+
38+
Result: 19ms 314µs 205ns
39+
40+
- Using `each` with 10,000,000 iterations:
41+
42+
```nu
43+
timeit {
44+
let randoms = (1..10_000_000 | each {random int})
45+
}
46+
```
47+
48+
Result: 4sec 233ms 865µs 238ns
49+
50+
As with many filters, the `each` statement also streams its results, meaning the next stage of the pipeline can continue processing without waiting for the results to be collected into a variable.
51+
52+
For tasks which can be optimized by parallelization, `par-each` can have even more drastic performance gains.

‎lang-guide/chapters/filters/each-par-each.md

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
# `each` and `par-each`
2+
3+
TODO: Provide detail on the `each` command set
4+
5+
Note: `each`/`par-each` only iterates over list/table data. To iterate over each key/value pair in a record, first pipe the record through `| transpose key value` to create a table of the keys/values.
6+
7+
Example:
8+
9+
```nu
10+
ls
11+
| get 0
12+
| transpose key value
13+
| inspect
14+
| each {|kv|
15+
$'The value of the "($kv.key) field is "($kv.value)"'
16+
}
17+
```
18+
19+
Result:
20+
21+
```nu
22+
╭─────────────┬──────────────────────────────────╮
23+
│ description │ list<any> │
24+
├──────────┬──┴──────────────────────────────────┤
25+
│ key │ value │
26+
├──────────┼─────────────────────────────────────┤
27+
│ name │ CNAME │
28+
│ type │ file │
29+
│ size │ 15 │
30+
│ modified │ 2024-01-31T10:21:46.068408713-05:00 │
31+
╰──────────┴─────────────────────────────────────╯
32+
33+
╭───┬──────────────────────────────────────────────────────────────────────────────────────╮
34+
│ 0 │ The value of the "name field is "CNAME" │
35+
│ 1 │ The value of the "type field is "file" │
36+
│ 2 │ The value of the "size field is "15 B" │
37+
│ 3 │ The value of the "modified field is "Wed, 31 Jan 2024 10:21:46 -0500 (3 months ago)" │
38+
╰───┴──────────────────────────────────────────────────────────────────────────────────────╯
39+
```

‎lang-guide/chapters/filters/select-get.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
# Understanding the difference between `get` and `select`
2+
3+
TODO

‎lang-guide/chapters/filters/selecting_data.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
# Filters to select subsets of data
2+
3+
TODO: `first`/`skip`/`select`/`get`/ cell-paths / `range` and other topics

‎lang-guide/chapters/filters/where-filter.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
# `where` and `filter`
2+
3+
TODO

‎lang-guide/chapters/flow_control/00_flow_control_overview.md

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
---
2+
next: ./if-else.md
3+
---
4+
5+
# Flow Control
6+
7+
Nushell includes a number of flow control statements and expressions similar to other languages.
8+
9+
However, keep in mind that many Nushell operations will be performed using structured data as input and/or output. While structured data can be created using flow control statements in conjunction with mutable variables, a better solution in these cases is to use Filters.
10+
11+
See:
12+
13+
```nu
14+
help commands | where category == filter
15+
```

‎lang-guide/chapters/flow_control/break.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
# `break`
2+
3+
_TODO_ - If you can provide detailed information on this command, beyond what is available in the Help, please consider contributing. Click below to ...

0 commit comments

Comments
 (0)