shelly-shell 0.5.4

A Rust based Unix style shell with a typed and structured language syntax.
# Environment and exported variables

A variable's shell visibility and a declaration's module visibility are different.
`let export` includes a binding in child-process environments. `pub` exports a
symbol to importing Shelly modules.

<!-- example: ENV-INFO -->
```shy
let $local_note = "draft"
let export $SHELLY_WIKI_NOTE = "published"
let $bindings = get_env
echo $bindings["local_note"].value
echo $bindings["SHELLY_WIKI_NOTE"].visibility
```

```text
draft
VariableVisibility::Exported
```


`get_env` returns `[String: VariableInfo]` for the visible scope, including
shadowing. Keys and `name` omit the leading `$`. `VariableInfo` contains `name`, `value`, and a `VariableVisibility`
(`Local` or `Exported`). These are snapshots of the binding information.
`optional_env` reads an environment name and returns a String or `()`.

## Retype an imported environment value

`let type` converts an existing binding and retains the conversion back to its
original environment representation. The prelude supplies colon-separated
String/array conversions, preserving empty entries.

<!-- example: ENV-RETYPE -->
```shy
let export $SHELLY_WIKI_PATH = "red::blue"
let type $SHELLY_WIKI_PATH = [String]
echo $SHELLY_WIKI_PATH.count
$SHELLY_WIKI_PATH = [$SHELLY_WIKI_PATH..., "green"]
/usr/bin/printenv SHELLY_WIKI_PATH
```

```text
3
red::blue:green
```


This is useful for `$PATH`: work with `[String]` inside Shelly while children
receive the conventional colon-separated text. Conversion uses target
`from_<source>`, then source `to_<target>`, then built-in conversions.

## Runtime variables

| Variable | Purpose |
| --- | --- |
| `$args` | Script arguments. |
| `$shelly` | Current Shelly executable. |
| `$pid` | Current process ID. |
| `$pwd` | Current directory in user-facing path form. |
| `$os` | Platform name, such as `linux` or `macos`. |
| `$tty_color_mode` | Native `TtyColorMode` enum. |
| `$SHELLY_MODULE_PATH` | Search directories for ordinary imports. |
| `$SHELLY_STD_PATH` | Override standard-library search. |
| `$SHELLY_STD_FOUND` | Selected prelude root, `embedded`, or `()`. |
| `$SHELLY_TAB_SIZE` | Default source tab stops, from 1 through 32; defaults to 4. |

A source's `#tab-size N` directive takes precedence over an explicit `--tab-width N`
option, which takes precedence over `$SHELLY_TAB_SIZE`. Set the variable in a
startup script to affect later submissions and module loads. Export it when child
Shelly processes should inherit it. See [pipeline splits](Pipeline-Splits).

Prompt, widget, history, and highlighting settings are described in their own
chapters. Environment variable names are case sensitive.

---

Related: [Variables](Variables-and-Scope) · [Conversions](Conversions) · [Startup](Startup-and-Standard-Library)