Lang guide refactor (#1403)

* Refactor monolithic Language Guide into smaller files

* Removed old lang-ref file; additional minor fixes

.vuepress/configs/sidebar/en.ts

@@ -157,7 +157,96 @@ export const sidebarEn: SidebarConfig = {
  text: 'Language Reference Guide',
  link: '/lang-guide/README.md',
  collapsible: false,
- children: ['/lang-guide/README.md', '/lang-guide/lang-guide.md'],
+ children: [
+ '/lang-guide/README.md',
+ {
+ text: 'Types in the Nu Language',
+ link: '/lang-guide/chapters/types/00_types_overview.md',
+ collapsible: true,
+ children: [
+ {
+ text: 'Basic Types',
+ link: '/lang-guide/chapters/types/basic_types/00_basic_types.md',
+ collapsible: true,
+ children: [
+ '/lang-guide/chapters/types/basic_types/any.md',
+ '/lang-guide/chapters/types/basic_types/bool.md',
+ '/lang-guide/chapters/types/basic_types/int.md',
+ '/lang-guide/chapters/types/basic_types/float.md',
+ '/lang-guide/chapters/types/basic_types/filesize.md',
+ '/lang-guide/chapters/types/basic_types/duration.md',
+ '/lang-guide/chapters/types/basic_types/date.md',
+ '/lang-guide/chapters/types/basic_types/range.md',
+ '/lang-guide/chapters/types/basic_types/string.md',
+ '/lang-guide/chapters/types/basic_types/record.md',
+ '/lang-guide/chapters/types/basic_types/list.md',
+ '/lang-guide/chapters/types/basic_types/table.md',
+ '/lang-guide/chapters/types/basic_types/closure.md',
+ '/lang-guide/chapters/types/basic_types/nothing.md',
+ '/lang-guide/chapters/types/basic_types/binary.md',
+ '/lang-guide/chapters/types/basic_types/glob.md',
+ '/lang-guide/chapters/types/basic_types/cellpath.md',
+ ],
+ },
+ {
+ text: 'Other Data Types',
+ collapsible: true,
+ children: [
+ {
+ text: 'Types that cannot be used to declare variables',
+ link: '/lang-guide/chapters/types/other_types/00_not_assignable.md',
+ children: ['/lang-guide/chapters/types/other_types/path.md'],
+ },
+ {
+ text: 'Types which are not declarable',
+ link: '/lang-guide/chapters/types/other_types/01_not_declarable.md',
+ children: [
+ '/lang-guide/chapters/types/other_types/lazy_record.md',
+ '/lang-guide/chapters/types/other_types/error.md',
+ '/lang-guide/chapters/types/other_types/custom_value.md',
+ '/lang-guide/chapters/types/other_types/block.md',
+ ],
+ },
+ ],
+ },
+ '/lang-guide/chapters/types/type_signatures.md',
+ '/lang-guide/chapters/types/related_commands.md',
+ ],
+ },
+ '/lang-guide/chapters/operators.md',
+ {
+ text: 'Flow control',
+ link: '/lang-guide/chapters/flow_control/00_flow_control_overview.md',
+ collapsible: true,
+ children: [
+ '/lang-guide/chapters/flow_control/if-else.md',
+ '/lang-guide/chapters/flow_control/loop.md',
+ '/lang-guide/chapters/flow_control/while.md',
+ '/lang-guide/chapters/flow_control/match.md',
+ '/lang-guide/chapters/flow_control/try-catch.md',
+ '/lang-guide/chapters/flow_control/break.md',
+ '/lang-guide/chapters/flow_control/return.md',
+ '/lang-guide/chapters/flow_control/continue.md',
+ ],
+ },
+ {
+ text: 'Filters',
+ link: '/lang-guide/chapters/filters/00_filters_overview.md',
+ collapsible: true,
+ children: [
+ '/lang-guide/chapters/filters/each-par-each.md',
+ '/lang-guide/chapters/filters/selecting_data.md',
+ '/lang-guide/chapters/filters/where-filter.md',
+ '/lang-guide/chapters/filters/select-get.md',
+ ],
+ },
+ '/lang-guide/chapters/custom_commands.md',
+ '/lang-guide/chapters/declarations.md',
+ '/lang-guide/chapters/variable_scope.md',
+ '/lang-guide/chapters/strings_and_text.md',
+ '/lang-guide/chapters/helpers_and_debugging.md',
+ '/lang-guide/chapters/pipelines.md',
+ ],
  },
  ],
 };

