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

IanManske · IanManske · commit a7ed14bf5e42 · 2024-04-14T15:08:38.000-04: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/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
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 shortend 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
@@ -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
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
@@ -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`
+```
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
