Merge branch 'main' into plugin-use-docs

devyn · devyn · commit bb6392dc79ed · 2024-04-23T18:11:28.000-07:00
diff --git a/.vuepress/configs/sidebar/en.ts b/.vuepress/configs/sidebar/en.ts
@@ -42,7 +42,7 @@ export const sidebarEn: SidebarConfig = {
         '/book/custom_commands.md',
         '/book/aliases.md',
         '/book/operators.md',
-        '/book/variables_and_subexpressions.md',
+        '/book/variables.md',
         '/book/control_flow.md',
         '/book/scripts.md',
         '/book/modules.md',
diff --git a/blog/2021-02-16-nushell_0_27.md b/blog/2021-02-16-nushell_0_27.md
@@ -32,7 +32,7 @@ The Nushell book received some much-needed updates. You'll notice new chapters a
 - [Updated section on data types](https://www.nushell.sh/book/types_of_data.html)
 - [A new section on creating your own commands](https://www.nushell.sh/book/custom_commands.html)
 - [An updated section on aliases](https://www.nushell.sh/book/aliases.html)
-- [A new section on working with variables and expressions](https://www.nushell.sh/book/variables_and_subexpressions.html)
+- [A new section on working with variables and expressions](https://www.nushell.sh/book/variables.html)
 - [The start of a new section on writing your own Nushell scripts](https://www.nushell.sh/book/scripts.html)
 
 # Improvements
diff --git a/blog/2023-06-27-road-to-1_0.md b/blog/2023-06-27-road-to-1_0.md
@@ -13,7 +13,7 @@ Today we release the 0.82 version of Nushell. Not only will it be our 65th publi
 
 Nushell reached a much wider user base in the last few months. On GitHub, Nushell is now officially recognized for [syntax highlighting](https://github.com/github-linguist/linguist/releases/tag/v7.26.0) and recently passed 25,000 stars. We are also actively thinking about how we want to move towards stabilization for our 1.0 release.
 
-Thus, we want to use this opportunity to share our general thoughts and announce that we will be slightly slowing down our regular release schedule. 
+Thus, we want to use this opportunity to share our general thoughts and announce that we will be slightly slowing down our regular release schedule.
 Our focus going forward will be getting Nushell to a high-quality 1.0, one that has a supported language that is reliable and backward-compatible, and a high-quality shell experience to match.
 
 ## A four-week release schedule
@@ -35,11 +35,11 @@ Apart from rewriting the engine, it included our own line editor [reedline](http
 The rewrite unlocked many improvements and opportunities for valuable experimentation.
 
 Since `0.60`, we achieved a much more mature system of [modules](https://www.nushell.sh/book/modules.html) and [overlays](https://www.nushell.sh/book/overlays.html) that allow you to build more composable applications in Nu.
-As part of this effort to strengthen the programming language chops of Nu, we also spent a lot of time finding the balance between our [functional programming philosophy of pipelined data](https://www.nushell.sh/book/thinking_in_nu.html) and the [mutation of variables](https://www.nushell.sh/book/variables_and_subexpressions.html#mutable-variables) to allow simple imperative patterns.
+As part of this effort to strengthen the programming language chops of Nu, we also spent a lot of time finding the balance between our [functional programming philosophy of pipelined data](https://www.nushell.sh/book/thinking_in_nu.html) and the [mutation of variables](https://www.nushell.sh/book/variables.html#mutable-variables) to allow simple imperative patterns.
 
 We also saw a few efforts that didn't pan out yet. For example, we tried to integrate the [Polars](https://github.com/pola-rs/polars/) dataframe engine directly into the grammar of Nushell commands, but this left many rough edges. Thus [with version 0.76, we returned to a simpler dataframe integration](https://www.nushell.sh/blog/2023-02-21-nushell_0_76.html#dataframe-commands-are-again-explicitly-separated-from-core-nushell-commands-7998) to focus on getting the core Nushell experience right.
 
-This all provided valuable lessons in how we decide which features are beginning to settle and where we need to focus our effort to get a consistent experience. 
+This all provided valuable lessons in how we decide which features are beginning to settle and where we need to focus our effort to get a consistent experience.
 
 ## What we are working on right now
 
@@ -66,7 +66,7 @@ Achieving stability will not be possible without all of you that have dedicated
 
 We want to incorporate you in formulating the priorities for the 1.0 release by reaching out to folks interested in particular problems to get clearer roadmaps for specific areas. Those write-ups will hopefully also provide some inspiration for folks interested in helping out and pushing Nushell forward.
 
-But setting our sights on reaching the stable 1.0 release will also impose some limitations on our development practices. We are now much less likely to accept new features, commands, or options as they need to work well together with the larger picture. 
+But setting our sights on reaching the stable 1.0 release will also impose some limitations on our development practices. We are now much less likely to accept new features, commands, or options as they need to work well together with the larger picture.
 A lot of effort will still need to go into cleaning up the internals and fixing bugs. As we want to systematically improve our binary size, compile times, and runtime performance, improving existing algorithms and paying back technical debt will be prioritized over experimental stuff.
 Any external dependencies will also come under much more scrutiny.
 This means, to reduce the total number of crates we will seek to replace redundant or mostly superfluous dependencies with fewer high-quality implementations and also severely restrict the addition of any new dependencies.
diff --git a/book/cheat_sheet.md b/book/cheat_sheet.md
@@ -412,7 +412,7 @@
 
 > **custom command which takes any number of positional arguments using rest params**
 
-## Variables & Subexpressions
+## Variables
 
 ```nu
     > let val = 42
@@ -475,10 +475,10 @@
 
 ```nu
     > let big_files = (ls | where size > 10kb)
-    >  $big_files
+    > $big_files
 ```
 
-> **using subexp­ression by wrapping the expression with parent­heses ()**
+> **assigning the result of a pipeline to a variable**
 
 ---
 
diff --git a/book/control_flow.md b/book/control_flow.md
@@ -3,7 +3,7 @@
 Nushell provides several commands that help determine how different groups of code are executed. In programming languages this functionality is often referred to as _control flow_.
 
 ::: tip
-One thing to note is that all of the commands discussed on this page use [blocks](/book/types_of_data.html#blocks). This means you can mutate [environmental variables](/book/environment.html) and other [mutable variables](http://localhost:8080/book/variables_and_subexpressions.html#mutable-variables) in them.
+One thing to note is that all of the commands discussed on this page use [blocks](/book/types_of_data.html#blocks). This means you can mutate [environmental variables](/book/environment.html) and other [mutable variables](/book/variables.html#mutable-variables) in them.
 :::
 
 ## Already covered
diff --git a/book/environment.md b/book/environment.md
@@ -80,7 +80,7 @@ Individual environment variables are fields of a record that is stored in the `$
 BAR
 ```
 
-Sometimes, you may want to access an environmental variable which might be unset. Consider using the [question mark operator](variables_and_subexpressions.md#variable-paths) to avoid an error:
+Sometimes, you may want to access an environmental variable which might be unset. Consider using the [question mark operator](types_of_data.md#optional-cell-paths) to avoid an error:
 ```nu
 > $env.FOO | describe
 Error: nu::shell::column_not_found
@@ -234,7 +234,7 @@ _(Important! The environment conversion string -> value happens **after** the en
 
 ## Removing environment variables
 
-You can remove an environment variable only if it was set in the current scope via [`hide-env`](/commands/docs/hide_env.md):
+You can remove an environment variable only if it was set in the current scope via [`hide-env`](/commands/docs/hide-env.md):
 
 ```nu
 > $env.FOO = 'BAR'
diff --git a/book/loading_data.md b/book/loading_data.md
@@ -184,7 +184,6 @@ There are other commands you can use to work with strings:
 
 - [`str`](/commands/docs/str.md)
 - [`lines`](/commands/docs/lines.md)
-- [`size`](/commands/docs/size.md)
 
 There is also a set of helper commands we can call if we know the data has a structure that Nu should be able to understand. For example, let's open a Rust lock file:
 
diff --git a/book/overlays.md b/book/overlays.md
@@ -67,7 +67,7 @@ In the following sections, the `>` prompt will be preceded by the name of the la
 
 ## Removing an Overlay
 
-If you don't need the overlay definitions anymore, call [`overlay hide`](/commands/docs/overlay_remove.md):
+If you don't need the overlay definitions anymore, call [`overlay hide`](/commands/docs/overlay_hide.md):
 
 ```nu
 (spam)> overlay hide spam
@@ -94,7 +94,7 @@ foo
 ───┴──────
 ```
 
-The last way to remove an overlay is to call [`overlay hide`](/commands/docs/overlay_remove.md) without an argument which will remove the last active overlay.
+The last way to remove an overlay is to call [`overlay hide`](/commands/docs/overlay_hide.md) without an argument which will remove the last active overlay.
 
 ## Overlays Are Recordable
 
diff --git a/book/pipelines.md b/book/pipelines.md
@@ -25,18 +25,16 @@ The `$in` variable will collect the pipeline into a value for you, allowing you
 
 ## Multi-line pipelines
 
-If a pipeline is getting a bit long for one line, you can enclose it within `(` and `)` to create a subexpression:
+If a pipeline is getting a bit long for one line, you can enclose it within parentheses `()`:
 
 ```nu
-(
+let year = (
     "01/22/2021" |
     parse "{month}/{day}/{year}" |
     get year
 )
 ```
 
-Also see [Subexpressions](https://www.nushell.sh/book/variables_and_subexpressions.html#subexpressions)
-
 ## Semicolons
 
 Take this example:
diff --git a/book/programming_in_nu.md b/book/programming_in_nu.md
@@ -11,7 +11,8 @@ Nushell's aliases work in a similar way and are a part of the programming langua
 Common operations can, such as addition or regex search, be done with [operators](operators.md).
 Not all operations are supported for all data types and Nushell will make sure to let you know.
 
-You can store intermediate results to [variables](variables_and_subexpressions.md) and immediately evaluate subroutines with [subexpressions](variables_and_subexpressions.html#subexpressions).
+You can store intermediate results to [variables](variables.md).
+Variables can be immutable, mutable, or a parse-time constant.
 
 The last three sections are aimed at organizing your code:
 
diff --git a/book/stdout_stderr_exit_codes.md b/book/stdout_stderr_exit_codes.md
@@ -20,12 +20,6 @@ Without the pipeline, Nushell will not do any redirection, allowing it to print
 
 Another common stream that external applications often use to print error messages is stderr. By default, Nushell does not do any redirection of stderr, which means that by default it will print to the screen.
 
-You can force Nushell to do a redirection by using `do { ... } | complete`. For example, if we wanted to call the external above and redirect its stderr, we would write:
-
-```nu
-> do { external } | complete
-```
-
 ## Exit code
 
 Finally, external commands have an "exit code". These codes help give a hint to the caller whether the command ran successfully.
@@ -37,7 +31,7 @@ Nushell tracks the last exit code of the recently completed external in one of t
 > $env.LAST_EXIT_CODE
 ```
 
-The second uses a command called [`complete`](/commands/docs/complete.md).
+The second way is to use the [`complete`](/commands/docs/complete.md) command.
 
 ## Using the [`complete`](/commands/docs/complete.md) command
 
@@ -46,7 +40,7 @@ The [`complete`](/commands/docs/complete.md) command allows you to run an extern
 If we try to run the external `cat` on a file that doesn't exist, we can see what [`complete`](/commands/docs/complete.md) does with the streams, including the redirected stderr:
 
 ```nu
-> do { cat unknown.txt } | complete
+> cat unknown.txt | complete
 ╭───────────┬─────────────────────────────────────────────╮
 │ stdout    │                                             │
 │ stderr    │ cat: unknown.txt: No such file or directory │
@@ -72,20 +66,59 @@ The log level for output can be set with the `NU_LOG_LEVEL` environment variable
 NU_LOG_LEVEL=DEBUG nu std_log.nu
 ```
 
-## Using `out>`, `err>` to redirect stdout and stderr to files
+## File redirections
 
-If you want to redirect output to file, you can just type something like this:
+If you want to redirect stdout of an external command to a file, you can use `out>` followed by a file path. Similarly, you can use `err>` to redirect stderr:
 
 ```nu
 cat unknown.txt out> out.log err> err.log
 ```
 
-If you want to redirect both stdout and stderr to the same file, just type something like this:
+If you want to redirect both stdout and stderr to the same file, you can use `out+err>`:
 
 ```nu
 cat unknown.txt out+err> log.log
 ```
 
+Note that `out` can be shortened to just `o`, and `err` can be shortened to just `e`. So, the following examples are equivalent to the previous ones above:
+```nu
+cat unknown.txt o> out.log e> err.log
+
+cat unknown.txt o+e> log.log
+```
+
+Also, any expression can be used for the file path, as long as it is a string value:
+```nu
+use std
+cat unknown.txt o+e> (std null-device)
+```
+
+Note that file redirections are scoped to an expression and apply to all external commands in the expression. In the example below, `out.txt` will contain `hello\nworld`:
+```nu
+let text = "hello\nworld"
+($text | head -n 1; $text | tail -n 1) o> out.txt
+```
+Pipes and additional file redirections inside the expression will override any file redirections applied from the outside.
+
+## Pipe redirections
+
+If a regular pipe `|` comes after an external command, it redirects the stdout of the external command as input to the next command. To instead redirect the stderr of the external command, you can use the stderr pipe, `err>|` or `e>|`:
+
+```nu
+cat unknown.txt e>| str upcase
+```
+
+Of course, there is a corresponding pipe for combined stdout and stderr, `out+err>|` or `o+e>|`:
+
+```nu
+nu -c 'print output; print -e error' o+e>| str upcase
+```
+
+Unlike file redirections, pipe redirections do not apply to all commands inside an expression. Rather, only the last command in the expression is affected. For example, only `cmd2` in the snippet below will have its stdout and stderr redirected by the pipe.
+```nu
+(cmd1; cmd2) o+e>| cmd3
+```
+
 ## Raw streams
 
 Both stdout and stderr are represented as "raw streams" inside of Nushell. These are streams of bytes rather than structured data, which are what internal Nushell commands use.
diff --git a/book/table_of_contents.md b/book/table_of_contents.md
@@ -2,20 +2,20 @@
 
 - [Installation](installation.md) - Installing Nushell
 - [Introduction](README.md) - Getting started
-- [Thinking in Nushell](thinking_in_nushell.md) - Thinking in Nushell
+- [Thinking in Nu](thinking_in_nu.md) - Thinking in Nushell
 - [Moving around](moving_around.md) - Moving around in Nushell
 - [Types of data](types_of_data.md) - Types of data in Nushell
 - [Loading data](loading_data.md) - Loading data and using it
 - [Strings](working_with_strings.md) - Strings, escape characters, and string interpolation
 - [Working with lists](working_with_lists.md) - Working with Nu lists
 - [Working with tables](working_with_tables.md) - Working with Nu tables
-- [Pipeline](pipeline.md) - How the pipeline works
+- [Pipelines](pipelines.md) - How the pipeline works
 - [Configuration](configuration.md) - How to configure Nushell
 - [3rd Party Prompts](3rdpartyprompts.md) - How to configure 3rd party prompts
 - [Custom commands](custom_commands.md) - Creating your own commands
 - [Aliases](aliases.md) - How to alias commands
 - [Operators](operators.md) - Operators supported by Nushell
-- [Variables and subexpressions](variables_and_subexpressions.md) - Working with variables and working with subexpressions
+- [Variables](variables.md) - Working with variables
 - [Control flow](control_flow.md) - Working with the control flow commands
 - [Environment](environment.md) - Working with environment variables
 - [Stdout, stderr, and exit codes](stdout_stderr_exit_codes.md) - Working with stdout, stderr, and exit codes
diff --git a/book/thinking_in_nu.md b/book/thinking_in_nu.md
@@ -51,7 +51,7 @@ Another common issue is trying to dynamically create the filename to source from
 This doesn't work if `my_path` is a regular runtime variable declared with `let`. This would require the
 evaluator to run and evaluate the string, but unfortunately Nushell needs this information at compile-time.
 
-However, if `my_path` is a [constant](/book/variables_and_subexpressions#constant-variables), then this
+However, if `my_path` is a [constant](/book/variables#constant-variables), then this
 would work, since the string can be evaluated at compile-time:
 
 ```nu
diff --git a/book/types_of_data.md b/book/types_of_data.md
@@ -404,7 +404,7 @@ Moreover, you can also access entire columns of a table by name, to obtain lists
 ╰───┴────╯
 ```
 
-Of course, these resulting lists don't have the column names of the table. To remove columns from a table while leaving it as a table, you'll commonly use the [`select`](/commands/docs/select.md) command with column names:
+Of course, these resulting lists don't have the column names of the table. To choose columns from a table while leaving it as a table, you'll commonly use the [`select`](/commands/docs/select.md) command with column names:
 
 ```nu
 > [{x:0 y:5 z:1} {x:4 y:7 z:3} {x:2 y:2 z:0}] | select y z
@@ -417,7 +417,7 @@ Of course, these resulting lists don't have the column names of the table. To re
 ╰───┴───┴───╯
 ```
 
-To remove rows from a table, you'll commonly use the [`select`](/commands/docs/select.md) command with row numbers, as you would with a list:
+To get specific rows from a table, you'll commonly use the [`select`](/commands/docs/select.md) command with row numbers, as you would with a list:
 
 ```nu
 > [{x:0 y:5 z:1} {x:4 y:7 z:3} {x:2 y:2 z:0}] | select 1 2
diff --git a/book/variables.md b/book/variables.md
diff --git a/book/variables_and_subexpressions.md b/book/variables_and_subexpressions.md
diff --git a/book/working_with_tables.md b/book/working_with_tables.md
diff --git a/i18n-meta.json b/i18n-meta.json
