Update docs for 0.92.0 (file, pipes, and io) (#1352)

* Update docs for 0.92.0 (file, pipes, and io)

* Fix typo

* Update links

Author: IanManske

.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',

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

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.

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**
 
 ---
 

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

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

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:

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:
 

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.

book/table_of_contents.md

@@ -15,7 +15,7 @@
 - [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

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

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

book/variables.md

@@ -0,0 +1,93 @@
+# Variables
+
+Nushell values can be assigned to named variables using the `let`, `const`, or `mut` keywords.
+After creating a variable, we can refer to it using `$` followed by its name.
+
+## Types of Variables
+
+### Immutable Variables
+
+An immutable variable cannot change its value after declaration. They are declared using the `let` keyword,
+
+```nu
+> let val = 42
+> print $val
+42
+```
+
+However, they can be 'shadowed'. Shadowing means that they are redeclared and their initial value cannot be used anymore within the same scope.
+
+```nu
+> let val = 42                   # declare a variable
+> do { let val = 101;  $val }    # in an inner scope, shadow the variable
+101
+> $val                           # in the outer scope the variable remains unchanged
+42
+```
+
+### Mutable Variables
+
+A mutable variable is allowed to change its value by assignment. These are declared using the `mut` keyword.
+
+```nu
+> mut val = 42
+> $val += 27
+> $val
+69
+```
+
+There are a couple of assignment operators used with mutable variables
+
+| Operator | Description                                                                |
+| -------- | -------------------------------------------------------------------------- |
+| `=`      | Assigns a new value to the variable                                        |
+| `+=`     | Adds a value to the variable and makes the sum its new value               |
+| `-=`     | Subtracts a value from the variable and makes the difference its new value |
+| `*=`     | Multiplies the variable by a value and makes the product its new value     |
+| `/=`     | Divides the variable by a value and makes the quotient its new value       |
+| `++=`    | Appends a list or a value to a variable                                    |
+
+> **Note**
+>
+> 1. `+=`, `-=`, `*=` and `/=` are only valid in the contexts where their root operations
+>    are expected to work. For example, `+=` uses addition, so it can not be used for contexts
+>    where addition would normally fail
+> 2. `++=` requires that either the variable **or** the argument is a
+>    list.
+
+#### More on Mutability
+
+Closures and nested `def`s cannot capture mutable variables from their environment. For example
+
+```nu
+# naive method to count number of elements in a list
+mut x = 0
+
+[1 2 3] | each { $x += 1 }   # error: $x is captured in a closure
+```
+
+To use mutable variables for such behaviour, you are encouraged to use the loops
+
+### Constant Variables
+
+A constant variable is an immutable variable that can be fully evaluated at parse-time. These are useful with commands that need to know the value of an argument at parse time, like [`source`](/commands/docs/source.md), [`use`](/commands/docs/use.md) and [`register`](/commands/docs/register.md). See [how nushell code gets run](how_nushell_code_gets_run.md) for a deeper explanation. They are declared using the `const` keyword
+
+```nu
+const plugin = 'path/to/plugin'
+register $plugin
+```
+
+## Variable Names
+
+Variable names in Nushell come with a few restrictions as to what characters they can contain. In particular, they cannot contain these characters:
+
+```
+.  [  (  {  +  -  *  ^  /  =  !  <  >  &  |
+```
+
+It is common for some scripts to declare variables that start with `$`. This is allowed, and it is equivalent to the `$` not being there at all.
+
+```nu
+> let $var = 42
+# identical to `let var = 42`
+```