nushell/crates/nu-engine/README.md

# Nu-Engine

Nu-engine handles most of the core logic of nushell. For example, engine handles:

- Passing of data between commands
- Evaluating a commands return values
- Loading of user configurations

## Top level introduction
The following topics shall give the reader a top level understanding how various topics are handled in nushell.

### How are environment variables handled?
Environment variables (or short envs) are stored in the `Scope` of the `EvaluationContext`. That means that environment variables are scoped by default and we don't use `std::env` to store envs (but make exceptions where convenient).

Nushell handles environment variables and their lifetime the following:
- At startup all existing environment variables are read and put into `Scope`. (Nushell reads existing environment variables platform independent by asking the `Host`. They will most likely come from `std::env::*`)
- Envs can also be loaded from config files. Each loaded config produces a new `ScopeFrame` with the envs of the loaded config.
- Nu-Script files and internal commands read and write env variables from / to the `Scope`. External scripts and binaries can't interact with the `Scope`. Therefore all env variables are read from the `Scope` and put into the external binaries environment-variables-memory area.
Refactor nu-cli/env* (#3041) * Revert "History, more test coverage improvements, and refactorings. (#3217)" This reverts commit 8fc8fc89aaf0ab40e7a149f2286eb97515f4ac9b. * Add tests * Refactor .nu-env * Change logic of Config write to logic of read() * Fix reload always appends to old vars * Fix reload always takes last_modified of global config * Add reload_config in evaluation context * Reload config after writing to it in cfg set / cfg set_into * Add --no-history to cli options * Use --no-history in tests * Add comment about maybe_print_errors * Get ctrl_exit var from context.global_config * Use context.global_config in command "config" * Add Readme in engine how env vars are now handled * Update docs from autoenv command * Move history_path from engine to nu_data * Move load history out of if * No let before return * Add import for indexmap 2021-03-31 07:52:34 +02:00			`# Nu-Engine`
fix markup (#4155) 2021-11-26 14:37:50 +01:00
Refactor nu-cli/env* (#3041) * Revert "History, more test coverage improvements, and refactorings. (#3217)" This reverts commit 8fc8fc89aaf0ab40e7a149f2286eb97515f4ac9b. * Add tests * Refactor .nu-env * Change logic of Config write to logic of read() * Fix reload always appends to old vars * Fix reload always takes last_modified of global config * Add reload_config in evaluation context * Reload config after writing to it in cfg set / cfg set_into * Add --no-history to cli options * Use --no-history in tests * Add comment about maybe_print_errors * Get ctrl_exit var from context.global_config * Use context.global_config in command "config" * Add Readme in engine how env vars are now handled * Update docs from autoenv command * Move history_path from engine to nu_data * Move load history out of if * No let before return * Add import for indexmap 2021-03-31 07:52:34 +02:00			`Nu-engine handles most of the core logic of nushell. For example, engine handles:`
fix markup (#4155) 2021-11-26 14:37:50 +01:00
			`- Passing of data between commands`
			`- Evaluating a commands return values`
			`- Loading of user configurations`
Refactor nu-cli/env* (#3041) * Revert "History, more test coverage improvements, and refactorings. (#3217)" This reverts commit 8fc8fc89aaf0ab40e7a149f2286eb97515f4ac9b. * Add tests * Refactor .nu-env * Change logic of Config write to logic of read() * Fix reload always appends to old vars * Fix reload always takes last_modified of global config * Add reload_config in evaluation context * Reload config after writing to it in cfg set / cfg set_into * Add --no-history to cli options * Use --no-history in tests * Add comment about maybe_print_errors * Get ctrl_exit var from context.global_config * Use context.global_config in command "config" * Add Readme in engine how env vars are now handled * Update docs from autoenv command * Move history_path from engine to nu_data * Move load history out of if * No let before return * Add import for indexmap 2021-03-31 07:52:34 +02:00
			`## Top level introduction`
			`The following topics shall give the reader a top level understanding how various topics are handled in nushell.`

			`### How are environment variables handled?`
			Environment variables (or short envs) are stored in the `Scope` of the `EvaluationContext`. That means that environment variables are scoped by default and we don't use `std::env` to store envs (but make exceptions where convenient).

			`Nushell handles environment variables and their lifetime the following:`
Fix typos and capitalization of "Unicode" (#3234) * Capitalize "Unicode" * Fix several typos * Fix mixed whitespace in nu-parser's tests 2021-04-03 21:14:07 +02:00			- At startup all existing environment variables are read and put into `Scope`. (Nushell reads existing environment variables platform independent by asking the `Host`. They will most likely come from `std::env::*`)
Refactor nu-cli/env* (#3041) * Revert "History, more test coverage improvements, and refactorings. (#3217)" This reverts commit 8fc8fc89aaf0ab40e7a149f2286eb97515f4ac9b. * Add tests * Refactor .nu-env * Change logic of Config write to logic of read() * Fix reload always appends to old vars * Fix reload always takes last_modified of global config * Add reload_config in evaluation context * Reload config after writing to it in cfg set / cfg set_into * Add --no-history to cli options * Use --no-history in tests * Add comment about maybe_print_errors * Get ctrl_exit var from context.global_config * Use context.global_config in command "config" * Add Readme in engine how env vars are now handled * Update docs from autoenv command * Move history_path from engine to nu_data * Move load history out of if * No let before return * Add import for indexmap 2021-03-31 07:52:34 +02:00			- Envs can also be loaded from config files. Each loaded config produces a new `ScopeFrame` with the envs of the loaded config.
			- Nu-Script files and internal commands read and write env variables from / to the `Scope`. External scripts and binaries can't interact with the `Scope`. Therefore all env variables are read from the `Scope` and put into the external binaries environment-variables-memory area.