lang-guide/chapters/custom_commands.md

@@ -0,0 +1,11 @@
+# Custom Commands
+
+## Defining Custom Commands
+
+## Calling Custom Commands
+
+## Function Scope
+
+## Closures
+
+## Arguments & Parameters

lang-guide/chapters/declarations.md

@@ -0,0 +1,3 @@
+# Declarations
+
+TODO - `let`, `mut`, `const` and others

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

@@ -0,0 +1,52 @@
+# Filters
+
+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.
+
+A sample of filter commands is listed in this Guide below. For the current list of commands categorized as filters, you can run:
+
+```nu
+help commands | where category == filters
+```
+
+## Filters vs. Flow Control Statements
+
+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.
+
+For example:
+
+- Using a `for` statement to create a list of 50,000 random numbers:
+
+ ```nu
+ timeit {
+ mut randoms = []
+ for _ in 1..50_000 {
+ $randoms = ($randoms | append (random int))
+ }
+ }
+ ```
+
+ Result: 1min 4sec 191ms 135µs 90ns
+
+- Using `each` to do the same:
+
+ ```nu
+ timeit {
+ let randoms = (1..50_000 | each {random int})
+ }
+ ```
+
+ Result: 19ms 314µs 205ns
+
+- Using `each` with 10,000,000 iterations:
+
+ ```nu
+ timeit {
+ let randoms = (1..10_000_000 | each {random int})
+ }
+ ```
+
+ Result: 4sec 233ms 865µs 238ns
+
+ 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.
+
+ 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

@@ -0,0 +1,39 @@
+# `each` and `par-each`
+
+TODO: Provide detail on the `each` command set
+
+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.
+
+Example:
+
+```nu
+ls
+| get 0
+| transpose key value
+| inspect
+| each {|kv|
+ $'The value of the "($kv.key) field is "($kv.value)"'
+ }
+```
+
+Result:
+
+```nu
+╭─────────────┬──────────────────────────────────╮
+│ description │ list<any> │
+├──────────┬──┴──────────────────────────────────┤
+│ key │ value │
+├──────────┼─────────────────────────────────────┤
+│ name │ CNAME │
+│ type │ file │
+│ size │ 15 │
+│ modified │ 2024-01-31T10:21:46.068408713-05:00 │
+╰──────────┴─────────────────────────────────────╯
+
+╭───┬──────────────────────────────────────────────────────────────────────────────────────╮
+│ 0 │ The value of the "name field is "CNAME" │
+│ 1 │ The value of the "type field is "file" │
+│ 2 │ The value of the "size field is "15 B" │
+│ 3 │ The value of the "modified field is "Wed, 31 Jan 2024 10:21:46 -0500 (3 months ago)" │
+╰───┴──────────────────────────────────────────────────────────────────────────────────────╯
+```

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

@@ -0,0 +1,3 @@
+# Understanding the difference between `get` and `select`
+
+TODO

lang-guide/chapters/filters/selecting_data.md

@@ -0,0 +1,3 @@
+# Filters to select subsets of data
+
+TODO: `first`/`skip`/`select`/`get`/ cell-paths / `range` and other topics

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

@@ -0,0 +1,3 @@
+# `where` and `filter`
+
+TODO

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

@@ -0,0 +1,15 @@
+---
+next: ./if-else.md
+---
+
+# Flow Control
+
+Nushell includes a number of flow control statements and expressions similar to other languages.
+
+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.
+
+See:
+
+```nu
+help commands | where category == filter
+```

lang-guide/chapters/flow_control/break.md

@@ -0,0 +1,3 @@
+# `break`
+
+_TODO_ - If you can provide detailed information on this command, beyond what is available in the Help, please consider contributing. Click below to ...

lang-guide/chapters/flow_control/continue.md

@@ -0,0 +1,3 @@
+# `continue`
+
+_TODO_ - If you can provide detailed information on this command, beyond what is available in the Help, please consider contributing. Click below to ...

