Crate nu_experimental 

Experimental Options for the Nu codebase.

This crate defines all experimental options used in Nushell.

An ExperimentalOption is basically a fancy global boolean. It should be set very early during initialization and lets us switch between old and new behavior for parts of the system.

The goal is to have a consistent way to handle experimental flags across the codebase, and to make it easy to find all available options.

Usage

Using an option is simple:

if nu_experimental::EXAMPLE.get() {
    // new behavior
} else {
    // old behavior
}

Adding New Options

1. Create a new module in options.rs.
2. Define a marker struct and implement ExperimentalOptionMarker for it.
3. Add a new static using ExperimentalOption::new.
4. Add the static to ALL.

That’s it. See EXAMPLE in options/example.rs for a complete example.

For Users

Users can view enabled options using either version or debug experimental-options.

To enable or disable options, use either the NU_EXPERIMENTAL_OPTIONS environment variable, or pass them via CLI using --experimental-options.

Environment variable

Set ENV before launching nu (comma-separated list of options):

NU_EXPERIMENTAL_OPTIONS=example=true,pipefail=false nu

Command line (--experimental-options)

Each --experimental-options flag takes one shell argument. That argument can be a single option, a comma-separated list, or a bracketed list (with optional spaces). You can repeat the flag to add more options.

nu --experimental-options example=true
nu --experimental-options '[example=true, pipefail=false]'
nu --experimental-options example=true --experimental-options pipefail=false

To run a script with experimental options, pass the script path after the option value (the script is not part of the option list):

nu --experimental-options '[example=true]' script.nu

For Embedders

If you’re embedding Nushell, prefer using parse_env or parse_iter to load options.

parse_iter is useful if you want to feed in values from other sources. Since options are expected to stay stable during runtime, make sure to do this early.

You can also call ExperimentalOption::set manually, but be careful with that.

Structs

ExperimentalOption

Experimental option (aka feature flag).

Enums

ParseWarning

Warnings that can happen while parsing experimental options.

Status

The status of an experimental option.

Constants

ENV

Environment variable used to load experimental options from.

Statics

ALL

A list of all available experimental options.

CELL_PATH_TYPES

Enable type inferencing on “full cell path” expressions which are all typed as any if disabled. Inferred types are stored on internal AST, which are helpful for some downstream tasks such as nu-lsp inlay hints. As a side effect, some previously allowed operations may get rejected with type-mismatch parsing errors.

ENFORCE_RUNTIME_ANNOTATIONS

Enable runtime type annotation feature to ensure that type annotations are checked against the type that binds to them, returning conversion errors if the types are incompatible.

EXAMPLE

Example experimental option.

NATIVE_CLIP

Enable clip copy and clip paste commands that use native API.

PIPE_FAIL

Enable pipefail feature to ensure that the exit status of a pipeline accurately reflects the success or failure of all commands within that pipeline, not just the last one.

REORDER_CELL_PATHS

Reorder cell-path members in Value::follow_cell_path to decrease memory usage.

Functions

parse_env

Parse experimental options from the ENV environment variable.

parse_iter

Parse and activate experimental options.

set_all^⚠

Sets the state of all experimental option that aren’t deprecated.