Limitations of Static Parsing: `cd` and `source`, Summary, and Immutable Variables

::: details Comparing Rust and C++ Imagine that the code above was written in a typical compiled language such as C++: ```cpp #include <string> std::string my_path("foo"); #include <my_path + "/common.h"> ``` or Rust ```rust let my_path = "foo"; use format!("{}::common", my_path); ``` If you've ever written a simple program in any of these languages, you can see these examples aren't valid in those languages. Like Nushell, compiled languages require that all of the source code files are ready and available to the compiler beforehand. ::: ::: tip See Also As noted in the error message, however, this can work if `my_path` can be defined as a [constant](/book/variables#constant-variables) since constants can be (and are) resolved during parsing. ```nu const my_path = "~/nushell-files" source $"($my_path)/common.nu" ``` See [Parse-time Constant Evaluation](./how_nushell_code_gets_run.md#parse-time-constant-evaluation) for more details. ::: #### Example: Change to a different directory (`cd`) and `source` a file Here's one more — Change to a different directory and then attempt to `source` a file in that directory. ```nu:line-numbers if ('spam/foo.nu' | path exists) { cd spam source-env foo.nu } ``` Based on what we've covered about Nushell's Parse/Eval stages, see if you can spot the problem with that example. ::: details Solution In line 3, during Parsing, the `source-env` attempts to parse `foo.nu`. However, `cd` doesn't occur until Evaluation. This results in a parse-time error, since the file is not found in the _current_ directory. To resolve this, of course, simply use the full-path to the file to be sourced. ```nu source-env spam/foo.nu ``` ::: ### Summary ::: important For a more in-depth explanation of this section, see [How Nushell Code Gets Run](how_nushell_code_gets_run.md). ::: ::: warning Thinking in Nushell Nushell is designed to use a single Parsing stage for each expression or file. This Parsing stage occurs before and is separate from Evaluation. While this enables many of Nushell's features, it also means that users need to understand the limitations it creates. ::: ## Variables are Immutable by Default Another common surprise when coming from other languages is that Nushell variables are immutable by default. While Nushell has optional mutable variables, many of Nushell's commands are based on a functional-style of programming which requires immutability. Immutable variables are also key to Nushell's [`par-each` command](/commands/docs/par-each.md), which allows you to operate on multiple values in parallel using threads.

This section continues to explore limitations of Nushell's static parsing, presenting an example where changing the directory with `cd` before sourcing a file fails because `source-env` attempts to parse the file during the parsing stage, before the `cd` command is evaluated. The solution is to provide the full path to the file. A summary section references the 'How Nushell Code Gets Run' guide for more in-depth explanation and emphasizes that users need to understand the limitations it creates. Finally, the section introduces the concept of immutable variables in Nushell, highlighting that variables are immutable by default and that Nushell has optional mutable variables, and that the `par-each` command leverages immutability for parallel operations.