lang-guide/chapters/flow_control/if-else.md

@@ -0,0 +1,27 @@
+# if/else
+
+The `if` expression evaluates a condition and then chooses to run a block based on the condition.
+
+For example, you can print "yes", based on a true condition:
+
+```nu
+if true {
+ print yes
+} else {
+ print no
+}
+```
+
+Alternately, you can print "no", based on a false condition:
+
+```nu
+if false {
+ print yes
+} else {
+ print no
+}
+```
+
+The `else` part of `if` is optional. If not provided, if a condition is false, the `if` expression returns `null`.
+
+The code that follows the `else` is an expression rather than a block, allowing any number of follow-on `if` expressions as well as other types of expressions. For example, this expression returns 100: `if false { 1 } else 100`.

lang-guide/chapters/flow_control/loop.md

@@ -0,0 +1,5 @@
+# `loop`
+
+See the [`loop` Help](/commands/docs/loop.html).
+
+_TODO_ - If you can provide detailed information on this command, beyond what is available in the Help, please consider contributing. Click below to ...

lang-guide/chapters/flow_control/match.md

@@ -0,0 +1,3 @@
+# `match`
+
+_TODO_ - If you can provide detailed information on this command, beyond what is available in the Help, please consider contributing. Click below to ...

lang-guide/chapters/flow_control/return.md

@@ -0,0 +1,3 @@
+# `return`
+
+_TODO_ - If you can provide detailed information on this command, beyond what is available in the Help, please consider contributing. Click below to ...

lang-guide/chapters/flow_control/try-catch.md

@@ -0,0 +1,3 @@
+# `try`/`catch`
+
+_TODO_ - If you can provide detailed information on this command, beyond what is available in the Help, please consider contributing. Click below to ...

lang-guide/chapters/flow_control/while.md

@@ -0,0 +1,5 @@
+# `while`
+
+See the [`while` Help](/commands/docs/while.html).
+
+_TODO_ - If you can provide detailed information on this command, beyond what is available in the Help, please consider contributing a PR. Click below to ...

lang-guide/chapters/functional_programming.md

@@ -0,0 +1,3 @@
+# Functional Programming Concepts in Nu
+
+Currently a placeholder file. Will not show up in sidebar until content is added and the file is added to `.vuepress/configs/sidebar`

lang-guide/chapters/helpers_and_debugging.md

@@ -0,0 +1,17 @@
+# Helpers and debugging commands
+
+TODO
+
+## debug
+
+## metadata
+
+## error make
+
+## inspect
+
+## scope
+
+## ast
+
+## others

lang-guide/chapters/metadata.md

@@ -0,0 +1,3 @@
+# Metadata
+
+Currently a placeholder file. Will not show up in sidebar until content is added and the file is added to `.vuepress/configs/sidebar`

lang-guide/chapters/operators.md

@@ -0,0 +1,50 @@
+# Operators
+
+## Arithmetic Operators
+
+- `+` - Plus / Addition
+- `-` - Minus / Subtraction
+- `*` - Multiply
+- `/` - Divide
+- `=` - Equal
+- `!=` - Not Equal
+- `//` - Floor Division
+- `<` - Less Than
+- `>` - Greater Than
+- `<=` - Less Than or Equal To
+- `>=` - Greater Than or Equal To
+- `mod` - Modulo
+- `**` - Pow
+
+## Bitwise Operators
+
+Nushell provides support for these bitwise operators:
+
+- `bit-or` - bitwise or
+- `bit-xor` - bitwise exclusive or
+- `bit-and` - bitwise and
+- `bit-shl` - bitwise shift left
+- `bit-shr` - bitwise shift right
+
+## Other operators
+
+- `=~` - Regex Match / Contains
+- `!~` - Not Regex Match / Not Contains
+- `in` - In / Contains (doesn't use regex)
+- `not-in` - Not In / Not Contains (doesn't use regex)
+- `starts-with` - Starts With
+- `ends-with` - Ends With
+- `&&` - And
+- `and` - And
+- `||` - Or
+- `or` - Or
+
+## Brackets
+
+TODO
+
+### `(` and `)`
+
+### `[` and `]`
+
+### `{` and `}`