# Rad

> A scripting language designed to make writing CLI tools delightful. Familiar, Python-like syntax with CLI essentials built-in.

## Guide

- [Getting Started](https://amterp.dev/rad/guide/getting-started.md): What is Rad?, Installation, Editor Support, Your First Rad Script - Hello World, Adding In Some Rad Features, Improving The Script Usage String, Shebang, A Complete Example
- [Basics](https://amterp.dev/rad/guide/basics.md): Variables & Assignment, Data Types, Destructuring, Operators, Functions, Control Flow, List Comprehensions, Truthy / Falsy, Converting Types, Errors
- [Args](https://amterp.dev/rad/guide/args.md): Arg Declarations, How Argument Parsing Works, Argument Types and User Input, Constraints
- [Functions](https://amterp.dev/rad/guide/functions.md): Syntax, Function Arguments, Custom Functions, Reference
- [Strings (Advanced)](https://amterp.dev/rad/guide/strings-advanced.md): String Interpolation, Formatting, Multiline Strings, Raw Strings, Escape Sequences, String Attributes, Patterns: Literal by Default
- [Rad Blocks](https://amterp.dev/rad/guide/rad-blocks.md): Basic Example, Additional Rad Block Options, Rad Block Options, Source Types, Understanding HTTP Requests
- [Type Annotations](https://amterp.dev/rad/guide/type-annotations.md): The Basics, Collection Types, Optional Types, Defaults, Union Types, Advanced Types, Variadic and Named Parameters
- [Error Handling](https://amterp.dev/rad/guide/error-handling.md): Error Propagation, Catch Blocks, The `??` Operator, The `catch` Operator, Creating Your Own Errors, Holding an Error
- [Shell Commands](https://amterp.dev/rad/guide/shell-commands.md): Invoking Commands, Which Shell Runs My Command?, Capturing Output, Reading One Result Inline, Error Handling, String Interpolation, Commands As Lists, Modifiers, Practical Examples
- [Script Commands](https://amterp.dev/rad/guide/script-commands.md): Basic Syntax, Multiple Commands, Adding Descriptions, Command Arguments, Shared Args, Nested Commands, Default Commands, Command Callbacks, Shared Logic, Getting Help, Practical Example
- [Resources](https://amterp.dev/rad/guide/resources.md): `pick`, `pick_kv`, `pick_from_resource`
- [Global Flags](https://amterp.dev/rad/guide/global-flags.md): `help`, `interactive`, `debug`, `quiet`, `color`, `src`, `cst-tree`, `ast-tree`, `tls-insecure`, `mock-response`, `reply`, `reply-na`
- [Defer & Errdefer](https://amterp.dev/rad/guide/defer-errdefer.md): Defer, Errdefer, Errors in defer blocks
- [Stashes](https://amterp.dev/rad/guide/stashes.md): The Basics, State Storage, File Storage, Stash Structure, Managing Stashes
- [Configuration](https://amterp.dev/rad/guide/config.md): Invocation Logging
- [Built-in Commands](https://amterp.dev/rad/guide/built-in-commands.md): `rad new`, `rad check`, `rad fmt`, `rad docs`, `rad stash`, `rad gen-id`, `rad home`, `rad completion`
- [REPL](https://amterp.dev/rad/guide/repl.md): Blocks take several lines, Mistakes don't end the session, Editing, Commands, Two things behave differently than in a script, Piping input, What it doesn't do yet
- [Shell Completion](https://amterp.dev/rad/guide/shell-completion.md): Quick Setup, What Gets Completed, Script Completions, Multiple Scripts & Globs, Full Example

## Examples

- [Examples](https://amterp.dev/rad/examples/index.md)
- [brewi](https://amterp.dev/rad/examples/brewi.md): Preview, Tutorial: Building `brewi`, Concepts demonstrated
- [epoch](https://amterp.dev/rad/examples/epoch.md): Preview, Tutorial: Building `epoch`, Concepts demonstrated
- [hm](https://amterp.dev/rad/examples/hm.md): Preview, Tutorial: Building `hm`, Concepts demonstrated

## Reference

- [Language Reference](https://amterp.dev/rad/reference/syntax.md): Script Structure, Comments, Data Types, Variables and Assignment, String Interpolation, Ternary Operator, Collection Access and Slicing, Control Flow, Additional Control Flow, Functions, List Comprehensions, Argument Parsing, Script Commands, Shell Commands, JSON Processing and Display Blocks, Advanced Features, Operators, Scoping and Variables, Built-in Types and Methods, Type System, Rad Code Style
- [Functions](https://amterp.dev/rad/reference/functions.md): How to Read This Document, Crypto, Formatting, HTTP, IO, Lists, Math, Parsing, Random, Stash, Strings, System, Time
- [Errors](https://amterp.dev/rad/reference/errors.md): Syntax Errors (RAD1xxxx), Runtime Errors (RAD2xxxx), Type Errors (RAD3xxxx), Validation & Lint Errors (RAD4xxxx)

## Migrations

- [How to Migrate](https://amterp.dev/rad/migrations/index.md): Guides, Upgrade Workflow
- [v0.12](https://amterp.dev/rad/migrations/v0.12.md): Breaking Change: Shell Commands Quote Interpolated Values, Breaking Change: Shell Captures Bind stdout First, Exit Code Last, Breaking Change: `$` Takes The Command, Not The Whole Expression, Breaking Change: List Args Collect Every Positional Value, Breaking Change: Constraints On A List Arg Are Enforced, Breaking Change: Flag-Like Tokens Are Rejected As Values, Breaking Change: A Bare List Flag Is Rejected, Breaking Change: `split()` and `replace()` Match Literally, Breaking Change: Scripts That Prompt Stop Before Running Without A Terminal, Behavior Change: `??` and `catch` See Errors You Already Hold, New: Reading A Command Inline, New: `len` Bounds On List Args, Error Messages
- [v0.9](https://amterp.dev/rad/migrations/v0.9.md): Breaking Change: `request` and `display` Keywords Removed, Breaking Change: `get_stash_dir` Renamed, Migration Steps, Breaking Change: `??` Now Fires on Null, New: `catch` Operator, Breaking Change: Strict `+` Concatenation, Breaking Change: `parse_epoch` Unit Names Shortened, Error Messages, Behavior Change: Invocation Logging Enabled by Default, Breaking Change: `trim_prefix` / `trim_suffix` Behavior Changed
- [v0.8](https://amterp.dev/rad/migrations/v0.8.md): Breaking Change: `get_default` Removed, Migration Steps, Why This Change?, Error Messages
- [v0.7](https://amterp.dev/rad/migrations/v0.7.md): Breaking Change: For-Loop Index Syntax, Migration Steps, Error Messages, Why This Change?, Bonus: Rad Block Lambda Context

## Other

- [Project Status](https://amterp.dev/rad/status.md): Platform Support, Near-term Focus, Long-term Vision, Get Involved
- [Releases](https://amterp.dev/rad/releases.md)

---

# Getting Started

## What is Rad?

*If you want to jump straight to programming, feel free to skip forwards to Installation.*

**Rad is a modern programming language and interpreter designed to make writing CLI scripts delightful.** It has a familiar, Python-like syntax with
built-in concepts like declarative arguments, JSON handling, first-class shell integration, and user prompts - making common scripting tasks easy and
fast to implement.

If you've ever written scripts and felt like your tools were fighting you, you're not alone:

**With Bash**, you might find yourself:

- Wrestling with `while getopts` boilerplate just to parse a few arguments
- Doing `curl | jq | awk` gymnastics to process JSON
- Skipping the "nice-to-haves" like `--help` or input validation because they're too painful to implement
- Delivering scripts that work, but are hard to read and harder to maintain

**With Python**, you get better syntax, but:

- You need argparse boilerplate before you even start solving your problem, or reach for additional libraries
- Sharing scripts means coordinating runtimes and dependencies (virtualenvs, lockfiles)
- Simple CLI tasks feel heavier than they should

**With Rad**, the language is purpose-built for CLI scripting:

- **Delightful to write** - familiar syntax without the footguns
- **Self-documenting** - automatic `--help` generation from your code comments
- **Declarative arguments** - type checking, validation, and parsing built into the language
- **Easy to share** - batteries included, no external dependencies needed

If you ever write a CLI script, **Rad is the language to do it in**.

**Project Status:** Rad is in early development but useful today for real scripts. Core features work well, though expect breaking changes between
versions as the language evolves. Your feedback directly shapes Rad's future!

Let's get into it.

## Installation

### macOS (Homebrew)

```bash
brew install rad
```

### Go (from source, all platforms)

```bash
go install github.com/amterp/rad@latest
go install github.com/amterp/rad/radls@latest
```

The first command installs the `rad` interpreter. The second installs `radls`, the language server for editor support.

**Note:** You will need to run `go install` yourself to upgrade Rad as new versions are released.
For automated updates, use one of the supported package managers that allow it.

### Binary Downloads

Pre-built binaries for macOS, Linux, and Windows: releases page (https://github.com/amterp/rad/releases)

Each release archive includes both `rad` (the interpreter) and `radls` (the language server).

### Checking Installation

After you've installed Rad and ensured it's on your PATH, you can check your installation:

```sh
rad -h
```

If this prints the help string for Rad, you're set!

## Editor Support

### Visual Studio Code

Rad has a VS Code extension here (https://marketplace.visualstudio.com/items?itemName=amterp.rad-extension) which provides:

- **Syntax highlighting** - makes your Rad code easy to read
- **Real-time validation** - catches syntax errors as you type
- **Diagnostics** - warnings and hints from the Rad Language Server

Installing it is highly recommended!

!vsc-example.png

**Note: Language Server Requirement**

    The VS Code extension uses the Rad Language Server (`radls`) for real-time validation and diagnostics.
    This is installed automatically when you install Rad via Homebrew or `go install`.

    If you see "Rad Language Server not found", make sure `rad` and `radls` are on your PATH.

### Other Editors

The Rad Language Server (`radls`) can be used with any editor that supports the Language Server Protocol (LSP):

- **Neovim**: Configure with `nvim-lspconfig` - point it to the `radls` binary
- **Sublime Text**: Use the LSP package with the `radls` command

For syntax highlighting without LSP, Rad's TextMate grammar can be used in editors that support it.

## Your First Rad Script - Hello World

Let's write the classic "Hello, World!" program. We'll then modify it to give it a bit of a Rad twist, demoing a few features that Rad provides.

First, create a file, let's call it simply `hello`, and give it the following contents:

```rad
print("Hello, World!") 
```

**Tip: `print()`**

    `print()` is the go-to function for outputting to stdout. It behaves a lot like `print()` in Python.

    You can read more about it in the reference (rad docs print).

**Info: File Extension**

    If you want to give your Rad scripts an extension, you can use `.rad` as a convention.

Then, run the script from your CLI by invoking `rad` on it, and you should see it print out like so:

```sh
> rad hello
```

```
Hello, World!
```

Nice! Now, let's spruce it up with a few Rad features.

## Adding In Some Rad Features

One of Rad's primary features is its simple, declarative style to defining script arguments.

Let's modify the script to greet a name you input from command line.

```rad
args:
  name str

print("Hello, {name}!")
```

A couple of things to note here:

1. We define an "args block". Right now it contains just the one line, but you can do lots of things in here (rad docs guide/args).
2. The modified `print()` utilizes string interpolation (rad docs guide/strings-advanced). String interpolation in Rad behaves a lot like it does in Python (you'll see this is a pattern).

Now, let's try invoking the script again, and this time, input a name:

```sh
> rad hello Alex
```

```
Hello, Alex!
```

Cool! What happens if we invoke *without* a name?

```sh
> rad hello
```

```
Usage:
  hello <name>

Script args:
      --name str
```

If you run a Rad script without providing *any* args to a script which expects at least one, Rad will print out the script usage, interpreting your invocation as if you had passed `--help`.

**Tip: Positional vs Flag Arguments**

    Arguments can be passed positionally or via flags. For example, both `./hello Alice` and `./hello --name Alice` work identically. The help text shows both forms: `<name>` for positional usage and `--name str` for the flag form.

This shows a little of the automatic script usage that Rad generates for you. Let's explore that a bit more.

## Improving The Script Usage String

Rad facilitates writing well-documented and easy-to-use scripts, in part through unique syntax. Let's use a couple of those now.

First, we'll add a **file header** to your script.

```rad
---
Prints a polite greeting using an input name.
---
args:
  name str
  
print("Hello, {name}!")
```

**Tip: File Headers**

    File headers, as the name suggests, go at the top of Rad scripts (with the exception of shebangs, to be covered later). 
    They allow you to write a description for your script in between two `---` lines. The contents will get printed as part of the script's usage string.

    A couple of ideas on what to cover in your file headers:

    - A brief description of what the script does and how it works
    - Examples of valid invocations and what they do.

Second, we can add **comments** to args that a script declares. Let's do that too:

```rad
---
Prints a polite greeting using an input name.
---
args:
  name str  # The name of someone to greet.
  
print("Hello, {name}!")
```

**Info: Note on `#` vs. `//`**

    Rad uses `#` to denote *arg* comments.
    `#` comments are special and **do get passed** to Rad's parser and can affect script behavior (namely in this case, adding information to the script usage string). 

    Standard code comments in Rad use `//`, similar to Java or C/C++, and **don't** impact script behavior.

Now, when someone reads the script, it's pretty clear what the script does and what the expected arguments are.

But it gets better! Let's try invoking the script's usage string again (this time let's try using the `-h` flag explicitly, though it's not necessary):

```sh
> rad hello -h
```

```
Prints a polite greeting using an input name.

Usage:
  hello <name>

Script args:
      --name str   The name of someone to greet.
```

Not only is the script now easier to maintain for developers, it's also easier for users to understand!

## Shebang

Needing to manually invoke `rad` each time you want to run a Rad script can be a little cumbersome. Thankfully, Unix kernels provide a mechanism known as a "shebang".

Let's add one to our script. It has to go on the very first line.

```rad
#!/usr/bin/env rad
---
Prints a polite greeting using an input name.
---
args:
  name str  # The name of someone to greet.
  
print("Hello, {name}!")
```

Then, make the script executable using the following command:

```sh
chmod +x ./hello
```

Now, you can invoke the script directly:

```sh
> ./hello Bob
```

```
Hello, Bob!
```

When you invoke an executable script this way, the kernel scans for a shebang (`#!`) in the first line.
If it finds a path to an interpreter (in this case, it will find `rad`, if set up correctly in your `PATH`),
then it will invoke said interpreter on the script (equivalent to `rad hello` like we were doing before).

**Tip: rad new**

    Rad has a command `rad new <script>` (rad docs guide/built-in-commands) which saves you repeating these steps.
    It creates a ready-to-edit executable file with a `rad` shebang on the top.

**Tip: Tab completion**

    Once you have scripts on your PATH, you can enable tab completion for them.
    See Shell Completion (rad docs guide/shell-completion) for setup instructions.

## A Complete Example

Now that you've seen the basics, let's skip ahead a little with our example, to get a better idea of what Rad can really do.
Don't worry - we'll cover everything in detail in later sections. For now, just observe what Rad gives you for free.

Update your `hello` script to this:

```rad
#!/usr/bin/env rad
---
Prints a polite greeting using an input name.
---
args:
  name str                # The name of someone to greet.
  times t int = 1         # How many times to greet them.
  style s str = "normal"  # Greeting style.

  times range (0, 10]
  style enum ["normal", "excited", "formal"]

greeting = switch style:
  case "excited" -> "HEY"
  case "formal" -> "Good day"
  default -> "Hello"

for i in range(times):
  print("{greeting}, {name}!")
```

**What we added:**

- Two more arguments with **default values** (`times` and `style`)
- **Short flag aliases** (`-t` and `-s`) for convenience
- **Argument constraints**
    - `times` must be greater than 0, and max 10 (inclusive)
    - `style` must be one of three values
- A **switch expression** to map style to greeting text
- A **for loop** to repeat the greeting

All of this in ~20 lines, with zero validation boilerplate.

### Try it out

Normal usage with short flags:

```sh
> ./hello Alice -t 3 -s excited
```

```
HEY, Alice!
HEY, Alice!
HEY, Alice!
```

Check the automatically generated help:

```sh
> ./hello -h
```

```
Prints a polite greeting using an input name.

Usage:
  hello <name> [times] [style] [OPTIONS]

Script args:
      --name str    The name of someone to greet.
  -t, --times int   How many times to greet them. Range: (0, 10] (default 1)
  -s, --style str   Greeting style. Valid values: [normal, excited, formal] (default normal)
```

Note how the constraints appear in the help automatically.

### What about invalid input?

Try providing an invalid range:

```sh
> ./hello Bob -t 15
```

```
'times' value 15 is > maximum 10
```

Try an invalid enum value:

```sh
> ./hello Bob -s casual
```

```
Invalid 'style' value: casual (valid values: normal, excited, formal)
```

**You didn't write any of this validation code.**
Rad enforced the constraints you declared and generated helpful error messages automatically.

## Summary

In this section, we were introduced to several key features:

- **String interpolation** with `{variable}` syntax for readable output
- **args blocks** for declarative argument definitions
- **File headers** and **arg comments** for self-documenting scripts
- **Shebangs** to make scripts more convenient to run
- **Argument constraints** (range, enum) with automatic validation - no manual validation needed
- **Short flag aliases** for better user experience
- **Automatic `--help` generation** from your code comments

Features you'd normally skip in Bash, or need external dependencies for in other languages, come built-in with Rad's declarative syntax. 🤙

**Info: Note on Rad script content ordering**

    Rad expects a certain order between shebangs, file headers, arg blocks, and the rest of your code.

    **It's important to adhere to the following ordering in Rad scripts**, or you'll see errors:

    1) Shebang (if present)

    2) File header (if present)

    3) Args block (if present)

    4) Rest of the file

## Next

Great job on getting this far! You've gotten a small peek at what Rad has to offer.

From here, you have a couple of options:

1. Continue your Rad journey: dive into more details with the next section: Basics (rad docs guide/basics).

2. If you'd like to see additional unique Rad features, here are some sections you can jump to:
    - Args (rad docs guide/args)
    - Rad Blocks (rad docs guide/rad-blocks)
    - Shell Commands (rad docs guide/shell-commands)
    - Example: brewi (rad docs examples/brewi)

---

# Basics

This section of the guide will rapidly cover the basics of Rad.
Rad shares a lot of conventions and syntax with popular languages like Python,
so if you're familiar with programming, this will be a breeze.

## Variables & Assignment

To create a variable, you can do it through assignment. Let's use a string example:

```rad
name = "Alice"
```

You can re-assign variables. Types don't need to stay the same:

```rad
name = "Alice"
name = 2
```

## Data Types

Rad has 6 basic types: strings, ints, floats, bools, lists, and maps.

### str

Strings can be delimited in three ways:

1. Double quotes: `"text"`
2. Single quotes: `'text'`
3. Backticks: ``` `text` ```

All three behave the same way. To demonstrate:

```rad
print("Hello!")
print('Hello!')
print(`Hello!`)
```

```
Hello!
Hello!
Hello!
```

**Info: Why 3 different delimiters?**

    Having 3 different delimiters is particularly useful when you want your string to contain one (or more) of those delimiter characters.

    For example, if you want a double quote in your string, you *can* use double quote delimiters and escape them:

    ```rad
    "She said \"Goodbye\""
    ```

    However, this can be finicky and hard to read. Instead, you can pick one of the other two delimiters, for example:

    ```rad
    'She said "Goodbye"'
    `She said "Goodbye"`
    ```

    We'll cover this again later, but as a note, backticks can be particularly useful in
    shell commands (rad docs guide/shell-commands), as shell/bash commands may include single or double quotes, and backticks
    save us from having to escape them.

Strings can include special characters such as `\n` for new lines and `\t` for tabs.

```rad
print("Hello\tdear\nreader!")
```

```
Hello	dear
reader!
```

Strings also support **interpolation**. String interpolation allows you to write expressions *inside your string* that will be evaluated and replaced for the final string. We'll cover this in more depth in a future section, but to give a very simple example:

```rad
name = "Alice"
print("Hi, {name}!")
```

```
Hi, Alice!
```

Anything encapsulated in a `{}` gets treated as an expression. Here, the expression is just the identifier `name`, which gets evaluated and substituted, giving us the final `Hi, Alice!` string.

Those are the basics for strings - we'll cover additional string concepts in a future section, Strings (Advanced) (rad docs guide/strings-advanced).

### int

Rad has ints. There's nothing unusual about them. Example:

```rad
team_size = 20
celsius = -5
```

For large numbers, you can use underscores to improve readability:

```rad
population = 1_234_567
distance = 93_000_000
```

Note that if you divide two ints, you will get back a float.

```rad
liters = 10
people = 4
print("This is a float:", liters / people)
```

```
This is a float: 2.5
```

### float

The other number type is float:

```rad
length_meters = 2.68
```

If you want to define a whole number as a float, simply include a decimal place:

```rad
years = 20.0
```

Like ints, floats also support underscores for readability and scientific notation:

```rad
precise_value = 123.456_789  // 123.456789
small_number = 5e-3          // 0.005
```

### bool

Rad uses lowercase `true` / `false`:

```rad
is_running = true
is_tired = false
```

### list

Rad has two collection types: lists and maps. First, let's look at lists.

```rad
names = ["alice", "bob", "charlie"]
```

Lists you define can contain any types:

```rad
mixed = ["alice", true, 50, -2.4]
```

They can also be nested:

```rad
nested = ["alice", [1, ["very nested", "bird"]]]
```

Indexing and slicing works very similarly to Python. Using the above 3 variables for an example, you can index with both positive and negative indexes:

```rad
print(names[0])
print(mixed[-1])  // grab last element in the list
print(nested[1][1][0])
```

```
alice
-2.4
very nested
```

You can also slice:

```rad
numbers = [10, 20, 30, 40, 50]
print(numbers[1:3])
print(numbers[2:])
print(numbers[:-1])
```

```
[20, 30]
[30, 40, 50]
[10, 20, 30, 40]
```

**Tip: String Indexing and Slicing**

    All the same indexing and slicing rules that apply to lists also work with strings:

    ```rad
    text = "hello"
    print(text[0])      // h
    print(text[-1])     // o
    print(text[1:4])    // ell
    print(text[:3])     // hel
    ```

### map

The other collection type is 'map'. These may also be referred to as 'hashmap' or 'dictionary' in other languages.

```rad
scores = { "alice": 25, "bob": 17, "charlie": 36 }
```

Like lists, they can contain mixed types for values, and can nest.

```rad
mixed_map = { 
  "alice": "accountant",
  "mylist": [ "London", 25 ],
}

nested_map = {
  "error": {
    "msg": "Request failed!",
    "code": 400,
  }
}
```

If we take the above example, values can then be accessed in two ways. First is the square bracket lookup:

```rad
print(mixed_map["alice"])
print(nested_map["error"]["msg"])
```

```
accountant
Request failed!
```

Alternatively, you can use a dot syntax. Note this second way only works for keys with no spaces in the name.

```rad
print(mixed_map.alice)
print(nested_map.error.msg)
```

```
accountant
Request failed!
```

You can modify maps using either syntax:

```rad
mymap = { "alice": 30 }

mymap["alice"] = 40
print(mymap)

mymap.alice = 50
print(mymap)
```

```
{ alice: 40 }
{ alice: 50 }
```

You can also add keys this way:

```rad
mymap = { "alice": 30 }
mymap["bob"] = 31
mymap.charlie = 32
print(mymap)
```

```
{ alice: 30, bob: 31, charlie: 32 }
```

Accessing a key that doesn't exist will cause an error. You can check if a key exists using `in`:

```rad
scores = { "alice": 25, "bob": 17 }
print("alice" in scores)  // true
print("dave" in scores)   // false
```

Alternatively, use the `??` fallback operator to provide a default value when a key is missing:

```rad
scores = { "alice": 25, "bob": 17 }
print(scores["alice"] ?? 0)  // 25
print(scores["dave"] ?? 0)   // 0
```

This is handy when you're not sure if a key exists and want to avoid errors.

The `??` operator also works with lists and strings for out-of-bounds index access:

```rad
items = ["a", "b", "c"]
print(items[1] ?? "missing")   // b
print(items[10] ?? "missing")  // missing
```

### Other Types

Rad has other types that we won't cover here. For example `null` and function references (rad docs guide/functions).

## Destructuring

You can unpack values from lists into separate variables. Let's start with the traditional way of accessing list elements:

```rad
coords = [10, 20]
print(coords[0], coords[1])  // 10 20
```

Instead of using indices, you can **destructure** the list by unpacking its values into separate variables:

```rad
[x, y] = [10, 20]
print(x, y)  // 10 20
```

As syntactic sugar, the square brackets are optional:

```rad
x, y = 10, 20
print(x, y)  // 10 20
```

Keep in mind that this is still destructuring - Rad is creating a list `[10, 20]` behind the scenes and unpacking it into `x` and `y`.

Destructuring is particularly useful when functions return multiple values:

```rad
x, y = get_coordinates()
width, height = get_dimensions()
```

You can also destructure in for loops, which we'll see later in the Control Flow section.

## Operators

Rad offers operators similar to many other languages. Below sections very quickly demonstrate.

### Arithmetic

Rad follows the standard order of operations for operators `() , * , / , % , + , -`:

1. Parentheses
2. Multiplication, Division, Modulo
3. Addition, Subtraction

```rad
print(1 + 4 / 2)    // 3
print(2.5 * 3 - 1)  // 6.5
print((4 + 5) * 2)  // 18
print(5 % 3)        // 2
```

Dividing two integers will result in a floating point number.

```rad
print(5 / 2)  // 2.5
```

You can multiply strings to repeat them:

```rad
name = "alice"
print(name * 3)  // alicealicealice
```

### Comparison

Comparisons return bools that can be used in e.g. if statements.

String comparison is done based on contents.

```rad
print("alice" == "alice")  // true
print("alice" == "bob")    // false
print("alice" != "bob")    // true
print("alice" == "Alice")  // false
```

Numbers can also be compared with the standard comparators `> , >= , < , <= , ==`.

```rad
print(2 >= 2)  // true
print(2 > 2)   // false
print(2 <= 2)  // true
print(2 < 2)   // false
print(2 == 2)  // true
```

You cannot use these operators (outside of `==`) to compare non-numbers such as strings:

```rad
print("alice" > "bob")  // error
```

But you *can* check them for equality (will always return false, except ints and floats that are equal):

```rad
print(2 == "alice")  // false
print(2 == 2.0)      // true
```

**Info: Difference From Python on `True == 1` and `False == 0`**

    In Python, `False == 0` and `True == 1` are true, because under the hood, False is really int 0 and True is really int 1,
    hence they're equal. That's not the case in Rad. In Rad, **any two values of different types are not equal** (except ints/floats).

    The reasoning stems from truthy/falsy-ness. In Python, both `1` and `2` are truthy. But only `1` equals `True`.
    Rad avoids this oddity of making `1` special by instead making any two different types not equal (except ints/floats).

### Logical

Rad uses `and` and `or` for binary logical operations.

```rad
print(false and false)  // false
print(false and true)   // false
print(true  and false)  // false
print(true  and true)   // true

print(false or  false)  // false
print(true  or  false)  // true
print(false or  true)   // true
print(true  or  true)   // true
```

And it uses `not` for logical negation.

```rad
print(not true)   // false
print(not false)  // true
```

### Membership

You can check if an item exists in a collection using the `in` operator:

```rad
names = ["alice", "bob", "charlie"]
print("alice" in names)     // true
print("david" in names)     // false
```

The `in` operator also works with strings to check for substrings:

```rad
text = "hello world"
print("world" in text)      // true
print("goodbye" in text)    // false
```

For maps, `in` checks if a key exists:

```rad
scores = { "alice": 25, "bob": 17 }
print("alice" in scores)    // true
print("charlie" in scores)  // false
```

You can use `not in` to check for the absence of an item:

```rad
names = ["alice", "bob", "charlie"]
print("david" not in names)  // true
print("alice" not in names)  // false
```

### Concatenation

To combine strings with other types, use **string interpolation** - it handles any type automatically:

```rad
count = 5
pi = 3.14
print("count: {count}, pi: {pi}")
```

```
count: 5, pi: 3.14
```

For joining strings together, you can also use the `+` operator:

```rad
first = "Alice"
last = "Bobson"
print(first + " " + last)
```

```
Alice Bobson
```

The `+` operator requires both sides to be strings (errors also work, since they behave like strings for concatenation). To concatenate non-string values with `+`, convert them explicitly using `str` (rad docs str):

```rad
a = 1
text = ". Bullet point one"
print(str(a) + text)
```

```
1. Bullet point one
```

### Compound Operators

Rad also supports compound operators for modifying variables in-place.

```rad
a = 3
a += 2   // a is now 5
a -= 1   // a is now 4
a *= 3   // a is now 12
a %= 10  // a is now 2
a /= 4   // a is now 0.5
```

### Increment / Decrement

You can quickly increment and decrement ints and floats using `++` and `--` syntax.

```rad
a = 2
a++
print(a)

b = 2.5
b--
print(b)
```

```
3
1.5
```

The increment and decrement operators produce *statements*, not *expressions*.
This means that `a++` does not *return* anything, and so cannot be used inside e.g. a conditional.

For example, the following two uses are invalid, because `a++` doesn't return a value:

```rad
a = 5
if a++ > 0:  // invalid, nothing for > to evaluate against on the left side
    ...
  
b = a++  // also invalid because a++ doesn't return any value
```

Because of that, there's also no reason to support *pre*-incrementing, and so `++a` or `--a` are invalid statements.

### Ternary

Rad supports `? :` style ternary operators. 

`<condition> ? <true case> : <false case>`

```rad
a = 5
b = a > 0 ? "larger than 0" : "less than 0"
print(b)
```

```
larger than 0
```

## Functions

Rad provides many built-in functions to help you write scripts. Functions can be invoked using a standard syntax:

```rad
names = ["Bob", "Charlie", "Alice"]
num_people = len(names)
print("There are {num_people} people.")

sorted_names = sort(names)
print(sorted_names)
```

```
There are 3 people.
[ "Alice", "Bob", "Charlie" ]
```

In this example, we use `len()` to get the list length, `sort()` to sort it, and `print()` to display output.

You can also define your own custom functions - we'll cover that (and more) in detail in the Functions (rad docs guide/functions) section.
For a complete list of all built-in functions, see the Functions Reference (rad docs reference/functions).

## Control Flow

### If Statements

Rad employs very standard if statements.

You are **not** required to wrap conditions in parentheses `()`.

```rad
units = "metric"
if units == "metric":
    print("That's 10 meters.")
else if units == "imperial":
    print("That's almost 33 feet.")
else:
    print("I don't know that measurement system!")
```

**Info: Blocks use whitespace & indentation**

    Note that Rad uses whitespace & indentation to denote blocks, instead of braces.

    As a convention, you can use 4 spaces for indentation. Mixing tabs and spaces is not allowed.

### For Loops

Rad allows "for each" loops for iterating through collections such as lists.

```rad
names = ["Alice", "Bob", "Charlie"]
for name in names:
    print("Hi {name}!")
```

```
Hi Alice!
Hi Bob!
Hi Charlie!
```

You can also iterate through a range of numbers using the `range` (rad docs range) function, which returns a list of numbers within some specified range.

```rad
for i in range(5):
    print(i)
```

```
0
1
2
3
4
```

You can also invoke `range` with a starting value i.e. `range(start, end)` and with a step value i.e. `range(start, end, step)`.

If you want to iterate through a list while also having access to the item's index, you can use the `with` clause to access a context object:

```rad
names = ["Alice", "Bob", "Charlie"]
for name in names with loop:
    print("{name} is at index {loop.idx}")
```

```
Alice is at index 0
Bob is at index 1
Charlie is at index 2
```

The context object provides two fields:

- **`loop.idx`** - The current iteration index (0-based)
- **`loop.src`** - An immutable snapshot of the original collection

You can name the context variable anything you like, but `loop` is the convention for for-loops:

```rad
names = ["Alice", "Bob", "Charlie"]
for name in names with loop:
    print("Processing {loop.idx + 1} of {loop.src.len()}: {name}")
```

```
Processing 1 of 3: Alice
Processing 2 of 3: Bob
Processing 3 of 3: Charlie
```

**Tip: Naming Convention**

    By convention, use `loop` for context in for-loops and list comprehensions, and `ctx` for context in rad block (rad docs guide/rad-blocks) lambdas.

When iterating through a map, if you have one variable in the loop, then that variable will be the key:

```rad
colors = { "alice": "blue", "bob": "green" }
for k in colors:
    print(k)
```

```
alice
bob
```

If you have two, then the first will be the key, and the second will be the value.

```rad
colors = { "alice": "blue", "bob": "green" }
for k, v in colors:
    print(k, v)
```

```
alice blue
bob green
```

You can also combine map iteration with the context object:

```rad
colors = { "alice": "blue", "bob": "green" }
for k, v in colors with loop:
    print("{loop.idx}: {k} = {v}")
```

```
0: alice = blue
1: bob = green
```

A useful function to know when iterating is `zip` (rad docs zip).
It lets you combine parallel lists into a list of lists. To demonstrate:

```rad
names = ["alice", "bob", "charlie"]
ages = [30, 40, 25]
zipped = zip(names, ages)
print(zipped)  // [ [ "alice", 30 ], [ "bob", 40 ], [ "charlie", 25 ] ]
```

These inner lists can then be unpacked by specifying the appropriate number of identifiers in a for loop:

```rad
names = ["alice", "bob", "charlie"]
ages = [30, 40, 25]
for name, age in zip(names, ages):
    print(name, age)
```

```
alice 30
bob 40
charlie 25
```

You can also access the index when unpacking with `zip`:

```rad
for name, age in zip(names, ages) with loop:
    print("{loop.idx + 1}. {name} is {age}")
```

```
1. alice is 30
2. bob is 40
3. charlie is 25
```

#### Breaking Out of Loops

You can exit a loop early using the `break` statement:

```rad
numbers = [1, 2, 3, 4, 5]
for n in numbers:
    if n == 3:
        break
    print(n)
```

```
1
2
```

The loop stops completely when it reaches `3`, so numbers after that are never processed.

#### Skipping Iterations

You can skip to the next iteration using the `continue` statement:

```rad
numbers = [1, 2, 3, 4, 5]
for n in numbers:
    if n == 3:
        continue
    print(n)
```

```
1
2
4
5
```

The number `3` is skipped, but the loop continues with the remaining numbers.

### While Loops

While loops repeat a block of code as long as a condition is true:

```rad
count = 0
while count < 3:
    print("Count: {count}")
    count++
```

```
Count: 0
Count: 1
Count: 2
```

You can create an infinite loop by omitting the condition:

```rad
while:
    print("This runs forever!")
    // Use break to exit when needed
```

The `break` and `continue` statements work in while loops just like they do in for loops.

### Switch Statements

Rad has switch statements and switch expressions.

You can `switch` on a value and write cases to match against, including a `default`.

```rad
args:
    a float
    op str
    b float

switch op:
    case "add":
        result = a + b
        print("added: {result}")
    case "times":
        result = a * b
        print("multiplied: {result}")
    default:
        print("I don't know how to do that.")
```

Cases can be written as blocks or single-line expressions.
For example, the above `default` could be made into a single line:

```rad
args:
    a float
    op str
    b float

switch op:
    case "add":
        result = a + b
        print("added: {result}")
    case "times":
        result = a * b
        print("multiplied: {result}")
    default -> print("I don't know how to do that.")
```

The above examples are switch **statements**, because they do not return anything.
Switch **expressions** can be used in assignments.

```rad
args:
    object str

sound = switch object:
    case "car" -> "vroom"
    case "mouse" -> "squeak"
    default -> "moo"  // default to cow

print(sound)
```

The above example cases are all single-line expressions (`case ... -> ...`).
If you want to write a case as a block in a switch expression, you can use the `yield` keyword to return values.

Note also that you can assign and return more than 1 value at a time. To demonstrate:

```rad
args:
    object str

sound, plural = switch object:
    case "car" -> "vroom", "cars"
    case "mouse" -> "squeak", "mice"
    default:
        print("Don't know '{object}'; defaulting to cow.")
        yield "moo", "cows"

print(`{plural} go "{sound}"`)
```

## List Comprehensions

List comprehensions provide a concise way to create lists by transforming or filtering existing collections. They use familiar for loop syntax but produce a new list as a result.

### Basic Syntax

```rad
numbers = [1, 2, 3, 4, 5]
squares = [x * x for x in numbers]
print(squares)
```

```
[ 1, 4, 9, 16, 25 ]
```

The general pattern is `[expression for variable in collection]`, which creates a new list by evaluating the expression for each item in the collection.

### Using Functions

You can call functions in list comprehensions:

```rad
words = ["hello", "world"]
uppercase = [upper(word) for word in words]
print(uppercase)
```

```
[ "HELLO", "WORLD" ]
```

### Context in List Comprehensions

List comprehensions support the same `with` syntax as for loops:

```rad
items = ["a", "b", "c"]
indexed = ["{loop.idx}: {item}" for item in items with loop]
print(indexed)
```

```
[ "0: a", "1: b", "2: c" ]
```

### Filtering with `if`

You can add an `if` clause to filter items while creating a list:

```rad
numbers = [1, 5, 10, 15, 20, 8]
small_numbers = [x for x in numbers if x < 10]
print(small_numbers)
```

```
[ 1, 5, 8 ]
```

The filter condition can use any expression, including function calls:

```rad
words = ["a", "ab", "abc", "abcd"]
short_words = [w for w in words if len(w) < 3]
print(short_words)
```

```
[ "a", "ab" ]
```

You can combine filtering with transformation:

```rad
numbers = [1, 2, 3, 4, 5, 6]
even_squares = [x * x for x in numbers if x % 2 == 0]
print(even_squares)
```

```
[ 4, 16, 36 ]
```

**Note: Side Effects in Comprehensions**

    If the expression in a comprehension produces side effects (like calling `print()`), the comprehension will still execute those side effects but returns an empty list:

    ```rad
    [print(x) for x in [1, 2, 3]]  // Prints 1, 2, 3 but returns []
    ```

## Truthy / Falsy

Rad supports truthy/falsy logic.

This means that, instead of writing the following (as an example):

```rad
if len(my_list) > 0:
    print("My list has elements!")
```

you can write

```rad
if my_list:
    print("My list has elements!")
```

Essentially, you can use any type as a condition, and it will resolve to true or false depending on the value.

The following table shows which values return false for each type. **All other values resolve to true.**

| Type   | Falsy | Description   |
| ------ | ----- | ------------- |
| string | `""`  | Empty strings |
| int    | `0`   | Zero          |
| float  | `0.0` | Zero          |
| list   | `[]`  | Empty lists   |
| map    | `{}`  | Empty maps    |

**Note: Blank strings and `null`**

    - A string which is all whitespace e.g. `" "` is still truthy.
    - `null` is falsy.

## Converting Types

Converting types may involve simple casts, or parsing.

When casting, you can use the following functions:
`str` (rad docs str),  `int` (rad docs int),  `float` (rad docs float)

```rad
print(int(2.1))  // 2
print(float(2))  // 2.0
print(str(2.2))  // "2.2"
```

Note that `int` and `float` will error on strings. To parse a string, use the following functions:
`parse_int` (rad docs parse_int),  `parse_float` (rad docs parse_float)

```rad
print(parse_int("2"))      // 2
print(parse_float("2.2"))  // 2.2

print(parse_int("2.2"))    // error
print(parse_float("bob"))  // error
```

## Errors

When something goes wrong, Rad displays errors in a format designed to help you quickly locate and understand the problem:

```
error[RAD20029]: Index out of bounds: 5 (length 2)
  --> script.rad:11:13
   |
10 | names = ["alice", "bob"]
11 | print(names[5])
   |             ^
12 |
   |
   = info: rad docs RAD20029
```

Every error includes a code (like `RAD20029`) that identifies the type of error. To learn more about any error, use the `rad docs` command:

```shell
rad docs RAD20029
```

This displays detailed documentation about the error, including common causes and how to fix it.

## Summary

- We rapidly covered many basic topics such as assignment, data types, operators, and control flow.
- Rad has 6 basic types: strings, ints, floats, bools, lists, and maps.
- Strings and lists support indexing and slicing with the same syntax.
- **Destructuring** lets you unpack list values into separate variables: `x, y = [10, 20]` or simply `x, y = 10, 20`.
- Rad has operators such as `+ , - , * , / , %`. For bool logic, it uses `or` and `and`. For membership, `in` and `not in`.
- Rad provides many built-in functions like `len()`, `sort()`, `upper()`, and more. You can also define custom functions.
- Rad uses a "for-each" variety `for` loop. You always loop through items in a collection (or string).
    - If you want to increment through a number range, use the `range` function to generate you a list of ints.
    - Use `break` to exit loops early and `continue` to skip to the next iteration.
- **List comprehensions** provide a concise way to create lists: `[x * 2 for x in numbers]`
    - Support filtering with `if`: `[x for x in numbers if x < 10]`
- Rad also has `while` loops for repeating code while a condition is true.
- Rad offers truthy/falsy logic for more concise conditional expressions.
- Rad has switch statements and expressions. The latter uses `yield` as a keyword to return values from cases.
- Rad has functions for casting `str`, `int`, `float` and for parsing `parse_int`, `parse_float` values.
- When errors occur, use `rad docs <code>` to get detailed help.

## Next

Good job on getting through the basics of the language! 

Next, let's dive into one of the areas of Rad that make it shine: Args (rad docs guide/args).

---

# Args

This section covers syntax for declaring arguments that your script can accept.

## Arg Declarations

Rad takes a declarative approach to arguments.
You simply declare what arguments your script accepts, you can define some constraints you want for them,
and let Rad take care of the rest, including parsing user input and validation.

Arguments are declared as part of an **args block**.

Here's an example script we'll call `printwords` that prints an input word some number of times:

```rad
#!/usr/bin/env rad
args:
    word str
    repeats int
    
for _ in range(repeats):
    print(word)
```

We can print its usage string using the `-h` flag:

```shell
./printwords -h
```

```
Usage:
  printwords <word> <repeats>

Script args:
      --word str
      --repeats int
```

This script defines two mandatory arguments: `word` that is expected to be a string, and `repeats` which is expected to be an integer.

Some important things to note:

- **Every argument you declare works both as a positional parameter and as a named flag - automatically.** You don't have to choose between them, and your users can mix and match. Bools are the one exception: they are flags only. See How Argument Parsing Works below for the full details.
- The positional ordering of args follows the order of declaration in the args block.
- Flags (like `--word` and `--repeats`) are generated for you based on each argument's name.

Let's look at a more complex example to demonstrate some more features. Let's call it `wordjoin`.

```rad
#!/usr/bin/env rad
---
Given some words, joins them together, and optionally capitalizes them.
---
args:
    words str[]                            # Words to join together.
    joiner j str = "-"                     # Joiner for the words.
    should_capitalize "capitalize" c bool  # If true, capitalize the words.

if should_capitalize:
    words = [upper(w) for w in words]

print(join(words, joiner))
```

If we run `-h` on this one:

```shell
./wordjoin -h
```

```
Given some words, joins them together, and optionally capitalizes them.

Usage:
  wordjoin <words...> [OPTIONS]

Script args:
      --words strs   Words to join together.
  -j, --joiner str   Joiner for the words. (default -)
  -c, --capitalize   If true, capitalize the words.
```

Let's break down each declaration to see what's going on here.

1. `words str[]  # Words to join together.`
    - We declare an arg `words` which is a list of strings. Note that `int[]`, `float[]` and `bool[]` can be used for int, float, and bool lists respectively.
    - We also define an arg comment to make the usage string include a description of what the argument is.

2. `joiner j str = "-"  # Joiner for the words.`
    - We declare a second argument, this one a string called `joiner`. We also define a shorthand flag `j`, allowing users to specify the arg with a simple `-j` flag.
    - After that, we define a **default** value `-` for this parameter that will be used if the user doesn't provide one. We finish with another arg comment.
    - Notice `joiner` doesn't appear in the usage line. `words` is a list, so it collects *every* bare value the user types - there's nothing left for a later positional slot. Users set `joiner` with `-j` instead.

3. `should_capitalize "capitalize" c bool  # If true, capitalize the words.`
    - We declare our final argument `should_capitalize`. We rename it with `"capitalize"`, which will be what users see exposed to them, instead of the initial variable name.
`should_capitalize` will remain the name of the variable to be referenced throughout the script. We define a shorthand `c`, and specify the parameter is a `bool` before finally giving it an arg comment.

Bool args are always false by default.

---

To bring it all together, this is the anatomy of an arg declaration (`<angle brackets>` mean it's required, `[square brackets]` indicate it's optional):

`<name> [rename] [shorthand flag] <type> [= default] [# arg comment]`

Feel free to go back up and check this against the example scripts we wrote, you'll see how each one fits this mold.

**Tip: Underscores become hyphens**

    If you name an argument with underscores (e.g., `my_arg`), Rad automatically converts it to hyphens for the CLI
    flag: `--my-arg`. Inside your script, you still reference the variable as `my_arg`.

## How Argument Parsing Works

Most CLI frameworks force you to choose: either an argument is positional, or it's a named flag.
Rad doesn't make you choose - every argument you declare automatically works as *both*.

This section explains that model and a few related parsing behaviors that are useful to know.

### The Dual-Nature Model

When you declare an argument, Rad generates both a positional slot and a named flag for it - except for bools, which are flags only.
Your users can then invoke your script whichever way is most convenient - or mix both styles in the same call.

Consider this script:

```rad
args:
    src str       # Source file
    dest str      # Destination path
    verbose v bool
```

All of these invocations are equivalent:

```shell
# Pure positional
./script myfile.txt /backup/

# Pure flags
./script --src myfile.txt --dest /backup/

# Mixed - positional for src, flag for dest
./script myfile.txt --dest /backup/
```

### Parsing Order

Rad processes arguments left-to-right. The rules are simple:

1. If an argument starts with `--` or `-`, it's matched as a flag by name (or short name).
2. If an argument is a bare value (no `-` prefix), it's assigned to the next unfilled positional slot, in the order you declared your args. If that slot is a list, it keeps taking bare values until the next flag, and does not resume afterwards.
3. Flags can appear anywhere - before, after, or interspersed with positional values.
4. A `-`-prefixed token is never read as another flag's value. `--name --verbose` is an error, not `name = "--verbose"`.

The key insight: when a flag "fills" an argument, that positional slot is skipped. For example:

```rad
args:
    first str
    second str
    third str
```

```shell
# --second fills the second slot via flag, so the two bare values
# fill "first" and "third" (the remaining unfilled slots, in order).
./script alpha --second beta gamma
```

Here, `first` = `"alpha"`, `second` = `"beta"`, `third` = `"gamma"`.

### The `--` Separator

Rad supports the standard Unix `--` convention: everything after a bare `--` is treated as a positional argument, even if it starts with `-`.

This is useful when you need to pass values that look like flags:

```shell
./script -- --not-a-flag
```

Here, `--not-a-flag` is treated as a positional string value, not as a flag.

### Negative Numbers

Passing negative numbers can look like flags since they start with `-`. There are a few ways to handle this:

```rad
args:
    count int
```

```shell
# Use flag + value
./script --count -5

# Use equals syntax
./script --count=-5

# Use -- to force positional
./script -- -5
```

The first form works because `count` is a number. Rad only reads a `-`-prefixed
token as a value for `int` and `float` args - for a `str` arg, `--name -5` is an
error, and `--name=-5` is how you say you meant it.

### Equals Syntax

Both `--name=value` and `--name value` work for all flag types. For bool flags specifically,
`--flag` sets the value to `true` by presence, while `--flag=false` explicitly sets it to `false`.

Equals syntax is especially useful when you need to be unambiguous - for example, when passing negative numbers or values that start with `-`.

## Argument Types and User Input

This section explains the different argument types you can declare and how users pass values for each type.

### Basic Types

For basic types (`int`, `float`, `str`), users can pass values either positionally or via flags:

```rad
#!/usr/bin/env rad
args:
    name str
    age int
    height float

print("{name} is {age} years old and {height}m tall")
```

Both invocations work identically:

```shell
./script Alice 25 1.65
./script --name Alice --age 25 --height 1.65
./script Alice 25 --height 1.65
```

Type validation happens automatically. If a user provides `--age abc` when age is an `int`, Rad will show an error.

### Bool Flags

Bool arguments are **never positional** - they must always be passed via flags. You can set bool flags either by presence or with an explicit value:

```rad
args:
    verbose v bool
    debug d bool

print("verbose: {verbose}, debug: {debug}")
```

```shell
./script --verbose           # verbose=true, debug=false
./script -v                  # Same as above (short flag)
./script -v -d               # Both true
./script --verbose=true      # Explicit value
./script --verbose=false     # Explicitly set to false
```

Bool args always default to `false` unless you give them a different default:

```rad
args:
    verbose bool = true  # Defaults to true
```

### List Types

For list arguments (`str[]`, `int[]`, `float[]`, `bool[]`), users pass several values either as bare positional values or by **repeating the flag**:

```shell
./script hello.txt world.txt
```

A list arg is greedy positionally - it collects every bare value until the next
flag. Through its own flag it takes exactly one value per occurrence, so repeat
the flag to pass several:

```rad
args:
    files f str[]
    counts int[]

print("files: {files}")
print("counts: {counts}")
```

```shell
./script -f hello.txt -f world.txt --counts 1 --counts 2 --counts 3
```

```
files: [ "hello.txt", "world.txt" ]
counts: [ 1, 2, 3 ]
```

Both long and short flags can be used interchangeably and repeated as needed.

### Variadic Arguments

Variadic arguments use a `*` prefix and collect any number of positional values into a list:

```rad
args:
    command str
    *files str
    verbose v bool

print("command: {command}")
print("files: {files}")
```

```shell
./script build file1.txt file2.txt file3.txt --verbose
```

```
command: build
files: [ "file1.txt", "file2.txt", "file3.txt" ]
```

Variadic args can have defaults and work with any type (`*numbers int`, `*values float`, etc.):

```rad
args:
    *items str = ["default.txt"]
```

You can have multiple variadic sections separated by flags - the flags act as delimiters:

```rad
args:
    *section1 str
    *section2 int
    flag f bool

print("section1: {section1}")
print("section2: {section2}")
```

```shell
./script a b c --flag 1 2 3
```

```
section1: [ "a", "b", "c" ]
section2: [ 1, 2, 3 ]
```

**Note: List types vs variadic**

    List args and variadic args both produce lists, and both collect bare positional values greedily. They differ in the flag form: a variadic takes a run of values after its own flag (`--files a.txt b.txt`), while a list takes one per occurrence (`--files a.txt --files b.txt`).

    Reach for a list for an ordinary several-values arg. Reach for a variadic when you're writing a wrapper that passes unrecognized flags through to another command - that's the job it keeps to itself.

### Optional Arguments

Mark arguments as optional with `?` suffix. When not provided, their value is `null`:

```rad
args:
    name str
    role str?
    year int?

if role == null:
    print("{name} has no role assigned")
else:
    print("{name} is a {role}")
```

```shell
./script Alice
```

```
Alice has no role assigned
```

You can check for null values with `== null` or use truthy/falsy logic: `if role:` will be false when role is null.

**Info: Defaults vs Optional**

    There are three states an argument can be in:

    - **Required** (e.g., `name str`): The user must provide a value. No default, not nullable.
    - **Has a default** (e.g., `joiner str = "-"`): Optional from the user's perspective - they can omit it and the default is used. The value is never `null`.
    - **Nullable** (e.g., `role str?`): If the user doesn't provide it, the value is `null`.

    Use a default when you have a sensible fallback value. Use `?` when the *absence* of a value is meaningful and you want to handle it explicitly in your script.

### Short Flag Clustering

When you define short flags (single letters), users can cluster multiple bool flags together:

```rad
args:
    verbose v bool
    debug d bool
    quiet q bool
```

```shell
./script -vdq    # Same as: -v -d -q
```

All three flags are set to true with this single clustered argument.

### Int Flag Counting

For `int` arguments with short flags, repeating the flag increments the count:

```rad
args:
    verbosity v int
```

```shell
./script -vvv           # verbosity = 3
./script -vvvvv         # verbosity = 5
```

This is useful for verbosity levels. If an explicit value is provided, it overrides the counting:

```shell
./script -vvv=10        # verbosity = 10 (not 3)
```

## Constraints

In addition to declaring the arguments themselves, Rad also allows you to declare constraints on those arguments, such as what kinds of values are valid.

By doing this in the args block, Rad can use this information to validate input for you, and automatically include the information in your script's usage string.

If a user gives an input which doesn't meet one of the listed constraints, Rad will print:

1. The specific error and constraint that was violated.

2. The usage string.

### Enums

If you have a string argument where you really only want to accept some limited number of known values, you can use an **enum constraint**.

Let's use a simple example, we'll call the script `colors`:

```rad
#!/usr/bin/env rad
args:
    color str
    color enum ["red", "green", "blue"]
print("You like {color}!")
```

If we print the usage string, you can see it tells users what values are valid:

```shell
./colors -h
```

```
Usage:
  colors <color>

Script args:
      --color str    Valid values: [red, green, blue].
```

If we invoke this script with a value outside the listed valid values:

```shell
./colors yellow
```

```
Invalid 'color' value: yellow (valid values: red, green, blue)
Usage:
  colors <color>

Script args:
      --color str    Valid values: [red, green, blue].
```

Whereas using a valid value will run the script as intended:

```shell
./colors green
```

```
You like green!
```

### Range

For numeric arguments (`int` or `float`), you can enforce minimum and maximum values using a **range constraint**.

Range constraints use `[` for inclusive bounds and `(` for exclusive bounds:

```rad
#!/usr/bin/env rad
args:
    age int
    temperature float

    age range [0, 120]              // 0 to 120, both inclusive
    temperature range (-50.0, 50.0) // Between -50 and 50, both exclusive
```

You can also specify only a floor or only a ceiling:

```rad
args:
    count int
    score float

    count range [1,]      // Minimum of 1, no maximum
    score range (,100.0]  // No minimum, maximum of 100 (inclusive)
```

**Info: Floor/Ceiling Syntax**

    When specifying only a floor or ceiling, both `[0,]` and `[0,)` are equivalent (both mean "minimum of 0, no maximum"). The closing delimiter doesn't affect the meaning when the value is omitted.

Let's look at a complete example with various range types:

```rad
#!/usr/bin/env rad
args:
    age int              # Person's age
    score float          # Test score
    count int            # Item count

    age range [0, 120]
    score range (0, 100]
    count range [1,]
```

The help text automatically shows the constraints:

```shell
./validator -h
```

```
Usage:
  validator <age> <score> <count> [OPTIONS]

Script args:
      --age int      Person's age. Range: [0, 120]
      --score float  Test score. Range: (0, 100]
      --count int    Item count. Range: [1, )
```

If a user provides an invalid value, they get a clear error:

```shell
./validator 150 50.0 5
```

```
'age' value 150 is > maximum 120

Usage:
  validator <age> <score> <count> [OPTIONS]

Script args:
      --age int      Person's age. Range: [0, 120]
      --score float  Test score. Range: (0, 100]
      --count int    Item count. Range: [1, )
```

When using exclusive bounds, values exactly at the boundary are rejected:

```shell
./validator 25 0 5   # score of 0 is invalid (exclusive minimum)
```

```
'score' value 0 is <= minimum (exclusive) 0
```

### Regex

If you'd like input strings to match a certain pattern, you can do that via a **regex constraint**.

```rad
args:
    name str
    name regex "[A-Z][a-z]*"
print("Hi, {name}")
```

In this example, a valid `name` value must start with a capital letter, and can then be followed by any number of lowercase letters.
No other characters will be accepted, so `Alice` will be a valid value, but `bob` or `John123` are not.

As with other constraints, Rad will validate input against this regex, and if it doesn't match, it will print an error. The constraint is also printed in the script's usage string.

### Constraints on lists

`enum`, `regex` and `range` work on list and variadic args too, where they describe **each value** rather than the list:

```rad
#!/usr/bin/env rad
args:
    scores int[]
    envs str[]

    scores range [0, 100]
    envs enum ["dev", "stg", "prd"]
print("{scores} on {envs}")
```

Every value has to pass, however it was supplied - repeated flags, or bare positional values:

```shell
./deploy --scores 5 --scores 500 --envs dev
```

```
'scores' value 500 is > maximum 100
```

Pick the constraint that matches what the arg holds. A `str[]` takes `enum` and `regex`; an `int[]` or `float[]` takes `range`. Declaring one that can't apply - `enum` on an `int[]`, say - is an error rather than something Rad ignores.

### Length

`len` bounds **how many** values a list or variadic takes, using the same interval notation as `range`:

```rad
#!/usr/bin/env rad
args:
    pair str[]
    sample int[]
    *ports int

    pair len [2,2]      // exactly two
    sample len [3,5)    // three or four
    ports len [1,]      // at least one
print(pair, sample, ports)
```

Without a `len`, `targets str[]` already means "at least one" and `targets str[] = []` means "may be empty" - `len` is how you say anything else.

It pairs with the constraints above rather than replacing them: `len` bounds the count, `range` bounds each value.

```shell
./pairs a
```

```
'pair' takes at least 2 values, got 1
```

### Relational

Relational constraints let you express logical relationships **between your script's arguments**. There are two types of constraints you can define:

- `excludes` (arguments can't appear together)
- `requires` (an argument depends on another argument also being provided)

You can optionally precede these with the `mutually` keyword to indicate that the constraint applies in both directions.

#### Exclusion

Use `excludes` to prevent arguments from being specified together. For example, consider a script that accepts either a file (`--file`) or a URL (`--url`), but not both:

```rad
#!/usr/bin/env rad
args:
  file str
  url str

  file mutually excludes url

if file:
    print("Reading from file:", file)
else:
    print("Fetching from URL:", url)
```

You can then provide either argument:

```
> ./fetcher --file data.json
Reading from file: data.json

> ./fetcher --url https://example.com/data.json
Fetching from URL: https://example.com/data.json
```

If both are provided, Rad gives a clear error:

```
> ./fetcher --file data.json --url https://example.com/data.json
Invalid arguments: 'file' excludes 'url', but 'url' was given
```

Note in this example, that if e.g. `file` is provided, then `url` will be `null` (and vice versa).

#### Requirement

Use the `requires` keyword to indicate that, when one argument is defined, so must another argument.

Consider a script that can authenticate either by using a token or by providing a username/password pair. 

If the user provides a username, the password is also required.

```rad
args:
  token str
  username str
  password str

  username mutually requires password
  token mutually excludes username, password

if token:
    print("Authenticating with token {token}")
else:
    print("Authenticating user {username} with password length {len(password)}")
```

Valid usage examples:

```
> ./auth --token abc123
Authenticating with token abc123

> ./auth --username alice --password secret
Authenticating user alice with password length 6
```

Invalid usage examples:

```
> ./auth --username alice
Invalid arguments: 'username' requires 'password', but 'password' was not provided

> ./auth --token abc123 --password secret
Invalid arguments: 'token' excludes 'password', but 'password' was given
```

## Summary

- Rad takes a *declarative* approach to args, and handles parsing user input.
- **Every argument works both positionally and as a named flag** - users can mix and match freely.
- Parsing is left-to-right: flags fill slots by name, bare values fill the next unfilled positional slot in declaration order.
- Anatomy of an arg declaration:

    `<name> [rename] [shorthand flag] <type> [= default] [# arg comment]`

- Argument names with underscores become hyphenated flags (e.g., `my_arg` becomes `--my-arg`).
- Rad supports various argument types:
    - Basic types: `int`, `float`, `str`, `bool`
    - List types: `str[]`, `int[]`, `float[]`, `bool[]` (bare positional values, or the flag repeated)
    - Variadic: `*args <type>` (like a list, but greedy after its own flag too)
    - Optional: `<type>?` (value is `null` when not provided)
- Bool flags are never positional. All other types are both positional and flag-based.
- Short flags support clustering (`-vdq`) and counting for ints (`-vvv` = 3).
- Use `--` to force everything after it to be treated as positional (useful for values starting with `-`).
- Both `--flag=value` and `--flag value` work. A `-`-prefixed token is never taken as a value, so equals syntax is how you pass one (`--name=-5`); number args accept `--count -5` directly.
- A list arg absorbs every remaining positional value, so args declared after one can only be set by flag.
- You can apply constraints to arguments inside the arg block:
    - `enum` for discrete values
    - `range` for numeric bounds (using `` for inclusive, `(` for exclusive)
    - `regex` for pattern matching
    - Relational constraints (`requires`, `excludes`)
- Details in the arg block are used by Rad to provide a better usage/help string.

## Next

Next, we'll look at another important concept in Rad: [Functions (rad docs guide/functions).

---

# Functions

Rad offers a range of built-in functions to help you write your scripts, and also allows you to define your own.
In this section, we'll take a look at the syntax and a few examples.
For a complete list of built-in functions, see the reference (rad docs reference/functions).

## Syntax

The syntax for invoking functions is pretty standard. Here's a script with some examples:

```rad
names = ["Bob", "Charlie", "Alice"]
num_people = len(names)
print("There are {num_people} people.")

sorted_names = sort(names)
print(sorted_names)
```

```
There are 3 people.
[ "Alice", "Bob", "Charlie" ]
```

This example uses three different built-in functions `len` (rad docs len), `print` (rad docs print), and `sort` (rad docs sort).

### UFCS

Rad supports a syntax called Uniform Function Call Syntax (UFCS) that lets you call functions using dot notation. This means you can write:

```rad
upper("hello")

// ... is the same as ...

"hello".upper()
```

Both styles work identically, it's just syntactic sugar, but the dot notation really shines when you're chaining multiple function calls together.

Compare these two approaches:

```rad
// Traditional nested calls - hard to read
result = upper(trim(text))

// UFCS chaining - reads left to right
result = text.trim().upper()
```

The chained version is much more readable - you can follow the data flow naturally from left to right.

UFCS works with any function where its first parameter matches the type you're calling it on.

**Tip: Encouraged Style**

    You're encouraged to use UFCS, especially when it helps you avoid nested function calls.

## Function Arguments

Rad functions can accept arguments in several different ways. Let's explore each pattern.

### Positional Arguments

Most functions accept arguments by position - you pass values in a specific order. Here are a few examples:

```rad
// Single argument
num = abs(-5)
print(num)  // 5

// Multiple arguments
text = "hello world".replace("world", "Rad")
print(text)  // hello Rad
```

Many functions also have **optional parameters with defaults**. For example, `join` (rad docs join) combines list items into a string:

```rad
numbers = [1, 2, 3]

// Just the list - uses default separator ""
print(numbers.join())

// Custom separator
print(numbers.join("... "))

// Separator and prefix
print(numbers.join("... ", "Counting: "))

// Separator, prefix, and suffix
print(numbers.join("... ", "Counting: ", "!"))
```

```
123
1... 2... 3
Counting: 1... 2... 3
Counting: 1... 2... 3!
```

The function signature for `join` shows these optional parameters: `join(list, sep="", prefix="", suffix="")`. You can provide as many or as few as you need.

**Tip: Example using join for url query params**

    The `prefix` parameter is handy for generating URL query params:

    ```rad
    url = "https://api.github.com/repos/amterp/rad/commits"
    query_params = ["path=README.md", "per_page=5"]
    url += query_params.join("&", "?")
    print(url)
    ```

    This produces: `https://api.github.com/repos/amterp/rad/commits?path=README.md&per_page=5` (https://api.github.com/repos/amterp/rad/commits?path=README.md&per_page=5)

### Named Arguments

Some functions accept **named arguments** that you pass using `name=value` syntax. Named arguments always come after positional arguments and are typically optional.

A good example is `http_post` (rad docs reference/functions), which performs HTTP POST requests:

```rad
// Just the URL (simplest form)
response = url.http_post()

// With custom headers
my_headers = {
    "Authorization": "Bearer {token}",
}
response = url.http_post(headers=my_headers)

// With both headers and a body
response = url.http_post(headers=my_headers, body=data)
```

Named arguments make it clear what each value represents, especially when a function has many optional parameters.

### Variadic Arguments

Some functions accept **unlimited arguments**. For example, `zip` (rad docs zip) can combine any number of lists:

```rad
names = ["alice", "bob", "charlie"]
ages = [30, 40, 25]
cities = ["NYC", "LA", "Chicago"]
scores = [100, 90, 85]

// Combine 2 lists
pairs = zip(names, ages)
print(pairs)

// Combine 3 lists
triples = zip(names, ages, cities)
print(triples)

// Combine 4 lists (or more!)
quads = zip(names, ages, cities, scores)
print(quads)
```

```
[ [ "alice", 30 ], [ "bob", 40 ], [ "charlie", 25 ] ]
[ [ "alice", 30, "NYC" ], [ "bob", 40, "LA" ], [ "charlie", 25, "Chicago" ] ]
[ [ "alice", 30, "NYC", 100 ], [ "bob", 40, "LA", 90 ], [ "charlie", 25, "Chicago", 85 ] ]
```

Variadic functions can also have named arguments. For example, `zip` accepts `strict=true` for ensuring that all lists have the same length.

### Mixed Patterns

Some functions combine multiple argument patterns. For example, `pick` (rad docs pick) takes positional arguments and a named argument:

```rad
options = ["vim", "emacs", "nano"]
editor = pick(options, prompt="Choose your editor")
```

When in doubt about how to call a function, check the Functions Reference (rad docs reference/functions) for complete signature details.

## Custom Functions

Rad lets you define your own functions using the `fn` keyword.
You can create either **named functions** that you reference by name, or **lambdas** (anonymous functions) that you assign to variables or pass as arguments.

### Named Functions

Named functions include the function name as part of the definition, making them easy to call from anywhere in your code.

#### Basic Definition

Here's a simple function that adds two numbers:

```rad
fn add(x, y):
    return x + y

result = add(5, 3)
print(result)  // 8
```

Functions use the `return` keyword to send values back. If your function body is a single expression, you can use a more concise syntax:

```rad
fn add(x, y) x + y

result = add(5, 3)
print(result)  // 8
```

Notice there's no colon (`:`) after the parameters in the single-line form, and no `return` keyword is needed.

#### Multiple Return Values

Functions can return multiple values at once using comma separation:

```rad
fn get_coords():
    x = 10
    y = 20
    return x, y  // equivalent to 'return [x, y]'

x_pos, y_pos = get_coords()
print("Position: ({x_pos}, {y_pos})")
```

```
Position: (10, 20)
```

This uses **destructuring** (covered in Basics (rad docs guide/basics)) to unpack the returned values into separate variables.

#### Type Annotations

You can optionally add type annotations to function parameters and return values:

```rad
fn calculate_area(width: int, height: int) -> int:
    return width * height

area = calculate_area(5, 10)
print(area)  // 50
```

There are three benefits to using these.

1. They serve as documentation (self-documenting code).
2. They are validated at runtime i.e. the above function will error early if a string is passed into `calculate_area`.
3. They help Rad's static analysis tools reason about your code, making them more useful.

They are covered in detail in a later section: Type Annotations (rad docs guide/type-annotations).

#### Hoisting

Named functions have some special scoping rules worth knowing:

**At the root level, functions are hoisted** - you can call them before they're defined:

```rad
result = multiply(4, 5)
print(result)  // 20

fn multiply(a, b):
    return a * b
```

This works because Rad processes all root-level function definitions before executing the script.

**Inside blocks, functions are NOT hoisted** - you must define them before calling:

```rad
if true:
    print(helper())  // Error - can't call before definition

    fn helper():
        return "I'm a helper!"
    
    print(helper())  // This is okay!
```

### Lambdas

Sometimes you need a quick function without giving it a name. That's where **lambdas** come in - they're anonymous functions you can assign to variables or pass as arguments.

Lambdas use the same `fn` keyword, but without a name:

```rad
// Single-line lambdas
double = fn(x) x * 2
add = fn(x, y) x + y

print(double(5))  // 10
print(add(3, 4))  // 7
```

For multi-line logic, use the block style with a colon:

```rad
calculate = fn(x):
    result = x * 2 + 10
    return result

print(calculate(5))  // 20
```

Lambdas are particularly useful for defining once-off operations and passing them as arguments.
For example, with `map` (rad docs map), `filter` (rad docs filter), and `flat_map` (rad docs flat_map):

```rad
numbers = [1, 2, 3, 4, 5]
doubled = numbers.map(fn(x) x * 2)
print(doubled)  // [2, 4, 6, 8, 10]

evens = numbers.filter(fn(x) x % 2 == 0)
print(evens)  // [2, 4]

// flat_map is useful for transformations that produce lists
words = ["hello world", "foo bar"]
all_words = words.flat_map(fn(s) s.split(" "))
print(all_words)  // ["hello", "world", "foo", "bar"]
```

**Tip: Named Functions vs Lambdas**

    - Use **named functions** (`fn add(x, y):`) for reusable logic that you'll call from multiple places
    - Use **lambdas** (`fn(x) x * 2`) for one-off operations or callbacks

## Reference

There are a lot of built-in functions. If you want to see what's available and how to use them, refer to the reference (rad docs reference/functions).
You can also look up any individual function directly from the terminal: `rad docs len`, `rad docs sort`, etc.

## Summary

- Function invocation syntax is similar to Python, Java, and other familiar languages
- **UFCS** (Uniform Function Call Syntax) lets you chain functions using dot notation: `text.trim().upper()`
- Functions can accept arguments in several ways:
    - **Positional**: passed by order, may have defaults (`join(list)`, `join(list, "|")`)
    - **Named**: passed with `name=value` syntax (`http_get(url, headers=my_headers)`)
    - **Variadic**: accept unlimited arguments (`zip(list1, list2, list3, ...)`)
    - **Mixed**: combinations of the above patterns
- You can define **named functions** with `fn name():` for reusable logic
    - Supports block style (with `:`) 
    - Supports single-line style (without `:` e.g. `fn add(x, y) x + y`)
    - Can return multiple values using comma separation
    - Are **hoisted** at the root of scripts (can be called before definition)
    - Can have optional **type annotations**
- **Lambdas** are anonymous functions: `double = fn(x) x * 2`
    - Useful for one-off operations and callbacks - functions like `map()`, `filter()`, and `flat_map()`

## Next

We've already covered the Basics of strings (rad docs guide/basics),
but there are some more advanced string concepts which are worth covering, such as formatting in string interpolations,
raw strings, etc.

We'll cover these in the next section: Strings (Advanced) (rad docs guide/strings-advanced)

---

# Strings (Advanced)

Strings are everywhere in scripting - from building messages to formatting output. In the Basics (rad docs guide/basics) section, we covered simple string operations, but Rad offers much more powerful features for working with text.

In this section, we'll explore:

- **String interpolation** - embed expressions directly in strings
- **Formatting** - control how values are displayed (padding, fill characters, zero-padding, precision, thousands separators)
- **Multiline strings** - work with text spanning multiple lines
- **Raw strings** - disable interpolation and escaping when you need literal text
- **Escape sequences** - include special characters like newlines and tabs
- **String attributes** - add color, bold, and other terminal styling

## String Interpolation

Rad allows embedding expressions inside your strings that will get evaluated and replaced to produce the 'final' string.

Some examples:

```rad
name = "Alice"
print("Hi, {name}!")

print("Uppercase: {name.upper()}")

print("Conditions: {name.len() > 5 ? 'long name' : 'short name'}!")
```

```
Hi, Alice!
Uppercase: ALICE
Conditions: short name!
```

String interpolation expressions can be as simple as just an identifier, or can involve function calls, math, list comprehensions, etc (though you should consider extracting complex expressions into named variables beforehand for the sake of clarity).

Note the use of single quote `'` strings inside the last line of the above example.
You don't have to switch delimiters like that, though it can help readability:
everything inside `{ }` is parsed as code, not text, so nested strings using the
*same* delimiter as the outer string work, no escaping needed.

```rad
tokens = ["Hello", "World"]
print("{tokens.join(" ")}")
print("Count: {tokens.len() > 1 ? "several" : "just one"}")
```

```
Hello World
Count: several
```

The one exception is a nested string *immediately* after the `{`, because
`"{"` is also how you write a literal opening brace, and the two cannot be
told apart. Switch delimiters there, or add a space:

```rad
print("{'ERROR'.red()}")     // fine
print("{ "ERROR".red() }")   // also fine
```

## Formatting

You can format expression results while doing string interpolation.
To do so, follow your expression with a colon `:` and then the relevant syntax for the formatting you want to do.
We'll demonstrate through some examples:

```rad
pi = 3.14159265359

print("Pi: {pi}_")       // no formatting
print("Pi: {pi:20}_")    // left-pad to 20 places (default)
print("Pi: {pi:<20}_")   // right-pad to 20 places
print("Pi: {pi:.3}_")    // print to 3 decimal places
print("Pi: {pi:10.2}_")  // left-pad to 10 places, including 2 decimal places
```

```
Pi: 3.14159265359_
Pi:             3.141593_
Pi: 3.141593            _
Pi: 3.142_
Pi:       3.14_
```

### Fill Characters

By default, padding uses spaces. You can specify a different fill character by placing it before the alignment indicator (`>` or `<`):

```rad
name = "Alice"
num = 42

print("_{name:*>10}_")   // fill with *, right-align
print("_{name:.<10}_")   // fill with ., left-align
print("_{num:->8}_")     // fill with -, right-align
```

```
_*****Alice_
_Alice....._
_------42_
```

The fill character can be any single character. The `>` and `<` after it control the alignment, just like without a fill character.

### Zero-Padding

You can use the zero-pad shorthand by placing `0` before the width. This works on any type:

```rad
name = "alice"
num = 42
neg = -7

print("_{name:08}_")     // pad string with zeros to width 8
print("_{num:05}_")      // pad number with zeros to width 5
print("_{neg:06}_")      // sign-aware for numbers: sign before zeros
print("_{num:08.2}_")    // combine with precision
```

```
_000alice_
_00042_
_-00007_
_00042.00_
```

You can also combine zero-padding with thousands separators:

```rad
num = 7000
print("_{num:010,}_")
```

```
_00,007,000_
```

For numbers, zero-pad is sign-aware (signs placed before zeros). For non-numbers, it simply prepends zeros (same as explicit zero fill `{x:0>5}`).

### Thousands Separator

For large numbers, you can add comma separators using `,` in your formatting:

```rad
population = 1234567
price = 1234.56

print("Population: {population:,}")
print("Price: {price:,.2}")
print("Large: {population:20,.0}")  // combine padding, comma, and precision
```

```
Population: 1,234,567
Price: 1,234.56
Large:            1,234,567
```

### Number vs String Formatting

Decimal place formatting (`.X`) and thousands separators (`,`) only work on numbers. Using them on strings will cause an error:

```rad
name = "Alice"
print("{name:.2}")   // Error: cannot format string with decimal places
print("{name:,}")    // Error: cannot format string with thousands separator
```

However, padding, fill characters, and zero-padding work on all types:

```rad
name = "Alice"
print("{name:10}")     // "     Alice" (padded to 10 chars)
print("{name:*>10}")   // "*****Alice" (fill with *, any type)
print("{name:08}")     // "000Alice"   (zero-pad shorthand, any type)
```

## Multiline Strings

Sometimes you want to write strings that contain several lines. These strings may themselves also contain string delimiters e.g. `"` or `'`.
For these scenarios, Rad offers `"""` multiline string syntax. To demonstrate:

```rad
text = """
This is an
example of text
that "may contain quotes"!
It also supports interpolation:
One plus one equals {1 + 1}
"""
print(text)
```

```
This is an
example of text
that "may contain quotes"!
One plus one equals 2
```

Multiline strings must follow some rules:

1. The opening `"""` must not be followed by any non-comment tokens on the same line.
2. The newline after the opening `"""` is *excluded* from the contents of the string. Contents begin on the next line.
3. The closing `"""` must not be preceded by any non-whitespace characters on that same line.
   The newline before the closing `"""` is likewise *excluded* - the string does **not** end with a newline (see the warning below).
4. Whitespace preceding the closing `"""` will get removed from the front of each line in the string block.
    - In other words, you can use the indentation of the closing `"""` to control the desired indentation of your contents.
    - If the closing `"""` is preceded by more whitespace than exists on any line of string contents, that means we cannot remove that amount of whitespace from the line, leading to an error.

Below, we demonstrate the 4th point. Note that to make the "whitespaces" more visible, I've replaced them with dots, but keep in mind they *do represent spaces*:

```rad
text = """
....This is an
.....example of text
..that "may contain quotes"!
.."""  // < 2 preceding spaces. will get removed from each line in the contents.
print(text)
```

```
..This is an
...example of text
that "may contain quotes"!
```

**Warning: Multiline strings do not end with a newline**

    The newline before the closing `"""` is stripped (rule 3). That reads
    naturally when printing, but it's a footgun when *assembling* text, e.g.
    building a shell script or config file by concatenation:

    ```rad
    BLOCK = """
    echo "step done" >&2
    """
    script = BLOCK + "pwd"
    print(script)
    ```

    ```
    echo "step done" >&2pwd
    ```

    The two fragments run together on one line - and bash happily parses
    `>&2pwd` as a redirect to a file named `2pwd`, so the assembled script
    even *succeeds* silently. When concatenating multiline strings, add the
    joining newline yourself (`BLOCK + "\n" + ...`), or leave an intentionally
    blank last line in the block - only the single final newline is stripped:

    ```rad
    BLOCK = """
    echo "step done" >&2

    """
    print(BLOCK + "pwd")
    ```

    ```
    echo "step done" >&2
    pwd
    ```

## Raw Strings

Rad also supports **raw strings**.
Raw strings don't perform string interpolation and do not allow any escaping (including the delimiter used to create them).
Use them when you want your contents to remain as "raw" and unprocessed as possible.

To use them, just prefix the delimiter of your choice (single/double quotes or backticks) with `r`.

```rad
text = r"Hello\n{name}"
print(text)
```

```
Hello\n{name}
```

Notice the printed string is exactly as written in code - the newline character and string interpolation are left as-is.

You can use any of the string delimiters for raw strings, including multiline `"""`:

```rad
text = r"Hello\n{name}"
text = r'Hello\n{name}'
text = r`Hello\n{name}`
text = r"""
Hello\n{name}
"""
```

**Tip: Common uses for raw strings**

    Raw strings can be quite handy for file paths, especially Windows-style ones that use backslashes:

    ```rad
    path = r"C:\Users\Documents\notes.txt"
    ```

    They can also be useful for text containing lots of braces `{}`, in order to disable string interpolation:

    ```rad
    json_str = r"{ 'my_key': { 'my_key2' : 3 } }"
    ```

## Escape Sequences

When you need special characters in your strings, you can use backslash `\` to escape them:

```rad
print("Line 1\nLine 2")      // newline
print("Col1\tCol2")          // tab
print("Path: C:\\Users")     // backslash
print("She said \"Hi!\"")    // quote (though prefer using a different delimiter, or raw strings)
```

```
Line 1
Line 2
Col1	Col2
Path: C:\Users
She said "Hi!"
```

**Available escape sequences:**

- `\n` - newline
- `\t` - tab
- `\\` - literal backslash
- `\"` `\'` `` \` `` - the delimiter itself (though prefer using a different delimiter)
- `\{` `\}` - literal braces (prevents interpolation, but consider using raw strings)

A brace that cannot open an interpolation needs no escape: `"{"`, `"{}"` and
`"{ }"` are all literal, as is any `}` with no interpolation open.

## String Attributes

Strings in Rad can carry attributes like color, bold, italic, and underline. These attributes are preserved through string interpolation and concatenation:

```rad
name = "Alice".green()
print("Hello, {name}!")  // "Alice" appears green in terminal
print("Status: " + "ACTIVE".bold())  // "ACTIVE" appears bold
```

You can apply multiple attributes by chaining function calls:

```rad
title = "Important".underline().bold()
warning = "WARNING".bold().red()
print(title)
print(warning)
```

Rad provides color functions (`red`, `green`, `blue`, `yellow`, etc.), style functions (`bold`, `dim`, `italic`, `strikethrough`, `underline`),
and the `hyperlink` function for creating clickable terminal links. See the functions reference (rad docs reference/functions).

**Info: When Attributes Are Preserved**

    - **Preserved**: Interpolation, concatenation, index lookup, slicing, `upper()`, `lower()`, `trim()`, `trim_prefix()`, `trim_suffix()`, `trim_left()`, `trim_right()`, and `reverse()`
    - **Not preserved**: `replace()`, `split()`

**Tip: String Manipulation Functions**

    In addition to the syntax features covered here, Rad provides many built-in functions for working with strings.
    Use UFCS (rad docs guide/functions) (dot notation) for cleaner, more readable code:

    - `text.upper()`, `text.lower()` - change case
    - `text.replace(old, new)`, `text.split(sep)`, `items.join(sep)` - transform and combine strings
    - `text.trim()`, `text.trim_left()`, `text.trim_right()` - strip matching characters
    - `text.trim_prefix(prefix)`, `text.trim_suffix(suffix)` - remove a literal prefix/suffix
    - `text.starts_with(prefix)`, `text.ends_with(suffix)` - check string prefixes/suffixes
    - `text.count(substr)` - count substring occurrences
    - And many more!

    See the Functions Reference (rad docs reference/functions) for the complete list with examples.

## Patterns: Literal by Default

Rad's string functions match literally. `split`, `replace`, `count`, `index_of`,
`starts_with` and friends all look for the exact text you give them, so a `.` is a
dot and a `(` is a parenthesis - nothing needs escaping.

```rad
print(split("1.2.3", "."))            // -> ["1", "2", "3"]
print(replace("cost: $5", "$5", "$8")) // -> "cost: $8"
```

When you do want a regex, ask for one. `split` and `replace` take a `regex` parameter:

```rad
print(split("a b  c", "\s+", regex=true))       // -> ["a", "b", "c"]
print(replace("order 66", "\d+", "N", regex=true)) // -> "order N"
```

`matches` is the exception, and it's the one you'd expect: it exists to test patterns,
so it's always a regex.

```rad
print(matches("hello", "h.+o"))   // -> true
```

Patterns use Go's RE2 dialect, which has no backreferences or lookaround. A pattern
that doesn't compile is an error rather than a silent fallback.

**Info: Changed in v0.12**

    `split` and `replace` used to treat their pattern as a regex by default. See the
    v0.12 migration guide (rad docs migrations/v0.12) if you're upgrading.

## Summary

- We learned about **escape sequences** like `\n`, `\t`, and `\{` for including special characters in strings.
- We covered **string interpolation**, which lets us put expressions directly into strings for evaluation.
- We saw how to **format** interpolated expressions using padding, fill characters, zero-padding, precision, and more. Example: `{num:0>10,.3}`.
- We explored **multiline strings** using `"""` syntax, which support both quotes and interpolation.
- We learned about **raw strings** (prefixed with `r`) that prevent interpolation and escaping.
- We covered **string attributes** like color and bold that are preserved through interpolation and concatenation.
- We saw that string functions match **literally** by default, with `regex=true` to opt into pattern matching.
- Rad also provides many built-in string manipulation functions covered in the Functions Reference (rad docs reference/functions).

## Next

Next, let's look at another Rad feature which makes it uniquely suited to certain types of scripting: Rad Blocks (rad docs guide/rad-blocks).

---

# Rad Blocks

Working with JSON APIs is a common scripting task. You might need to query GitHub for repository info, check the
status of your cloud services, or pull data from internal APIs. Typically, this involves making HTTP requests,
parsing JSON responses, extracting the fields you care about, and formatting everything for display.

Rad makes this entire workflow concise and declarative with **rad blocks** - a special syntax that lets you query
JSON APIs and display results as formatted tables in just a few lines of code. Instead of writing imperative parsing
logic, you declare what you want, and Rad handles the rest.

## Basic Example

This concept will become clearer with an example.

Below is a simple script capable of querying a given GitHub repo (leveraging GitHub's public API) for information about
its latest commits.

```rad
args:
    repo str        # The repo to query. Format: user/project
    limit int = 20  # The max commits to return.

url = "https://api.github.com/repos/{repo}/commits?per_page={limit}"

Time = json[].commit.author.date
Author = json[].commit.author.name
SHA = json[].sha

rad url:
    fields Time, Author, SHA
```

And running it looks something like this:

```shell
rad commits amterp/rad 5
```

```
Querying url: https://api.github.com/repos/amterp/rad/commits?per_page=5
Time                  Author          SHA
2025-01-11T04:15:06Z  Alexander Terp  306f3a4ddb3b09747d61a5eab264c3d72fbbc36e
2025-01-11T03:07:56Z  Alexander Terp  304a914644dfd73a59b85a191481f9c429b4d25e
2025-01-11T01:00:42Z  Alexander Terp  7171ec92ae729f9d04e224e16272c9b888dffe41
2025-01-10T12:11:08Z  Alexander Terp  4b64f585d08d9a5ee40549b6b9624530ac713eb1
2025-01-09T11:34:51Z  Alexander Terp  abfcf2d940a18b819f7ae9e9040550a9644e5120
```

This is a simple example, but it demonstrates the ability to query GitHub's API (which returns JSON), extracting fields we're interested in (commits' time, author, and SHA).

And that's with just a few lines of code! Let's break it down piece by piece.

### Arg Block

```rad
args:
    repo str        # The repo to query. Format: user/project
    limit int = 20  # The max commits to return.
    
url = "https://api.github.com/repos/{repo}/commits?per_page={limit}"
```

Here we have an args block (rad docs guide/args) where we declare a `repo` string and a `limit` int with a default of 20.
After the args block, we create a `url` string using string interpolation (rad docs guide/strings-advanced) to fill in the repo name, and the limit for how many commits we want GitHub to give us.

### Json Paths

```rad
Time = json[].commit.author.date
Author = json[].commit.author.name
SHA = json[].sha
```

This is where things get more interesting. The above definitions correspond to expected *paths* in the JSON response i.e. a series of keys to look up.

In Rad nomenclature, we refer to these as **json path definitions**.

If you query GitHub's API and take a look at the JSON response, you can see how these paths correspond to the data.
Example URL if you want to see for yourself:

<a href="https://api.github.com/repos/amterp/rad/commits?per_page=2" target="_blank">https://api.github.com/repos/amterp/rad/commits?per_page=2</a>

Here's a simplified example response with two commits, showing the structure we're interested in:

```json
[
  {
    "sha": "306f3a4ddb3b09747d61a5eab264c3d72fbbc36e",
    "commit": {
      "author": {
        "name": "Alexander Terp",
        "date": "2025-01-11T04:15:06Z"
      }
    }
  },
  {
    "sha": "2b642c482b32e4d87924839b2f5a9592670dee69",
    "commit": {
      "author": {
        "name": "Alexander Terp",
        "date": "2025-01-10T12:21:03Z"
      }
    }
  }
]
```

You can see how the path for `Author = json[].commit.author.name` corresponds to a final value of "Alexander Terp".

Json paths leverage a special syntax that Rad offers. They always start with `json`.
`json` can be thought of as representing the JSON blob as a whole, or its root, if you want to think of the JSON data as a tree.

The `[]` after `json` tells Rad that you expect the `json` blob to be a list, and to "unwrap" it and dig into individual items in that list for the remainder of the path.
`commit` then tells it to look up a key of that name (literally `commit`), and to then look up `author` next, and then finally `name`.

### Basic Path Syntax Summary

The examples above demonstrate the core JSON path patterns you'll use most often:

- **Dot notation**: `json.field` or `json.commit.author.name` for nested fields
- **Array unwrapping**: `json[]` tells Rad to iterate through a list
- **Combined**: `json[].field.nested` extracts nested data from each array item

**Tip: Advanced JSON Path Features**

    The JSON path syntax supports additional powerful features like wildcards (`json[].*`), indexed access
    (`json[0]`, `json.items[2]`), and multiple levels of array unwrapping (`json[].items[][].related[]`).
    These will be covered in a later section.

When a json path declaration is executed, its variable (`Author` for example) is initialized as an empty list.
It's a "special" list though, as it has a json field definition tied to it, which can be used in a rad block, let's look at that one next.

### Rad Block

```rad
rad url:
    fields Time, Author, SHA
```

**Info: Why 'rad'?**

    The project name **Rad** comes from its original core use case: **R**equest **A**nd **D**isplay.
    This workflow - querying data from APIs and displaying it in readable tables - is exactly
    what `rad` blocks are designed for. It's not just the project name, it's what the keyword does!

`rad` is a keyword that executes a "Request And Display" workflow.

Following the `rad` keyword, we provide the `url` variable which will get used to execute an `HTTP GET` request.
Then, inside the rad block itself, using the keyword `fields`, we specify the earlier json fields that we defined.
Listing them here will tell the rad block to extract data from the resulting JSON blob according to the json field
paths that you defined.
The ordering in which the fields are listed also controls the ordering of columns in the ensuing table that gets printed.

When run, this will print the table we saw earlier; here it is again for reference (with a limit of 3).

```
Time                  Author          SHA
2025-01-11T04:15:06Z  Alexander Terp  306f3a4ddb3b09747d61a5eab264c3d72fbbc36e
2025-01-11T03:07:56Z  Alexander Terp  304a914644dfd73a59b85a191481f9c429b4d25e
2025-01-11T01:00:42Z  Alexander Terp  7171ec92ae729f9d04e224e16272c9b888dffe41
```

Note that the variable names we choose for the json field definitions become the header names in the table.

## Additional Rad Block Options

Rad blocks include options to control the resulting table.

### Sorting

By default, the rows in your table are sorted by their original order in the JSON blob. However, you can control this.

Let's say we have the following table by default:

```
City         Country  Population
Los Angeles  USA      3800000
London       England  8800000
Houston      USA      2300000
Copenhagen   Denmark  640000
```

The simplest sorting option is alphabetically, across the whole row.

```rad
rad url:
    fields City, Country, Population
    sort
```

```
City         Country  Population
Copenhagen   Denmark  640000
Houston      USA      2300000
London       England  8800000
Los Angeles  USA      3800000
```

What if we wanted to sort by Country, though? And then break ties with City? We can do that:

```rad
rad url:
    fields City, Country, Population
    sort Country, City
```

```
City         Country  Population
Copenhagen   Denmark  640000
London       England  8800000
Houston      USA      2300000
Los Angeles  USA      3800000
```

If we wanted to sort by descending population, you can add `desc` after the name of the column:

```rad
rad url:
    fields City, Country, Population
    sort Population desc
```

```
City         Country  Population
London       England  8800000
Los Angeles  USA      3800000
Houston      USA      2300000
Copenhagen   Denmark  640000
```

**Note: 'asc' is the default**

    `sort City` and `sort City asc` are both valid and identical in functionality - you can include it if you want to be explicit.

### Mapping

You can also *transform* a column's values before it gets printed.

For example, let's say you wanted the 'Population' column in the above example to be in millions, and to display one decimal place, you can do that with a `map` column modifier:

```rad
rad url:
    fields City, Country, Population
    Population:
        map fn(p) "{p/1e6:.1}"
```

The syntax here is `map <lambda>`. In this example, the lambda is `fn(p) "{p/1e6:.1}"`.

You can read about lambdas in an earlier section here: Functions: Lambdas (rad docs guide/functions).

If we run this, you'll see the change:

```
City         Country  Population
Los Angeles  USA      3.8
London       England  8.8
Houston      USA      2.3
Copenhagen   Denmark  0.6
```

Let's break down this syntax more. After declaring the fields:

```rad
Population:
    map fn(p) "{p/1e6:.1}"
```

`Population:` begins a column modifier block. The identifier prior to the colon is expected to be one of the fields. Inside one of these blocks, you can apply modifiers on that column, such as `map` or `color`.

`map` is considered a keyword in the context of rad blocks. After `map`, a lambda expression is expected, which you can think of as a mini-function.

In this case, we've written `fn(p) "{p/1e6:.1}"`. The lambda takes a variable `p` (name could be any valid identifier). This will represent an individual value in the `Population` list.
The expression that follows is what will get evaluated and decide the final value in each cell.
It is the *output* of your lambda mini-function. In this example, we turn it into a string, created using string interpolation.

Inside the string interpolation expression, we first divide it by one million (`p/1e6`, using scientific notation), and then
use formatting syntax (right of the colon) to specify that we want the resulting float to be stringified with one decimal place (`.1`).

**Note: Modifier Execution Order**

    Field modifiers execute in a specific order: **filter → sort → map**

    - **Filter** first: Removes unwanted rows before sorting
    - **Sort** middle: Sorts the filtered data in its original form
    - **Map** last: Transforms values for display only

    This means sorting and filtering see the original extracted values, not the transformed display values from `map`.

#### Lambda Context Parameter

When transforming columns with `map`, your lambda can optionally accept a second parameter to access context information about the transformation:

```rad
rad url:
    fields City, Country, Population
    Population:
        map fn(p, ctx) "{p / sum(ctx.src) * 100:.1}%"
```

This shows each city's population as a percentage of the total.

The context object provides three fields:

- **`ctx.idx`** - The current row index (0-based)
- **`ctx.src`** - An immutable snapshot of the full column data (as a list)
- **`ctx.field`** - The name of the field being transformed (e.g., "Population")

This is useful for operations that need to know about the overall dataset:

```rad
// Highlight the largest city
City:
    map fn(city, ctx) ctx.idx == 0 ? "{city} ★" : city
```

The `field` property is especially helpful when applying the same transformation to multiple columns:

```rad
// Apply to multiple columns, with field-specific logic
timestamp, strategy, fund:
    map fn(x, ctx):
        if ctx.field == "timestamp":
            return format_time(x)
        return str(x)
```

**Note: Context is Optional**

    Single-parameter lambdas continue to work exactly as before. The context parameter is completely optional:

    ```rad
    Population:
        map fn(p) p / 1e6  // No context needed
    ```

### Filtering

You can also *filter* rows based on conditions. This is useful when you only want to display data that matches certain criteria.

For example, let's say you're querying an API that returns users, but you only want to see active users over 18 years old:

```rad
rad url:
    fields Name, Age, Status
    Age:
        filter fn(age) age >= 18
    Status:
        filter fn(s) s == "active"
```

The syntax is `filter <function>`. The function receives each value from that column and returns a boolean (or truthy value). If it returns true, that row is kept. If false, the entire row is discarded.

In this example, we're applying two filters:

- `Age`: Keep only rows where age is 18 or greater
- `Status`: Keep only rows where status equals "active"

When multiple fields have filters, a row must pass **all filters** to be displayed (AND logic). In our example, both the age and status filters must pass.

Let's see this in action with some mock data:

```rad
Ages = [25, 15, 30, 20, 12]
Names = ["Alice", "Bob", "Charlie", "Diana", "Eve"]
Status = ["active", "active", "inactive", "active", "active"]

rad:
    fields Names, Ages, Status
    Ages:
        filter fn(a) a >= 18
    Status:
        filter fn(s) s == "active"
```

```
Names   Ages  Status
Alice   25    active
Diana   20    active
```

Notice that Charlie doesn't appear (age >= 18 but status is inactive), Bob doesn't appear (active but age < 18), and Eve doesn't appear (active but age < 18).

Like with sorting and mapping, the filter predicate can be a lambda expression or a function reference:

```rad
rad:
    fields Name, Age
    Age:
        filter is_adult

fn is_adult(age):
    return age >= 18
```

Just like `map`, filter lambdas can accept an optional context parameter with `idx`, `src`, and `field`:

```rad
// Keep only even-indexed rows
Names:
    filter fn(n, ctx) ctx.idx % 2 == 0

// Keep values below the column average
Age:
    filter fn(age, ctx) age < sum(ctx.src) / ctx.src.len()
```

**Note: Execution Order: filter → sort → map**

    Filtering happens **before** sorting and mapping. This means:
    - Filters see the original extracted values (not transformed by `map`)
    - Sorting operates on already-filtered data
    - Mapping transforms the final filtered+sorted values for display

    This order ensures your filters work on raw data and your sorts only process rows that will actually be displayed.

### Color

Another column modifier uses the keyword `color`. You can tell Rad to color a cell's value depending on its contents by using a regex (https://en.wikipedia.org/wiki/Regular_expression).

For example:

```rad
rad url:
    fields City, Country, Population
    Country:
        color "pink" ".*"
        color "red" "Denmark"
        color "blue" "USA"
```

The syntax is `color <color> <regex>`. You can apply multiple rules, and later rules override earlier ones. 
For example, here we start off by coloring *everything* pink.
Then, we add three more rules: any sequence "Denmark" should be colored red, and "USA" should be colored blue.

!color

This screenshot from a terminal demonstrates the colors. England is colored pink because the initial `.*` rule is the only regex that matched it.

Note that the specific colors that appear varies between terminals and user settings.

Valid colors: `plain`, `black`, `red`, `green`, `yellow`, `blue`, `magenta`, `cyan`, `white`, `orange`, `pink`.

#### Multi-Column Modifiers

You can apply the same modifiers to multiple columns at once by listing them together:

```rad
rad url:
    fields Status, Priority, Assignee, DueDate
    Status, Priority:
        color "green" "complete|high"
        color "red" "blocked|low"
    Status, Priority, Assignee:
        map fn(s) upper(s)
```

This example applies color rules to both `Status` and `Priority`, then transforms three columns to uppercase with a single `map` block. This is much more concise than writing separate modifier blocks for each column.

Any column modifier (`filter`, `map`, `color`) can be applied to multiple columns this way.

### If Statements

Rad blocks can contain if statements, so if you want slightly different behavior for your rad block based on some condition, you don't need to
copy and paste the whole block into two separate if blocks.

Let's say your script had a flag for sorting by population or not. Here's an example of how that could look:

```rad
args:
    sort_by_population p bool  # Enable to sort by population.

// ... some script stuff here

rad url:
    fields City, Country, Population
    if sort_by_population:
        sort Population desc
    else:
        sort
```

If the flag is enabled, we sort by descending population, otherwise we sort rows alphabetically.

You can put any rad block statements into these if blocks, including `fields`, column modifiers, etc.

## Rad Block Options

### noprint: Suppress Table Output

By default, a `rad` block prints its results as a table. Add `noprint` to suppress this, which is useful when you want
to process the extracted data further without displaying it.

```rad
rad url:
    noprint
    fields City, Country, Population
    sort Population desc

// From here, the field lists are populated and sorted
// City[0] is now the city with the largest population
largest_city = City[0]
print("The largest city is {largest_city}")
```

Note that `filter`, `sort`, and `map` all work with `noprint` since they modify the underlying data. However, `color` has no effect since nothing gets displayed.

### quiet: Suppress HTTP Log

When fetching from a URL, Rad logs "Querying url: ..." to stderr. Add `quiet` to suppress this log:

```rad
rad url:
    quiet
    fields Name, Age
```

Both `noprint` and `quiet` support explicit boolean values: `noprint true`, `noprint false`, `noprint some_variable`.

### transpose: Swap Rows and Columns

By default, fields become column headers and each record is a row. Add `transpose` to flip the table on its side - the original headers become the first column, and each record becomes a subsequent column:

```rad
Name = ["Alice", "Bob", "Charlie"]
Age = [30, 40, 25]
rad:
    fields Name, Age
    transpose
```

```
Name  Alice  Bob  Charlie
Age   30     40   25
```

This is handy when you have only a few records but many fields - the normal layout would scroll off-screen horizontally, while the transposed layout keeps each field visible on its own line.

Like `noprint` and `quiet`, `transpose` accepts an explicit boolean: `transpose true`, `transpose false`, or `transpose some_variable`. It also works inside `if` blocks, so you can conditionally flip the layout based on a flag or row count:

```rad
rad url:
    fields Name, Age, City, Country
    if len(Name) <= 3:
        transpose
```

`transpose` composes with the other rad block features - `sort`, `filter`, `map`, and `color` all apply to the underlying data first, and the transpose happens at render time. So `sort Name asc` still sorts records by name, even though those records will end up as columns rather than rows.

## Source Types

The behavior of a `rad` block depends on what source you give it:

### URL String Source

When the source evaluates to a string, Rad treats it as a URL and performs an HTTP GET request:

```rad
rad url:
    fields Name, Age
```

### List/Map Source

When the source is a list or map (e.g. from `http_get`), Rad extracts data from it without making an HTTP request.
This is useful when you need custom headers or authentication:

```rad
// Fetch data with custom headers
resp = http_get(url, headers=my_headers)

// Define JSON paths
Name = json[].name
Age = json[].age

// Extract and display
rad resp.body:
    fields Name, Age
    sort Age desc
```

### No Source

When no source is given, Rad displays already-populated data as a table:

```rad
Nums = [1, 2]
Words = ["hi", "hello"]
rad:
    fields Nums, Words
```

```
Nums  Words
1     hi
2     hello
```

**Info: Modifiers and Data Mutation**

    When a rad block has a source, it's performing data extraction - pulling values from JSON into your field
    variables. Since it's *populating* those variables, it naturally owns them, and modifiers (`filter`, `sort`,
    `map`) operate directly on the extracted data.

    When there's no source, the rad block is simply *presenting* data that already exists. Your variables were
    populated elsewhere, so modifiers are applied only for rendering - the original data is left untouched.

## Understanding HTTP Requests

When you write a `rad` block with a URL string source, Rad automatically performs an **HTTP GET** request to the URL and expects a JSON response.
This happens behind the scenes - you don't need to explicitly call any HTTP functions.

### Headers and Authentication

Currently, `rad` blocks with URL sources don't support custom headers or authentication directly. If you need to add headers (for example, to authenticate with an API), use the `http_get` (rad docs reference/functions) or `http_post` (rad docs reference/functions) functions first, then pass the response body as the source:

```rad
args:
    token str  # API authentication token

headers = {
    "Authorization": "Bearer {token}",
    "Accept": "application/json"
}

url = "https://api.github.com/user/repos"
resp = http_get(url, headers=headers)

// Define JSON paths for the response
Name = json[].name
Stars = json[].stargazers_count

// Extract and display the data we fetched
rad resp.body:
    fields Name, Stars
    sort Stars desc
```

This pattern gives you full control over the HTTP request while still leveraging rad blocks for data extraction and display.

## Summary

- **Rad blocks** make working with JSON APIs concise and declarative - request, extract, and display data in just a few lines
- Source type determines behavior:
    - **`rad url:`** (string source) - Fetch JSON from URL, extract, and display
    - **`rad data:`** (list/map source) - Extract from in-memory data and display
    - **`rad:`** (no source) - Display already-populated data as a table
- **Options** control output:
    - **`noprint`** - Suppress table output (extract data only)
    - **`quiet`** - Suppress the "Querying url: ..." stderr log
    - **`transpose`** - Swap rows and columns so fields stack vertically
- **JSON field definitions** use special path syntax to extract data from JSON responses
    - Basic patterns: `json.field`, `json[]`, `json[].nested.path`
    - Advanced features exist (wildcards, indexing) for complex extraction needs
- **Table customization** options:
    - **Filtering**: Remove rows based on conditions
    - **Sorting**: `sort`, `sort Field`, `sort Field desc`
    - **Transforming**: Map functions to modify column values
    - **Styling**: Color cells based on regex patterns
    - **Multi-column**: Apply same modifiers to multiple columns at once
    - **Conditional**: Use `if` statements for dynamic behavior
    - **Execution order**: filter → sort → map
- **HTTP control**: rad blocks perform GET automatically; use `http_get()`/`http_post()` and pass the response body as a rad block source for more advanced queries (e.g. requiring headers/auth)

## Next

Next, we'll cover an important concept for keeping your scripts maintainable: Type Annotations (rad docs guide/type-annotations).

---

# Type Annotations

As your scripts grow beyond quick one-offs, type annotations become increasingly valuable.
They help catch errors early, make your code self-documenting, and keep scripts maintainable as they evolve or get shared with others.

In the Functions (rad docs guide/functions) section, we briefly introduced type annotations for function parameters and return values.
Now let's explore Rad's complete type system - from basic primitives to advanced types like unions, structs, and function signatures.

## The Basics

Type annotations let you declare what types of values your function parameters accept and what type of value your
function returns. The syntax follows a pattern you may recognize from TypeScript or Python's type hints:

```rad
fn calculate_area(width: int, height: int) -> int:
    return width * height

area = calculate_area(5, 10)
print(area)  // 50
```

Here, `width: int` and `height: int` specify that both parameters must be integers, and `-> int` declares that the function returns an integer.

### Why Use Type Annotations?

Type annotations provide three key benefits:

1. **Self-documenting code** - The function signature clearly communicates what types it expects and returns
2. **Runtime validation** - Rad checks types at runtime and produces helpful error messages when types don't match
3. **Tooling support** - IDEs and linters can provide better autocomplete and catch errors before you run your code

Let's see runtime validation in action:

```rad
fn greet(name: str) -> str:
    return "Hello, {name}!"

message = greet(42)  // Error!
print(message)
```

```
Error at L4:17

message = greet(42)  // Error!
                ^^ Value '42' (int) is not compatible with expected type 'str'
```

The error message clearly identifies the problem - we passed an integer when the function expects a string.

### Basic Primitive Types

Rad supports the standard primitive types you'd expect: `str`, `int`, `float`, and `bool`

```rad
fn process_data(
    name: str,
    age: int,
    salary: float,
    is_active: bool
) -> str:
    status = is_active ? "active" : "inactive"
    return "{name} ({age}) earns ${salary:.2} - {status}"

result = process_data("Alice", 30, 75000.50, true)
print(result)
```

```
Alice (30) earns $75000.50 - active
```

### Special Types: void and null

Two additional types appear throughout Rad but work differently from the primitives:

**`void`**: Indicates a function returns nothing. Functions marked `-> void` don't return a value, and attempting to return a value is an error:

```rad
fn log_message(msg: str) -> void:
    print(msg)                 // OK

fn log_message(msg: str) -> void:
    return msg                 // Error: can't return values
```

**`null`**: The single value representing "no value" or "absence." Important: `null` is only a valid value for optional types marked with `?`:

```rad
fn get_name() -> str:
    return null          // Error: can't return null from str function

fn get_name() -> str?:
    return null          // OK: str? can return null
```

Think of `null` as belonging exclusively to optional types - it's the way to represent "this optional value is absent."

## Collection Types

Rad also lets you specify collection types, with their contents being either typed or untyped.

### Typed Lists

You can specify what type of values a list contains using the `<type>[]` syntax:

```rad
fn sum_numbers(nums: int[]) -> int:
    total = 0
    for num in nums:
        total += num
    return total

result = sum_numbers([1, 2, 3, 4, 5])
print(result)  // 15
```

The `int[]` annotation means "a list of integers". Like with other type annotations, if you try to pass a list
containing non-integers, you'll get a runtime error.

More examples with different types:

```rad
fn join_words(words: str[]) -> str:
    return words.join(" ")

fn average(numbers: float[]) -> float:
    return sum(numbers) / len(numbers)

sentence = join_words(["Hello", "from", "Rad"])
print(sentence)
```

```
Hello from Rad
```

### Typed Maps

Maps can also be typed, specifying both key and value types using `{ <key type>: <value type> }` syntax:

```rad
fn count_words(text: str) -> { str: int }:
    words = text.split(" ")
    counts = {}
    for word in words:
        if word in counts:
            counts[word] += 1
        else:
            counts[word] = 1
    return counts

result = count_words("hello world hello")
print(result)
```

```
{ "hello": 2, "world": 1 }
```

The `{ str: int }` annotation means "a map with string keys and integer values".

### Generic Collections

When you don't want to specify what's inside a collection, use the generic forms:

```rad
fn print_items(items: list) -> void:
    for item in items:
        print(item)

fn lookup(data: map, key: str) -> any:
    return data[key]
```

Here, `list` accepts a list with any types of values, and `map` accepts a map with any keys and values.

The `any` type means "any type of value" - it's the most permissive type and accepts strings, numbers, booleans, lists, maps, or any other value.

Generic collections are useful when your types are mixed or you don't wish to overcomplicate your type annotations unnecessarily.

### Nested Collections

Types can be nested for complex data structures:

```rad
fn organize_by_category(items: str[]) -> { str: str[] }:
    categories = {}
    for item in items:
        category = item[0].upper()  // First letter
        if category not in categories:
            categories[category] = []
        categories[category] += [item]
    return categories

items = ["apple", "banana", "apricot", "blueberry"]
result = organize_by_category(items)
print(result)
```

```
{ "A": [ "apple", "apricot" ], "B": [ "banana", "blueberry" ] }
```

The return type `{ str: str[] }` describes a map where each key is a string and each value is a list of strings.

## Optional Types

Sometimes a parameter might not always be needed. Rad's optional type syntax with `?` makes parameters completely optional - you can pass a value, pass `null`, or omit the parameter entirely:

```rad
fn greet(name: str, title: str?) -> str:
    if title == null:
        return "Hello, {name}!"
    else:
        return "Hello, {title} {name}!"

print(greet("Alice", "Dr."))     // Pass a value
print(greet("Bob", null))        // Explicitly pass null
print(greet("Charlie"))          // Omit the parameter entirely
```

```
Hello, Dr. Alice!
Hello, Bob!
Hello, Charlie!
```

The `str?` annotation means "an optional string parameter". When omitted or explicitly set to `null`, the parameter will be `null` inside the function. This makes it clear that the `title` parameter is optional and the function knows how to handle its absence.

Optional types work with any type:

```rad
fn find_user(id: int, users: map[]) -> map?:
    for user in users:
        if user["id"] == id:
            return user
    return null

users = [{"id": 1, "name": "Alice"}, {"id": 2, "name": "Bob"}]
user = find_user(1, users)
print(user)  // {"id": 1, "name": "Alice"}

missing = find_user(999, users)
print(missing)  // null
```

The `map?` return type indicates the function might return a map or might return null if no user is found.

### Narrowing Optionals

An explicit null-check *narrows* an optional type: inside the check, the type
checker treats the value as non-null, so operations that need the underlying
type stop being flagged. This matters for functions like
`index_of` (rad docs index_of), which return `int?`:

```rad
my_args = ["build", "-o", "out"]
idx = my_args.index_of("-o")

if idx != null:
    // idx is narrowed from int? to int here
    if idx + 1 < my_args.len():
        print("output:", my_args[idx + 1])
```

Without the `idx != null` check, `idx + 1` reports a hint (`cannot do
'int? + int'`) - the value really could be null. The null-check is both the
fix for the hint and the correctness fix.

A guard doesn't need its own block. `and` reaches its right operand only when
the left was true, and `or` only when it was false, so the narrowing carries
across:

```rad
my_args = ["build", "-o", "out"]
idx = my_args.index_of("-o")

if idx != null and idx + 1 < my_args.len():
    print("output:", my_args[idx + 1])
```

Order decides it, though. Written the other way round, as
`idx + 1 < my_args.len() and idx != null`, the comparison runs before anything
is known and still reports.

An `in` guard narrows `index_of` on the spot, with no variable to hold the
result:

```rad
my_args = ["build", "-o", "out"]
flag = "-o"

if flag in my_args:
    // the lookup can't miss here, so it's int rather than int?
    print(my_args.index_of(flag) + 1)
```

That last one is a pattern match rather than general reasoning. It wants the
same container and the same target on both sides, and it drops if you pass `n`
or `start`, which ask for an occurrence membership doesn't promise.

## Defaults

Parameters can have default values, making them optional to provide when calling the function. This works whether or not the parameter is marked with `?`:

```rad
fn greet(name: str, greeting: str = "Hello") -> str:
    return "{greeting}, {name}!"

print(greet("Alice"))                // Uses default "Hello"
print(greet("Bob", "Hi"))            // Uses provided "Hi"
```

```
Hello, Alice!
Hi, Bob!
```

The `greeting` parameter has a default value of `"Hello"`. When you omit it, the default is used. Note that `greeting` is not marked with `?` - it always has a string value, never `null`.

### Defaults & Optionals

When you combine defaults with optional types (`?`), you can choose whether the default should be `null` or something else:

```rad
fn format_price(amount: float, currency: str? = "USD") -> str:
    if currency == null:
        return "${amount:.2}"
    return "{amount:.2} {currency}"

print(format_price(19.99))           // Uses default "USD"
print(format_price(19.99, "EUR"))    // Uses provided "EUR"
print(format_price(19.99, null))     // Explicitly passes null
```

```
19.99 USD
19.99 EUR
$19.99
```

With `str?` alone, omitting the parameter means it defaults to `null`. With `str? = "USD"`, you can provide a non-null default value, but callers can still explicitly pass `null` if they want.

## Union Types

Sometimes a function can accept or return multiple different types. Union types express this with the `|` operator:

```rad
fn to_string(val: int|float|str) -> str:
    return str(val)

print(to_string(42))
print(to_string(3.14))
print(to_string("hello"))
```

```
42
3.14
hello
```

The `int|float|str` annotation means "accepts an int, float, or string" - any of these three types is valid.

### Error Union Types

A common union pattern in Rad is combining `error` with another type to represent operations that might fail:

```rad
fn divide(a: float, b: float) -> float|error:
    if b == 0:
        return error("Cannot divide by zero")
    return a / b

result = divide(10, 2)
print(result)  // 5
```

The `float|error` return type signals that this function returns either a float (on success) or an error value (on failure).

**Note: Error Handling in Rad**

    Rad has a comprehensive error handling model. We'll cover error handling in detail in a later section: Error Handling (rad docs guide/error-handling).

## Advanced Types

Rad's type system includes several advanced features for expressing complex data structures and constraints.

### Enum Types

When a value should be restricted to specific strings, use enum types:

```rad
fn set_log_level(level: ["debug", "info", "warn", "error"]) -> str:
    return "Log level set to: {level}"

print(set_log_level("info"))
// set_log_level("trace")  // Error: "trace" not in enum
```

```
Log level set to: info
```

The `["debug", "info", "warn", "error"]` annotation restricts the parameter to exactly these four string values. Any other string will cause a runtime type error.

This is particularly useful for configuration options, status values, and other cases where only certain strings are valid:

```rad
fn create_connection(
    host: str,
    protocol: ["http", "https", "ws", "wss"] = "https"
) -> str:
    return "{protocol}://{host}"

url = create_connection("api.example.com")
print(url)
```

```
https://api.example.com
```

### Structured Maps

For maps with specific named fields, use the struct syntax with quoted keys:

```rad
fn create_user(name: str, age: int, email: str) ->
        { "name": str, "age": int, "email": str, "id": int }:
    return {
        "name": name,
        "age": age,
        "email": email,
        "id": rand_int(1000, 9999)
    }

user = create_user("Alice", 30, "alice@example.com")
print(user)
```

```
{ "name": "Alice", "age": 30, "email": "alice@example.com", "id": 7234 }
```

The `{ "name": str, "age": int, "email": str, "id": int }` annotation describes a map with exactly these four fields, each with a specific type. Notice the quoted keys - this distinguishes named fields from the typed map syntax we saw earlier.

#### Optional Fields in Structs

Fields can be marked as optional with `?`:

```rad
fn get_user_profile(id: int) ->
        { "name": str, "age": int, "bio"?: str, "avatar"?: str }:
    // Fetch user... in this example, we'll return mock data
    return {
        "name": "Bob",
        "age": 25,
        "bio": "Software engineer"
        // avatar field is omitted
    }

profile = get_user_profile(123)
print(profile)
```

```
{ "name": "Bob", "age": 25, "bio": "Software engineer" }
```

The `"bio"?: str` and `"avatar"?: str` fields are optional - the map might or might not contain them.

#### Nested Structures

Struct types can be nested for complex data:

```rad
fn fetch_article() -> {
    "title": str,
    "author": { "name": str, "id": int },
    "metadata": { "views": int, "likes": int },
}:
    return {
        "title": "Getting Started with Rad",
        "author": {"name": "Alice", "id": 1},
        "metadata": {"views": 1234, "likes": 56}
    }

article = fetch_article()
print("Article: {article.title} by {article.author.name}")
print("Stats: {article.metadata.views} views, {article.metadata.likes} likes")
```

```
Article: Getting Started with Rad by Alice
Stats: 1234 views, 56 likes
```

### Function Types

Functions themselves can be typed, which is especially useful when passing functions as parameters:

```rad
fn apply_to_list(items: str[], transform: fn(str) -> str) -> str[]:
    result = []
    for item in items:
        result += [transform(item)]
    return result

words = ["hello", "world"]
upper_words = apply_to_list(words, upper)
print(upper_words)
```

```
[ "HELLO", "WORLD" ]
```

The `fn(str) -> str` annotation describes a function that takes a string parameter and returns a string.

Other examples of valid function type annotations:

```
fn() -> int
fn(str, str) -> str
fn(str[]) -> void
```

## Variadic and Named Parameters

Type annotations work seamlessly with Rad's parameter patterns, as seen earlier in Functions (rad docs guide/functions).

### Variadic Parameters

When a function accepts unlimited arguments, you can type the variadic parameter:

```rad
fn sum_all(*numbers: int) -> int:
    total = 0
    for num in numbers:
        total += num
    return total

result = sum_all(1, 2, 3, 4, 5)
print(result)
```

```
15
```

The `*numbers: int` annotation means "zero or more integer arguments". All arguments passed to this variadic parameter must be integers.

### Named-Only Parameters

Named-only parameters (those after `*`) can also be typed:

```rad
fn format_text(
    text: str,
    *,
    uppercase: bool = false,
    prefix: str = "",
    suffix: str = ""
) -> str:
    result = prefix + text + suffix
    return uppercase ? upper(result) : result

output = format_text("hello", uppercase=true, prefix=">>> ")
print(output)
```

```
>>> HELLO
```

### Combining Everything

Here's a function that combines positional, variadic, and named-only parameters with types:

```rad
fn create_report(
    title: str,
    *data_points: int|float,
    *,
    format: ["text", "html", "json"] = "text",
    include_summary: bool = true
) -> str:
    total = sum(data_points)
    avg = total / len(data_points)

    report = "=== {title} ===\n"
    report += "Data: {data_points.join(', ')}\n"

    if include_summary:
        report += "Total: {total}, Average: {avg:.2}"

    return report

output = create_report(
    "Q4 Sales",
    100, 150, 200, 175,
    format="text",
    include_summary=true
)
print(output)
```

```
=== Q4 Sales ===
Data: 100, 150, 200, 175
Total: 625, Average: 156.25
```

This example demonstrates:

- A required positional parameter (`title: str`)
- A typed variadic parameter accepting multiple numeric values (`*data_points: int|float`)
- Named-only parameters with enum and boolean types
- A clear, self-documenting function signature

## Summary

Type annotations are an optional but powerful tool for keeping your Rad scripts maintainable and self-documenting,
especially as they grow in complexity or get reused across projects.

**Key takeaways:**

- **Syntax**: Parameter types use `param: <type>`, return types use `-> <type>`
- **Benefits**: Self-documenting code, runtime validation, better tooling support
- **Primitive types**: `str`, `int`, `float`, `bool` for basic values
- **Special types**: `void` (function returns nothing), `null` (only valid for optional types marked with `?`)
- **Collection types**:
    - `T[]` for typed lists (e.g., `str[]`, `int[]`, `float[]`)
    - `{ <key type>: <value type> }` for typed maps (e.g., `{ str: int }`)
    - `list` and `map` for generic collections (any contents)
    - Nested collections like `int[][]` and `{ str: str[] }`
- **Optional types**: `T?` for nullable values (e.g., `str?`, `int?`)
- **Union types**: `T|U` for multiple acceptable types (e.g., `int|float`, `str|list`)
- **Advanced types**:
    - **Enums**: `["value1", "value2", "value3"]` for restricted string values
    - **Structs**: `{ "field1": type1, "field2"?: type2 }` for structured maps with named fields (quoted keys) and optional fields
    - **Function types**: `fn(<param_type>) -> <return_type>` for function parameters and variables
    - **Nested structures**: Complex combinations of the above
- **Special parameters**: Work with variadic (`*param: <type>`) and named-only parameters

## Next

We've briefly seen `error|T` union types in this section - functions that return either a value or an error.

In the next section, we'll explore Rad's comprehensive error handling model in depth: Error Handling (rad docs guide/error-handling).

---

# Error Handling

Things go wrong in scripts - users provide invalid input, files don't exist, network requests fail.
Generally, for smaller CLI scripts, it's okay if we just exit on the spot, and that's also Rad's default behavior.
However, if you wish to more gracefully handle these errors or attempt recovery, Rad gives you the tools to do so.

In Rad, **errors are values**. Functions that might fail return either a result or an error,
and you can decide how to handle them. This makes error handling explicit, predictable, and easy to reason about.

In this section, we'll explore:

- **Error propagation** - how errors bubble up by default (and why scripts exit)
- **The `catch:` block** - handle errors with full control (logging, reassignment, exit)
- **The `??` operator** - shorthand for fallback values on null or error
- **The `catch` operator** - like `??`, but only catches errors (null passes through)
- **Creating errors** - using `error()` in your own functions
- **Error type unions** - making fallible operations explicit with `T|error` type annotations

## Error Propagation

Let's start with a simple script that takes a user's age as input:

```rad
args:
    age_str str  # User's age as a string

age = parse_int(age_str)
print("You are {age} years old")
```

In reality, you'd instead declare the arg as an `int` and let Rad handle input validation,
but for the purposes of this guide, we write it as a `str`.

If we run this with a valid number, everything works:

```shell
rad age 25
```

```
You are 25 years old
```

But what happens with invalid input?

```shell
rad age "not-a-number"
```

```
Error at L4:7

age = parse_int(age_str)
      ^^^^^^^^^^^^^^^^^^ parse_int() failed to parse "not-a-number" (RAD20001)
```

The script **exits immediately** with an error code of 1 when `parse_int` encounters invalid input.
What's happening is that `parse_int` returned an `error` value, and since we're not handling it, it immediately gets propagated up.
Since we're at the root of the script and not nested within any other function call, this triggers a script exit on the spot.

### Nested Calls

Errors don't just propagate from built-in functions - they bubble up through your own function calls too. Here's an example:

```rad
fn calculate_discount(price_str: str) -> float|error:
    price = parse_float(price_str)  // Error starts here...
    return price * 0.1

fn process_order(item_price: str) -> str|error:
    discount = calculate_discount(item_price)  // ...propagates through here...
    return "Discount: {discount:.2} USD"

result = process_order("invalid")  // ...and exits the script here
print(result)
```

```
Error at L2:13

      price = parse_float(price_str)  // Error starts here...
              ^^^^^^^^^^^^^^^^^^^^^^
              parse_float() failed to parse "invalid" (RAD20002)
```

The error originates in `parse_float`, propagates through `calculate_discount`, then through `process_order`, and finally exits at the top level. At any point in this chain, we could choose to handle the error instead of letting it propagate.

This sets up the question: how do we handle errors gracefully instead of crashing?

## Catch Blocks

The `catch:` block gives you full control over error handling. Attach it as a suffix to any expression that might error, and you can inspect the error, log it, provide a fallback value, or decide whether to exit.

### Basic Error Handling

Here's how to handle our age parsing example gracefully:

```rad
args:
    age_str str

age = parse_int(age_str) catch:
    print_err("Invalid age, falling back to 0: {age}")  // 'age' contains the error value
    age = 0  // Provide fallback

print("Age: {age}")
```

Now when we run it with invalid input:

```shell
rad age "not-a-number"
```

```
Invalid age, falling back to 0: parse_int() failed to parse "not-a-number"
Age: 0
```

The script **continues running** with our fallback value. Inside the `catch:` block, the `age` variable contains the
error string, as returned by `parse_int`, which we can log or inspect. We then reassign `age` to a sensible default value of `0`.

To summarize:

- **Suffix** form: write `... catch:` directly after the error-able expression.
- **Binding**: the target variable is first bound to the error value; inside the block, interpolating it (e.g. `{age}`) prints the error's message.
- **Control**: you can log, reassign a fallback, or exit(code).
- **Flow**: execution continues after the block unless you exit.

### Exiting on Errors

Sometimes you want to fail fast - handle the error just enough to log a helpful message, then exit:

```rad
args:
    config_file str

config = read_file(config_file) catch:
    print_err("Failed to read config: {config}")
    exit(1)

print("Config loaded successfully")
// Continue processing config...
```

Running this with a non-existent file:

```shell
rad readconfig "missing.txt"
```

```
Failed to read config: open missing.txt: no such file or directory
```

This example is not much better than the default error propagation and exit, but you can imagine providing
more useful guidance to users in a more detailed error message.

### Ignoring Errors with `pass`

Sometimes you want to ignore errors entirely - the operation might fail, but that's perfectly fine and requires no action:

```rad
// Custom fn to clean up temp file if it exists
delete_path(temp_file) catch:
    pass  // File already doesn't exist, that's fine

// Continue with the rest of the script...
```

Here, `pass` does nothing - it's a way to explicitly say "I know this might error, but I don't care." This is useful for cleanup operations where the failure itself is harmless.

## The `??` Operator

For simple cases where you just want a default value without any logging or conditional logic, the `??` operator provides a concise shorthand:

```rad
age = parse_int(age_str) ?? 0
timeout = parse_int(get_env("TIMEOUT")) ?? 30
max_retries = parse_int(config["retries"]) ?? 5
```

`??` fires when the left side is **null or an error**, making it a null-coalescing operator:

```rad
name = user["name"] ?? "anonymous"   // handles both missing keys and null values
config = read_file(config_path) ?? get_default_config()
```

The right side uses **lazy evaluation** - it's only evaluated if the left side is null or an error. This means you can safely call functions on the right without worrying about unnecessary work.

This makes `??` useful for safely drilling into nested data. If any key along the way is missing or null, the whole expression falls back:

```rad
name = response.user.profile.display_name ?? "anonymous"
```

## The `catch` Operator

The `catch` operator is similar to `??`, but **only catches errors** - null values pass through unchanged:

```rad
age = parse_int(age_str) catch 0      // error -> 0, but null stays null
data = parse_json(raw_input) catch {}  // parse failure -> empty map
```

This is useful when you want to handle errors but need to preserve null as a meaningful value:

```rad
m = {"key": null}
m["key"] ?? "fallback"     // -> "fallback" (?? treats null as missing)
m["key"] catch "fallback"  // -> null       (catch lets null through)
```

Like `??`, `catch` supports lazy evaluation and chaining:

```rad
result = risky_call() catch fallback_call() catch "final default"
```

**Note: Not to be confused with `catch:` blocks**

    The `catch` operator is an inline expression. The `catch:` block (with a colon) is a statement-level construct covered above that gives you full control, including logging and conditional exit.

### Comparing `??`, `catch`, and `catch:`

These three give you different levels of control:

```rad
// ?? - fallback on null or error
age = parse_int(age_str) ?? 0

// catch - fallback on error only (null passes through)
age = parse_int(age_str) catch 0

// catch: block - full control (logging, conditional handling)
age = parse_int(age_str) catch:
    print_err("Invalid age '{age_str}': {age}")
    age = 0
```

**Tip: When to use which**

    Use `??` when you want a default for both null and error cases.
    Use `catch` when you only want to handle errors and null is a valid value.
    Use `catch:` when you need to log, inspect, or conditionally handle the error.

The two operators look at the value the left side produced, so they also fire on an error
you already hold - see Holding an Error. A `catch:` block instead
catches an operation that failed, so a statement that merely assigns an error you already
had doesn't trigger it.

All three work on a shell command read inline, since a non-zero exit is an ordinary error:

```rad
tag = $`git describe --tags`.stdout.trim() catch "untagged"
```

That holds for `.stdout` and `.stderr`. `.code` and `.ok` never produce an error - reading
them is how you handle a failure - so wrapping those in `??` or `catch` does nothing. See
Reading One Result Inline (rad docs guide/shell-commands).

## Creating Your Own Errors

When writing your own functions, you can return errors using the `error(str)` function.
If you're using type annotations, then functions that may return errors should reflect that in its return type: `T|error`.

```rad
fn validate_port(port: int) -> int|error:
    if port < 1 or port > 65535:
        return error("Port must be between 1-65535, got {port}")
    return port

fn start_server(port_str: str) -> void:
    port = parse_int(port_str) ?? 8080

    validated_port = validate_port(port) catch:
        print_err("Invalid port: {validated_port}")
        exit(1)

    print("Starting server on port {validated_port}")

start_server("99999")
```

```
Invalid port: Port must be between 1-65535, got 99999
```

Our custom error message provides clear feedback about what went wrong.
By returning `int|error`, the type signature tells you three things:

1. This function normally returns an `int`
2. It might return an `error` instead
3. Callers should consider handling the error case (otherwise let it propagate)

This pattern is used throughout Rad's built-in functions:

- `parse_int(str) -> int|error`
- `parse_float(str) -> float|error`
- `read_file(path) -> error|{ "size_bytes": int, "content": str }`
- `round(num, decimals) -> error|int|float`

**Info: More on Union Types**

    We covered union types in detail in an earlier section: Type Annotations (rad docs guide/type-annotations).
    Error unions are just one application of Rad's union type system.

## Holding an Error

A `catch:` block that doesn't reassign leaves the error itself in the variable, where you
can read it:

```rad
fn fail() -> str|error:
    return error("boom")

stored = fail() catch:
    pass

print(stored)           // boom
print(type_of(stored))  // error
```

It is still live, though. Returning it from another function raises it again, and the
script exits pointing at that second call rather than the original one:

```rad
fn fail() -> str|error:
    return error("boom")

fn relay(x):
    return x

stored = fail() catch:
    pass

result = relay(stored)  // exits: boom
```

Rad doesn't record whether an error has been handled before. A function that returns an
error has failed, whatever that error's history, so guard the call like any other:

```rad
result = relay(stored) ?? "default"
result = relay(stored) catch "default"
```

The alternative - marking an error handled so it never fires again - would make a real
failure vanish the moment it passed through a function that returned it unchanged.
Assigning the value elsewhere and reading it are both safe; only a call that returns it
raises it.

## Summary

Rad's error handling model gives you the tools to write robust scripts that handle failures gracefully:

- **Errors are values** that **propagate** by default, unless handled
- **Scripts exit** if errors propagate up to the root of the script
- **`catch:` blocks** provide full error handling control:
    - Variable contains the error string inside the block
    - You can log errors, provide fallbacks, or call `exit()`
    - Execution continues unless you explicitly exit
- **`??` operator** provides concise fallbacks on null or error
    - Use for simple cases without logging
    - Right side only evaluated if left side is null or errors
- **`catch` operator** provides fallbacks on error only
    - Null values pass through unchanged
    - Useful when null is a meaningful value you want to preserve
- **Create errors** with `error("message")` in your own functions
- **Type unions** (`T|error`) make fallible operations explicit in function signatures
- **A held error stays live** - returning it from another function raises it there, so
  guard that call too

## Next

CLI scripts and the shell go hand in hand, and Rad offers first-class support for invoking shell commands and handling its output.
We explore this in the next section: Shell Commands (rad docs guide/shell-commands).

---

# Shell Commands

The shell offers a wide range of utilities and is essential for CLI scripting - from file operations to invoking
installed programs like git, make, or docker.

Rad has rich built-in functionality (`http_get`, `read_file`, `write_file`, etc.), but sometimes you need to invoke
system tools or installed programs. Rad makes this ergonomic through first-class shell command support, and quotes
the values you interpolate so a filename with a space - or a string from somewhere you don't control - can't turn
into shell syntax.

## Invoking Commands

Shell commands are invoked by prefixing a string with `$`:

```rad
$`ls -la`
```

You can also pre-define the command as a string variable:

```rad
cmd = `ls -la`
$cmd
```

`$` takes the command and nothing else. Anything after it reads the command's
*result*, so a command you compute on the spot goes in parentheses:

```rad
cmds = [`ls -la`, `ls -l`]
$(cmds[0])
```

By default, the stdout/stderr will be printed directly to the user's terminal as if they had invoked it directly themselves.

**Tip: Prefer backticks for shell command strings**

    Shell commands often use 'single' and "double" quotes, so backticks minimize delimiter conflicts.
    However, you can use any string delimiter.

## Which Shell Runs My Command?

Rad picks a shell to run your command in this order:

1. **`SHELL` env var** if it's set - this is the user's explicit choice and always wins.
2. **On Windows** (when `SHELL` is unset): `pwsh.exe` (PowerShell 7+), then `powershell.exe` (Windows PowerShell, ships with every Win10+), then `cmd.exe` as a last resort.
3. **On Linux/macOS** (when `SHELL` is unset): `/bin/sh`.

## Capturing Output

Shell commands produce three things: **stdout**, **stderr**, and an **exit code**. You can capture anywhere from zero to all three, depending on what you need.

### Capture Modes

There are four levels of capture:

**1. No capture - output goes to terminal**

When you don't assign any variables, all output goes to the terminal:

```rad
$`ls -la`
```

**2. Capture stdout**

Assign to one variable to capture the command's output:

```rad
stdout = $`git show 0dd21e6`
```

Stdout is captured as a `str`. Stderr still goes to the terminal.
**Important:** When you capture a stream, it stops printing to the terminal - it's redirected to your variable.

**3. Capture stdout + stderr**

Assign to two variables to capture both streams:

```rad
stdout, stderr = $`npm install`
```

Both are captured as `str`. Nothing the command prints reaches the terminal.

**4. Capture everything, including the exit code**

Assign to three variables:

```rad
stdout, stderr, code = $`npm install`
```

The exit code is an `int`. It needs no capturing, so it comes last - and you often don't need it at all, because a non-zero exit already raises an error you handle with `catch:` (see Error Handling below).

### Named Assignment

Rad supports a special form of assignment when working with shell commands. When **all** your variables are named
exactly `code`, `stdout`, or `stderr`, then assignment happens by name rather than by position.
This means the order doesn't matter:

```rad
// Named assignment - order independent
stdout, code = $`echo hi`           // code=0, stdout="hi\n"
stderr = $`bad-command`             // Just capture stderr
code, stderr = $`make format`       // code=1, stderr=""
stderr, stdout, code = $`ls`        // All three, any order
```

It's the only way to capture the exit code without also capturing the streams:
`code = $cmd` leaves stdout and stderr going to the terminal.

**The rule:** If ALL variables use exactly `code`, `stdout`, or `stderr`, assignment is by name. Otherwise, it's positional:

```rad
// Positional - neither name is reserved, so slots decide
out, err = $`echo hi`               // out = stdout, err = stderr
result, errors, status = $`ls`      // Assigned in (stdout, stderr, code) order
```

Note that the two rules agree as long as you keep to the canonical order - `stdout = $cmd` and
`stdout, stderr = $cmd` mean the same thing whether Rad reads them by name or by position.

**Warning: Don't mix reserved and unreserved names**

    One unreserved name drops the *whole* statement to positional, so a reserved name in the
    wrong slot silently gets something else:

    ```rad
    code, output = $`echo hi`       // 'code' gets stdout!
    ```

    Rad warns about this (RAD40018 (rad docs reference/errors)). Name them all, or name none.

**Tip: Silencing outputs**

    Use `_` to discard a stream you don't want printed: `_ = $cmd` swallows stdout,
    and `_, _ = $cmd` swallows both streams for fully silent execution.

## Reading One Result Inline

Capturing into a variable is right when you want several results, or want to
keep working with them. When you want one value, put the accessor on the command
and use it where you stand:

```rad
branch = $`git branch --show-current`.stdout.trim() catch "unknown"

if not $`which docker`.ok:
    print_err("docker is not installed")
    exit(1)
```

There are four accessors, and one of them must immediately follow the command:

| Accessor  | Type   | Fails if the command failed |
| --------- | ------ | --------------------------- |
| `.stdout` | `str`  | yes                         |
| `.stderr` | `str`  | yes                         |
| `.code`   | `int`  | no                          |
| `.ok`     | `bool` | no                          |

Capture works the same way it does for assignment: the stream you name is
captured, the other still reaches the terminal, and the two status accessors
capture neither.

### Which One To Reach For

`.stdout` and `.stderr` give you what the command produced, and fail if it
failed - output a failed command never produced isn't an answer, so you get an
error rather than an empty string:

```rad
files = $`git ls-files`.stdout.split("\n")
```

`.ok` and `.code` describe the outcome and never fail. Asking about the outcome
*is* handling it, which is what makes them the right way to test a command:

```rad
if not $`git diff --quiet`.ok:
    print("you have uncommitted changes")

// grep exits 1 for "no match" - that's data, not a failure
matched = $`grep -q TODO src.rad`.code == 0
```

**Note: This differs from `code = $cmd`**

    Capturing the code in an assignment still propagates the error, because a
    statement's only product is its effect. Reading `.code` doesn't, because
    you've asked about the failure directly.

### Failing Softly

Since the output accessors propagate, everything you'd use on a fallible
function works here too:

```rad
tag = $`git describe --tags`.stdout.trim() catch "untagged"
tag = $`git describe --tags`.stdout.trim() ?? "untagged"

tag = $`git describe --tags`.stdout.trim() catch:
    print_err("no tags yet")
    tag = "untagged"
```

### An Accessor Is Required

A command on its own isn't a value:

```rad
if $`git status --porcelain`:      // Error: RAD40025
    print("dirty")
```

This is deliberate. In shell, `if cmd` tests the exit code but `if $(cmd)` tests
whether it printed anything - two different questions that look nearly the same.
Naming the accessor means the reader never has to guess which you meant:

```rad
// "did it print anything?"
if $`git status --porcelain`.stdout.trim():
    print("dirty")

// "did it succeed?"
if $`git diff --quiet`.ok:
    print("clean")
```

Modifiers work inline, and the ⚡️ echo stays on so you can see which commands
actually ran when `and` / `or` short-circuits:

```rad
tag = quiet $`git describe --tags`.stdout.trim() catch "untagged"
```

One last limit: the inline form gives you one value per run. When you want both
streams from one command, capture them.

## Error Handling

Now that you understand how to capture output, let's talk about error handling.

When a shell command exits with a non-zero exit code, it triggers error propagation - just like functions that return errors.
This means you can handle potential failures using `catch:` blocks:

```rad
// Handle errors with catch block
$`make build` catch:
    print_err("Build failed!".red())
    exit(1)

// Or ignore failures
$`make build` catch:
    pass  // Continue on failure
```

You can **combine capturing with error handling**. When the `catch:` block runs, your variables are already
assigned their actual values, so you can inspect them:

```rad
// Capture the exit code AND handle errors
code = $`make test` catch:
    print_err("Command failed to run. Error code {code}")
    exit(1)

print("Tests passed!")
```

This works with any capture pattern:

```rad
code, stdout = $`git tag --list` catch:
    print_err("Failed to get tags")
    exit(1)

version = stdout.trim()
```

This uses the same error model covered in Error Handling (rad docs guide/error-handling) - errors propagate by default, so you need `catch:` blocks to handle them.

## String Interpolation

The text you write in a shell command is shell - pipes, redirects, `&&`, all of it. Interpolations are data. Each
one becomes exactly one argument, whatever it contains:

```rad
args:
    version str
    message str

$`git tag v{version}` catch:
    print_err("Failed to create tag")
    exit(1)

$`git commit -m {message}` catch:
    print_err("Commit failed")
    exit(1)
```

Note that `{message}` has no quotes around it. Rad quotes it for you, at the point it knows what the value is.
A message of `it's fine` reaches git as `it's fine`; one containing `$HOME`, `*` or `;` arrives with those
characters intact rather than being expanded or run.

**Warning: Don't add your own quotes**

    Writing `` $`git commit -m "{message}"` `` puts the quote characters *into* the message. Rad flags this as
    RAD40023 (rad docs reference/errors). If your argument is literal text plus a value, build the string first:

    ```rad
    version = "1.2.3"

    message = "Bump to {version}"
    $`git commit -m {message}`
    ```

Because the shell joins adjacent quoted fragments, values glue onto neighboring text without any help:

```rad
name = "My Notes.txt"
version = "1.2.3"

$`cp {name} backup/{name}`      // two arguments, spaces and all
$`docker build -t app:{version} .`
```

### Lists Become Several Arguments

A list expands to one argument per element, each quoted separately. An empty list contributes nothing, which
makes conditional flags straightforward:

```rad
args:
    all bool

flags = all ? ["--hidden", "--no-ignore"] : []
needle = "two words"

$`rg {flags} -- {needle}` catch:
    pass
```

A list has to stand alone as its own argument - `--file={files}` is an error, because there is no obvious answer
to which element gets the prefix. Join it yourself when you want a single argument:

```rad
files = ["a.txt", "b.txt"]

$`tar -czf out.tgz {files}`          // three arguments
$`echo --files={files.join(",")}`    // one argument
```

## Commands As Lists

When a command is a list rather than a string, Rad runs the program directly and skips the shell entirely. Each
element is one argument:

```rad
message = "it's fine"

$["git", "commit", "-m", message]
```

This is the form to reach for when you're assembling a command piece by piece. Nothing needs quoting, because
nothing is ever parsed as shell:

```rad
args:
    start str?
    end str?

path = "clip.mp4"

cmd = ["ffmpeg", "-i", path]
if start:
    cmd += ["-ss", start]
if end:
    cmd += ["-to", end]
cmd += ["-c", "copy", "out.mp4"]

$cmd catch:
    print_err("ffmpeg failed")
    exit(1)
```

The trade-off is that you give up everything the shell provides: no pipes, no redirects, no globs, no `$VAR`
expansion, and no shell builtins such as `cd`. Use a command string when you need those, and a list when you
don't.

**Note: A command that is already a string runs verbatim**

    `$cmd` where `cmd` is a *string* is the raw form: you assembled the text, so you own its quoting. Rad has no
    interpolation to protect at that point - the interpolation already happened when the string was built. Prefer
    a list.

## Modifiers

Rad provides two modifiers that can be applied to shell commands.

### The `quiet` Modifier

By default, Rad announces each shell command with a ⚡️ prefix. For example, this command:

```rad
$`touch hello.txt` catch:
    print_err("Failed to create file")
    exit(1)
```

Shows in the terminal:

```
⚡️ touch hello.txt
```

To suppress this announcement, use the `quiet` modifier:

```rad
quiet $`touch hello.txt` catch:
    print_err("Failed to create file")
    exit(1)
```

```
(no output - unless there's an error)
```

This is useful for scripts that run many commands or when you want minimal output.

### The `confirm` Modifier

The `confirm` modifier prompts the user before running a command:

```rad
confirm $`rm -rf node_modules`
```

This is particularly useful for destructive operations.

## Practical Examples

Let's look at some real-world patterns that combine these features.

### Development Workflow

Here's a script inspired by a typical development workflow:

```rad
---
Validates code, checks git status, and optionally pushes changes.
---
args:
    push p bool  # Push changes after validation

// Run validation steps
steps = ["go mod tidy", "make format", "make build", "make test"]

for step in steps:
    $step catch:
        print_err("❌ {step} failed".red())
        exit(1)
    print("✅ {step} passed".green())

if push:
    // Check for uncommitted changes
    stdout = $`git status --porcelain` catch:
        print_err("Failed to check git status")
        exit(1)

    if stdout.trim() != "":
        print_err("Working directory has uncommitted changes!")
        print_err("Commit your changes before pushing.")
        exit(1)

    // Get current branch and push
    stdout = $`git branch --show-current` catch:
        print_err("Failed to get current branch")
        exit(1)

    branch = stdout.trim()
    print("Pushing to {branch}...".yellow())

    $`git push origin {branch}` catch:
        print_err("Push failed")
        exit(1)

    print("✅ Pushed to {branch}".green())

print("✅ Done!".green())
```

### Conditional Construction

Building commands dynamically based on script arguments. Collect the arguments in a list so each one stays a
single argument no matter what it contains:

```rad
args:
    verbose v bool
    output o str?

cmd = ["docker", "build", "."]

if verbose:
    cmd += ["--progress=plain"]

if output:
    cmd += ["-t", output]

$cmd catch:
    print_err("Docker build failed")
    exit(1)

print("Docker image built successfully".green())
```

### Checking Prerequisites

Verifying that required tools are installed:

```rad
tools = ["git", "docker", "make"]

for tool in tools:
    if not quiet $`which {tool}`.ok:
        print_err("Required tool not found: {tool}")
        print_err("Please install {tool} before running this script")
        exit(1)

print("All prerequisites installed ✅".green())
```

## Summary

- Shell commands use the `$` prefix and follow the same error model as functions
- **Reading one value:** put `.stdout`, `.stderr`, `.code` or `.ok` on the command
  and use it in place; `.stdout`/`.stderr` fail if the command did, `.code`/`.ok` don't
- **Error handling:** Non-zero exit codes propagate errors unless handled with `catch:` blocks
- **Capture modes:**
    - None: output goes to terminal
    - Stdout: `stdout = $cmd` (stderr to terminal)
    - Stdout + stderr: `stdout, stderr = $cmd` (nothing to terminal)
    - All three: `stdout, stderr, code = $cmd`
- **Assignment semantics:**
    - **Named** when ALL variables are `code`, `stdout`, or `stderr` (order-independent)
    - **Positional** otherwise, filling `(stdout, stderr, code)` in that order
    - Mixing the two is the one trap: one unreserved name makes the whole statement positional
- **Output routing:** Captured values don't print to the terminal (they're redirected to variables)
- **The exit code comes last** because you rarely need it - a non-zero exit already raises an error
- **Command forms:**
    - `` $`text {value}` ``: the text is shell, each interpolation is one argument, quoted for you
    - `$list`: an argument vector, run directly with no shell involved
    - `$str`: a string you assembled yourself, run verbatim
- Interpolate a list to get one argument per element; an empty list contributes none
- Don't put your own quotes around an interpolation - Rad already quotes it
- Backticks are preferred for shell command strings to avoid delimiter conflicts

## Next

Shell commands let you invoke external programs, but what if you want to organize your *script* into multiple
operations - like `git commit`, `docker build`, or `kubectl apply`?

That's where commands come in. We'll explore them in the next section: Script Commands (rad docs guide/script-commands).

---

# Script Commands

When you think of powerful CLI tools - `git`, `docker`, `kubectl` - they all share a common pattern: they're organized
around commands. You don't just run `git` with flags; you run `git commit`, `git push`, `git branch` - each a distinct
operation with its own arguments.

Rad lets you build tools like this through first-class command support. You can define multiple commands in a single
script, each with their own arguments and implementation.

## Basic Syntax

Let's start with a very simple example:

```rad
#!/usr/bin/env rad

command greet:
    name str
    calls greet_user

fn greet_user():
    print("Hello, {name}!")
```

This script defines a single command called `greet` that takes a `name` argument.

Invoke it by specifying the command name followed by its arguments:

```
> ./script.rad greet Alice
```

```
Hello, Alice!
```

Let's break down the syntax:

1. **`command greet:`** - Defines a command named `greet`
2. **`name str`** - The command takes one required string argument called `name`
3. **`calls greet_user`** - Specifies which function to execute when this command runs
4. **`fn greet_user():`** - Defines the function that implements the command logic (defined after commands)

Command arguments (like `name`) become script-wide variables, accessible throughout your script.

**Note: Underscores become hyphens**

    Command names with underscores are automatically converted to hyphens for CLI invocation.
    This matches standard CLI conventions (like `kubectl`, `docker-compose`).

    For example, `command deploy_staging:` is invoked as `deploy-staging`:

    ```
    > ./script.rad deploy-staging
    ```

    This is the same convention used for argument names (rad docs guide/args).

## Multiple Commands

The power of commands emerges when you define several in one script. Let's create a simple deployment tool:

```rad
#!/usr/bin/env rad

command deploy:
    env str
    calls do_deploy

command status:
    env str
    calls do_status

fn do_deploy():
    print("Deploying to {env}...".yellow())
    print("Deployment complete!".green())

fn do_status():
    print("Checking status of {env}...".yellow())
    print("Environment {env} is healthy".green())
```

Now you can invoke either command:

```
> ./tool.rad deploy staging
```

```
Deploying to staging...
Deployment complete!
```

```
> ./tool.rad status production
```

```
Checking status of production...
Environment production is healthy
```

Each command has its own arguments and implementation, but they live in the same script and can share code.

## Adding Descriptions

Commands should include descriptions to make your tool self-documenting. Use the familiar `--- ... ---` header syntax:

```rad
#!/usr/bin/env rad

command deploy:
    ---
    Deploy the application to an environment
    ---
    env str
    calls do_deploy

command status:
    ---
    Check the health of an environment
    ---
    env str
    calls do_status

fn do_deploy():
    print("Deploying to {env}...".yellow())

fn do_status():
    print("Environment {env} is healthy".green())
```

These descriptions appear in the help output:

```
> ./tool.rad -h
```

```
Usage:
  tool.rad [command] [OPTIONS]

Commands:
  deploy    Deploy the application to an environment
  status    Check the health of an environment
```

**Tip: Multi-line descriptions**

    Just like script headers, command descriptions can span multiple lines:

    ```rad
    command deploy:
        ---
        Deploy the application to an environment.
        This will build, test, and deploy your application.
        ---
    ```

    **Important:** The first line appears in the script's overall help output, so keep it concise. Additional lines
    only appear when you request help for that specific command (`./tool.rad deploy -h`).

## Command Arguments

Each command can define its own arguments using the same syntax you learned in Args (rad docs guide/args). Let's expand our
deployment tool:

```rad
#!/usr/bin/env rad

command deploy:
    ---
    Deploy the application to an environment
    ---
    env str              # Environment to deploy to
    branch str = "main"  # Branch to deploy from
    skip_tests bool      # Skip running tests before deploy
    calls do_deploy

fn do_deploy():
    if skip_tests:
        print("⚠️  Skipping tests".yellow())
    else:
        print("Running tests...".yellow())

    print("Deploying {branch} to {env}...".yellow())
    print("✅ Deployment complete!".green())
```

The arguments work exactly as they do in the `args:` block - you can use defaults, optional types, constraints, and
comments for help text.

Invoke with positional arguments:

```
> ./tool.rad deploy staging feature-branch
```

```
Running tests...
Deploying feature-branch to staging...
✅ Deployment complete!
```

Or use flags (especially for booleans):

```
> ./tool.rad deploy --env=production --skip-tests
```

```
⚠️  Skipping tests
Deploying main to production...
✅ Deployment complete!
```

## Shared Args

Often you want arguments that apply to *all* commands - like a `--verbose` flag or a `--config` path. Define these in
an `args:` block to share them across commands:

```rad
#!/usr/bin/env rad

args:
    verbose v bool   # Enable verbose output
    config str = "~/.config/tool.yaml"

command deploy:
    ---
    Deploy the application
    ---
    env str
    calls do_deploy

command status:
    ---
    Check environment status
    ---
    env str
    calls do_status

fn do_deploy():
    if verbose:
        print("Config: {config}".yellow())
        print("Deploying to {env}...".yellow())
    print("✅ Deployed!".green())

fn do_status():
    if verbose:
        print("Config: {config}".yellow())
        print("Checking {env}...".yellow())
    print("Environment healthy".green())
```

Shared args are available to all commands:

```
> ./tool.rad deploy staging --verbose
```

```
Config: ~/.config/tool.yaml
Deploying to staging...
✅ Deployed!
```

```
> ./tool.rad status production --verbose
```

```
Config: ~/.config/tool.yaml
Checking production...
Environment healthy
```

**Note: Shared args are flag-only**

    When commands exist, shared args can only be passed as flags (like `--verbose`, `-v`, or `--config=value`), not
    positionally. That keeps the first positional argument free to name a command - or, if you declare a
    default command, to be that command's first argument.

    Both long form (`--verbose`) and short form (`-v`) work for shared args.

    Command-specific args can be positional or flags, just like regular script args.

## Nested Commands

Larger tools group related commands under a namespace, like `git remote add`. A command that **contains other commands** becomes one: it has no `calls` of its own, and routes to its sub-commands instead.

```rad
#!/usr/bin/env rad

command remote:
    ---
    Manage remotes.
    ---
    timeout int = 30        # shared with every sub-command

    command add:
        ---
        Add a remote.
        ---
        name str
        url str
        calls do_add

    command remove:
        name str
        calls do_remove

fn do_add():
    print("Adding {name} -> {url} (timeout {timeout})")

fn do_remove():
    print("Removing {name}")
```

Name the full path to reach the command you want:

```
> ./tool.rad remote add origin https://github.com/me/repo.git
> ./tool.rad remote remove origin
```

Args declared directly on a namespace are **shared with every descendant**. They behave like the script-level `args:` block, just scoped to that sub-tree - flag-only, and accepted at any point along the path:

```
> ./tool.rad remote add origin https://... --timeout 5
> ./tool.rad remote --timeout 5 add origin https://...
```

Namespaces nest as deep as you like. Only the terminal command's callback runs; an intermediate namespace exists to group and to share args, not to execute.

## Default Commands

Most tools have one thing they mostly do. Marking a command `default` means the user doesn't have to type its name:

```rad
#!/usr/bin/env rad

command add:
    ---
    Add a reminder.
    ---
    *tokens str     # Time spec followed by message.
    default
    calls do_add

command list:
    ---
    Show upcoming reminders.
    ---
    calls do_list

fn do_add():
    print("Adding: {tokens}")

fn do_list():
    print("Listing")
```

```
> ./remind.rad 15m standup
```

```
Adding: [ "15m", "standup" ]
```

`./remind.rad add 15m standup` does exactly the same thing. The default keeps its own name, and that matters more than it looks.

### When A Value Looks Like A Command

A named command always wins. So if you want to add a reminder that says "list", the short form won't do it - `list` is a command:

```
> ./remind.rad list          # runs do_list, no reminder added
```

Two ways to say you meant the value. Name the default explicitly, or use `--`:

```
> ./remind.rad add list      # adds a reminder saying "list"
> ./remind.rad -- list       # same
```

**Note: Which command runs, exactly**

    Routing happens at the first token the level can't consume itself. A command name appearing *after* one of those goes to the default as data, not as a command. If a flag is needed by the default but rejected elsewhere, declare it as a shared arg so it's consumed before routing.

### Defaults And Namespaces

The rule is the same at every level, so a namespace's default is what runs when you name the namespace and stop:

```rad
#!/usr/bin/env rad

command remote:
    command list:
        default
        calls do_list

    command add:
        name str
        calls do_add

fn do_list():
    print("Listing remotes")

fn do_add():
    print("Adding {name}")
```

`./tool.rad remote` lists remotes, exactly as `./tool.rad remote list` would.

Only leaf commands can be marked. A namespace routes rather than runs, so marking one would leave the question unanswered - mark one of its sub-commands instead.

## Command Callbacks

We've been using function references (`calls on_deploy`), which is the recommended approach for most commands.
However, for very short implementations, you can also use inline lambdas:

```rad
#!/usr/bin/env rad

command deploy:
    ---
    Deploy the application
    ---
    env str
    calls on_deploy

command rollback:
    ---
    Rollback a deployment
    ---
    env str
    calls fn():
        print("Rolling back {env}...".yellow())
        print("✅ Rollback complete!".green())

fn on_deploy():
    print("Deploying to {env}...".yellow())
    print("✅ Done!".green())
```

## Shared Logic

You can write code after all command blocks that runs before any callback is invoked. This is useful for setup logic that all commands need:

```rad
#!/usr/bin/env rad

command deploy:
    env str
    calls on_deploy

command rollback:
    env str
    calls on_rollback

// This runs before any callback
print("Initializing...".yellow())
config = read_file("config.yaml")
print("Config loaded".green())

fn on_deploy():
    // config is available here
    print("Deploying to {env} using config...")

fn on_rollback():
    // config is available here too
    print("Rolling back {env}...")
```

When you run `./script.rad deploy staging`, the flow is:

1. Parse arguments
2. Run shared logic (lines 12-14)
3. Run the callback (`on_deploy`)

## Getting Help

Rad automatically generates help documentation for your commands. There are two levels of help:

**Script-level help** shows all available commands:

```
> ./tool.rad -h
```

```
Usage:
  tool.rad [command] [OPTIONS]

Commands:
  deploy      Deploy the application
  rollback    Rollback a deployment
  status      Check environment status
```

**Command-level help** shows arguments for a specific command:

```
> ./tool.rad deploy -h
```

```
Deploy the application

Usage:
  deploy <env> [branch] [OPTIONS]

Command args:
      --env str       Environment to deploy to
      --branch str    Branch to deploy from (default "main")
      --skip-tests    Skip running tests before deploy
  -v, --verbose       Enable verbose output
      --config str    (default "~/.config/tool.yaml")
```

Notice how the help includes:

- The command description
- Required and optional arguments
- Default values
- Shared args (like `--verbose` and `--config`)
- Help text from `#` comments

## Practical Example

Here's a concise, realistic example that demonstrates the "dev script" pattern - a common use case for replacing messy `Makefile`s or complex `package.json` script sections with a single, readable CLI entry point.

### Dev Script

Instead of remembering different commands for building, testing, and running your project, you can wrap them in a
single `dev.rad` script. This demonstrates shared arguments, boolean flags, and how to pass arguments down to underlying tools:

```rad
#!/usr/bin/env rad
---
Facilitates working with this repo's project.
---

args:
    verbose v bool   # Enable verbose output

command start:
    ---
    Start the local development server
    ---
    port int = 3000    # Port to listen on
    detach d bool      # Run in background
    calls on_start

command test:
    ---
    Run the test suite
    ---
    grep str?      # Filter tests by name
    watch w bool   # Re-run on file changes
    calls on_test

command build:
    ---
    Compile for production
    ---
    calls on_build

// Shared setup logic runs before any callback
if verbose:
    print("Checking project structure...".yellow())

if not get_path("package.json")["exists"]:
    print_err("Error: package.json not found".red())
    print_err("Run this script from the project root".yellow())
    exit(1)

fn on_start():
    print("🚀 Starting server on http://localhost:{port}...")

    if detach:
        $`npm start -- --port {port} &`
        print("Server started in background".green())
    else:
        $`npm start -- --port {port}`

fn on_test():
    opts = []
    if watch:
        opts += ["--watch"]
    if grep:
        opts += ["-t", grep]

    if verbose:
        print("Running: pytest {opts.join(" ")}".yellow())

    print("🧪 Running tests...")
    $`pytest {opts}` catch:
        print_err("Tests failed!".red())
        exit(1)

fn on_build():
    print("📦 Building for production...".yellow())

    $`rm -rf ./dist`
    $`npm run build` catch:
        print_err("Build failed".red())
        exit(1)

    print("✅ Build complete in ./dist".green())
```

**Usage:**

```
> ./dev.rad start
🚀 Starting server on http://localhost:3000...

> ./dev.rad start --port 8080 --detach
🚀 Starting server on http://localhost:8080...
Server started in background

> ./dev.rad test --grep "login_flow" --watch
🧪 Running tests...

> ./dev.rad build
📦 Building for production...
✅ Build complete in ./dist
```

Notice how this example uses:

- Shared args (`--verbose`) available to all commands
- Command-specific arguments with defaults (`port`, `detach`, `grep`, `watch`)
- Shared logic that runs before any callback
- Function references for callbacks (`calls on_start`, etc.)
- Integration with shell commands to wrap existing tools
- Clear, self-documenting help text

## Summary

- **Script commands** partition scripts into operations using `command name:` blocks
- Each command has:
    - Its own arguments (using standard `args` syntax)
    - A description block (`--- ... ---`)
    - A callback implementation (function reference or inline lambda)
- **Shared args** (from `args:` block) are available to all commands
    - Must be passed as flags when commands exist
- **Shared logic** runs before any callback. Write code after command blocks for setup that all commands need.
- **Help is automatic:**
    - `./script -h` lists available commands
    - `./script command -h` shows command-specific help
- **Callbacks:**
    - Function references: `calls function_name` (recommended)
    - Inline lambdas: `calls fn():` (for short implementations)
- **Use script commands to build CLI tools, not just scripts**

## Next

Rad provides a powerful system for looking up values from predefined resource files, which is particularly useful for
building interactive tools.

We'll explore this in the next section: Resources (rad docs guide/resources).

---

# Resources

Depending on your script, you may wish to look up values at some point, such as URL endpoints depending on your input. Rad offers a function for this, `pick_from_resource`, but before we dive into it, we'll first cover a couple of related functions.

## `pick`

`pick` (rad docs pick) is an in-built function which allows you to choose one value from a list of inputs, using some filter. If the filter has several matches, Rad will enter an interactive mode which allows the user to pick a single value to continue with.

You can try it yourself with this example:

```rad
options = ["chicken burger", "chicken sandwich", "ham sandwich"]
output = pick(options, "sandwich")
print("You chose: {output}")
```

When you initially run this, the `sandwich` filter should exclude `chicken burger` and ask you to select between two remaining options.

Note: You can enable exact match priority with `prefer_exact=true`. When enabled, if your filter exactly matches one of the options (case-insensitive), that option will be selected immediately without entering interactive mode.
For example, `pick(["r", "red", "rose"], "r", prefer_exact=true)` would immediately select "r" without prompting.

```
┃ Pick an option
┃ > chicken sandwich
┃   ham sandwich
```

After you choose, you get the final output:

```
You chose: chicken sandwich
```

## `pick_kv`

A similar function is `pick_kv` (rad docs pick_kv). However, instead of the values you're filtering and picking between also being the *output*, `pick_kv` performs the filtering/picking on a list of *keys*, each which map to a value that will get output from the function if its associated key is picked. For example:

```rad
keys = ["chicken burger", "chicken sandwich", "ham sandwich"]
values = ["CHICKEN", "CHICKEN", "HAM"]

output = pick_kv(keys, values)

print("We'll need {output}!")
```

In this example, we leave out the filter, as it's optional, which will launch us into an interactive select between all the key values:

```
┃ Pick an option
┃   chicken burger
┃   chicken sandwich
┃ > ham sandwich
```

If we pick this third option, this is the final output of the script:

```
We'll need HAM!
```

Notice that the function did not output the *key* `ham sandwich` that was selected, but instead the *value* `HAM` that it mapped to.

## `pick_from_resource`

Now we'll look at actually using what this section is about - resources. `pick_from_resource` (rad docs pick_from_resource) allows you to pre-define a resource file (using JSON) which contains a range of key-value pairs. When invoked, it will behave similarly to the two previous `pick` functions i.e. it lets you apply an optional filter, and will launch into an interactive picking mode to narrow down a single choice, if needed. Unlike `pick` and `pick_kv`, `pick_from_resource` has `prefer_exact=true` by default—if your filter exactly matches one of the keys (case-insensitive), that option will be selected immediately.

Let's do a simple example. As mentioned, a resource file is simply a JSON file. We'll create an example where we look up a url based on user input:

```json
{
  "options": [
    {
      "keys": ["gl", "lab"],
      "values": ["gitlab.com", "GitLab"]
    },
    {
      "keys": ["gh", "hub"],
      "values": ["github.com", "GitHub"]
    }
  ]
}
```

You may see some similarity here to what we did with `pick_kv`. We're defining two options: one which can get matched by either `gl` or `lab`, and one which gets matched by `gh` or `hub`. In the first case, if chosen, `pick_from_resource` will return *two* values: `gitlab.com` and `GitLab`. Similarly it will return `github.com` and `GitHub` for the latter.

Let's create a Rad script to use this resource:

```rad
args:
    website str = ""

url, name = pick_from_resource("./resources/websites.json", website)
print("url: {url}, name: {name}")
```

Note that the first argument to `pick_from_resource` is a path to a resource file. This path is *relative to the script's path*.
This allows you to store your resources with your scripts. In this example, we'll place our files like so:

```
.
├── example.rad
└── resources
    └── websites.json
```

This means that it doesn't matter where on your computer you invoke your script from including if it's on your PATH - the script will consistently look in the same spot for resource files.

TBC

## Summary

- `pick` and `pick_kv` are built-in functions that allow users to select one option from many, allowing for an optional filter.
- `pick_from_resource` is similar, but uses a pre-defined resource file to define the options.
- The resource file is defined in JSON.
- The resource file path can be defined relative to the script's path.

## Next

The shell offers a ton of useful utilities, and Rad allows you to leverage them from within your scripts.

We'll look at that in the next section: Shell Commands (rad docs guide/shell-commands).

---

# Global Flags

Rad offers a range of global flags that are available with every Rad script. We'll explore some of them in this section.

## `help`

The most basic global flag is `--help` or `-h`. *All* Rad scripts automatically generate a usage string that can be displayed by invoking this flag.

`--help` also prints available *global* flags:

```
Global options:
  -h, --help                Print usage string.
  -i, --interactive         Interactively prompt for script args not already provided, then run.
  -d, --debug               Enables debug output. Intended for Rad script developers.
      --rad-debug           Enables Rad debug output. Intended for Rad developers.
      --color mode          Control output colorization. Valid values: [auto, always, never] (default auto)
  -q, --quiet               Suppresses some output.
      --shell               Outputs shell/bash exports of variables, so they can be eval'd
  -v, --version             Print rad version information.
      --confirm-shell       Confirm all shell commands before running them.
      --tls-insecure        Skip TLS certificate verification for all HTTP requests.
      --src                 Instead of running the target script, just print it out.
      --cst-tree            Instead of running the target script, print out its CST (concrete syntax tree).
      --ast-tree            Instead of running the target script, print out its AST (abstract syntax tree).
      --rad-args-dump       Instead of running the target script, print out an args dump for debugging argument parsing.
      --mock-response str   (optional) Add mock response for json requests (pattern:filePath)
      --reply line:value    Answer a prompt when there's no terminal. Repeatable; repeat a line to answer it again.
      --reply-na line       Assert a prompt won't be reached on this run; rad fails cleanly if it is.
```

Note that when `--shell` is enabled, help output goes to stderr instead of stdout, and stdout gets an `exit 0` statement.
This keeps stdout safe to `eval`: wrappers using `eval "$(rad - --shell "$@" <<< "$script")"` won't execute usage text as shell code, and stop cleanly after showing help.

## `interactive`

Use `--interactive` or `-i` to be walked through a script's args interactively instead of typing them all out. Rad prompts for each arg you haven't already provided on the command line, using a prompt suited to the arg's type:

- enum-constrained strings offer a picker of the valid values
- bools are gathered into a single toggleable multi-pick (defaults pre-checked); a lone bool just asks y/n
- ints, floats, and regex-constrained strings validate as you submit, re-prompting inline on invalid values
- list and variadic args collect one value per line until an empty line

Each answered prompt collapses to a compact transcript line (`--env staging`, `--replicas (skip - default: 3)`), so you can see at a glance what was chosen. Optional args can be skipped (Enter on an empty field, or a dedicated "skip" row in pickers), in which case their defaults apply. If the script defines commands (rad docs guide/script-commands) and you didn't specify one, you first pick the command, then get prompted for its args.

Relational constraints react as you go: an arg excluded by something you've already set is skipped with a note (`Skipping --url (excluded by --file)`), and an arg required by one becomes mandatory - its prompt blocks an empty Enter with `required by --<arg>`. Press Ctrl+C at any prompt to abort without running the script.

`-i` composes with partially-supplied args - anything already on the command line isn't re-prompted:

```
rad deploy.rad -i prod
```

Before running, Rad prints the equivalent non-interactive invocation to stderr, so you can copy it to rerun or script the same call directly:

```
Equivalent: rad deploy.rad --env prod --replicas 3 --force
```

This makes `-i` double as an invocation builder for unfamiliar scripts: answer the prompts once, keep the one-liner.

## `debug`

`debug` (rad docs debug) is a built-in function which behaves exactly like `print`, except that it only prints if the global flag `--debug` is enabled. You can use them in your script for debugging as desired.

For example, given this example:

```rad
print("1")
debug("2")
print("3")
```

the following invocations will give the respective outputs:

```
rad debug.rad
```

```
1
3
```

```
rad debug.rad -d
```

```
1
DEBUG: 2
3
```

## `quiet`

Use `--quiet` or `-q` to suppress *some* outputs, including print statements and errors. Some outputs still get printed e.g. shell command outputs.

## `color`

```
--color mode
    Control output colorization.
    Valid values: [auto, always, never].
    (default auto)
```

A lot of Rad's outputs have colors e.g. `pick` (rad docs pick) interaction or `pprint` (rad docs pprint) JSON formatted output.
By default (`auto`), Rad checks your terminal to detect if it's appropriate to enable colors or not. Things like piping or redirecting output will disable coloring.

However, you can override the automatic detection by explicitly setting `--color=always` or `--color=never` to force having colors, or force *not* having colors, respectively. 

## `src`

Use `--src` to print the source code of a script instead of running it. This is handy when you want to quickly inspect a script without opening it in an editor - for example, checking what a script does before running it.

```
rad my-script.rad --src
```

## `cst-tree`

Use `--cst-tree` to print the concrete syntax tree (CST) of a script instead of running it. The CST is the raw parse tree that directly mirrors the grammar - every token, whitespace, and syntactic element is represented.

This flag bypasses argument validation, so you can inspect the tree even if the script expects arguments you haven't provided.

```
rad my-script.rad --cst-tree
```

This is primarily useful for debugging the parser or understanding how Rad tokenizes your script.

## `ast-tree`

Use `--ast-tree` to print the abstract syntax tree (AST) instead of running the script. The AST is the simplified, semantic tree that Rad actually interprets - syntactic sugar has been desugared, and irrelevant tokens are stripped away.

Like `--cst-tree`, this bypasses argument validation.

```
rad my-script.rad --ast-tree
```

Comparing `--cst-tree` and `--ast-tree` output can help you understand how Rad transforms your code before execution - for instance, how compound assignments like `x += 1` get desugared.

## `tls-insecure`

Use `--tls-insecure` to skip TLS certificate verification for all HTTPS requests made by the script. This is useful when developing against servers with self-signed certificates.

```
rad my-api-script.rad --tls-insecure
```

**Warning: Development only**

    Don't use this flag in production. It disables certificate verification for *all* requests in the script, making them vulnerable to man-in-the-middle attacks.

## `mock-response`

You might be writing a script which hits a JSON API and uses its output e.g. formatting it into a table using a `rad` block (rad docs guide/rad-blocks).

In writing said script, you may wish to test it against certain responses that the live API isn't giving you at the moment, perhaps because the server is down. To accomplish this, you can use the `mock-response` flag.

`mock-response` takes an argument in a `<url regex>:<file path>` format.
In other words, you can mock responses based on a regex match of the queried URL, and make them return the contents of a specified file.

For example, if you wanted to mock a response from GitHub's API, you could define an example response in a file:

```json
[
  {
    "sha": "306f3a4ddb3b09747d61a5eab264c3d72fbbc36e",
    "commit": {
      "author": {
        "name": "Alice Smith",
        "date": "2025-01-11T04:15:06Z"
      }
    }
  },
  {
    "sha": "2b642c482b32e4d87924839b2f5a9592670dee69",
    "commit": {
      "author": {
        "name": "Charlie Johnson",
        "date": "2025-01-10T12:21:03Z"
      }
    }
  }
]
```

And then define it as the mock response with the following example invocation:

```shell
rad commits.rl --mock-response "api.github.*:commits.json"
```

Before executing the HTTP request, Rad checks for defined mock responses and if there's a regex match against the URL, it will short circuit,
avoiding the HTTP request, and simply returning the contents of the mocked response.

**Tip: Match all URLs with .***

    It's common for scripts to perform just one API query, in which case the regex filter doesn't need to be specific.
    Instead, you can just write `.*` e.g. `.*:commits.json`.

## `reply`

`input`, `confirm`, `pick`, `pick_kv`, `pick_from_resource`, `multipick`, and `confirm`-gated shell commands all need a person at a terminal. Rad looks for one on stdin and, failing that, on `/dev/tty`, which still works when stdin carries data rather than keystrokes. In CI, cron, and AI agent tool calls, neither is there.

Rather than run until it hits a prompt and dies, rad stops first and prints what the script would ask:

```shell
rad deploy.rad prod
```

```title="stderr"
error[RAD20046]: this script needs to ask you something, but there's no terminal

  deploy.rad prompts in 3 places. rad found no terminal - stdin isn't one and
  /dev/tty isn't available - so it can't ask. Supply the answers up front,
  keyed by line number.

  deploy.rad:5  confirm "Deploy to prod?"
  deploy.rad:6  input   "Release notes"
  deploy.rad:7  pick    options: web-1, web-2, db-1

    rad deploy.rad prod --reply '5:<yes|no>' --reply '6:<value>' --reply '7:<option>'
```

Nothing in the script has run yet, so there is no half-finished work to reason about before you retry. The last line is your own command with a `--reply` per prompt: keys in place, answers blank. Rad won't guess those - whether you mean yes, or which server you want, isn't in the script. Fill in each `<...>` and run it; rad takes whatever you put there literally.

Rad exits `7` when it stops like this, so a wrapper can tell "this run needs input" apart from "this run failed" without reading the message.

Each listed prompt may also carry a note about how it behaves:

| Note                                                                  | Meaning                                                                                                                                                                       |
| --------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `filtered - may not prompt, and then only accepts what it settles on` | A `pick` whose filter rad can't work through ahead of time. If it narrows to one option it asks nothing, and an answer naming anything else fails - see filtered picks below. |
| `settles on "web-1" - won't ask`                                      | A `pick` whose options and filter are both written literally, leaving one survivor. It takes that option without asking, so rad answers it with `--reply-na` for you.         |
| `used as a value - ...`                                               | An interactive function passed around rather than called. Takes `--reply-na` only.                                                                                            |
| `may run more than once - repeat --reply per run`                     | It sits in a loop, or in a function called from several places. One `--reply` answers one execution.                                                                          |
| `secret - cannot be answered on the command line`                     | See secret inputs below.                                                                                                                                                      |
| `options computed at runtime`                                         | Rad can't list the choices without running the script. They're checked when the prompt is reached.                                                                            |

### Prompts rad can't answer

One shape takes no `--reply`: passing an interactive function around as a value rather than calling it.

```rad
ask = pick
answer = ask(["dev", "prod"])
```

Answers are addressed by the position of the call, and rad can't see where such a value ends up or how many times it runs - so there is nothing for a value to attach to. It's still listed and still keyed, so `--reply-na` can assert the value is never invoked:

```shell
rad dispatch.rad --reply-na 1
```

That matters for a script that merely *mentions* one on a path this run won't take - a handler map where the interactive entry isn't selected. If the assertion turns out to be wrong, the script stops at the prompt with RAD20047 (rad docs reference/errors) rather than acting on a guess.

Answers are matched by the kind of prompt on that line - which is what the blank names - and only `multipick` needs escaping:

| Prompt                                  | Blank          | Answer                                                                |
| --------------------------------------- | -------------- | --------------------------------------------------------------------- |
| `confirm`, `confirm $\`...\``           | `<yes|no>`     | `yes` or `no` (also `y`, `n`, `true`, `false`)                        |
| `input`                                 | `<value>`      | everything after the colon, verbatim; empty takes the arg's `default` |
| `pick`, `pick_kv`, `pick_from_resource` | `<option>`     | one option, matched exactly                                           |
| `multipick`                             | `<option,...>` | comma-separated; `\,` is a literal comma, `\\` a literal backslash    |

Only the first colon separates the key from the value, so `--reply 6:https://example.com` works without quoting. For `pick_kv`, answer with the key the user would see, not the value it returns - the listing names it `pick_kv` rather than `pick` for exactly this reason.

Matching is exact. A near miss fails rather than running the wrong thing.

A `multipick` answer must name each option at most once, and must satisfy the prompt's own `min` and `max`. Where those are written literally in the script, a bad count fails at pre-flight rather than partway through the run. Answer with an empty value (`--reply 3:`) to select nothing, which a `min=0` prompt accepts.

### Prompts that run more than once

A prompt inside a loop asks once per pass. Repeat its key to answer each one, in order:

```shell
rad cleanup.rad --reply 12:yes --reply 12:no
```

Answers queue per line rather than globally, so adding a prompt earlier in the script never silently re-targets a later answer. If the loop runs out of answers, rad stops. It does not reuse the last one - a single `yes` approving five hundred deletions is the accident this avoids. When there *is* a terminal, running out just means rad asks you for the rest, so you can pre-answer the first few passes and type the others.

A prompt in a function called from several places repeats for the same reason, and then one key stands for several different questions:

```rad
fn ask(label):
    return input("Enter {label}: ")

host = ask("hostname")
user = ask("username")
print("{user}@{host}")
```

Answers bind in the order the calls run - here hostname, then username. Where rad can account for every execution it lists the calls, so you can read that order off the pre-flight rather than opening the script:

```title="stderr"
  deploy.rad:2  input may run more than once - repeat --reply per run
      reached from:
        4  host = ask("hostname")
        5  user = ask("username")
```

It says nothing where it can't account for them all: a call inside a loop, a function passed around as a value, a caller that itself runs more than once, or a recursive function. A list missing one call would read exactly like a complete one, and you'd count passes off an undercount.

Rad can't count the passes for you either way - that depends on the script's own data. Where stopping partway would cost you something, read the script and count before you answer.

### Filtered picks

One answer is consumed per execution of the line, not per prompt you would have seen. A filtered `pick` that narrows to one option asks nothing, but still takes its answer - otherwise a pass that quietly skipped would hand every later answer to the wrong one. The same applies when a `pick`'s list simply happens to hold one entry on this run.

What it does with that answer depends on whether the two agree. Naming the option the filter settled on is fine, and the run carries on. Naming anything else fails with RAD20047 (rad docs reference/errors):

```rad
services = ["api", "worker", "scheduler"]
target = pick(services, "api", prefer_exact=true)
```

`--reply 2:worker` asks for one service where the script's own filter chose another, and rad won't pick a winner. Usually the filter is the thing to change - it's normally built from an arg, so `worker` belongs there rather than in the answer.

## `reply-na`

Some prompts sit on branches a given run won't take. Rather than invent a value you expect to go unused, assert that the prompt won't be reached:

```shell
rad deploy.rad --dry-run --reply-na 20
```

If the script reaches it anyway, rad fails with RAD20047 (rad docs reference/errors) instead of acting on a guess.

This is also a good answer for a `pick` given a filter. Such a call narrows its options first and never asks when one survives, so it often needs no answer at all. Where the options and the filter are both written literally, rad works that out for you and puts `--reply-na` in the suggested command itself. Where either is computed while the script runs, it can't, so the prompt is listed like any other - reach for `--reply-na` on the runs you expect the filter to settle.

Secret inputs are the one case with no `--reply` at all. Command-line arguments are visible to other processes, so a secret `input` can only be answered at a terminal. Use `--reply-na` if this run won't reach it. This holds whether `secret` is written as a literal or computed while the script runs - in the second case rad can't warn you up front, but it still refuses the answer.

**Note: Scripts that disable global options**

    A script setting `@enable_global_options = false` has no `--reply` flag to give it. Rad says so rather than suggesting a command the script would reject; such a script can only be answered at a terminal.

## Summary

- Rad provides several global flags that can be used across all Rad scripts.
- Use `--reply` and `--reply-na` to run scripts that prompt in CI, cron, or an AI agent.
- Use `--src`, `--cst-tree`, and `--ast-tree` to inspect scripts without running them.
- Use `--tls-insecure` for development against self-signed certs.
- Use `--mock-response` to test your scripts against canned API responses.
- To browse this documentation from the terminal, see `rad docs` (rad docs guide/built-in-commands).

**Info: Script args can shadow global flags**

    If a script defines an arg such as `debug`, conflicting with an existing global flag, then the script arg will **shadow** the global flag.

    This means that the global flag's functionality is effectively disabled for the script. It gets removed from the script's usage string, and
    the script itself defines the behavior of the flag.

## Next

Sometimes you may wish to run commands before your script ends, either normally or via an error, such as cleanups.
Rad provides a way to do this that we will explore in the next section: Defer & Errdefer (rad docs guide/defer-errdefer).

---

# Defer & Errdefer

With defer statements, you can specify blocks of code to be run before the script exits.

You may wish to use them to clean up or undo operations before exiting.

## Defer

`defer` blocks always run before the script exits, regardless of if it's due to an error or not.

Here is an example:

```rad
$`mv notes.txt notes-tmp.txt`
defer:
    $`mv notes-tmp.txt notes.txt`
    print("Moved back!")

$`echo "hi!" >> notes.txt`
$`cat notes.txt`
```

Let's say we already have a file `notes.txt` containing some text. In this script, we take the following steps, largely by invoking shell commands (rad docs guide/shell-commands):

1. Rename `notes.txt` to `notes-tmp.txt`
2. Define a `defer` block which will undo the rename, and then print `Moved back!`.
3. Create a *new* `notes.txt` with the contents `hi!`
4. Print the contents `notes.txt` to show what it contains.

When run:

```shell
rad defer.rl
```

```
⚡️ mv notes.txt notes-tmp.txt
⚡️ echo "hi!" >> notes.txt
⚡️ cat notes.txt
hi!
⚡️ mv notes-tmp.txt notes.txt
Moved back!
```

Note that despite the `Moved back!` print statement appearing *earlier* in the script, it only gets run at the end due to being in a `defer` block.

**Warning: Defer runs at *script* exit and does not capture function locals**

    If you're coming from Go, two behaviors will surprise you:

    1. A `defer` inside a function runs when the **script** exits - not when
       the function returns.
    2. The `defer` block does **not** close over the enclosing function's
       local variables. By the time it runs, those locals are gone.

    Together these make the Go-style cleanup pattern fail - and because
    `rad check` does not flag it, the failure only surfaces as a runtime
    error on the *cleanup* path, where it can hide until long after the
    code was written:

    ```rad
    fn run_remote(script):
        tmp = "/tmp/xyz"
        defer:
            $`rm -f {tmp}`  // RAD20028: Undefined variable: tmp
    ```

    Instead, reference only top-level variables from `defer` blocks, or do
    function-local cleanup explicitly before returning.

## Errdefer

Sometimes, you only want certain deferred statements to run in the event of a failure.
This is useful when your script is working toward a critical step that, once executed, should not be rolled back.
However, if the script fails before reaching that step, rollback actions may still be necessary.

Below is an example of a version-bumping script. Using `sed`, this script replaces the version in a file called `VERSION`, stages the file with git,
and commits it. However, if there's a failure in between the `sed` and `commit` steps, then we want to undo earlier steps as a cleanup, in order to
make the script *atomic* i.e. it either succeeds entirely or does nothing, leaving no intermediary state changes behind. We accomplish this through `errdefer` blocks. 

```rad
args:
    version str

path = "VERSION"
expr = "s/Version = .*/Version = {version}/"

$`sed -i '' {expr} {path}`
errdefer:
    print("Undoing bump...")
    $`git checkout -- {path}`

if false:  // failure simulation point 1
    print("Oh no! ERROR!")
    exit(1)

$`git add {path}`
errdefer:
    print("Resetting {path}...")
    _, _ = $`git reset {path}`

if false:  // failure simulation point 2
    print("Bah! ERROR!")
    exit(1)

message = "Bump version to {version}"
$`git commit -m {message}`
print("Done!")
```

We include a couple of "failure points". We can set their condition to `true` to have them simulate an error, as the exit code of '1' indicates failure.

Before we do that though, we can see an example of this script working correctly. Let's say we define our `VERSION` file in the same directory as the script as follows:

```txt
Version = 1
```

If we execute our script, we get the following output:

```shell
rad bump.rl 2
```

```
⚡️ sed -i '' "s/Version = .*/Version = 2/" VERSION
⚡️ git add VERSION
⚡️ git commit -m "Bump version to 2"
[main 6ce2ebb] Bump version to 2
 1 file changed, 1 insertion(+), 1 deletion(-)
Done!
```

We can see the series of commands get run as we expect, including output from git. Notice that none of our `errdefer` blocks ran, because there were no failures.

**Now let's say that we activate failure point 1** by setting its condition to `true`. This means that, after performing the `sed` command, but before we `git add`, the script exits, and we trigger just the first `errdefer` block to 'reset' the `VERSION` file.

```shell
rad bump.rl 3
```

```
⚡️ sed -i '' "s/Version = .*/Version = 3/" VERSION
Oh no! ERROR!
Undoing bump...
⚡️ git checkout -- VERSION
```

If you run this locally, you should see with `git status` that there are no changes to the `VERSION` file, thanks to our `errdefer` block rolling back the `sed` replacement.

Next let's try deactivating failure point 1 again and enabling failure point 2, and running our script again. This time, we can expect the `git add` to run, and our failure will occur after, but before the `git commit`.

```shell
rad bump.rl 3
```

```
⚡️ sed -i '' "s/Version = .*/Version = 3/" VERSION
⚡️ git add VERSION
Bah! ERROR!
Resetting VERSION...
⚡️ git reset VERSION
Undoing bump...
⚡️ git checkout -- VERSION
```

Here we see a very important detail about defer blocks that applies both to `defer` and `errdefer` - if you have multiple, they run in LIFO (last in, first out) order. In other words, the defer blocks defined *later* run *first*.

This is typically desirable, as this example demonstrates. After we `git commit`, we need to first `git reset`, otherwise the `git checkout` to undo the bump won't work. Thanks to LIFO, our `git reset` runs first and all is good.

## Errors in defer blocks

If a script exits successfully and has multiple `defer` blocks, and the first one to run encounters an error, **the remaining defer blocks still run**. This also applies to `errdefer`. However, the script will exit with a non-0 error code.

`errdefer` blocks are only triggered if the *main script* fails. If the main script runs successfully, but a `defer` block then errors, that does *not* trigger `errdefer` blocks to run.

## Summary

- Use `defer` and `errdefer` blocks to run operations after your main script ends.
- They can commonly be used for clean up operations and making your scripts atomic.
- Defer blocks run in LIFO order - last in, first out.

## Next

Now that you understand `defer`, you're ready to learn about **stashes** - Rad's built-in persistent storage that pairs perfectly with `defer` for saving state reliably.

Continue to Stashes (rad docs guide/stashes).

---

# Stashes

Sometimes your script needs to remember things between runs - user preferences, counters, cached data, or configuration.
Stashes are Rad's built-in mechanism for persistent, per-script storage.

## The Basics

Every script can have its own **stash** - a dedicated storage area that persists between runs.
To use a stash, you need to declare a **stash ID** in your script's file header using the `@stash_id` macro:

```rad
#!/usr/bin/env rad
---
A simple counter that remembers how many times it's been run.
@stash_id = JJRNBOSKHpa
---

state = load_state()
defer save_state(state)

count = state["count"] ?? 0
count++
state["count"] = count

print("This script has been run {count} time(s)!")
```

Let's run it a few times:

```shell
rad counter.rad
```

```
This script has been run 1 time(s)!
```

```shell
rad counter.rad
```

```
This script has been run 2 time(s)!
```

The count persists because it's saved to the stash.

### Generating a Stash ID

You might wonder what that `JJRNBOSKHpa` string is. It's a unique identifier for your script's stash.
You can use any string you like, but Rad provides a built-in command to generate collision-resistant IDs:

```shell
rad gen-id
```

```
K7mPqR2xNfL
```

Using `rad gen-id` is recommended, especially if you plan to share your scripts.
It ensures your stash ID won't accidentally collide with another script's stash on someone else's machine.

### The Defer Save State Pattern

The example above demonstrates the recommended pattern for working with stashes:

```rad
state = load_state()
defer save_state(state)

// ... use and modify state ...
```

The `defer` (rad docs guide/defer-errdefer) ensures your state is saved even if the script exits early or encounters an error.
This pattern is so common that you'll want to use it almost every time you work with stashes.

## State Storage

The primary way to use stashes is through **state** - a map that gets persisted as JSON.

### Loading State

`load_state()` (rad docs load_state) returns your script's saved state as a map.
If no state exists yet (first run), it returns an empty map `{}`:

```rad
state = load_state()
print(state)  // {} on first run, or previously saved data
```

### Saving State

`save_state(map)` (rad docs save_state) persists the map to disk:

```rad
state = {"username": "alice", "theme": "dark"}
save_state(state)
```

The state is stored as JSON at `~/.rad/stashes/<stash_id>/state.json`, making it easy to inspect or debug.

### Working with State

Since state is just a map, you can use all of Rad's map operations.
The `??` fallback operator (rad docs guide/basics) is particularly useful for providing default values:

```rad
#!/usr/bin/env rad
---
Remembers user preferences.
@stash_id = K7mPqR2xNfL
---
args:
    set_editor str?  # Set preferred editor
    set_theme str?   # Set color theme

state = load_state()
defer save_state(state)

// Update preferences if provided
if set_editor:
    state["editor"] = set_editor
    print("Editor set to: {set_editor}")

if set_theme:
    state["theme"] = set_theme
    print("Theme set to: {set_theme}")

// Show current preferences
editor = state["editor"] ?? "vim"
theme = state["theme"] ?? "dark"
print("Current preferences: editor={editor}, theme={theme}")
```

```shell
rad preferences.rad
```

```
Current preferences: editor=vim, theme=dark
```

```shell
rad preferences.rad --set-editor nano --set-theme light
```

```
Editor set to: nano
Theme set to: light
Current preferences: editor=nano, theme=light
```

```shell
rad preferences.rad
```

```
Current preferences: editor=nano, theme=light
```

## File Storage

Beyond state, stashes can also store arbitrary files. This is useful for caching larger data, storing user-created content, or managing configuration files.

### Writing Files

`write_stash_file(path, content)` (rad docs write_stash_file) writes a file to your stash:

```rad
write_stash_file("cache.json", r'{"data": [1, 2, 3]}')
write_stash_file("logs/run.log", "Script executed at {now().time}")
```

Nested paths work automatically - Rad creates any necessary directories.

### Loading Files

`load_stash_file(path, default)` (rad docs load_stash_file) loads a file from your stash, creating it with the default content if it doesn't exist:

```rad
result = load_stash_file("config.txt", "# Default config\nkey=value")
print("Path: {result.full_path}")
print("Was just created: {result.created}")
print("Content: {result.content}")
```

The return value is a map containing:

- `full_path` - the absolute path to the file
- `created` - `true` if the file was just created, `false` if it already existed
- `content` - the file's contents

The `created` field is particularly useful for first-time setup:

```rad
#!/usr/bin/env rad
---
A simple notes manager.
@stash_id = N4xPmK8wQrT
---
args:
    add str?  # Add a new note

result = load_stash_file("notes.txt", "")

if result.created:
    print("Created new notes file!")

if add:
    // Append the new note
    new_content = result.content + add + "\n"
    write_stash_file("notes.txt", new_content)
    print("Note added!")
else:
    if result.content:
        print("Your notes:")
        print(result.content)
    else:
        print("No notes yet. Use --add to create one.")
```

### Getting the Stash Path

`get_stash_path(subpath?)` (rad docs get_stash_path) returns the path to your stash directory:

```rad
stash_path = get_stash_path()
print(stash_path)  // ~/.rad/stashes/<stash_id>

file_path = get_stash_path("data/config.json")
print(file_path)  // ~/.rad/stashes/<stash_id>/data/config.json
```

This is useful when you need to work with stash files using other Rad functions like `read_file` (rad docs read_file) or `get_path` (rad docs get_path).

## Stash Structure

Your stash lives at `~/.rad/stashes/<stash_id>/` with this structure:

```
~/.rad/stashes/<stash_id>/
├── state.json          # Your state map (from save_state)
└── files/              # Your stash files
    ├── config.txt
    ├── cache.json
    └── logs/
        └── run.log
```

State and files are kept separate - `state.json` is managed by `load_state`/`save_state`, while the `files/` subdirectory is managed by `load_stash_file`/`write_stash_file`.

## Managing Stashes

The built-in `rad stash` (rad docs guide/built-in-commands) command inspects and manages stashes
for scripts on your PATH - viewing their state, printing their stash ID, or deleting them.

**Info: Scripts Must Be on PATH**

    The `rad stash` command looks up scripts on your PATH.
    For scripts not on your PATH, you can inspect the stash directly at `~/.rad/stashes/<stash_id>/`.

## Summary

- Stashes provide persistent, per-script storage that survives between runs.
- Declare a stash ID in the file header with `@stash_id = <id>`.
- Use `rad gen-id` to generate collision-resistant IDs.
- **State storage**: Use `load_state()` and `save_state(map)` for map-based data.
- **File storage**: Use `load_stash_file()` and `write_stash_file()` for arbitrary files.
- The recommended pattern is `state = load_state()` followed by `defer save_state(state)`.
- Stashes live at `~/.rad/stashes/<stash_id>/`.

## Next

Now that you know how scripts can persist their own data, learn how to configure Rad itself - including invocation logging, which tracks your script usage for diagnostics.

Continue to Configuration (rad docs guide/config).

---

# Configuration

Rad stores its configuration in a single file: `~/.rad/config.toml`. This file is optional - if it doesn't exist, Rad uses sensible defaults for everything.

The file uses TOML (https://toml.io) format.

## Invocation Logging

By default, Rad logs basic metadata every time you run a script. These logs power `rad check --from-logs`, which bulk-checks your recently-used scripts for issues after an upgrade.

### What Gets Logged

Each log entry records:

- **Script path** - the absolute path to the script that was run
- **Timestamp** - when the script was invoked
- **Rad version** - which version of Rad ran the script
- **Duration** - how long the script took to execute

Arguments are **not** logged by default. The log file lives at `~/.rad/logs/invocations.jsonl`.

### Using `rad check --from-logs`

After upgrading Rad, you can check whether your scripts still parse correctly:

```shell
rad check --from-logs all
```

```
Checked 47 scripts: 47 passed, 0 failed (3 hints, 120 skipped).
```

This reads the invocation log to find scripts you've actually used, then checks each one. It's a quick way to catch compatibility issues before they surprise you.

The `--from-logs` flag takes a duration value that controls how far back to look. Use `all` to check everything, or a duration like `7d` to check only recently-used scripts:

```shell
rad check --from-logs 7d
```

### Settings

All settings live under `[invocation_logging]`:

```toml
[invocation_logging]
enabled = true          # Enable/disable logging (default: true)
include_args = false    # Log script arguments too (default: false)
max_size_mb = 10        # Max log file size before rotation, in MB (default: 10)
keep_rolled_logs = 2    # Rotated log files to keep (default: 2)
```

`include_args` is off by default because arguments may contain sensitive information (passwords, tokens, etc.). When rotation kicks in, Rad keeps at most `keep_rolled_logs` older copies alongside the current log file, deleting anything older.

## Summary

- Rad's config file lives at `~/.rad/config.toml` (TOML format).
- The file is optional - Rad uses defaults if it's absent.
- Invocation logging is enabled by default, powering `rad check --from-logs`.
- Only script path, timestamp, version, and duration are logged - no arguments by default.
- Log rotation is automatic, controlled by `max_size_mb` and `keep_rolled_logs`.

## Next

`rad check --from-logs` is just one of several commands built into the `rad` binary. Let's take a tour of the rest.

Continue to Built-in Commands (rad docs guide/built-in-commands).

---

# Built-in Commands

Rad is more than a script runner - the `rad` binary ships with a small toolbox of commands
for creating, checking, formatting, and managing your scripts. Run `rad` on its own to see them listed.

Every command documents itself: `rad <command> --help` is the complete, always-up-to-date
reference for its flags. This page is a tour, so you know what exists and when to reach for it.

## `rad new`

`rad new` scaffolds a new script, saving you the ritual of creating a file,
adding a shebang, and marking it executable:

```shell
rad new greet
```

```
⚡️ touch greet
⚡️ chmod +x greet
greet is ready to go.
```

The result is a ready-to-run executable containing a small Hello World template to edit.
If you just want the shebang without the template, pass `--shebang`.
You can also jump straight into editing with `--open`:

```shell
rad new greet --shebang --open vim
```

## `rad check`

`rad check` validates and lints a script without running it:

```shell
rad check greet
```

It prints any diagnostics - errors, warnings, and hints - with the offending line and an
explanation, and exits non-zero if there are errors. Add `--strict` to also surface
advisory checks, such as unhandled fallible calls.

It has a flag `--from-logs`, which bulk-checks scripts you've actually used - handy
after upgrading Rad:

```shell
rad check --from-logs 30d   # scripts used in the last 30 days ('all' for everything)
```

This is powered by invocation logging - see Configuration (rad docs guide/config) for details.

## `rad fmt`

`rad fmt` rewrites scripts into Rad's canonical style, in place:

```shell
rad fmt greet
```

```
Formatted greet
```

A few useful variations:

- `rad fmt --stdout greet` prints the formatted result instead of writing it.
- `rad fmt --check greet` writes nothing and exits non-zero if anything is unformatted - built for CI.
- With no paths, it formats stdin to stdout, making it easy to plug into editors and pipes.

## `rad docs`

`rad docs` is Rad's built-in documentation browser. It serves docs embedded directly in the binary,
so it always reflects the version you have installed - no browser or network required.

```
rad docs                     # list all topics grouped by section
rad docs guide/basics        # read the Basics guide page
rad docs len                 # look up a single built-in function
rad docs reference/functions # read the functions reference
rad docs migrations          # list the migration guides
rad docs migrations/v0.12    # read one of them
rad docs all                 # dump the full doc corpus
```

`rad docs all` covers the guide, reference, and examples - the same set as
llms-full.txt (https://amterp.dev/rad/llms-full.txt). Migration guides are
addressable but stay out of it, since they demonstrate syntax that no longer
works.

Error codes are also accessible this way:

```
rad docs RAD20003           # explain a specific error code
rad docs 20003              # shorthand (no RAD prefix needed)
```

By default, `rad docs` renders markdown with color and formatting on a TTY,
and outputs raw markdown when piped. Use `--raw` to force raw output, or `--render`
to force rendered output regardless of destination. Pass `--web` / `-w` to open the
corresponding page on the documentation website instead.

## `rad stash`

Scripts can persist their own data in stashes (rad docs guide/stashes). `rad stash` lets you
inspect and manage those stashes for scripts on your PATH:

```shell
rad stash myscript --state   # view the script's persisted state
rad stash myscript --id      # print the stash ID
rad stash myscript --delete  # delete the stash
```

## `rad gen-id`

`rad gen-id` generates a unique string ID:

```shell
rad gen-id
```

```
VOMPLCB1B4GN7
```

By default it generates FIDs (https://github.com/amterp/flexid) - short, time-ordered,
URL-safe identifiers. Pass `--uuid4` or `--uuid7` if you prefer UUIDs. Its classic use
case is minting stash IDs (rad docs guide/stashes) for new scripts.

## `rad home`

`rad home` prints Rad's home directory - where config, stashes, and logs live:

```shell
rad home
```

```
/home/alice/.rad
```

Useful when you want to poke around Rad's files, or reference them from other tools.

## `rad completion`

`rad completion` generates shell tab-completion - for the `rad` CLI itself and even for
your own scripts. It gets a dedicated page: Shell Completion (rad docs guide/shell-completion).

## Summary

- The `rad` binary includes built-in commands beyond running scripts - run `rad` alone to list them.
- `rad <command> --help` is the full reference for any command's flags.
- `rad new` scaffolds scripts; `rad check` lints them; `rad fmt` formats them.
- `rad docs` browses this documentation offline, straight from your terminal.
- `rad stash`, `rad gen-id`, and `rad home` help manage Rad's persisted data.

## Next

One of those commands - `rad completion` - deserves a closer look: tab completion for
rad commands, script flags, and even enum values.

Continue to Shell Completion (rad docs guide/shell-completion).

---

# REPL

`rad repl` starts an interactive session. You type Rad, it runs it, and
whatever you define stays defined until you leave.

```
$ rad repl
🤙 Rad REPL v0.12.0
Type ':help' for help, ':exit' or Ctrl+D to quit.

> name = "world"
> upper(name)
"WORLD"
```

An expression prints its value; an assignment prints nothing. Values print the
way you would write them, so a string comes back quoted and you can tell `"5"`
from `5`. `print()` is still there when you want the unquoted form.

## Blocks take several lines

A block construct keeps taking lines until you enter a blank one. Rad scopes
blocks by indentation, so there is no closing token to look for - the blank
line is what says you are done. The prompt changes to `.` while the REPL is
still gathering, and the next line is indented for you.

```
> fn greet(name):
.     print("hi {name}")
.
> greet("world")
hi world
```

Everything with a body works this way: `if`, `for`, `while`, `switch`, named
`fn`, and `catch:` blocks. A blank line also gets you out of a buffer you would
rather abandon - though Ctrl+C is quicker, and throws the whole thing away.

Pasting a multi-line block works too. The REPL can tell a pasted newline from a
pressed Enter, so the whole snippet arrives before anything runs.

## Mistakes don't end the session

An error prints the same diagnostic it would print in a script, and then you
get your prompt back:

```
> x = 5
> undefined_variable
error[RAD20028]: Undefined variable: undefined_variable
  --> <repl>:1:1
  |
1 | undefined_variable
  | ^^^^^^^^^^^^^^^^^^
  |
  = info: rad docs RAD20028

> x
5
```

Ctrl+C interrupts whatever is running - a slow shell command, an HTTP request,
a loop that turned out to be infinite - and returns you to the prompt with the
session intact. Press it twice if something is truly wedged; the second one
exits immediately.

## Editing

The line you are typing is editable:

| Key                 | Does                              |
| ------------------- | --------------------------------- |
| `←` `→`             | move the cursor                   |
| `Ctrl+A` / `Ctrl+E` | jump to start / end of line       |
| `Ctrl+W`            | delete the word behind the cursor |
| `Ctrl+K`            | delete to end of line             |
| `Ctrl+U`            | delete the line                   |
| `↑` `↓`             | recall earlier input              |
| `Ctrl+C`            | abandon this line                 |
| `Ctrl+D`            | leave (on an empty line)          |

Inside a multi-line block, `↑` and `↓` move between the lines you are typing
and only reach for history once the cursor is already at the top or bottom.

History lasts for the session and is not written to disk.

## Commands

A line starting with `:` is a REPL command rather than Rad:

| Command          | Does                                                |
| ---------------- | --------------------------------------------------- |
| `:help`          | the summary                                         |
| `:vars`          | variables you have defined                          |
| `:docs <topic>`  | docs for a function, an error code, or a guide page |
| `:load <file>`   | run a `.rad` file into this session                 |
| `:clear`         | clear the screen                                    |
| `:reset`         | forget every variable and start over                |
| `:exit`, `:quit` | leave                                               |

`:docs` takes anything `rad docs` takes:

```
> :docs upper
> :docs RAD20028
> :docs guide/shell-commands
```

`:load` runs a file's statements against your session, so the functions and
variables it defines are yours afterwards. It is the way to work on a script
and try its pieces without pasting them.

## Two things behave differently than in a script

**`defer` runs at the end of the turn that registered it**, not when the
session ends. A turn is the REPL's whole notion of a script. Holding a defer
until you quit would mean it does nothing observable for as long as you keep
working, and never runs at all if a later turn ends badly.

**`args` blocks, command blocks, and file headers are refused.** All three
describe how a script is invoked from a command line, and a session was not
invoked from one. Put the script in a file and `:load` it, or run it normally
to exercise its argument parsing. See
RAD20049 (rad docs reference/errors) for the details.

## Piping input

With no terminal to draw on - a pipe, CI, an agent's tool call - `rad repl`
reads lines and prints results without drawing a prompt:

```
$ printf 'x = 20\nx * 2\n' | rad repl
🤙 Rad REPL v0.12.0
Type ':help' for help, ':exit' or Ctrl+D to quit.

40
```

Blocks work the same way, blank line and all. This is also how the REPL's own
tests drive it.

## What it doesn't do yet

No tab completion, no syntax highlighting, no `Ctrl+R` search, and no history
file that survives the session. None of these are ruled out; they just aren't
built.

---

# Shell Completion

Tab completion lets you press Tab in your terminal to auto-complete rad commands, flags, and argument values. You can enable it for the `rad` CLI itself and for your own Rad scripts.

## Quick Setup

Add one of these lines to your shell startup file:

**Bash (~/.bashrc)**

    ```shell
    eval "$(rad completion bash)"
    ```

**Zsh (~/.zshrc)**

    ```shell
    eval "$(rad completion zsh)"
    ```

After saving, either restart your terminal or re-source the file (e.g. `source ~/.bashrc`).

That's it - you now have tab completion for the `rad` CLI.

## What Gets Completed

With CLI completion enabled, pressing Tab after `rad` will suggest:

- **Embedded commands** - `new`, `docs`, `check`, `home`, `gen-id`, `stash`, `explain`, etc
- **Global flags** - `--help`, `--debug`, `--color`, `--quiet`, and the rest

For example, typing `rad ch` and pressing Tab completes to `rad check`. Typing `rad check --` and pressing Tab shows the flags that `check` accepts.

## Script Completions

You can generate tab completions for your own Rad scripts too - including their flags, enum values, commands, and command arguments.

To enable completion for a script, pass its path to `rad completion`:

**Bash**

    ```shell
    eval "$(rad completion bash ~/bin/deploy)"
    ```

**Zsh**

    ```shell
    eval "$(rad completion zsh ~/bin/deploy)"
    ```

### What Gets Completed

Given a script like this:

```rad
#!/usr/bin/env rad
---
Deploy services to a target environment.
---
args:
    service str       # Service to deploy.
    env e str = "dev" # Target environment.

    env enum ["dev", "staging", "prod"]

print("Deploying {service} to {env}...")
```

Tab completion will suggest:

- `--service` and `--env` (or `-e`) as flags
- `dev`, `staging`, `prod` as values when completing `--env`

If your script uses commands (rad docs guide/script-commands), those are completed too - along with each command's own arguments.

**Note: Shebang required**

    Scripts must have a `rad` shebang (e.g. `#!/usr/bin/env rad`) to be detected. Files without one are silently skipped.

## Multiple Scripts & Globs

You can pass multiple paths or glob patterns to register completions for many scripts at once:

**Bash**

    ```shell
    eval "$(rad completion bash ~/.rad/bin/* ~/scripts/*)"
    ```

**Zsh**

    ```shell
    eval "$(rad completion zsh ~/.rad/bin/* ~/scripts/*)"
    ```

Non-Rad files matched by the glob are silently skipped, so it's safe to point at directories containing a mix of file types.

**Info: Separate lines for CLI and scripts**

    When you pass script paths, `rad completion` generates completions for those scripts only - not the rad CLI. Use a separate line without paths for rad CLI completions.

## Full Example

Here's a typical setup in `~/.bashrc` that covers everything:

**Bash (~/.bashrc)**

    ```shell
    # Rad tab completion
    eval "$(rad completion bash)"                    # rad CLI commands & flags
    eval "$(rad completion bash ~/.rad/bin/*)"        # all scripts in ~/.rad/bin/
    eval "$(rad completion bash ~/bin/deploy ~/bin/status)"  # specific scripts
    ```

**Zsh (~/.zshrc)**

    ```shell
    # Rad tab completion
    eval "$(rad completion zsh)"                    # rad CLI commands & flags
    eval "$(rad completion zsh ~/.rad/bin/*)"        # all scripts in ~/.rad/bin/
    eval "$(rad completion zsh ~/bin/deploy ~/bin/status)"  # specific scripts
    ```

**Tip: Adding new scripts**

    When you add a new script to a directory that's already covered by a glob, re-source your shell config (or open a new terminal) to pick it up.

## Summary

- `rad completion bash` / `rad completion zsh` generates shell completion scripts.
- Without script paths, it completes the rad CLI (embedded commands, global flags).
- With script paths, it completes those scripts (flags, enum values, commands, command args).
- Scripts must have a `rad` shebang to be detected.
- Non-Rad files in glob expansions are silently skipped.
- Use separate `eval` lines for rad CLI and script completions.

---

# Examples

Real-world scripts demonstrating Rad's features in practice.

| Example                         | Description                                | Demonstrates                                              |
| ------------------------------- | ------------------------------------------ | --------------------------------------------------------- |
| brewi (rad docs examples/brewi) | Check a Homebrew formula before installing | Args, shell commands, `confirm()` prompt                  |
| epoch (rad docs examples/epoch) | Convert epoch timestamps across timezones  | Optional args, `display` blocks, `.map()`, loop unpacking |
| hm (rad docs examples/hm)       | Personal command cheatsheet manager        | Stashes, script commands, file storage                    |

---

# brewi

## Preview

```rad
#!/usr/bin/env rad
---
Facilitates checking a brew formula before installing it.
---
args:
    formula str    # Name of the formula to install.
    cask c bool    # Enable if it's a cask.

$`brew info {formula}`
if confirm():
    $`brew install{cask ? " --cask" : ""} {formula}`
```

```
> brewi -h
Facilitates checking a brew formula before installing it.

Usage:
  brewi <formula> [cask]

Script args:
      --formula str      Name of the formula to install.
  -c, --cask             Enable if it's a cask.
```

## Tutorial: Building `brewi`

### Motivation

I tend to run `brew info` before installing formulas just to double-check that I've got the right one.
Most of the time, it is, so I follow that with a `brew install`.

Rather than writing out these two commands manually each time, it'd be neat if I had an alias, which not only saved some characters, but did this workflow *for* me.

### Writing the script

We can use `rad` to create the script file for us. The `-s` flag gives us a minimal template with just a shebang, and `-o code` opens it in VS Code.

```sh
rad new brewi -s -o code
```

First, we want to quickly describe what the script is aiming to do, so we'll add a file header.

```rad
#!/usr/bin/env rad
---
Facilitates checking a brew formula before installing it.
---
```

We want the script to accept a formula as an argument, i.e. the formula we may be installing. It'll be a string, so let's add this in an arg block (rad docs guide/args). We'll include a little comment to improve our usage string.

```rad
#!/usr/bin/env rad
---
Facilitates checking a brew formula before installing it.
---
args:
    formula str # Name of the formula to install.
```

`formula` will serve both as the variable name for the rest of the script, and be exposed to the user as the script's CLI API.

Setup done. First thing we'll wanna do is run `brew info` with the formula. We'll do this via a shell command (rad docs guide/shell-commands).

Specifically, we'll use a *critical* (rad docs guide/shell-commands) shell command, because if the command fails (including if the formula just doesn't exist), we want to just print the error and exit the script.

This uses the `$` syntax.

```rad
#!/usr/bin/env rad
---
Facilitates checking a brew formula before installing it.
---
args:
    formula str # Name of the formula to install.

$`brew info {formula}`
```

We use string interpolation (rad docs guide/strings-advanced) to insert the formula into the command.

You can try running the command now! Make sure it's executable (`chmod +x ./brewi`).

Next, we want to ask the user if they'd like to proceed with installing the formula. For that, Rad offers the `confirm` (rad docs confirm) function.
The default prompt is `Confirm? [Y/n] > `, which works fine for us here, so we'll do a simple 0-arg `confirm()` call. The function returns a bool for yes/no, so we'll put it in an if statement.

```rad
#!/usr/bin/env rad
---
Facilitates checking a brew formula before installing it.
---
args:
    formula str # Name of the formula to install.

$`brew info {formula}`
if confirm():
    $`brew install {formula}`
```

Feel free to try it again now!

One last touch: we should also allow installing casks with this script. We'll aim to offer a simple `-c` flag users can set which modifies the command. 

We'll add the `bool` arg, and insert an additional interpolation in our `brew install` command, leveraging Rad's ternary (rad docs guide/basics) syntax.
We need to pay close attention to whitespace so we make sure the command comes out correct in the cask and non-cask cases.

```rad
#!/usr/bin/env rad
---
Facilitates checking a brew formula before installing it.
---
args:
    formula str # Name of the formula to install.
    cask c bool    # Enable if it's a cask.

$`brew info {formula}`
if confirm():
    $`brew install{cask ? " --cask" : ""} {formula}`
```

Note the shorthand flag in `cask c bool`.

Done! You've now got a great, convenient helper script for installing things with brew :)

## Concepts demonstrated

| Concept                                                | Where                           |
| ------------------------------------------------------ | ------------------------------- |
| File header (rad docs guide/getting-started)           | Script description for `--help` |
| Args block (rad docs guide/args)                       | `formula str`, `cask c bool`    |
| Short flags (rad docs guide/args)                      | `cask c bool` gives `-c`        |
| Shell commands (rad docs guide/shell-commands)         | `$\`brew info {formula}\``      |
| String interpolation (rad docs guide/strings-advanced) | `{formula}` in shell command    |
| `confirm()` (rad docs confirm)                         | Interactive yes/no prompt       |
| Ternary operator (rad docs guide/basics)               | `cask ? " --cask" : ""`         |

---

# epoch

## Preview

```rad
#!/usr/bin/env rad
---
Convert epoch timestamps to human-readable times across multiple timezones.
---
args:
    epoch int?  # Epoch time to convert. Defaults to current time if omitted.

if not epoch:
    epoch = now().epoch.millis
    print("Epoch millis: {epoch.yellow()}")

tz_to_flag = [
    ['Europe/London', '🇬🇧'],
    ['America/New_York', '🇺🇸'],
    ['Asia/Tokyo', '🇯🇵'],
    ['Australia/Melbourne', '🇦🇺'],
]

Timezone = tz_to_flag.map(fn(x) "{x[1]} {x[0]}")

Time = []
for tz, _ in tz_to_flag:
    time = parse_time(epoch, tz)
    Time += [time]

rad:
    fields Timezone, Time

fn parse_time(epoch: int, tz: str) -> str:
    time = parse_epoch(epoch, tz=tz)
    return "{time.date} {time.time}"
```

```
> epoch -h
Convert epoch timestamps to human-readable times across multiple timezones.

Usage:
  epoch [epoch] [OPTIONS]

Script args:
      --epoch int   (optional) Epoch time to convert. Defaults to current time if omitted.
```

```
> epoch 1700000000000
Timezone                Time
🇬🇧 Europe/London         2023-11-14 22:13:20
🇺🇸 America/New_York      2023-11-14 17:13:20
🇯🇵 Asia/Tokyo            2023-11-15 07:13:20
🇦🇺 Australia/Melbourne   2023-11-15 09:13:20

> epoch
Epoch millis: 1769378597483
Timezone                Time
🇬🇧 Europe/London         2026-01-25 22:03:17
🇺🇸 America/New_York      2026-01-25 17:03:17
🇯🇵 Asia/Tokyo            2026-01-26 07:03:17
🇦🇺 Australia/Melbourne   2026-01-26 09:03:17
```

## Tutorial: Building `epoch`

### Motivation

When debugging distributed systems or reading logs, you'll often encounter epoch timestamps - large integers representing milliseconds (or seconds, or nanoseconds) since 1970. Converting these to human-readable times is tedious, and when you're coordinating across timezones, you often want to see the same moment in multiple locations at once.

Let's build a script that converts an epoch timestamp into a table showing that moment across several timezones.

### Writing the script

We can use `rad` to create the script file for us.

```sh
rad new epoch -s
```

This will set us up with an executable script named `epoch`, and the `-s` simplifies the template it's instantiated with to contain *just* a shebang (rad docs guide/getting-started).

The shebang will allow us to invoke the script as `epoch` from the CLI rather than writing out `rad ./epoch`. Open up `epoch` in your editor, and you should see something like this:

```rad
#!/usr/bin/env rad
```

Let's begin editing it. First, we want to quickly describe what the script is aiming to do, so we'll add a file header.

```rad
#!/usr/bin/env rad
---
Convert epoch timestamps to human-readable times across multiple timezones.
---
```

### Adding an optional argument

We want the script to accept an epoch timestamp, but it should also work without one - defaulting to the current time. We declare this with `int?`, where the `?` makes it optional (it will be `null` if not provided).

```rad
#!/usr/bin/env rad
---
Convert epoch timestamps to human-readable times across multiple timezones.
---
args:
    epoch int?  # Epoch time to convert. Defaults to current time if omitted.
```

Now we handle the case where no epoch was provided:

```rad
#!/usr/bin/env rad
---
Convert epoch timestamps to human-readable times across multiple timezones.
---
args:
    epoch int?  # Epoch time to convert. Defaults to current time if omitted.

if not epoch:
    epoch = now().epoch.millis
    print("Epoch millis: {epoch.yellow()}")
```

The `now()` (rad docs now) function returns a map with various time fields. We access `.epoch.millis` to get the current epoch in milliseconds, then print it so the user knows what value we're working with.

### Setting up our timezone data

We'll store our timezones alongside their flag emoji in a list of pairs. Each inner list contains `[timezone_id, flag]`:

```rad
#!/usr/bin/env rad
---
Convert epoch timestamps to human-readable times across multiple timezones.
---
args:
    epoch int?  # Epoch time to convert. Defaults to current time if omitted.

if not epoch:
    epoch = now().epoch.millis
    print("Epoch millis: {epoch.yellow()}")

tz_to_flag = [
    ['Europe/London', '🇬🇧'],
    ['America/New_York', '🇺🇸'],
    ['Asia/Tokyo', '🇯🇵'],
    ['Australia/Melbourne', '🇦🇺'],
]
```

### Building the display columns

For our table output, we need two columns: `Timezone` (for display) and `Time` (the converted times).

First, let's create the `Timezone` column. We want it to show the flag followed by the timezone name, like "🇬🇧 Europe/London". We'll use `.map()` (rad docs map) with a lambda to transform each pair:

```rad
#!/usr/bin/env rad
---
Convert epoch timestamps to human-readable times across multiple timezones.
---
args:
    epoch int?  # Epoch time to convert. Defaults to current time if omitted.

if not epoch:
    epoch = now().epoch.millis
    print("Epoch millis: {epoch.yellow()}")

tz_to_flag = [
    ['Europe/London', '🇬🇧'],
    ['America/New_York', '🇺🇸'],
    ['Asia/Tokyo', '🇯🇵'],
    ['Australia/Melbourne', '🇦🇺'],
]

Timezone = tz_to_flag.map(fn(x) "{x[1]} {x[0]}")
```

Each `x` is a `[timezone, flag]` pair, so `x[1]` is the flag and `x[0]` is the timezone name. We interpolate them into a string with the flag first.

**Tip: List comprehension alternative**

    You could also write this as a list comprehension, which is a bit more concise in this case:

    ```rad
    Timezone = ["{x[1]} {x[0]}" for x in tz_to_flag]
    ```

### Iterating with unpacking

Now we need to build the `Time` column by converting the epoch for each timezone. When iterating over a list of lists, we can *unpack* each inner list directly into named variables:

```rad
#!/usr/bin/env rad
---
Convert epoch timestamps to human-readable times across multiple timezones.
---
args:
    epoch int?  # Epoch time to convert. Defaults to current time if omitted.

if not epoch:
    epoch = now().epoch.millis
    print("Epoch millis: {epoch.yellow()}")

tz_to_flag = [
    ['Europe/London', '🇬🇧'],
    ['America/New_York', '🇺🇸'],
    ['Asia/Tokyo', '🇯🇵'],
    ['Australia/Melbourne', '🇦🇺'],
]

Timezone = tz_to_flag.map(fn(x) "{x[1]} {x[0]}")

Time = []
for tz, _ in tz_to_flag:
    time = parse_time(epoch, tz)
    Time += [time]
```

The `for tz, _ in tz_to_flag:` line unpacks each `[timezone, flag]` pair. The first element becomes `tz`, and we use `_` for the second element to indicate we don't need the flag here - it's a convention meaning "discard this value."

This is cleaner than writing:

```rad
for pair in tz_to_flag:
    tz = pair[0]
    // ...
```

We're calling a `parse_time` function we haven't written yet - let's do that next.

### The helper function

We'll define a function that takes an epoch and timezone, then returns a formatted string:

```rad
#!/usr/bin/env rad
---
Convert epoch timestamps to human-readable times across multiple timezones.
---
args:
    epoch int?  # Epoch time to convert. Defaults to current time if omitted.

if not epoch:
    epoch = now().epoch.millis
    print("Epoch millis: {epoch.yellow()}")

tz_to_flag = [
    ['Europe/London', '🇬🇧'],
    ['America/New_York', '🇺🇸'],
    ['Asia/Tokyo', '🇯🇵'],
    ['Australia/Melbourne', '🇦🇺'],
]

Timezone = tz_to_flag.map(fn(x) "{x[1]} {x[0]}")

Time = []
for tz, _ in tz_to_flag:
    time = parse_time(epoch, tz)
    Time += [time]

// rad block will go here

fn parse_time(epoch: int, tz: str) -> str:
    time = parse_epoch(epoch, tz=tz)
    return "{time.date} {time.time}"
```

The `parse_epoch()` (rad docs parse_epoch) function converts an epoch timestamp to a time map, accepting a `tz` parameter for the timezone. We then format the `.date` and `.time` fields into a string.

Note the type annotations `epoch: int, tz: str` and `-> str` - these are optional but help document what the function expects and returns.

### The rad block

Finally, we use a `rad` block (rad docs guide/rad-blocks) (with no source) to render our two columns as a formatted table:

```rad
#!/usr/bin/env rad
---
Convert epoch timestamps to human-readable times across multiple timezones.
---
args:
    epoch int?  # Epoch time to convert. Defaults to current time if omitted.

if not epoch:
    epoch = now().epoch.millis
    print("Epoch millis: {epoch.yellow()}")

tz_to_flag = [
    ['Europe/London', '🇬🇧'],
    ['America/New_York', '🇺🇸'],
    ['Asia/Tokyo', '🇯🇵'],
    ['Australia/Melbourne', '🇦🇺'],
]

Timezone = tz_to_flag.map(fn(x) "{x[1]} {x[0]}")

Time = []
for tz, _ in tz_to_flag:
    time = parse_time(epoch, tz)
    Time += [time]

rad:
    fields Timezone, Time

fn parse_time(epoch: int, tz: str) -> str:
    time = parse_epoch(epoch, tz=tz)
    return "{time.date} {time.time}"
```

The `rad` block (with no source) takes our pre-populated lists and renders them as aligned columns. The variable names (`Timezone`, `Time`) become the column headers.

### Try it out

```
> epoch 1700000000000
Timezone                Time
🇬🇧 Europe/London         2023-11-14 22:13:20
🇺🇸 America/New_York      2023-11-14 17:13:20
🇯🇵 Asia/Tokyo            2023-11-15 07:13:20
🇦🇺 Australia/Melbourne   2023-11-15 09:13:20
```

Or without an argument, to see the current time:

```
> epoch
Epoch millis: 1769378597483
Timezone                Time
🇬🇧 Europe/London         2026-01-25 22:03:17
🇺🇸 America/New_York      2026-01-25 17:03:17
🇯🇵 Asia/Tokyo            2026-01-26 07:03:17
🇦🇺 Australia/Melbourne   2026-01-26 09:03:17
```

## Concepts demonstrated

| Concept                                         | Where                                        |
| ----------------------------------------------- | -------------------------------------------- |
| Optional arguments (rad docs guide/args)        | `epoch int?`                                 |
| Null checking                                   | `if not epoch:`                              |
| Built-in `now()` (rad docs now)                 | `now().epoch.millis`                         |
| List of lists (rad docs guide/basics)           | `tz_to_flag`                                 |
| `.map()` with lambdas (rad docs map)            | `tz_to_flag.map(fn(x) ...)`                  |
| Loop unpacking (rad docs guide/basics)          | `for tz, _ in tz_to_flag:`                   |
| Functions with types (rad docs guide/functions) | `fn parse_time(epoch: int, tz: str) -> str:` |
| `parse_epoch()` (rad docs parse_epoch)          | Time conversion                              |
| `rad` blocks (rad docs guide/rad-blocks)        | Tabular output                               |

---

# hm

## Preview

```rad
#!/usr/bin/env rad
---
A personal cheatsheet manager.
Store and retrieve help snippets for commands you forget.
@stash_id = J8xKmN3pQrT
---

command show:
    ---
    Show the help entry for a topic.
    ---
    topic str  # The topic to look up.
    calls do_show

command edit:
    ---
    Edit or create a help entry for a topic.
    ---
    topic str  # The topic to edit.
    calls do_edit

command list:
    ---
    List all stored topics.
    ---
    calls do_list

state = load_state()
defer save_state(state)

fn do_show():
    file_path = get_stash_path("files/entries/{topic}.txt")
    if not file_path.get_path().exists:
        print("No entry for '{topic}'. Use 'hm edit {topic}' to create one.")
    else:
        print(file_path.read_file().content)

fn do_edit():
    editor = state.load("editor", fn() input("Editor? > ", default="vim"))
    result = load_stash_file("entries/{topic}.txt", "")
    $`{editor} {result.full_path}`
    print("Entry for '{topic}' saved.")

fn do_list():
    entries_dir = get_stash_path("files/entries")
    if not entries_dir.get_path().exists:
        print("No entries yet. Use 'hm edit <topic>' to create one.")
        exit()
    files = entries_dir.find_paths(depth=1, relative="absolute")
    if files.len() == 0:
        print("No entries yet. Use 'hm edit <topic>' to create one.")
        exit()
    for file in files:
        name = file.get_path().base_name.replace(".txt", "")
        print(name)
```

```
> hm -h
A personal cheatsheet manager.
Store and retrieve help snippets for commands you forget.

Usage:
  hm [command] [OPTIONS]

Commands:
  edit   Edit or create a help entry for a topic.
  list   List all stored topics.
  show   Show the help entry for a topic.
```

```
> hm edit tar
Editor? > vim
# Opens vim with empty file, user writes their notes, saves and exits
Entry for 'tar' saved.

> hm show tar
tar - extract and create archives

Extract:    tar -xvf archive.tar.gz
Create:     tar -cvzf archive.tar.gz files/
List:       tar -tvf archive.tar.gz

> hm edit rsync
# No prompt this time - editor preference was saved!
Entry for 'rsync' saved.

> hm list
tar
rsync
```

## Tutorial: Building `hm`

### Motivation

Some commands have notoriously hard-to-remember syntax - `tar`, `find`, `rsync`. You look them up, use them once, and
forget again. Tools like `tldr` help, but sometimes you want your *own* notes - the specific incantations that work for
your use cases.

Let's build `hm` - a personal cheatsheet manager that stores your notes in a stash (rad docs guide/stashes), so they
persist between sessions.

### Writing the script

Let's start with a new script:

```sh
rad new hm -s
```

First, we'll add a description and set up a stash ID. The stash ID is what tells Rad where to store our persistent data.
You can generate one with `rad gen-id`:

```rad
#!/usr/bin/env rad
---
A personal cheatsheet manager.
Store and retrieve help snippets for commands you forget.
@stash_id = J8xKmN3pQrT
---
```

The `@stash_id` macro in the file header creates a dedicated storage area at `~/.rad/stashes/J8xKmN3pQrT/` for this
script.

### Defining commands

We'll use script commands (rad docs guide/script-commands) to organize our CLI into commands. Each command gets its own
description and arguments:

```rad
#!/usr/bin/env rad
---
A personal cheatsheet manager.
Store and retrieve help snippets for commands you forget.
@stash_id = J8xKmN3pQrT
---

command show:
    ---
    Show the help entry for a topic.
    ---
    topic str  # The topic to look up.
    calls do_show

command edit:
    ---
    Edit or create a help entry for a topic.
    ---
    topic str  # The topic to edit.
    calls do_edit

command list:
    ---
    List all stored topics.
    ---
    calls do_list
```

Each command block declares its own arguments (like `topic str`) and uses `calls` to specify which function handles it.
The `---` sections become the command descriptions shown in `--help`.

### Setting up state

Before implementing our commands, we need to set up state management. We'll use state to remember user preferences (like
their preferred editor):

```rad
#!/usr/bin/env rad
---
A personal cheatsheet manager.
Store and retrieve help snippets for commands you forget.
@stash_id = J8xKmN3pQrT
---

command show:
    ---
    Show the help entry for a topic.
    ---
    topic str  # The topic to look up.
    calls do_show

command edit:
    ---
    Edit or create a help entry for a topic.
    ---
    topic str  # The topic to edit.
    calls do_edit

command list:
    ---
    List all stored topics.
    ---
    calls do_list

state = load_state()
defer save_state(state)
```

The `defer save_state(state)` ensures our state is saved when the script exits, even if something goes wrong later.

### The show command

Now let's implement `do_show()`. We check if the entry exists and display it:

```rad
#!/usr/bin/env rad
---
A personal cheatsheet manager.
Store and retrieve help snippets for commands you forget.
@stash_id = J8xKmN3pQrT
---

command show:
    ---
    Show the help entry for a topic.
    ---
    topic str  # The topic to look up.
    calls do_show

command edit:
    ---
    Edit or create a help entry for a topic.
    ---
    topic str  # The topic to edit.
    calls do_edit

command list:
    ---
    List all stored topics.
    ---
    calls do_list

state = load_state()
defer save_state(state)

fn do_show():
    file_path = get_stash_path("files/entries/{topic}.txt")
    if not file_path.get_path().exists:
        print("No entry for '{topic}'. Use 'hm edit {topic}' to create one.")
    else:
        print(file_path.read_file().content)
```

We use `get_stash_path()` to build the path to where the entry file would live. The `"files/"` prefix is needed because
stash files are stored in a `files/` subdirectory. Then we chain `.get_path().exists` to check if it exists - if not, we
tell the user how to create it. If it does exist, we read and print it with `.read_file().content`.

### The edit command

The edit command opens the entry in the user's editor. Here's where it gets interesting - we use `load()` (rad docs load) to handle first-run configuration:

```rad
#!/usr/bin/env rad
---
A personal cheatsheet manager.
Store and retrieve help snippets for commands you forget.
@stash_id = J8xKmN3pQrT
---

command show:
    ---
    Show the help entry for a topic.
    ---
    topic str  # The topic to look up.
    calls do_show

command edit:
    ---
    Edit or create a help entry for a topic.
    ---
    topic str  # The topic to edit.
    calls do_edit

command list:
    ---
    List all stored topics.
    ---
    calls do_list

state = load_state()
defer save_state(state)

fn do_show():
    file_path = get_stash_path("files/entries/{topic}.txt")
    if not file_path.get_path().exists:
        print("No entry for '{topic}'. Use 'hm edit {topic}' to create one.")
    else:
        print(file_path.read_file().content)

fn do_edit():
    editor = state.load("editor", fn() input("Editor? > ", default="vim"))
    result = load_stash_file("entries/{topic}.txt", "")
    $`{editor} {result.full_path}`
    print("Entry for '{topic}' saved.")
```

The `load()` function is the star here. It checks if `"editor"` exists in `state`:

- **First run**: Key doesn't exist, so it calls the loader function - which prompts the user with `input()`. The result
  gets stored in `state["editor"]`.
- **Subsequent runs**: Key exists, so it returns the cached value immediately - no prompt.

Since we have `defer save_state(state)`, the editor preference persists between sessions.

### The list command

Finally, we list all stored entries by finding files in the entries directory:

```rad
#!/usr/bin/env rad
---
A personal cheatsheet manager.
Store and retrieve help snippets for commands you forget.
@stash_id = J8xKmN3pQrT
---

command show:
    ---
    Show the help entry for a topic.
    ---
    topic str  # The topic to look up.
    calls do_show

command edit:
    ---
    Edit or create a help entry for a topic.
    ---
    topic str  # The topic to edit.
    calls do_edit

command list:
    ---
    List all stored topics.
    ---
    calls do_list

state = load_state()
defer save_state(state)

fn do_show():
    file_path = get_stash_path("files/entries/{topic}.txt")
    if not file_path.get_path().exists:
        print("No entry for '{topic}'. Use 'hm edit {topic}' to create one.")
    else:
        print(file_path.read_file().content)

fn do_edit():
    editor = state.load("editor", fn() input("Editor? > ", default="vim"))
    result = load_stash_file("entries/{topic}.txt", "")
    $`{editor} {result.full_path}`
    print("Entry for '{topic}' saved.")

fn do_list():
    entries_dir = get_stash_path("files/entries")
    if not entries_dir.get_path().exists:
        print("No entries yet. Use 'hm edit <topic>' to create one.")
        exit()
    files = entries_dir.find_paths(depth=1, relative="absolute")
    if files.len() == 0:
        print("No entries yet. Use 'hm edit <topic>' to create one.")
        exit()
    for file in files:
        name = file.get_path().base_name.replace(".txt", "")
        print(name)
```

We use `get_stash_path()` (rad docs get_stash_path) to get the path to our entries folder - note the
`"files/"` prefix since stash files live in a `files/` subdirectory. We chain `.get_path()` (rad docs get_path) to check if it exists, and `.find_paths()` (rad docs find_paths) to list all files. The `depth=1` parameter limits the search to
direct children only, and `relative="absolute"` gives us full paths so that subsequent `get_path()` calls resolve
correctly. For each file, we extract the topic name with `.get_path().base_name` and strip the `.txt` extension.

### Try it out

Create your first entry:

```
> hm edit tar
Editor? > vim
# Editor opens, you write your notes, save and exit
Entry for 'tar' saved.
```

View it later:

```
> hm show tar
tar - extract and create archives

Extract:    tar -xvf archive.tar.gz
Create:     tar -cvzf archive.tar.gz files/
List:       tar -tvf archive.tar.gz
```

Add another entry - notice no editor prompt this time:

```
> hm edit rsync
# Opens vim immediately - preference was remembered!
Entry for 'rsync' saved.
```

List all your entries:

```
> hm list
tar
rsync
```

Your notes live at `~/.rad/stashes/J8xKmN3pQrT/files/entries/` and your preferences are stored in
`~/.rad/stashes/J8xKmN3pQrT/state.json`.

## Concepts demonstrated

| Concept                                          | Where                                              |
| ------------------------------------------------ | -------------------------------------------------- |
| Stash ID (rad docs guide/stashes)                | `@stash_id = J8xKmN3pQrT`                          |
| State persistence (rad docs guide/stashes)       | `load_state()` / `save_state()`                    |
| Defer pattern (rad docs guide/stashes)           | `defer save_state(state)`                          |
| `load()` (rad docs load)                         | First-run config with `state.load("editor", ...)`  |
| `input()` (rad docs input)                       | Prompting for editor preference                    |
| `load_stash_file()` (rad docs load_stash_file)   | Creating entry files in `do_edit()`                |
| `read_file()` (rad docs read_file)               | Reading entry content in `do_show()`               |
| `get_stash_path()` (rad docs get_stash_path)     | Getting entries paths                              |
| Script commands (rad docs guide/script-commands) | `command show:`, `command edit:`, `command list:`  |
| Shell commands (rad docs guide/shell-commands)   | `$\`{editor} {result.full_path}\``                 |
| `find_paths()` (rad docs find_paths)             | Listing files in the entries directory             |
| `get_path()` (rad docs get_path)                 | Checking if directory exists, extracting base name |
| Custom functions (rad docs guide/functions)      | `fn do_show():`, etc.                              |

---

# Rad Language Reference

This document provides a comprehensive overview of Rad's syntax for quick reference in development sessions.

## Script Structure

### Basic Script Format

```rad
#!/usr/bin/env rad
---
Script description goes here.
Multi-line descriptions are supported.
---

// Optional arguments section
args:
    name str              # Required string argument
    count int = 5         # Optional with default value
    verbose v bool        # Boolean flag (can use short form)

// Script body
print("Hello {name}!")
```

### File Header for Automatic Help Generation

The file header automatically generates the help text shown when users run your script with `-h` or `--help`. This is a core Rad feature that eliminates the need to manually write help documentation.

```rad
---
Script description that appears in --help.

Detailed explanation of what the script does.
Can be multiple paragraphs.

@stash_id = my_script_data
@enable_global_options = true  
@enable_args_block = true
---
```

#### Special @ Macros

- `@stash_id` - Sets the stash identifier for the script
- `@enable_global_options` - Enable/disable global Rad options (default: true)
- `@enable_args_block` - Enable/disable argument parsing (default: true)

### Static Analysis

Use `rad check <script>` to statically analyze your scripts for errors before running them. This catches syntax errors, type mismatches, and other issues without executing the script.

```bash
rad check my_script.rad
```

## Comments

```rad
// Code comments use double slash
// Multi-line code comments use multiple // lines
// like this

// In args blocks, argument descriptions use # for help text generation:
args:
    name str    # This comment appears in --help usage
    count int   # This also appears in --help
```

## Data Types

### Primitives

```rad
// Strings
name = "alice"
path = 'path/to/file'

// Multi-line strings (triple quotes)
text = """
Hello world
How are you?
"""

// Numbers
age = 25                   // int
height = 5.9               // float
scientific = 1.23e4        // exponential notation
large_num = 1_234_567      // underscore separators for readability
float_with_sep = 123.456_789

// Booleans
is_valid = true
is_empty = false

// Null
value = null
```

### Collections

```rad
// Lists
numbers = [1, 2, 3, 4, 5]
mixed = [1, "hello", true, [1, 2]]
empty_list = []

// Maps/Objects
person = {"name": "alice", "age": 25}
nested = {"user": {"name": "bob", "roles": ["admin", "user"]}}
empty_map = {}
```

### Multi-line Strings (Triple Quotes)

```rad
// Basic multi-line string
text = """
Hello world
How are you?
"""
// Contents: "Hello world\nHow are you?" - the newlines adjacent to the
// opening and closing """ are excluded, so the string does NOT end with
// a newline. Add a blank last line (or concatenate "\n") if you need one,
// e.g. when assembling scripts or files from fragments.

// Indentation control - closing """ position determines whitespace stripping
indented = """
  Line 1
   Line 2
     Line 4
 """
// Result: " Line 1\n  Line 2\n    Line 4" (1 space stripped from each line)

// String interpolation works in multi-line strings
name = "alice"
message = """
Hello {name}!
How are you today?
"""

// Raw multi-line strings (no interpolation or escape processing)
raw_text = r"""
Literal \n and {name}
No processing here
"""

// Comments allowed after opening triple quotes
documented = """ // This is allowed
Content starts on next line
Always on next line
"""
```

**Multi-line String Rules:**
- Content must start on a new line after opening `"""`
- The indentation of the closing `"""` determines how much leading whitespace is stripped from each line
- Support string interpolation with `{variable}` syntax unless raw (`r"""`)
- Support escape sequences (like `\n`, `\t`) unless raw
- Comments can follow the opening `"""` on the same line
- Cannot have content on the same line as the opening `"""`

### Raw Strings

```rad
// Raw strings: no interpolation, no escape processing
regex = r"\d{2}:\d{2}"            // stays literally \d{2}:\d{2}
win_path = r"C:\Users\notes.txt"
single = r'single quotes work'
ticks = r`backticks too`
```

**Raw String Rules:**
- Prefix any string delimiter with `r`: `r"..."`, `r'...'`, `` r`...` ``, or multi-line `r"""..."""`
- Contents are taken literally: no `{interpolation}` and no escape sequences
- Handy for regexes, Windows paths, and text full of braces

## Variables and Assignment

### Basic Assignment

```rad
name = "alice"
age = 25
```

### Multiple Assignment

```rad
a, b = 1, 2
x, y = some_function_returning_tuple()
```

### Compound Assignment

```rad
count = 5
count += 1              // count = 6
count -= 2              // count = 4
count *= 3              // count = 12
count /= 4              // count = 3
```

### Increment/Decrement

```rad
i = 0
i++                     // i = 1
i--                     // i = 0
```

## String Interpolation

```rad
name = "alice"
age = 25
message = "Hello {name}, you are {age} years old!"

// Works with expressions
total = "Result: {x + y}"

// Format specifiers
price = 123.456
formatted = "Price: {price:.2}"          // "Price: 123.46" (2 decimal places)
padded = "Name: {name:<10}"              // "Name: alice     " (left-aligned, padded to 10)
right_aligned = "Name: {name:>10}"       // "Name:      alice" (right-aligned)

// Thousands separators (numbers only)
big_num = 1234567
formatted = "{big_num:,}"                // "1,234,567"
with_decimals = "{big_num:,.2}"          // "1,234,567.00"
padded_thousands = "{big_num:>15,}"      // "      1,234,567"
```

### Braces in Strings

A `{` opens an interpolation. Rad never silently re-reads a broken
interpolation as ordinary text, so a brace you meant literally either
falls under one of the narrow exemptions below or has to be escaped.

1. `{expr}`, optionally with a format specifier, interpolates.
2. A `{` is literal where an interpolation is impossible: the string ends
   immediately after it, or the `{...}` pair holds only ASCII spaces or tabs.
   Other Unicode whitespace does not count - `{` followed by U+00A0 is an
   error, not a literal brace.
3. A `}` with no interpolation open is literal.
4. `\{` and `\}` are literal braces. A raw string (`r"..."`) disables
   interpolation and escapes for the whole string.
5. Anything else that opens like an interpolation and isn't one is an
   error.

```rad
print("{")             // {        -- string ends after the brace
print("{}")            // {}       -- pair holds nothing
print("{ }")           // { }      -- pair holds only whitespace
print("}")             // }        -- no interpolation open
print("\{a\}")         // {a}      -- both escapes
print(r"\d{4}")        // \d{4}    -- raw string, nothing interpolates
```

The rule that catches people is the regex quantifier. `"\d{4}"` is a valid
interpolation of the number 4, so it produces `\d4`:

```rad
pattern = "\d\{4}"     // \d{4}   -- escape the brace
pattern = r"\d{4}"     // \d{4}   -- or use a raw string
```

Rad warns (`RAD40017`) when an interpolation holds a literal, since that is
almost always this mistake.

Exemption 2 is deliberately narrow. `"{name"` stays an error rather than
printing itself, because a forgotten closing brace should be loud.

An interpolation must not open with a same-delimiter string, since `"{"` is
then indistinguishable from a literal brace at the end of a string. Reach
for a different quote type:

```rad
print("{'ERROR'.red()}")     // use a different delimiter
print("{ "ERROR".red() }")   // or separate the braces from the quotes
print("{"ERROR".red()}")     // error - reads as the literal brace "{"
```

## Ternary Operator

```rad
// Basic ternary syntax
result = condition ? value_if_true : value_if_false

// Examples
status = age >= 18 ? "adult" : "minor"
message = count == 1 ? "1 item" : "{count} items"
max_value = a > b ? a : b

// Can be chained
category = age < 13 ? "child" : age < 18 ? "teen" : "adult"
```

## Collection Access and Slicing

### Indexing

```rad
items = [10, 20, 30, 40, 50]
first = items[0]        // 10
last = items[-1]        // 50

person = {"name": "alice", "age": 25}
name = person["name"]   // "alice"

// Fallback for out-of-bounds or missing keys with ??
value = items[100] ?? "not found"       // "not found" (index out of bounds)
role = person["role"] ?? "guest"        // "guest" (key not found)
char = "hello"[99] ?? "?"               // "?" (string index out of bounds)
```

### Slicing

```rad
items = [10, 20, 30, 40, 50]
subset = items[1:3]     // [20, 30]
from_start = items[:3]  // [10, 20, 30]
to_end = items[2:]      // [30, 40, 50]
all_items = items[:]    // [10, 20, 30, 40, 50]

// Negative indices
end_items = items[-2:]  // [40, 50]
```

### String Slicing

```rad
text = "hello"
substring = text[1:4]   // "ell"
```

## Control Flow

### If Statements

```rad
if age >= 18:
    print("Adult")
else if age >= 13:
    print("Teen")
else:
    print("Child")

// Single condition
if is_valid:
    process_data()
```

### Switch Statements

```rad
// Expression switches (single values)
result = switch value:
    case "a" -> "Apple"
    case "b" -> "Banana"
    default -> "Unknown"

// Multiple cases
status = switch code:
    case 200, 201, 204 -> "Success"
    case 400, 401, 403 -> "Client Error"
    case 500, 502, 503 -> "Server Error"
    default -> "Unknown"

// Multi-assignment from switch
a, b = switch condition:
    case true -> 10, 20
    case false -> 30, 40

// Block switches (multiple statements)
switch value:
    case "a":
        print("Found A!")
        do_something()
    case "b", "c":
        print("Found B or C!")
        do_something_else()
    default:
        print("Unknown value")

// Mixed syntax in same switch with yield
result = switch value:
    case 1:
        complex_processing()
        yield calculated_result    // Return value from case block
    case 2 -> simple_result
    default -> fallback_value

// Yield multiple values
a, b = switch condition:
    case "pair":
        calculate_values()
        yield first_result, second_result
    case "single" -> default_value, 0
```

### Loops

#### For Loops

```rad
// Iterate over list
items = ["a", "b", "c"]
for item in items:
    print(item)

// Access loop index and total via context
for item in items with loop:
    print("{loop.idx + 1}/{loop.src.len()}: {item}")

// Iterate with unpacking (for lists of lists)
data = [["alice", 25], ["bob", 30], ["charlie", 35]]
for name, age in data:
    print(name, age)

// Unpacking WITH context
for name, age in data with loop:
    print(loop.idx, name, age)

// Multiple variable unpacking with zip
names = ["alice", "bob", "charlie"]
ages = [25, 30, 35]
cities = ["NYC", "LA", "Chicago"]
for name, age, city in zip(names, ages, cities):
    print(name, age, city)

// With context
for name, age, city in zip(names, ages, cities) with loop:
    print(loop.idx, name, age, city)

// Iterate over map keys
person = {"name": "alice", "age": 25}
for key in person:
    print(key, person[key])

// Map iteration with context
for key in person with loop:
    print(loop.idx, key, person[key])

// Map with key and value
for key, value in person:
    print(key, value)

// Map with key, value, and context
for key, value in person with loop:
    print(loop.idx, key, value)

// Range iteration
for i in range(5):      // 0, 1, 2, 3, 4
    print(i)
```

**Loop Context Object**

When you use `with <identifier>` in a for-loop, you get access to a context object with these fields:

- `idx` - Current iteration index (0-based)
- `src` - Immutable snapshot of the original collection

```rad
items = [10, 20, 30]
for item in items with loop:
    print("Index: {loop.idx}, Item: {item}, Total: {loop.src.len()}")
```

#### While Loops

```rad
// Basic while loop
count = 0
while count < 5:
    print(count)
    count++

// Infinite loop with break
while:
    if condition:
        break
    // do something

// Continue statement
while condition:
    if skip_condition:
        continue
    process_item()
```

## Additional Control Flow

### Delete Statement

```rad
// Delete variables or data structures
my_var = "test"
del my_var              // Remove variable from scope

my_list = [1, 2, 3, 4]
del my_list[0]         // Remove first element

my_map = {"a": 1, "b": 2}
del my_map["a"]        // Remove key "a"
```

### Return Statement

```rad
fn calculate(x, y):
    if x < 0:
        return error("negative values not allowed")
    result = x * y
    return result      // Return single value

fn get_coordinates():
    x = 10
    y = 20
    return x, y        // Return multiple values

fn early_exit():
    if condition:
        return         // Early return with no value
    do_more_work()
```

### Yield Statement

```rad
// Yield can only be used in switch case blocks to return values
// (Examples shown in Switch Statements section above)

// NOT valid - yield cannot be used in regular functions
// fn generate_values():
//     yield i        // This would be an error
```

## Functions

### Function Definition

```rad
// Function definitions use fn name(): syntax
fn double(x):
    return x * 2

fn add(a, b):
    return a + b

fn greet():
    print("Hello!")

// Block functions
fn calculate(x, y):
    result = x * y + 10
    return result

// Function with multiple return values
fn coords(point):
    x = point["x"]
    y = point["y"]
    return x, y

// Anonymous functions can be assigned to variables
double_var = fn(x) x * 2
add_var = fn(a, b) a + b
greet_var = fn() print("Hello!")
```

### Function Calls

```rad
result = double(5)      // 10
sum_val = add(3, 4)     // 7

// UFCS (Uniform Function Call Syntax)
"hello".upper()         // "HELLO"
[1, 2, 3].len()        // 3

// You're encouraged to use UFCS, especially to un-nest function calls.
upper(trim(text))    // BAD
text.trim().upper()  // GOOD

// Built-in function assignment to variables
my_upper = upper
"test".my_upper()      // "TEST"
```

### Named Arguments

```rad
print("hello", "world", sep="|")    // hello|world
```

## List Comprehensions

```rad
// Basic comprehension
numbers = [1, 2, 3, 4, 5]
squares = [x * x for x in numbers]

// With function calls
words = ["hello", "world"]
uppers = [upper(word) for word in words]

// Side effects (returns empty list)
[print(x) for x in items]
```

## Argument Parsing

### Basic Arguments

```rad
args:
    name str                    # Required string
    age int                     # Required integer
    height float               # Required float
    verbose bool               # Required boolean

    // Optional arguments
    role str?                  # Optional string (null if not provided)
    count int = 10            # Optional with default
    debug d bool              # Short form flag
```

### Int Short Clustering

Int arguments with short forms can be "clustered" to increment the value:

```rad
args:
    verbosity v int
```

```bash
./script -v        # verbosity = 1
./script -vv       # verbosity = 2
./script -vvvvv    # verbosity = 5
./script -vv -v=10 # verbosity = 10 (explicit value overrides)
```

This is useful for verbosity levels and similar patterns where users want quick increment syntax.

### Argument Constraints

```rad
args:
    status str
    age int
    email str
    username str?
    password str?
    
    status enum ["active", "inactive", "pending"]
    age range [0, 120]        // Inclusive range
    age range (0, 120]        // Exclusive start, inclusive end
    email regex ".*@.*\\..*"
    username requires password   // If username provided, password required
```

Relational constraints:
- `a requires b`
- `a mutually requires b`
- `a excludes b`
- `a mutually excludes b`

## Script Commands

Organize CLI tools around subcommands, like `git commit` or `docker build`. The `args:` and `command` blocks must appear before any executable code.

```rad
#!/usr/bin/env rad
---
A deployment tool.
---

// Shared args available to all commands
args:
    verbose v bool
    config str = "config.yaml"

command deploy:
    ---
    Deploy the application.
    ---
    env str
    calls do_deploy

command status:
    ---
    Check deployment status.
    ---
    env str
    calls do_status

// Shared setup - runs before any command callback
validate_config(config)

fn do_deploy():
    if verbose:
        print("Config: {config}")
    print("Deploying to {env}...")

fn do_status():
    print("Status of {env}...")
```

Usage: `./tool.rad deploy staging --verbose`

### Command Name Hyphenation

Command names follow the same underscore-to-hyphen convention as arguments. Define with underscores, invoke with hyphens:

```rad
command deploy_staging:
    calls do_deploy_staging

// Invoked as: ./tool.rad deploy-staging
```

### Inline Callbacks

```rad
// Short implementations can use inline lambdas
command greet:
    name str
    calls fn():
        print("Hello, {name}!")
```

### Nested Commands

Group related commands under a namespace, like `git remote add`. A command that
contains other commands is a *namespace*: it has no `calls` of its own and routes
to its sub-commands instead. Args declared on it are shared - inherited by every
descendant, and accepted anywhere on the path.

```rad
command remote:
    ---
    Manage remotes.
    ---
    timeout int = 30        // shared with every sub-command

    command add:
        name str
        url str
        calls do_add

    command remove:
        name str
        calls do_remove

fn do_add():
    print("Adding {name} -> {url} (timeout {timeout})")

fn do_remove():
    print("Removing {name}")
```

`./tool.rad remote add origin https://... --timeout 5` runs `do_add`, and
`--timeout` is equally valid before the sub-command. Namespaces nest as deep as
you like; only the terminal command's `calls` runs.

### Default Commands

Mark one command per level `default` and it runs when the user names none, so a
tool's primary action doesn't have to be typed:

```rad
command add:
    ---
    Add a reminder.
    ---
    *tokens str
    default
    calls do_add

command list:
    ---
    Show upcoming reminders.
    ---
    calls do_list

fn do_add():
    print("Adding {tokens}")

fn do_list():
    print("Listing")
```

`./tool.rad 15m standup` and `./tool.rad add 15m standup` both run `do_add`.

A named command always wins, so a value that happens to match one goes to that
command instead. Two ways to say you meant the value: name the default
explicitly, or use `--`.

```
./tool.rad list            # runs do_list
./tool.rad add list        # adds a reminder saying "list"
./tool.rad -- list         # same
```

The rule applies at every level, so a namespace's default is what `./tool.rad
remote` runs. Only leaf commands can be marked - a namespace routes rather than
runs, so marking one would leave the question unanswered.

### Automatic Help

- `./tool.rad -h` — lists all commands with descriptions
- `./tool.rad deploy -h` — shows command-specific arguments
- `./tool.rad remote -h` — lists a namespace's sub-commands and shared args

When a default exists, `-h` marks it and shows a second usage line spelling out
the shorter invocation it enables.

## Shell Commands

### Invocation (`$`) — critical by default

Shell commands can be invoked with `$` and are *critical by default*: if the exit `code != 0`, an error will propagate unless you handle it.
If an error propagates up to the root level of the script and doesn't get handled, it exits.

> **Note on signals:** Rad shares its process group with subprocesses, so
> Ctrl+C reaches them too. The subprocess typically dies before Rad's signal
> handler runs. See Signal Handling for details.

```rad
// Fails script if code != 0
$`make build`
stdout = $`cmd`
stdout, stderr = $`cmd`
stdout, stderr, code = $`cmd`
```

`$` takes the command and nothing more: a command literal, a list, a variable
holding a command string, or a parenthesized expression. Anything written *after*
it reads the command's result (see Reading one result inline),
so a computed command goes in parentheses:

```rad
cmds = [`ls -la`, `ls -l`]
parts = ["git", "status"]

$(cmds[1])
$(parts.join(" "))
```

### Capture & assignment

**Capture behavior** depends on how many variables you assign. A stream you don't
capture goes to the terminal; a stream you do capture goes only to your variable.

```rad
$`cmd`                        // No capture, stdout/stderr → terminal
stdout = $`cmd`               // Capture stdout, stderr → terminal
stdout, stderr = $`cmd`       // Capture both
stdout, stderr, code = $`cmd` // Capture both, plus the exit code
```

**Assignment semantics** support both positional and *named* assignment.

- Positional targets are filled **(stdout, stderr, code)** in that order. The exit
  code is last: it needs no capturing, and a non-zero exit already raises a
  catchable error, so it's the value you reach for least.
- **Positional (default):** when variable names are arbitrary, assignment is by position.

```rad
out = $`cmd`                        // out = stdout
out, err = $`cmd`                   // out = stdout, err = stderr
result, errors, status = $`cmd`     // result = stdout, errors = stderr, status = code
```

- **Named:** if **all** variables are exactly `code`, `stdout`, or `stderr`, assignment is by name (order independent).

```rad
stdout, code = $`cmd`     // stdout = stdout, code = code
stderr = $`cmd`           // only capture stderr
code, stderr = $`cmd`     // capture code and stderr
code = $`cmd`             // only way to get the code without capturing a stream
```

> **Rule:** If *all* variables use the exact names `code`, `stdout`, or `stderr`, uses named assignment. Otherwise, assignment is positional.

The two rules agree on the canonical order, so `stdout = $cmd` and
`stdout, stderr = $cmd` mean the same thing read either way. They disagree when
you *mix* reserved and unreserved names, because one unreserved name makes the
whole statement positional:

```rad
code, output = $`cmd`     // 'code' gets stdout! Warns: RAD40018
```

### Reading one result inline

A shell command can be used as an expression when it's immediately followed by
one of four accessors: `.stdout`, `.stderr`, `.code`, or `.ok`.

```rad
branch = $`git branch --show-current`.stdout.trim() catch "unknown"

if $`git status --porcelain`.stdout.trim():
    print_err("Uncommitted changes!")

if not $`which docker`.ok:
    exit(1)
```

| Accessor  | Type   | Fails on non-zero exit |
| --------- | ------ | ---------------------- |
| `.stdout` | `str`  | yes                    |
| `.stderr` | `str`  | yes                    |
| `.code`   | `int`  | no                     |
| `.ok`     | `bool` | no                     |

**Capture follows the accessor**, exactly as it follows target names in a named
assignment: `.stdout` captures stdout and lets stderr through to the terminal,
`.stderr` the reverse, and the two status accessors capture nothing.

**The output accessors fail, the status accessors don't.** `.stdout` and
`.stderr` propagate a non-zero exit and compose with `??`, `catch` and `catch:`.
`.code` and `.ok` never propagate - using them *is* handling the failure, which
is what makes them the right way to test a command. Note this differs from
statement-form `code = $cmd`, which still propagates.

**There is no truthiness.** A command with no accessor is a check-time error
(`RAD40025`), because shell's `if cmd` (exit code) and `if $(cmd)` (printed
anything) are different questions that look alike.

**One value inline.** The expression form never gives you both streams from one
run; use assignment when you need more than one.

`quiet` and `confirm` work here too, and the ⚡️ echo stays on - under `and` /
`or` short-circuit it shows which commands actually ran.

```rad
tag = quiet $`git describe --tags`.stdout.trim() catch "untagged"
```

### Handling failures with a `catch` block

Use a suffix `catch:` block to handle non‑zero exit codes. Variables are already assigned to the actual results inside the block; you may log or reassign fallbacks, then execution continues.

```rad
code, stdout = $`grep hello file` catch:
    // Runs because code != 0
    print_err("grep failed with code {code}: {stdout}")
    stdout = ""  // example fallback
```

You can also attach `catch:` without capturing any variables:

```rad
$`make build` catch:
    pass  // continue on failure (do nothing)

$`make build` catch:
    print_err("Build failed")
    exit(1)
```

### Shell Command Modifiers

Two modifiers control shell command behavior:

```rad
// quiet - suppresses the ⚡️ command echo
quiet $`make build`
code, stdout = quiet $`grep pattern file` catch:
    stdout = ""

// confirm - prompts user approval before running (useful for destructive ops)
confirm $`rm -rf node_modules`
```

Modifiers go after `=` in assignments: `result = quiet $`cmd``, not `quiet result = $`cmd``.

## JSON Processing and Display Blocks

### JSON Path Definitions

```rad
// Define JSON field mappings
Name = json.results[].name
Email = json.results[].email
Age = json.results[].age

// JSON path with wildcards
AllFields = json.results[].*         // All fields in each result
DeepFields = json.data.*.value       // Wildcard in path
Indexed = json.items[0].name         // Specific index
```

### Rad Blocks

```rad
// Rad blocks do HTTP request + JSON extraction + print table (all-in-one)
url = "https://api.example.com/users"
Name = json.results[].name
Email = json.results[].email

rad url:
    fields Name, Email
    sort Name
    // Automatically prints formatted table after extraction
```

### Rad Blocks Without URL Source

```rad
// Rad block with no source: assumes lists are already populated, prints as table
names = ["alice", "bob", "charlie"]
ages = [25, 30, 35]

rad:
    fields names, ages
    sort ages desc, names

// Rad block with list/map source: runs JSON extraction + prints table
data = [
    {"name": "alice", "age": 25},
    {"name": "bob", "age": 30}
]

Name = json[].name
Age = json[].age
rad data:
    fields Name, Age
    sort Age desc, Name
```

### Field Modifiers

Field modifiers transform or filter data before display. Apply them to specific fields:

```rad
ages = [15, 25, 30, 12]
names = ["Alice", "Bob", "Charlie", "David"]

rad:
    fields ages, names
    ages:
        filter fn(a) a >= 18       // Keep only adults
        map fn(a) "{a} years"      // Transform display

// Output:
// ages       names
// 25 years   Bob
// 30 years   Charlie
```

**Filter** removes rows where the predicate returns false. **Map** transforms values for display. Filter runs before map.

```rad
// Apply same modifier to multiple fields
ages, scores:
    map fn(v) "{v}!"

// Use a named function
is_adult = fn(age) age >= 18
ages:
    filter is_adult
```

### Field Modifier Context

When a map or filter lambda accepts **two parameters**, the second receives a context object:

```rad
nums = [10, 20, 30]
rad:
    fields nums
    nums:
        map fn(x, ctx) "{ctx.idx + 1}. {x}"
        // Output: "1. 10", "2. 20", "3. 30"
```

**Context fields:**

| Field   | Type   | Description                                |
| ------- | ------ | ------------------------------------------ |
| `idx`   | `int`  | Current row index (0-based)                |
| `src`   | `list` | Immutable snapshot of the full column data |
| `field` | `str`  | Name of the field being processed          |

```rad
// Filter to values below average
nums:
    filter fn(x, ctx) x < sum(ctx.src) / ctx.src.len()

// Show position in total
nums:
    map fn(x, ctx) "{x} ({ctx.idx + 1}/{ctx.src.len()})"
```

Single-parameter lambdas continue to work unchanged for simple transformations.

## Advanced Features

### String Escape Sequences

```rad
// Supported escape sequences in strings
text = "Quote: \"Hello\""          // Escaped double quote
single = 'It\'s working'           // Escaped single quote  
backtick = `Backtick: \`command\`` // Escaped backtick
newline = "Line 1\nLine 2"         // Newline
tab = "Column1\tColumn2"           // Tab
backslash = "Path\\to\\file"       // Literal backslash
brace = "Not interpolated: \{var}" // Escaped brace (literal {)
close = "Escaped: \}"              // Escaped brace (literal })
```

### Defer and Error Defer Blocks

```rad
// Defer block - runs before script ends regardless of success/failure
defer:
    print("This always runs before script exits")
    cleanup_resources()

// Error defer block - only runs before script ends if an error occurs
errdefer:
    print("This only runs if script exits with error")
    emergency_cleanup()

process_data()
// More code can run here
exit(0)  // defer blocks run just before this
```

**Defer and signals:** SIGINT (Ctrl+C) and SIGTERM are intercepted by Rad
and routed through the normal exit path with code `128 + signal_number`.
This means `defer` blocks run on Ctrl+C, and `errdefer` blocks run because
the exit code is non-zero. Scripts that allocate temp files or write
half-output get a chance to clean up. See Signal Handling
below for custom handlers beyond auto-defer.

### Signal Handling

Scripts can register handlers for OS signals using `signal_trap`, and ignore
signals at the OS level using `signal_ignore`. See the function reference
for full details.

```rad
fn cleanup():
    print_err("removing temp files")

// Clean up on Ctrl+C
signal_trap("sigint", fn(ctx):
    print_err("Cancelled")
    cleanup()
    exit(ctx.exit_code)
)

// Don't crash when a downstream pipe consumer closes
signal_ignore("sigpipe")

// Long-running loop that responds to SIGUSR1 for status dumps
n = 0
total = 100
signal_trap("sigusr1", fn(ctx):
    print("progress: {n}/{total}")  // no exit() - script continues
)
```

**Semantics worth knowing:**

- **Handlers run between statements**, not mid-statement. A signal arriving
  while a long computation is running waits for the current statement to
  finish before the handler fires.
- **After a handler returns, execution continues.** To terminate, the
  handler must explicitly call `exit()`. This matches Bash, Python, Ruby,
  and Node.
- **An unhandled error in a handler aborts the script** (exit 1), running
  `defer`/`errdefer` along the way - the same as an unhandled error anywhere
  else. Only a clean return continues execution.
- **`defer` runs on signal-triggered exit** (whether by default behavior or
  by the handler calling `exit()`).
- **A second SIGINT during a SIGINT handler force-exits** with code 130.
  Defer blocks do not run on this force-exit path - it's the escape hatch
  when a handler hangs.
- **Subprocesses started with `$\`cmd\`` share Rad's process group**, so
  Ctrl+C reaches both Rad and the subprocess. The Rad handler runs after
  the subprocess has already terminated. This is the same behavior as Bash.
- On **Windows**, only `sigint` and `sigterm` are supported.

### Rad Block Options

```rad
// noprint: run JSON extraction but don't print table
url = "https://api.example.com/users"
Name = json.results[].name
Email = json.results[].email

rad url:
    noprint
    fields Name, Email
    sort Name

// After this block, Name and Email contain the extracted data
print(Name)  // ["alice", "bob", "charlie"]
print(Email) // ["alice@example.com", "bob@example.com", "charlie@example.com"]

// quiet: suppress "Querying url: ..." stderr log
rad url:
    quiet
    fields Name, Email

// transpose: swap rows and columns - fields become rows, records become columns
Name = ["Alice", "Bob", "Charlie"]
Age = [30, 40, 25]
rad:
    fields Name, Age
    transpose
// Output:
//   Name  Alice  Bob  Charlie
//   Age   30     40   25

// All three options accept an explicit boolean expression:
//   noprint true / quiet false / transpose some_variable
// And can appear inside `if` blocks for conditional behavior.
```

### Advanced Function Features

```rad
// Vararg parameters
fn sum_all(*numbers: int):
    total = 0
    for num in numbers:
        total += num
    return total

result = sum_all(1, 2, 3, 4, 5)

// Named-only parameters (after *)
fn format_text(text: str, *, uppercase: bool = false, prefix: str = ""):
    result = prefix + text
    return uppercase ? upper(result) : result

formatted = format_text("hello", uppercase=true, prefix=">>> ")

// Function-typed parameters and union returns
fn process_data(
    input: str[],
    callback: fn(str) -> bool
) -> int|error:
    matched = 0
    for s in input:
        if callback(s):
            matched += 1
    return matched

fn is_long(s: str) -> bool:
    return s.len() > 5

count = process_data(["a", "bb", "ccccc", "dddddd"], is_long)
```

### Map Dot Syntax

```rad
person = {"name": "alice", "details": {"age": 25}}
name = person.name              // Same as person["name"]
age = person.details.age        // Nested access
```

### Error Handling

Errors in Rad are **values**. Functions typically return `value | error`. By default, errors **propagate** and exit if unhandled.

#### Simple fallback: `??`

Use `??` to provide a fallback value when the left side returns an error (right side is evaluated lazily).

```rad
result = text.parse_int() ?? 0
result = text.parse_int() ?? compute_fallback()
// Multi-return requires an explicit list fallback
a, b = fallible_pair() ?? [0, 0]
```

#### Complex handling: suffix `catch:`
Attach a `catch:` block to inspect the error (the assigned variable *is* the error string inside the block), log, and/or reassign a fallback. Execution continues after the block, unless it invokes `exit()`.

```rad
value = text.parse_int() catch:
    print_err("Parse failed: {value}")
    value = 0
```

For multi-return functions with `catch:`:

```rad
a, b = fallible_pair() catch:
    // a = error string, b = null
    print_err("Failed: {a}")
    a, b = 0, 0
```

#### Held errors stay live

A `catch:` block that doesn't reassign leaves the error in the variable. Rad doesn't
track that it was handled, so returning it from another function raises it again, at
that call:

```rad
fn fail() -> str|error:
    return error("boom")

fn relay(x):
    return x

stored = fail() catch:
    pass

relay(stored)               // exits
relay(stored) ?? "default"  // "default"
```

Assigning the value elsewhere and reading it are safe; only a call that returns it raises
it. `??` and `catch` inspect the value the left side produced, so they fire on a held
error too; a `catch:` block catches a failing operation, so it does not.

## Operators

### Arithmetic

```rad
a + b       // Addition
a - b       // Subtraction
a * b       // Multiplication
a / b       // Division
a % b       // Modulo
```

### Comparison

```rad
a == b      // Equal
a != b      // Not equal
a < b       // Less than
a <= b      // Less than or equal
a > b       // Greater than
a >= b      // Greater than or equal
```

### Logical

```rad
a and b     // Logical AND
a or b      // Logical OR
not a       // Logical NOT
```

### Membership

```rad
item in collection      // Check if item exists in collection
item not in collection  // Check if item doesn't exist
```

For maps, `in`/`not in` test **key** membership, not values:

```rad
scores = {"alice": 1}
has_alice = "alice" in scores   // true - "alice" is a key
has_one = 1 in scores           // false - values aren't checked
```

### Coalescing Operator (`??`)

The `??` operator yields the left value if it is **not null or an error**; otherwise it evaluates and yields the right-hand side. Useful for concise fallbacks when calling fallible functions or handling nullable values.

```rad
count = get_env("COUNT").parse_int() ?? 0
data = read_file("config.txt") ?? {"content": ""}
a, b = some_fallible_fn() ?? [0, 0]  // multi-return requires list fallback
```

### Error Catching Operator (`catch`)

The `catch` operator catches errors from the left side and returns the right side instead. Unlike `??`, it only catches errors - `null` values pass through.

```rad
count = parse_int(input_str) catch 0
data = parse_json(raw) catch {}
result = risky_call() catch fallback_call() catch "final"
```

`catch` is distinct from the `catch:` block syntax. The operator form is an inline expression, while `catch:` is a block attached to statements.

## Scoping and Variables

```rad
// Global scope
global_var = "global"

if true:
    // Can access global variables
    print(global_var)
    
    // Variables defined in blocks persist after the block
    block_var = "accessible"

// block_var IS accessible here
print(block_var)  // Works fine

// Variables defined in for loops also persist
for i in range(3):
    loop_var = "also accessible"

print(i)          // Last value: 2
print(loop_var)   // "also accessible"

// Function closures with anonymous functions assigned to variables
outer_var = 10
fn_with_closure = fn(x):
    return x + outer_var    // Can access outer_var
```

## Built-in Types and Methods

For a complete reference of all built-in functions, see: https://amterp.dev/rad/reference/functions/

### String Methods

```rad
text = "hello world"
text.upper()            // "HELLO WORLD"
text.lower()            // "hello world" 
text.split(" ")         // ["hello", "world"]
text.replace("hello", "hi")  // "hi world"
```

### List Methods

```rad
items = [3, 1, 4, 1, 5]
items.len()             // 5
items.sort()            // Returns sorted copy
items.reverse()         // Returns reversed copy
```

### Type Checking

```rad
// Runtime type checking happens automatically
// Type errors will be caught during execution
```

## Type System

Rad has a dynamic type system with runtime type checking. Here are the type annotations used in function signatures and documentation:

### Basic Types

```rad
str           // String type
int           // Integer type  
float         // Float type
bool          // Boolean type
any           // Any type (dynamic)
void          // No return value
error         // Error type
```

### Collection Types

```rad
list          // List of any type
str[]         // List of strings
int[]         // List of integers
any[]         // List of any type
map           // Map/object with any keys/values
{str: int}    // Map with specific key/value types
```

The `T[]` suffix is the only way to write a typed list. There's no
`list[T]` form; one canonical spelling keeps things simple.

### Optional Types

```rad
str?          // Optional string (can be null)
any?          // Optional any type
int?          // Optional integer
```

### Union Types

```rad
int|float     // Either int or float
str|list      // Either string or list
error|str     // Either error or string (common for fallible operations)
```

### Parenthesized Type Groups

Parentheses group a union so list / optional modifiers stack on
top of the whole group rather than just the rightmost arm:

```rad
(int|str)[]      // List whose elements are int or str
(int|str)?       // Optional value that's int or str
((int|str)|bool)[]?  // Combinations compose freely
```

Without the parens, `int|str[]` parses as `int | (str[])` - an int
or a list of strings, not a list of (int|str).

### Enum Types

```rad
["option1", "option2"]        // Enum with specific string values
["auto", "seconds", "millis"] // Enum for time units
```

### Function Types

```rad
fn(any) -> any                     // Function taking any, returning any
fn(any, any) -> bool               // Function taking two any params, returning bool
fn() -> any                        // Function with no params, returning any
```

### Complex Return Types

```rad
// Map with specific structure
{ "exists": bool, "size"?: int }

// Map with optional fields (? suffix)
{ "content": str, "created"?: bool }

// Nested structures
{ "epoch": { "seconds": int, "millis": int } }
```

### Variadic Parameters

```rad
*_items: any          // Variable number of any type
*_others: list|str    // Variable number of lists or strings
```

### Named Parameters

```rad
// Required named parameter
func(*, required_param: str)

// Optional named parameter with default
func(*, optional_param: str = "default")

// Mixed positional and named
func(_pos: str, *, named: int = 5)
```

### Parameter Constraints

```rad
// Parameter with underscore prefix (positional-only)
_path: str

// Named parameter (after *)
sep: str = " "

// Optional with default value
end: str = "\n"
```

### Real Examples from Built-ins

```rad
print(*_items: any, *, sep: str = " ", end: str = "\n") -> void
range(_arg1: float|int, _arg2: float?|int?, _step: float|int = 1) -> list[float|int] 
zip(*_lists: list, *, fill: any?, strict: bool = false) -> error|list[]
read_file(_path: str, *, mode: ["text", "bytes"] = "text") -> error|{ "size_bytes": int, "content": str|[int] }
```

## Rad Code Style

### Argument Block Formatting

```rad
// Good: Group args together, then constraints with empty line separation
args:
    name str           # Required string argument
    count int = 5      # Optional with default
    verbose v bool     # Boolean flag with short form
    email str?         # Optional argument
    
    name regex "^[a-zA-Z]+$"
    count range [1, 100]
    email requires verbose
```

### Comment Alignment

As a convention, align comments 2 spaces from the longest argument in the aligned group.

Good - align comments within reason (2 spaces from longest):

```rad
args:
    name str        # User's full name
    age int         # Age in years
    email str?      # Contact email
    very_long_param str  # Don't align with this one if it's much longer
    city str        # Align with the shorter ones instead
```

Bad - inconsistent alignment:

```rad
args:
    name str      # User's full name
    age int            # Age in years
    email str?  # Contact email
```

### Shell Command Delimiters

```rad
// Good: Prefer backticks to avoid delimiter conflicts
result = $`echo "Hello world"`
output = $`grep 'pattern' file.txt`
status = $`curl -H "Content-Type: application/json" api.example.com`

// Avoid: Quotes can conflict with shell command content
// result = $"echo "Hello world""  // This breaks
```

### Variable Naming

```rad
// Good: Use snake_case for variables
user_name = "alice"
max_retry_count = 3
is_valid = true

// Good: Common abbreviations are fine for CLI scripting
msg = "Hello world"
req = http_get(url)
cfg = load_config()
args = get_args()

// Good: Use descriptive names when clarity matters
user_data = load_user_info()
processed_items = filter(items, is_active)

// Avoid: Unclear single letters and confusing abbreviations
x = load_user_info()  // Too generic
a, b = 1, 2          // Meaningless names
usr_nm = "alice"     // Unclear abbreviation
```

### Function Definition Style

```rad
// Good: Clear, descriptive function names
fn calculate_tax(amount, rate):
    return amount * rate

fn validate_email(email):
    return "@" in email and "." in email

// Good: Anonymous functions for simple operations (note lack of colon)
double = fn(x) x * 2
is_even = fn(n) n % 2 == 0
```

### Control Flow Formatting

```rad
// Good: Consistent indentation and spacing
if user.is_admin:
    print("Admin access granted")
    log_admin_action(user.name)
else if user.is_moderator:
    print("Moderator access granted")
else:
    print("Regular user access")

// Good: Switch formatting
result = switch status:
    case "active" -> "Running"
    case "paused" -> "Waiting" 
    case "stopped" -> "Inactive"
    default -> "Unknown"
```

### Collection and Data Structure Style

```rad
// Good: Readable list formatting with trailing commas
users = [
    {"name": "alice", "role": "admin"},
    {"name": "bob", "role": "user"},
    {"name": "charlie", "role": "moderator"},
]

// Good: Multiline maps with trailing commas
config = {
    "host": "localhost",
    "port": 8080,
    "debug": true,
}

// Good: Simple lists on one line when short
colors = ["red", "green", "blue"]
numbers = [1, 2, 3, 4, 5]

// Good: Clear JSON path definitions
UserName = json.users[].name
UserEmail = json.users[].email  
UserRole = json.users[].role
```

### String Interpolation Style

```rad
// Good: Clear variable interpolation
message = "Hello {user_name}, you have {message_count} messages"
file_path = "{base_dir}/{filename}.txt"

// Good: Format specifiers for numbers
price = "Total: ${amount:.2}"
percentage = "Progress: {progress:.1}%"
```

### Error Handling Style

```rad
// Good: Clear handling with suffix catch:
user_data = load_user(user_id) catch:
    print_err("Failed to load user data: {user_id}")
    exit(1)

// Good: Simple fallback with ?? (right side evaluated lazily)
backup_data = load_backup() ?? {"version": "none"}

// Good: Multi-return fallback with ?? list
a, b = risky_pair() ?? [0, 0]

// Good: Shell command handling with catch
code, stdout = $`potentially_failing_command` catch:
    print_err("Command failed with code {code}")
    stdout = ""
```

---

# Functions

This page aims to concisely document *all* in-built Rad functions.

## How to Read This Document

### Function Signatures

You'll see notation like this for function signatures (below are not real functions in Rad; just examples):

```
greet(name: str, times: int = 10) -> string
```

This means the function `greet` takes one required string argument `name`, and an optional int argument `times` which
defaults to 10 if not specified. It returns a string.

```
greet_many(names: list[string] | ...string) -> none
```

This means that `greet_many` can be called in two ways: either with a single argument that is a list of strings, or `|`
a variable number of string arguments.
In both cases, the function returns nothing.

```
do_something(input: any, log: string?) -> any, error?!
```

This means the function `do_something` takes a required argument `input` which can be of *any* type.
It also has an optional argument `log` which will default to `null` if left unspecified.

The values it returns depends on how the function is called. If it's being assigned to two variables e.g.

```
foo, bar = do_something(myvar)
```

then it will return some `any` value for `foo`, and it returns a nullable `error` for `bar`.

The exclamation point `!` signifies that, if the call is only assigned to one variable e.g.

```
foo = do_something(myvar)
```

and the function *fails* i.e. *would* return a non-`null` `error` value, then it will instead panic and exit the script
with said error.

### `error`

`error` may be referenced as a return type for some functions. `error` is really a `map` with the following keys:

- `code: string` - An error code (e.g. `RAD20003`). Use `rad docs <code>` to learn more.
- `msg: string` - A description of the error.

Lastly, you may also see `number` referenced as a type -- this just means `int | float`, i.e. any numeric type.

---

## Crypto

### decode_base16

Decodes Base16 (hexadecimal) text back to original string.

```rad
decode_base16(_content: str) -> error|str
```

```rad
decode_base16("48656c6c6f")   // -> "Hello"
decode_base16("414243")       // -> "ABC"

// Handle errors - inside the block, `result` is the error
result = decode_base16("invalid hex") catch:
    print_err("Invalid hex string: {result}")
    exit(1)

// Or fall back
result = decode_base16("invalid hex") ?? ""
```

### decode_base64

Decodes Base64 text back to original string.

```rad
decode_base64(_content: str, *, url_safe: bool = false, padding: bool = true) -> error|str
```

```rad
encoded = encode_base64("Hello World")
decoded = decode_base64(encoded)           // -> "Hello World"

// URL-safe decoding
url_encoded = encode_base64("test", url_safe=true)
decoded = decode_base64(url_encoded, url_safe=true)

// Handle errors - inside the block, `result` is the error
result = decode_base64("invalid base64!") catch:
    print_err("Decode failed: {result}")
    exit(1)

// Or fall back
result = decode_base64("invalid base64!") ?? ""
```

**Parameters:**

| Parameter  | Type           | Description                                     |
| ---------- | -------------- | ----------------------------------------------- |
| `_content` | `str`          | Base64 text to decode                           |
| `url_safe` | `bool = false` | Expect URL-safe encoding (`-_` instead of `+/`) |
| `padding`  | `bool = true`  | Expect padding characters (`=`)                 |

Settings must match those used for encoding.

### encode_base16

Encodes text to Base16 (hexadecimal) format.

```rad
encode_base16(_content: str) -> str
```

```rad
encode_base16("Hello")        // -> "48656c6c6f"
encode_base16("ABC")          // -> "414243"
```

### encode_base64

Encodes text to Base64 format.

```rad
encode_base64(_content: str, *, url_safe: bool = false, padding: bool = true) -> str
```

```rad
encode_base64("Hello World")                      // -> "SGVsbG8gV29ybGQ="
encode_base64("Hello World", url_safe=true)       // -> URL-safe version
encode_base64("Hello World", padding=false)       // -> "SGVsbG8gV29ybGQ"
```

**Parameters:**

| Parameter  | Type           | Description                                  |
| ---------- | -------------- | -------------------------------------------- |
| `_content` | `str`          | Text to encode                               |
| `url_safe` | `bool = false` | Replace `+/` with `-_` for URL-safe encoding |
| `padding`  | `bool = true`  | Include `=` padding characters               |

Use `url_safe=true` to replace `+/` with `-_` for URL-safe encoding. Use `padding=false` to omit `=` padding.

### gen_fid

Generates a random flex ID (https://github.com/amterp/flexid) (fid) - a time-ordered, URL-safe identifier.

```rad
gen_fid(*, alphabet: str?, tick_size_ms: int?, num_random_chars: int?) -> error|str
```

```rad
gen_fid()                                    // -> "1a2b3c4d5e"
gen_fid(alphabet="0123456789")               // -> "1234567890"
gen_fid(num_random_chars=3)                  // -> "1a2b3c"
```

**Parameters:**

| Parameter          | Type                       | Description                            |
| ------------------ | -------------------------- | -------------------------------------- |
| `alphabet`         | `str? = "[0-9][A-Z][a-z]"` | Characters to use (base-62 by default) |
| `tick_size_ms`     | `int? = 1`                 | Time precision in milliseconds         |
| `num_random_chars` | `int? = 6`                 | Number of random characters to append  |

Defaults: `alphabet` is base-62 (`[0-9][A-Z][a-z]`), `tick_size_ms` is 1ms, `num_random_chars` is 6.

### hash

Generates a hash of the input text using various algorithms.

```rad
hash(_val: str, algo: ["sha1", "sha256", "sha512", "md5"] = "sha1") -> str
```

```rad
hash("hello world")                    // -> "2aae6c35c94fcfb415dbe95f408b9ce91ee846ed"
hash("hello world", algo="sha256")     // -> "b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9"
hash("sensitive data", algo="sha512")  // -> Long SHA-512 hash

// File checksums, e.g. change detection - no need to shell out to cksum/shasum
checksum = hash(read_file("config.yaml").content, algo="sha256")
```

**Parameters:**

| Parameter | Type                                           | Description              |
| --------- | ---------------------------------------------- | ------------------------ |
| `_val`    | `str`                                          | Text to hash             |
| `algo`    | `["sha1", "sha256", "sha512", "md5"] = "sha1"` | Hashing algorithm to use |

The default `sha1` is **not cryptographically secure**. Use `sha256` or `sha512` for security.

For checksumming files, combine with `read_file` as shown above.
This works for text files; hashing binary files is not yet supported.

### uuid_v4

Generates a random V4 UUID.

```rad
uuid_v4() -> str
```

```rad
uuid_v4()  // -> "f47ac10b-58cc-4372-a567-0e02b2c3d479"
```

### uuid_v7

Generates a random V7 UUID (time-ordered).

```rad
uuid_v7() -> str
```

```rad
uuid_v7()  // -> "01234567-89ab-7def-8123-456789abcdef"
```

## Formatting

### black

Wraps its argument in the ANSI escape codes for black text.

```rad
black(_item: any) -> str
```

```rad
black("Hello")        // -> "Hello" wrapped in the black escape
black(42)             // -> "42" wrapped in the black escape
```

See also: `red`, `blue`, `color_rgb`

### blue

Wraps its argument in the ANSI escape codes for blue text.

```rad
blue(_item: any) -> str
```

```rad
blue("Hello")        // -> "Hello" wrapped in the blue escape
blue(42)             // -> "42" wrapped in the blue escape
```

See also: `cyan`, `magenta`, `color_rgb`

### bold

Wraps its argument in the ANSI escape codes for bold text.

```rad
bold(_item: any) -> str
```

```rad
bold("Hello")        // -> "Hello" wrapped in the bold escape
bold(42)             // -> "42" wrapped in the bold escape
```

See also: `dim`, `italic`, `underline`

### cyan

Wraps its argument in the ANSI escape codes for cyan text.

```rad
cyan(_item: any) -> str
```

```rad
cyan("Hello")        // -> "Hello" wrapped in the cyan escape
cyan(42)             // -> "42" wrapped in the cyan escape
```

See also: `blue`, `green`, `color_rgb`

### dim

Wraps its argument in the ANSI escape codes for dimmed text - the reverse of bold, useful for de-emphasising less important output.

```rad
dim(_item: any) -> str
```

```rad
dim("Hello")        // -> "Hello" wrapped in the dim escape
dim(42)             // -> "42" wrapped in the dim escape
```

See also: `bold`, `italic`

### green

Wraps its argument in the ANSI escape codes for green text.

```rad
green(_item: any) -> str
```

```rad
green("Hello")        // -> "Hello" wrapped in the green escape
green(42)             // -> "42" wrapped in the green escape
```

See also: `red`, `yellow`, `color_rgb`

### italic

Wraps its argument in the ANSI escape codes for italic text. Not every terminal renders italics; some show inverse or coloured text instead.

```rad
italic(_item: any) -> str
```

```rad
italic("Hello")        // -> "Hello" wrapped in the italic escape
italic(42)             // -> "42" wrapped in the italic escape
```

See also: `bold`, `underline`

### magenta

Wraps its argument in the ANSI escape codes for magenta text.

```rad
magenta(_item: any) -> str
```

```rad
magenta("Hello")        // -> "Hello" wrapped in the magenta escape
magenta(42)             // -> "42" wrapped in the magenta escape
```

See also: `red`, `blue`, `color_rgb`

### orange

Wraps its argument in the ANSI escape codes for orange text. Rendered via the closest 256-colour palette entry on terminals that don't support 24-bit colour.

```rad
orange(_item: any) -> str
```

```rad
orange("Hello")        // -> "Hello" wrapped in the orange escape
orange(42)             // -> "42" wrapped in the orange escape
```

See also: `yellow`, `red`, `color_rgb`

### pink

Wraps its argument in the ANSI escape codes for pink text. Rendered via the closest 256-colour palette entry on terminals that don't support 24-bit colour.

```rad
pink(_item: any) -> str
```

```rad
pink("Hello")        // -> "Hello" wrapped in the pink escape
pink(42)             // -> "42" wrapped in the pink escape
```

See also: `magenta`, `red`, `color_rgb`

### plain

Returns its argument as a plain string with no terminal colour or style applied. Useful for stripping styling back out of an expression where some branches have it and others don't.

```rad
plain(_item: any) -> str
```

```rad
plain("Hello")        // -> "Hello" wrapped in the plain escape
plain(42)             // -> "42" wrapped in the plain escape
```

See also: `colorize`, `color_rgb`

### red

Wraps its argument in the ANSI escape codes for red text.

```rad
red(_item: any) -> str
```

```rad
red("Hello")        // -> "Hello" wrapped in the red escape
red(42)             // -> "42" wrapped in the red escape
```

See also: `green`, `yellow`, `color_rgb`

### strikethrough

Wraps its argument in the ANSI escape codes for strikethrough text. Renders with a line through it on terminals that support the attribute.

```rad
strikethrough(_item: any) -> str
```

```rad
strikethrough("Hello")        // -> "Hello" wrapped in the strikethrough escape
strikethrough(42)             // -> "42" wrapped in the strikethrough escape
```

See also: `underline`, `dim`

### underline

Wraps its argument in the ANSI escape codes for underlined text.

```rad
underline(_item: any) -> str
```

```rad
underline("Hello")        // -> "Hello" wrapped in the underline escape
underline(42)             // -> "42" wrapped in the underline escape
```

See also: `bold`, `italic`

### white

Wraps its argument in the ANSI escape codes for white text.

```rad
white(_item: any) -> str
```

```rad
white("Hello")        // -> "Hello" wrapped in the white escape
white(42)             // -> "42" wrapped in the white escape
```

See also: `black`, `plain`, `color_rgb`

### yellow

Wraps its argument in the ANSI escape codes for yellow text.

```rad
yellow(_item: any) -> str
```

```rad
yellow("Hello")        // -> "Hello" wrapped in the yellow escape
yellow(42)             // -> "42" wrapped in the yellow escape
```

See also: `red`, `green`, `color_rgb`

## HTTP

### http_connect

Sends an HTTP CONNECT to `url` and returns the response as a map. Typically used for tunnelling through a proxy.

```rad
http_connect(url: str, *, body: any?, json: any?, headers: map?, insecure: bool = false) -> { "success": bool, "status_code"?: int, "headers": map, "body"?: any, "error"?: str, "duration_seconds": float }
```

```rad
r = http_connect("https://api.example.com/resource")
if r.success:
    print(r.body)
```

**Response map keys:**

- `success: bool` - whether the request succeeded.
- `duration_seconds: float` - total request time.
- `status_code?: int` - present when a response was received.
- `headers: map` - response headers.
- `body?: any` - response body, JSON-decoded when possible.
- `error?: str` - error message when `success` is false.

**Body vs JSON:** `body` is sent as-is; `json` is JSON-serialised and sets `Content-Type: application/json` when no headers are supplied. The two are mutually exclusive.

**Insecure:** pass `insecure=true` to skip TLS certificate verification.

### http_delete

Sends an HTTP DELETE to `url` and returns the response as a map.

```rad
http_delete(url: str, *, body: any?, json: any?, headers: map?, insecure: bool = false) -> { "success": bool, "status_code"?: int, "headers": map, "body"?: any, "error"?: str, "duration_seconds": float }
```

```rad
r = http_delete("https://api.example.com/resource")
if r.success:
    print(r.body)
```

**Response map keys:**

- `success: bool` - whether the request succeeded.
- `duration_seconds: float` - total request time.
- `status_code?: int` - present when a response was received.
- `headers: map` - response headers.
- `body?: any` - response body, JSON-decoded when possible.
- `error?: str` - error message when `success` is false.

**Body vs JSON:** `body` is sent as-is; `json` is JSON-serialised and sets `Content-Type: application/json` when no headers are supplied. The two are mutually exclusive.

**Insecure:** pass `insecure=true` to skip TLS certificate verification.

### http_get

Sends an HTTP GET to `url` and returns the response as a map. See `## Notes` for the response shape.

```rad
http_get(url: str, *, body: any?, json: any?, headers: map?, insecure: bool = false) -> { "success": bool, "status_code"?: int, "headers": map, "body"?: any, "error"?: str, "duration_seconds": float }
```

```rad
r = http_get("https://api.example.com/resource")
if r.success:
    print(r.body)
```

**Response map keys:**

- `success: bool` - whether the request succeeded.
- `duration_seconds: float` - total request time.
- `status_code?: int` - present when a response was received.
- `headers: map` - response headers.
- `body?: any` - response body, JSON-decoded when possible.
- `error?: str` - error message when `success` is false.

**Body vs JSON:** `body` is sent as-is; `json` is JSON-serialised and sets `Content-Type: application/json` when no headers are supplied. The two are mutually exclusive.

**Insecure:** pass `insecure=true` to skip TLS certificate verification.

### http_head

Sends an HTTP HEAD to `url` and returns the response as a map. The server returns headers without a body; the response map's `body` is omitted.

```rad
http_head(url: str, *, body: any?, json: any?, headers: map?, insecure: bool = false) -> { "success": bool, "status_code"?: int, "headers": map, "body"?: any, "error"?: str, "duration_seconds": float }
```

```rad
r = http_head("https://api.example.com/resource")
if r.success:
    print(r.body)
```

**Response map keys:**

- `success: bool` - whether the request succeeded.
- `duration_seconds: float` - total request time.
- `status_code?: int` - present when a response was received.
- `headers: map` - response headers.
- `body?: any` - response body, JSON-decoded when possible.
- `error?: str` - error message when `success` is false.

**Body vs JSON:** `body` is sent as-is; `json` is JSON-serialised and sets `Content-Type: application/json` when no headers are supplied. The two are mutually exclusive.

**Insecure:** pass `insecure=true` to skip TLS certificate verification.

### http_options

Sends an HTTP OPTIONS request to `url` and returns the response as a map. Typically used to discover the methods supported by a resource.

```rad
http_options(url: str, *, body: any?, json: any?, headers: map?, insecure: bool = false) -> { "success": bool, "status_code"?: int, "headers": map, "body"?: any, "error"?: str, "duration_seconds": float }
```

```rad
r = http_options("https://api.example.com/resource")
if r.success:
    print(r.body)
```

**Response map keys:**

- `success: bool` - whether the request succeeded.
- `duration_seconds: float` - total request time.
- `status_code?: int` - present when a response was received.
- `headers: map` - response headers.
- `body?: any` - response body, JSON-decoded when possible.
- `error?: str` - error message when `success` is false.

**Body vs JSON:** `body` is sent as-is; `json` is JSON-serialised and sets `Content-Type: application/json` when no headers are supplied. The two are mutually exclusive.

**Insecure:** pass `insecure=true` to skip TLS certificate verification.

### http_patch

Sends an HTTP PATCH to `url` and returns the response as a map. Use `body` for raw payloads or `json` for automatic JSON serialisation.

```rad
http_patch(url: str, *, body: any?, json: any?, headers: map?, insecure: bool = false) -> { "success": bool, "status_code"?: int, "headers": map, "body"?: any, "error"?: str, "duration_seconds": float }
```

```rad
r = http_patch("https://api.example.com/resource")
if r.success:
    print(r.body)
```

**Response map keys:**

- `success: bool` - whether the request succeeded.
- `duration_seconds: float` - total request time.
- `status_code?: int` - present when a response was received.
- `headers: map` - response headers.
- `body?: any` - response body, JSON-decoded when possible.
- `error?: str` - error message when `success` is false.

**Body vs JSON:** `body` is sent as-is; `json` is JSON-serialised and sets `Content-Type: application/json` when no headers are supplied. The two are mutually exclusive.

**Insecure:** pass `insecure=true` to skip TLS certificate verification.

### http_post

Sends an HTTP POST to `url` and returns the response as a map. Use `body` for raw payloads or `json` for automatic JSON serialisation.

```rad
http_post(url: str, *, body: any?, json: any?, headers: map?, insecure: bool = false) -> { "success": bool, "status_code"?: int, "headers": map, "body"?: any, "error"?: str, "duration_seconds": float }
```

```rad
r = http_post("https://api.example.com/resource")
if r.success:
    print(r.body)
```

**Response map keys:**

- `success: bool` - whether the request succeeded.
- `duration_seconds: float` - total request time.
- `status_code?: int` - present when a response was received.
- `headers: map` - response headers.
- `body?: any` - response body, JSON-decoded when possible.
- `error?: str` - error message when `success` is false.

**Body vs JSON:** `body` is sent as-is; `json` is JSON-serialised and sets `Content-Type: application/json` when no headers are supplied. The two are mutually exclusive.

**Insecure:** pass `insecure=true` to skip TLS certificate verification.

### http_put

Sends an HTTP PUT to `url` and returns the response as a map. Use `body` for raw payloads or `json` for automatic JSON serialisation.

```rad
http_put(url: str, *, body: any?, json: any?, headers: map?, insecure: bool = false) -> { "success": bool, "status_code"?: int, "headers": map, "body"?: any, "error"?: str, "duration_seconds": float }
```

```rad
r = http_put("https://api.example.com/resource")
if r.success:
    print(r.body)
```

**Response map keys:**

- `success: bool` - whether the request succeeded.
- `duration_seconds: float` - total request time.
- `status_code?: int` - present when a response was received.
- `headers: map` - response headers.
- `body?: any` - response body, JSON-decoded when possible.
- `error?: str` - error message when `success` is false.

**Body vs JSON:** `body` is sent as-is; `json` is JSON-serialised and sets `Content-Type: application/json` when no headers are supplied. The two are mutually exclusive.

**Insecure:** pass `insecure=true` to skip TLS certificate verification.

### http_trace

Sends an HTTP TRACE to `url` and returns the response as a map. Often disabled at the server for security; expect failures against modern endpoints.

```rad
http_trace(url: str, *, body: any?, json: any?, headers: map?, insecure: bool = false) -> { "success": bool, "status_code"?: int, "headers": map, "body"?: any, "error"?: str, "duration_seconds": float }
```

```rad
r = http_trace("https://api.example.com/resource")
if r.success:
    print(r.body)
```

**Response map keys:**

- `success: bool` - whether the request succeeded.
- `duration_seconds: float` - total request time.
- `status_code?: int` - present when a response was received.
- `headers: map` - response headers.
- `body?: any` - response body, JSON-decoded when possible.
- `error?: str` - error message when `success` is false.

**Body vs JSON:** `body` is sent as-is; `json` is JSON-serialised and sets `Content-Type: application/json` when no headers are supplied. The two are mutually exclusive.

**Insecure:** pass `insecure=true` to skip TLS certificate verification.

## IO

### base_name

Returns the last element of a path.

```rad
base_name(_path: str) -> str
```

```rad
print(base_name("/home/alice/notes.txt"))  // -> "notes.txt"
print(base_name("src/core/"))              // -> "core" (trailing slashes are ignored)
print(base_name("standalone"))             // -> "standalone"
```

Pure string manipulation - the path does not need to exist, unlike
`get_path`, which only reports `base_name` for existing paths.

Edge cases follow Unix `basename` conventions: `base_name("/")` returns `"/"`,
and `base_name("")` returns `"."`.

See also `dir_name` and `join_paths`.

### confirm

Gets a boolean confirmation from the user (y/n prompt). Accepts "y", "yes", or Enter (empty input) as
confirmation.

```rad
confirm(prompt: str = "Confirm? [Y/n] > ") -> error|bool
```

```rad
if confirm():                        // -> Uses default "Confirm? [Y/n] > " prompt
    print("Confirmed!")

if confirm("Delete file? [Y/n] "):   // -> Custom prompt
    print("File deleted")
```

### debug

Behaves like `print` but only outputs when debug mode is enabled via `--debug` flag.

```rad
debug(*_items: any, *, sep: str = " ", end: str = "\n") -> void
```

```rad
debug("entering loop")             // -> nothing unless --debug is on
debug("x =", x, "y =", y)          // -> debug-only diagnostics
```

### delete_path

Deletes a file or directory at the specified path.

```rad
delete_path(_path: str) -> bool
```

```rad
delete_path("temp.txt")         // -> true (if file existed and was deleted)
delete_path("missing.txt")      // -> false (file didn't exist)
delete_path("directory/")       // -> true (if directory existed and was deleted)
```

Returns `true` if the path was successfully deleted, `false` if it didn't exist or couldn't be deleted.

A leading `~` in `_path` is expanded to your home directory.

### dir_name

Returns a path with its last element removed, i.e. the containing directory.

```rad
dir_name(_path: str) -> str
```

```rad
print(dir_name("/home/alice/notes.txt"))  // -> "/home/alice"
print(dir_name("src/core/funcs.go"))      // -> "src/core"
print(dir_name("standalone"))             // -> "."
```

Pure string manipulation - the path does not need to exist.

Edge cases follow Unix `dirname` conventions: `dir_name("/")` returns `"/"`,
and `dir_name("")` returns `"."`. The result is lexically cleaned, e.g.
`dir_name("a/b/../c")` returns `"a"` after resolving the `..`. The returned
path uses forward slashes on all platforms.

See also `base_name` and `join_paths`.

### find_paths

Returns a list of all paths under a directory.

```rad
find_paths(_path: str, *, depth: int = -1, relative: ["target", "cwd", "absolute"] = "target") -> error|str[]
```

```rad
// Find all files in directory
paths = find_paths("src/")
for path in paths:
    print(path)  // -> "file1.txt", "subdir/file2.txt", etc.

// Limit depth
paths = find_paths("src/", depth=1)  // -> Only direct children

// Get absolute paths
paths = find_paths("src/", relative="absolute")
```

**Parameters:**

| Parameter  | Type                                       | Description                            |
| ---------- | ------------------------------------------ | -------------------------------------- |
| `_path`    | `str`                                      | Directory to search                    |
| `depth`    | `int = -1`                                 | Max depth to search (-1 for unlimited) |
| `relative` | `["target", "cwd", "absolute"] = "target"` | How to format returned paths           |

- `"target"` - Relative to input path (default)
- `"cwd"` - Relative to current directory
- `"absolute"` - Full absolute paths

A leading `~` in `_path` is expanded to your home directory.

### input

Gets a line of text input from the user with optional prompt, default, hint, and secret mode.

```rad
input(prompt: str = "> ", *, hint: str = "", default: str = "", secret: bool = false) -> error|str
```

```rad
// Basic input
name = input("What's your name? ")                    // -> Prompts and waits for input

// With default value
color = input("Favorite color? ", default="blue")     // -> Returns "blue" if user presses enter

// With hint text
email = input("Email: ", hint="user@example.com")     // -> Shows placeholder text

// Hidden input for passwords
password = input("Password: ", secret=true)           // -> Hides typed characters
```

**Parameters:**

| Parameter | Type           | Description                                  |
| --------- | -------------- | -------------------------------------------- |
| `prompt`  | `str = "> "`   | The text prompt to display to the user       |
| `hint`    | `str = ""`     | Placeholder text shown in input field        |
| `default` | `str = ""`     | Default value if user doesn't enter anything |
| `secret`  | `bool = false` | If true, hides input (useful for passwords)  |

If `secret` is true, input is hidden (useful for passwords). The `hint` parameter has no effect when `secret` is
enabled.

### join_paths

Joins path segments into a single path.

```rad
join_paths(*_parts: str) -> str
```

```rad
print(join_paths("home", "alice", "notes.txt"))  // -> "home/alice/notes.txt"
print(join_paths("/etc", "nginx/", "conf.d"))    // -> "/etc/nginx/conf.d"
print(join_paths("a", "", "b"))                  // -> "a/b" (empty segments are skipped)
```

Pure string manipulation - the paths do not need to exist.

The result is lexically cleaned: redundant separators collapse, and `.` / `..`
segments are resolved, e.g. `join_paths("a/b", "../c")` returns `"a/c"`.
Joining nothing (or only empty strings) returns `""`.

The returned path uses forward slashes on all platforms.

See also `base_name` and `dir_name`.

### mkdir

Creates a directory, including any missing parent directories.

```rad
mkdir(_path: str) -> error|{ "path": str, "created": bool }
```

```rad
res = mkdir("output/reports")
print(res.created)  // -> true (false if it already existed)

// Idempotent - safe to call when the directory already exists
res = mkdir("output/reports")
print(res.created)  // -> false

// path is the input after ~ expansion, with forward slashes
res = mkdir("~/backups")
print(res.path)     // -> e.g. "/home/alice/backups"

// Errors are catchable
res = mkdir("/root/forbidden") catch:
    print("Could not create:", res)
```

Behaves like `mkdir -p`: creates all missing parents, and succeeds (with
`created: false`) if the directory already exists. Directories are created
with `0755` permissions.

Errors if the path exists but is a file, or if creation fails (e.g. missing
permissions).

A leading `~` in `_path` is expanded to your home directory. The returned
`path` is the input after that expansion, normalized to forward slashes on
all platforms - it is not resolved to an absolute path.

Counterpart to `delete_path`.

### multipick

Presents an interactive menu for selecting multiple options from a list.

```rad
multipick(_options: str[], *, prompt: str?, min: int = 0, max: int?) -> error|str[]
```

```rad
fruits = ["apple", "banana", "cherry", "date"]
selected = multipick(fruits)
// selected equals e.g. [ "apple", "cherry" ]
```

Shows an interactive multi-select menu where users can select zero or more options.
Unlike `pick`, which returns a single selection, `multipick` returns a list of all selected items.

**Parameters:**

| Parameter  | Type      | Description                                                                   |
| ---------- | --------- | ----------------------------------------------------------------------------- |
| `_options` | `str[]`   | List of options to display in the menu                                        |
| `prompt`   | `str?`    | Custom prompt text. If not provided, automatically generated based on min/max |
| `min`      | `int = 0` | Minimum number of selections required (default 0 allows empty selection)      |
| `max`      | `int?`    | Maximum number of selections allowed (optional, unlimited if not set)         |

The `prompt` parameter has smart defaults that adjust based on the min/max constraints.

### pick

Presents an interactive menu for selecting from a list of options.

```rad
pick(_options: str[], _filter: (str|str[])?, *, prompt: str = "Pick an option", prefer_exact: bool = false) -> error|str
```

```rad
pick(["apple", "banana", "cherry"])                        // -> Interactive menu
pick(["red", "green", "blue"], "r")                        // -> Fuzzy-filtered to "red", "green"
pick(["grape", "g"], "g", prefer_exact=true)                 // -> Immediately picks "g" (exact match)
pick(["one", "two", "three"], prompt="Choose:")            // -> Custom prompt
```

Shows a fuzzy-searchable menu. Filter can be a string or list of strings to pre-filter options.

When `prefer_exact=true`, exact key matches (case-insensitive) are prioritized: if exactly one option exactly matches a
filter, it's selected immediately; if multiple match exactly, only those are shown.

### pick_from_resource

Loads options from a resource file and presents an interactive menu.

```rad
pick_from_resource(path: str, _filter: str?, *, prompt: str = "Pick an option", prefer_exact: bool = true) -> any
```

```rad
pick_from_resource("servers.json")                    // -> Menu from file
pick_from_resource("configs.json", "prod")            // -> Pre-filtered, exact match priority
pick_from_resource("data.json", prompt="Select:")     // -> Custom prompt
pick_from_resource("data.json", "x", prefer_exact=false) // -> Pure fuzzy matching
```

Loads data from a JSON file and presents it as selectable options. Returns the selected item(s).

With `prefer_exact=true` (the default), exact key matches (case-insensitive) are prioritized: if exactly one entry has a
key that exactly matches the filter, it's selected immediately; if multiple match exactly, only those are shown. Set
`prefer_exact=false` to disable this and use pure fuzzy matching.

### pick_kv

Presents an interactive menu showing keys but returns corresponding values.

```rad
pick_kv(keys: str[], values: any[], _filter: (str|str[])?, *, prompt: str = "Pick an option", prefer_exact: bool = false) -> any
```

```rad
names = ["Alice", "Bob", "Charlie"]
ages = [25, 30, 35]
pick_kv(names, ages)                                        // -> Shows names, returns age
pick_kv(["Red", "Green"], ["#ff0000", "#00ff00"])           // -> Shows colors, returns hex
pick_kv(["grape", "g"], [1, 2], "g", prefer_exact=true)       // -> Returns 2 (exact match)
```

Displays keys in the menu but returns the value at the same index when selected.

When `prefer_exact=true`, exact key matches (case-insensitive) are prioritized: if exactly one key exactly matches a
filter, its value is returned immediately; if multiple match exactly, only those are shown.

### pprint

Pretty prints data in JSON format with indentation and colors.

```rad
pprint(_item: any?) -> void
```

```rad
item = { "name": "Alice", "age": 30 }
pprint(item)
// Output:
// {
//   "name": "Alice", 
//   "age": 30
// }
```

### print

Writes its arguments to stdout, separated by a space, followed by a
newline. The default workhorse for output. For error output, use
`print_err`; for structured pretty-printing, use `pprint`.

```rad
print(*_items: any, *, sep: str = " ", end: str = "\n") -> void
```

```rad
print("hello", "world")    // -> hello world
print(1, 2, 3, sep=", ")   // -> 1, 2, 3
print("no newline", end="") // -> no newline
```

See also: `print_err`, `pprint`, `debug`

### print_err

Behaves like `print` but outputs to stderr instead of stdout.

```rad
print_err(*_items: any, *, sep: str = " ", end: str = "\n") -> void
```

```rad
print_err("failed to load config")     // -> writes to stderr

// Inside a catch: block the assigned variable is the error itself
config = read_file("config.json") catch:
    print_err("error:", config)        // -> "error: <msg>" to stderr
```

### read_file

Reads the contents of a file.

```rad
read_file(_path: str, *, mode: ["text", "bytes"] = "text") -> error|{ "size_bytes": int, "content": str|int[] }
```

```rad
// Read text file
result = read_file("config.txt")
content = result.content      // -> string

// Read binary file
result = read_file("image.png", mode="bytes")
bytes = result.content        // -> list[int]

// Handle errors - inside the block, `result` is the error
result = read_file("missing.txt") catch:
    print_err("Read failed: {result}")
    exit(1)

// Or fall back
result = read_file("missing.txt") ?? { "size_bytes": 0, "content": "" }
```

**Parameters:**

| Parameter | Type                         | Description                     |
| --------- | ---------------------------- | ------------------------------- |
| `_path`   | `str`                        | Path to the file to read        |
| `mode`    | `["text", "bytes"] = "text"` | Read as UTF-8 text or raw bytes |

In text mode, decodes as UTF-8 and returns a string. In bytes mode, returns a list of integers.

A leading `~` in `_path` is expanded to your home directory.

**Return map contains:**

- `size_bytes: int` - File size in bytes
- `content: str|list[int]` - File contents (type depends on mode)

### read_stdin

Reads all data from stdin.

```rad
read_stdin() -> str?|error
```

```rad
read_stdin()                  // -> "piped content" (if piped)
read_stdin()                  // -> null (if not piped)
read_stdin()                  // -> Error 20026 if read fails
content = read_stdin()
lines = content.split_lines() // Process stdin line-by-line
```

### write_file

Writes content to a file. Creates the file if it doesn't exist.

```rad
write_file(_path: str, _content: str, *, append: bool = false) -> error|{ "bytes_written": int, "path": str }
```

```rad
// Write new file
result = write_file("output.txt", "Hello world")
print("Wrote", result.bytes_written, "bytes")

// Append to existing file
write_file("log.txt", "\nNew entry", append=true)

// Handle errors - inside the block, `result` is the error
result = write_file("/readonly/file.txt", "data") catch:
    print_err("Write failed: {result}")
    exit(1)
```

**Parameters:**

| Parameter  | Type           | Description                                       |
| ---------- | -------------- | ------------------------------------------------- |
| `_path`    | `str`          | Path where to write the file                      |
| `_content` | `str`          | Content to write                                  |
| `append`   | `bool = false` | Append to existing content instead of overwriting |

By default overwrites the file. Use `append=true` to append to existing content.

A leading `~` in `_path` is expanded to your home directory.

**Return map contains:**

- `bytes_written: int` - Number of bytes written
- `path: str` - Full path to the written file

## Lists

### filter

Applies a predicate function to filter elements of a list or map. Keeps only elements where the function returns true.

```rad
filter(_coll: map|list, _fn: fn(any) -> bool | fn(any, any) -> bool) -> map|list
```

```rad
filter([1, 2, 3, 4], fn(x) x % 2 == 0)      // -> [2, 4]
filter({"a": 1, "b": 2}, fn(k, v) v > 1)    // -> {"b": 2}
```

For lists, function receives `fn(value)`. For maps, function receives `fn(key, value)`.

### flat_map

Flattens a list of lists, or applies a mapping function that returns lists and flattens the results.

```rad
flat_map(_coll: map|list, _fn: any?) -> list
```

```rad
// Flatten list of lists (all elements must be lists)
[[1, 2], [3, 4]].flat_map()              // -> [1, 2, 3, 4]
[[], [1], []].flat_map()                 // -> [1]

// Only one level
[[[1]], [[2]]].flat_map()                // -> [[1], [2]]

// Map then flatten (function must return a list)
["a-b", "c-d"].flat_map(fn(e) e.split("-"))  // -> ["a", "b", "c", "d"]
[1, 2].flat_map(fn(x) [x, x * 10])           // -> [1, 10, 2, 20]
[1, 2].flat_map(fn(x) range(x))              // -> [0, 0, 1]

// Map collection - function required, must return list
{"a": [1, 2], "b": [3, 4]}.flat_map(fn(k, v) v)  // -> [1, 2, 3, 4]
{"a": 1, "b": 2}.flat_map(fn(k, v) [k, v])       // -> ["a", 1, "b", 2]

// Errors:
// [1, [2], 3].flat_map()           // Error: element 0 is not a list
// [1, 2].flat_map(fn(x) x * 2)     // Error: function must return a list
```

**For lists without function:** All elements must be lists. Flattens one level.

**With function:** The function must return a list. Results are flattened.

For lists, function receives `fn(value)`. For maps, function receives `fn(key, value)` and is required.

### join

Joins a list into a string with separator, prefix, and suffix.

```rad
join(_list: list, sep: str = "", prefix: str = "", suffix: str = "") -> str
```

```rad
join([1, 2, 3], sep=", ")           // -> "1, 2, 3"
join(["a", "b"], prefix="[", suffix="]")  // -> "[ab]"
join(["x", "y", "z"], sep="-", prefix="(", suffix=")")  // -> "(x-y-z)"
```

### keys

Returns all keys from a map as a list.

```rad
keys(_map: map) -> any[]
```

```rad
keys({"a": 1, "b": 2, "c": 3})  // -> ["a", "b", "c"]
keys({})                        // -> []
```

### len

Returns the number of elements in a string, list, or map. For
strings this is the rune count (not byte count), so unicode characters
contribute one each.

```rad
len(_val: str|list|map) -> int
```

```rad
len("hello")              // -> 5
len([1, 2, 3])            // -> 3
len({"a": 1, "b": 2})     // -> 2
len("héllo")              // -> 5 (rune count, not byte count)
```

See also: `sort`, `keys`, `values`

### map

Applies a function to every element of a list or entry of a map.

```rad
map(_coll: map|list, _fn: fn(any) -> any | fn(any, any) -> any) -> map|list
```

```rad
map([1, 2, 3], fn(x) x * 2)              // -> [2, 4, 6]
map({"a": 1, "b": 2}, fn(k, v) v * 10)   // -> {"a": 10, "b": 20}
```

For lists, function receives `fn(value)`. For maps, function receives `fn(key, value)`.

### sort

Returns a new sorted list (or string with characters sorted). The
input is not mutated. With `reverse=true`, sorts in descending order.
Multiple lists / strings can be passed - they're sorted in lockstep
using the first as the key.

```rad
sort(_primary: list|str, *_others: list|str, *, reverse: bool = false) -> list|str
```

```rad
sort([3, 1, 2])             // -> [1, 2, 3]
sort([3, 1, 2], reverse=true)  // -> [3, 2, 1]
sort("dcba")                // -> "abcd"

ages = [30, 25, 28]
names = ["alice", "bob", "carol"]
sort(ages, names)           // -> [25, 28, 30]
                            //    names is now ["bob", "carol", "alice"]
```

See also: `len`, `reverse`

### unique

Returns a list with duplicate values removed, preserving first occurrence order.

```rad
unique(_list: any[]) -> any[]
```

```rad
unique([2, 1, 2, 3, 1, 3, 4])  // -> [2, 1, 3, 4]
unique(["a", "b", "a", "c"])    // -> ["a", "b", "c"]
```

### values

Returns all values from a map as a list.

```rad
values(_map: map) -> any[]
```

```rad
values({"a": 1, "b": 2, "c": 3})  // -> [1, 2, 3]
values({})                         // -> []
```

### zip

Combines multiple lists into a list of lists, pairing elements by index.

```rad
zip(*_lists: list, *, fill: any?, strict: bool = false) -> error|list[]
```

```rad
// Basic usage
zip([1, 2, 3], ["a", "b", "c"])           // -> [[1, "a"], [2, "b"], [3, "c"]]
zip([1, 2, 3, 4], ["a", "b"])             // -> [[1, "a"], [2, "b"]]

// With fill value for unequal lengths
zip([1, 2, 3, 4], ["a", "b"], fill="-")   // -> [[1, "a"], [2, "b"], [3, "-"], [4, "-"]]

// Strict mode (errors on length mismatch)  
zip([1, 2, 3], ["a", "b"], strict=true)   // -> Error: Lists must have the same length
```

**Parameters:**

| Parameter | Type           | Description                              |
| --------- | -------------- | ---------------------------------------- |
| `*lists`  | `list`         | Variable number of lists to zip together |
| `strict`  | `bool = false` | If true, error on different list lengths |
| `fill`    | `any?`         | Value to fill shorter lists (optional)   |

- By default, truncates to the shortest list length
- Cannot use `strict=true` with `fill` parameter (mutually exclusive)
- Returns error if `strict=true` and lists have different lengths

## Math

### abs

Returns the absolute value of a number. The result's type matches
the input - `int` in, `int` out; `float` in, `float` out.

```rad
abs(_num: int|float) -> int|float
```

```rad
abs(-5)        // -> 5
abs(5)         // -> 5
abs(-3.14)     // -> 3.14
abs(0)         // -> 0
```

See also: `floor`, `ceil`, `round`

### ceil

Rounds a number up to the next integer.

```rad
ceil(_num: float) -> int
```

```rad
ceil(1.21)     // -> 2
ceil(-1.8)     // -> -1
ceil(5.0)      // -> 5
```

### clamp

Constrains a value between minimum and maximum bounds.

```rad
clamp(val: int|float, min: int|float, max: int|float) -> error|int|float
```

```rad
clamp(25, 20, 30)    // -> 25
clamp(10, 20, 30)    // -> 20
clamp(40, 20, 30)    // -> 30
clamp(5, 1.0, 10)    // -> 5.0 (float because 1.0 is float)
clamp(15, 30, 20)    // -> Error: min must be <= max
```

**Parameters:**

| Parameter | Type          | Description        |
| --------- | ------------- | ------------------ |
| `val`     | `int | float` | Value to constrain |
| `min`     | `int | float` | Minimum bound      |
| `max`     | `int | float` | Maximum bound      |

Returns `val` if between min and max, otherwise returns the nearest bound. Min must be ≤ max.
The return type preserves the input type: returns `int` if all inputs are integers, `float` if any input is a float.

### floor

Rounds a number down to the next integer.

```rad
floor(_num: float) -> int
```

```rad
floor(1.89)    // -> 1
floor(-1.2)    // -> -2
floor(5.0)     // -> 5
```

### max

Returns the maximum value from a list of numbers or from variadic arguments.

```rad
max(*_nums: float|float[]) -> int|float|error
```

```rad
max([1, 2, 3, 4])        // -> 4
max(1, 2, 3, 4)          // -> 4
max(5.5, 2.1, 8.9)       // -> 8.9
max(1, 2.0, 3)           // -> 3.0 (float because 2.0 is float)
max(5)                   // -> 5
max([])                  // -> Error: cannot find maximum of empty list
max([1, "text"])         // -> Error: requires list of numbers
```

Accepts either a single list of numbers or multiple number arguments.
The return type preserves the input type: returns `int` if all inputs are integers, `float` if any input is a float.

### min

Returns the minimum value from a list of numbers or from variadic arguments.

```rad
min(*_nums: float|float[]) -> int|float|error
```

```rad
min([1, 2, 3, 4])        // -> 1
min(1, 2, 3, 4)          // -> 1
min(5.5, 2.1, 8.9)       // -> 2.1
min(1, 2.0, 3)           // -> 1.0 (float because 2.0 is float)
min(5)                   // -> 5
min([])                  // -> Error: cannot find minimum of empty list
min([1, "text"])         // -> Error: requires list of numbers
```

Accepts either a single list of numbers or multiple number arguments.
The return type preserves the input type: returns `int` if all inputs are integers, `float` if any input is a float.

### pow

Raises `base` to the power of `exponent`. Useful for exponentiation, square roots, and cube roots.

```rad
pow(_base: float, _exponent: float) -> float
```

```rad
pow(2, 3)      // -> 8
pow(4, 0.5)    // -> 2.0 (square root)
pow(8, 1/3)    // -> 2.0 (cube root)  
pow(2, -2)     // -> 0.25
pow(-2, 3)     // -> -8
```

### range

Returns a list of numbers covering the half-open interval
`[start, stop)`. With one argument, `start` defaults to 0. The list
type matches the inputs - all ints produces an `int[]`, any float
produces a `float[]`.

```rad
range(_arg1: float|int, _arg2: (float|int)?, _step: float|int = 1) -> float[]|int[]
```

```rad
range(5)              // -> [0, 1, 2, 3, 4]
range(1, 5)           // -> [1, 2, 3, 4]
range(0, 1, 0.25)     // -> [0.0, 0.25, 0.5, 0.75]
range(10, 0, -2)      // -> [10, 8, 6, 4, 2]
```

See also: `for`, `len`

### round

Rounds a number to the specified decimal precision.

```rad
round(_num: float, _decimals: int = 0) -> error|int|float
```

```rad
round(3.14159)           // -> 3 (integer)
round(3.14159, 2)        // -> 3.14 (float)
round(2.7)               // -> 3 (integer)
round(3.14, -1)          // -> Error: precision must be non-negative
```

**Parameters:**

| Parameter   | Type      | Description                                     |
| ----------- | --------- | ----------------------------------------------- |
| `_num`      | `float`   | Number to round                                 |
| `_decimals` | `int = 0` | Number of decimal places (must be non-negative) |

With precision 0, returns an integer. With precision > 0, returns a float. Precision must be non-negative.

### sum

Sums all numbers in a list.

```rad
sum(_nums: float[]) -> error|int|float
```

```rad
sum([1, 2, 3, 4])        // -> 10
sum([1.5, 2.5, 3.0])     // -> 7.0
sum([1, 2.0, 3])         // -> 6.0 (float because 2.0 is float)
sum([])                  // -> 0
sum([1, "text", 3])      // -> Error: requires list of numbers
```

The return type preserves the input type: returns `int` if all inputs are integers, `float` if any input is a float.

## Parsing

### convert_duration

Converts a numeric value in the specified unit. Supports `nanos`, `micros`, `millis`, `seconds`, `minutes`, `hours`, and
`days`.

```rad
convert_duration(_value: int|float, _unit: ["nanos", "micros", "millis", "seconds", "minutes", "hours", "days"]) -> error|{ "nanos": int, "micros": float, "millis": float, "seconds": float, "minutes": float, "hours": float, "days": float }
```

```rad
convert_duration(90, "seconds").minutes   // -> 1.5
convert_duration(1, "days").hours         // -> 24.0
convert_duration(1.5, "hours").minutes    // -> 90.0
convert_duration(1500, "millis").seconds  // -> 1.5
```

### float

Converts a value to a float. Does not work on strings - use `parse_float` for string parsing.

```rad
float(_var: any) -> float|error
```

```rad
float(42)      // -> 42.0
float(true)    // -> 1.0
float(false)   // -> 0.0  
float("3.14")  // -> Error: cannot convert string
```

### int

Converts a value to an integer. Does not work on strings - use `parse_int` for string parsing.

```rad
int(_var: any) -> int|error
```

```rad
int(3.14)     // -> 3
int(true)     // -> 1
int(false)    // -> 0
int("42")     // -> Error: cannot convert string
```

### parse_duration

Parses a human-readable duration string into a map of time units. Supports all standard suffixes (`ns`, `us`/`µs`, `ms`,
`s`, `m`, `h`) plus `d` for days (1d = 24h) and `w` for weeks (1w = 7d). Spaces are stripped, and a leading `-` negates
the whole duration.

```rad
parse_duration(_duration: str) -> error|{ "nanos": int, "micros": float, "millis": float, "seconds": float, "minutes": float, "hours": float, "days": float }
```

```rad
parse_duration("5m23s")         // -> { nanos: 323000000000, micros: 323000000.0, millis: 323000.0, seconds: 323.0, minutes: 5.3833..., hours: 0.0897..., days: 0.00374... }
parse_duration("1d12h").hours   // -> 36.0
parse_duration("1w2d3h").hours  // -> 219.0
parse_duration("300ms").millis  // -> 300.0
parse_duration("-5m").minutes   // -> -5.0
parse_duration("5m 30s")        // -> same as "5m30s"
```

### parse_float

Parses a string to a float.

```rad
parse_float(_str: str) -> float|error
```

```rad
parse_float("3.14")  // -> 3.14
parse_float("42")    // -> 42.0
parse_float("abc")   // -> Error: invalid syntax
```

### parse_int

Parses a string to an integer.

```rad
parse_int(_str: str) -> int|error
```

```rad
parse_int("42")    // -> 42
parse_int("3.14")  // -> Error: invalid syntax
parse_int("abc")   // -> Error: invalid syntax
```

### parse_json

Parses a JSON string into Rad data structures.

```rad
parse_json(_str: str) -> any|error
```

```rad
parse_json(r'{"name": "Alice", "age": 30}')  // -> {"name": "Alice", "age": 30}
parse_json('[1, 2, 3]')                      // -> [1, 2, 3]
parse_json('invalid json')                   // -> Error: invalid JSON
```

Use a raw string (`r'...'`) when the JSON contains `{` or `}` - plain
single- and double-quoted strings interpolate `{expr}`, which makes
JSON literals trip the interpolator. Raw strings are also natural for
JSON pasted verbatim from a sample.

### str

Converts any value to a string representation. Useful when you need to concatenate non-string values with `+`, though
interpolation (`"value: {x}"`) is generally preferred.

```rad
str(_var: any) -> str
```

```rad
str(42)        // -> "42"
str(3.14)      // -> "3.14"
str([1, 2])    // -> "[1, 2]"
str(true)      // -> "true"
```

### to_json

Serializes a Rad value into a JSON string. The inverse of `parse_json`.

```rad
to_json(_val: any, *, indent: int = 0) -> str
```

```rad
to_json({"name": "Alice", "age": 30})  // -> '{"age":30,"name":"Alice"}'
to_json([1, 2, "x"])                   // -> '[1,2,"x"]'
to_json("hi")                          // -> '"hi"'
to_json({"a": 1}, indent=2)            // -> multi-line, 2-space indented
```

**Parameters:**

| Parameter | Type      | Description                                          |
| --------- | --------- | ---------------------------------------------------- |
| `_val`    | `any`     | Value to serialize                                   |
| `indent`  | `int = 0` | If > 0, pretty-print with that many spaces of indent |

Unlike string interpolation or `str()`, the output is guaranteed to be valid
JSON: strings are escaped and quoted, including top-level ones. HTML characters
(`<`, `>`, `&`) are not escaped. `null` serializes to `"null"`.

Map keys are currently emitted in alphabetical order, not insertion order.

See also: `parse_json`, `pprint`

## Random

### rand

Returns a random float between 0.0 (inclusive) and 1.0 (exclusive).

```rad
rand() -> float
```

```rad
rand()     // -> 0.7394832
rand()     // -> 0.2847293
```

### rand_int

Returns a random integer in a specified range.

```rad
rand_int(_arg1: int = 9223372036854775807, _arg2: int?) -> int
```

```rad
rand_int(10)        // -> Random int from 0-9
rand_int(5, 15)     // -> Random int from 5-14
rand_int(10, 5)     // -> Error: min (10) must be less than max (5)
```

With one argument, returns random int from 0 to `_arg1` (exclusive). With two arguments, returns random int from `_arg1`
to `_arg2` (exclusive). Min must be less than max.

### seed_random

Seeds the random number generator used by `rand` and `rand_int`.

```rad
seed_random(_seed: int) -> void
```

```rad
seed_random(42)
rand()              // -> Same sequence every time with seed 42
rand_int(10)        // -> Same sequence every time with seed 42
```

## Stash

### get_rad_home

Returns the path to rad's home folder on the user's machine.

**Return Values**

Defaults to `$HOME/.rad`, or `$RAD_HOME` if it's defined.

```rad
get_rad_home() -> str
```

```rad
home = get_rad_home()              // -> "/Users/me/.rad" (or $RAD_HOME)
```

### get_stash_path

Returns the full path to the script's stash directory, with the given subpath if specified.

Requires a stash ID to have been defined.

**Return Values**

- Without subpath defined: `<rad home>/stashes/<stash id>`
- With subpath defined: `<rad home>/stashes/<stash id>/<subpath>`

```rad
get_stash_path(_sub_path: str = "") -> error|str
```

```rad
root = get_stash_path()                // -> "<rad-home>/stashes/<stash-id>"
cache = get_stash_path("cache.json")   // -> "<rad-home>/stashes/<stash-id>/cache.json"
```

### load

Loads a value into a map using lazy evaluation. If key exists, returns cached value; otherwise runs loader function.

```rad
load(_map: map, _key: any, _loader: fn() -> any, *, reload: bool = false, override: any?) -> error|any
```

```rad
cache = {}
load(cache, "data", fn() expensive_calculation())    // -> Runs loader, caches result
load(cache, "data", fn() expensive_calculation())    // -> Returns cached value

// Force reload
load(cache, "data", fn() new_calculation(), reload=true)

// Override with specific value  
load(cache, "data", fn() ignored(), override="forced")
```

**Parameters:**

| Parameter  | Type           | Description                              |
| ---------- | -------------- | ---------------------------------------- |
| `_map`     | `map`          | Map to store/retrieve cached values      |
| `_key`     | `any`          | Key to lookup in the map                 |
| `_loader`  | `fn() -> any`  | Function to call if key doesn't exist    |
| `reload`   | `bool = false` | Force reload even if key exists          |
| `override` | `any?`         | Use this value instead of calling loader |

If key doesn't exist, `_loader` is called and result is cached. Cannot use `reload=true` with `override` (mutually
exclusive).

### load_stash_file

Loads a file from the script's stash directory, creating it with default content if it doesn't exist.

```rad
load_stash_file(_path: str, _default: str = "") -> error|{ "full_path": str, "created": bool, "content"?: str }
```

```rad
result = load_stash_file("config.txt", "default config")
if result.created:
    print("Created new config file")
content = result.content

// Handle errors - inside the block, `result` is the error
result = load_stash_file("config.txt") catch:
    print_err("Could not load stash file: {result}")
    exit(1)
```

**Return map contains:**

- `full_path: str` - Full path to the file
- `created: bool` - Whether the file was just created
- `content?: str` - File contents (if successfully loaded)

### load_state

Loads the script's stashed state. Creates it if it doesn't already exist.

Requires a stash ID to have been defined.

**Return Values**

1. `map` containing the saved state. Starts empty, before anything is saved to it.
2. `bool` representing if the state existed before the load, or if it was just created.

```rad
load_state() -> error|map
```

```rad
state = load_state()                   // -> map containing previous state
state["count"] = (state["count"] or 0) + 1
save_state(state)
```

### save_state

Saves the script's state to persistent stash storage.

```rad
save_state(_state: map) -> error?
```

```rad
state = {"counter": 42, "last_run": now().date}
save_state(state)
print("State saved")
```

### write_stash_file

Writes content to a file in the script's stash directory.

```rad
write_stash_file(_path: str, _content: str) -> error?
```

```rad
write_stash_file("log.txt", "Script executed at " + now().time)
write_stash_file("data/results.json", json_data)
print("Data saved to stash")
```

## Strings

### color_rgb

Applies RGB coloring to input text. RGB values must be in range [0, 255]. Not all terminals support this.

```rad
color_rgb(_val: any, red: int, green: int, blue: int) -> error|str
```

```rad
color_rgb("Hello", red=255, green=0, blue=0)     // -> "Hello" (in bright red)
color_rgb(42, red=0, green=255, blue=128)        // -> "42" (in green-cyan)
color_rgb("test", red=300, green=0, blue=0)      // -> Error: RGB values must be [0, 255]
```

**Parameters:**

| Parameter | Type  | Description             |
| --------- | ----- | ----------------------- |
| `_val`    | `any` | Value to apply color to |
| `red`     | `int` | Red component (0-255)   |
| `green`   | `int` | Green component (0-255) |
| `blue`    | `int` | Blue component (0-255)  |

RGB values must be in range [0, 255]. Not all terminals support this.

### colorize

Assigns consistent colors to values from a set of possible values. The same value always gets the same color within the
same set.

```rad
colorize(_val: any, _enum: any[], *, skip_if_single: bool = false) -> str
```

```rad
names = ["Alice", "Bob", "Charlie"]
colorize("Alice", names)     // -> "Alice" (in consistent color)
colorize("Bob", names)       // -> "Bob" (in different consistent color)

// In rad blocks
names = ["Alice", "Bob", "Charlie", "David"]
rad:
    fields names
    names:
        map fn(n) colorize(n, names)
```

**Parameters:**

| Parameter        | Type           | Description                                    |
| ---------------- | -------------- | ---------------------------------------------- |
| `_val`           | `any`          | Value to colorize                              |
| `_enum`          | `any[]`        | Set of possible values for consistent coloring |
| `skip_if_single` | `bool = false` | Don't colorize if only one value in set        |

Useful for automatically coloring table data or distinguishing values in lists.

### count

Counts the number of non-overlapping instances of substring in string.

```rad
count(_str: str, _substr: str) -> int
```

```rad
count("hello world", "l")     // -> 3
count("banana", "na")         // -> 2
count("test", "xyz")          // -> 0
```

### ends_with

Checks if a string ends with a given substring.

```rad
ends_with(_val: str, _end: str) -> bool
```

```rad
ends_with("hello world", "world")    // -> true
ends_with("hello world", "hello")    // -> false
```

### hyperlink

Creates a clickable hyperlink in supporting terminals.

```rad
hyperlink(_val: any, _link: str) -> str
```

```rad
hyperlink("Visit Google", "https://google.com")    // -> Clickable "Visit Google" link
hyperlink("localhost", "http://localhost:3000")    // -> Clickable "localhost" link
hyperlink(42, "https://example.com")               // -> Clickable "42" link
```

Converts text into a terminal hyperlink that can be clicked in supported terminals.

### index_of

Finds the index of a target value within a string or list. Returns `null` if not found.

```rad
index_of(_subject: str|list, _target: any, *, n: int = 0, start: int = 0) -> int?
```

```rad
// String search
"hello world hello".index_of("hello")           // -> 0
"hello world hello".index_of("hello", n=1)      // -> 12
"hello world hello".index_of("hello", n=-1)     // -> 12
"hello".index_of("xyz")                         // -> null
"hello".index_of("xyz") ?? -1                   // -> -1
"hello".index_of("")                             // -> null (empty target)

// List search
["a", "b", "c", "b", "a"].index_of("b")        // -> 1
["a", "b", "c", "b", "a"].index_of("b", n=-1)  // -> 3
[1, 2, 3].index_of(99)                          // -> null
```

**Parameters:**

| Parameter  | Type       | Description                                           |
| ---------- | ---------- | ----------------------------------------------------- |
| `_subject` | `str|list` | The string or list to search within                   |
| `_target`  | `any`      | The value to search for                               |
| `n`        | `int = 0`  | Which occurrence to find (0=first, 1=second, -1=last) |
| `start`    | `int = 0`  | Position to start searching from                      |

Since the return type is `int?`, check the result against `null` before using
it as an `int` - the check narrows the type, satisfying `rad check`:

```rad
idx = ["a", "b"].index_of("b")
if idx != null:
    print(idx + 1)  // idx is int here, not int?
```

### lower

Converts a string to lowercase. Preserves color attributes.

```rad
lower(_val: str) -> str
```

```rad
lower("HELLO")          // -> "hello"
lower("Hello World")    // -> "hello world"
```

### matches

Tests whether `_str` matches the regular-expression `_pattern`. By default the pattern must match the whole string; pass `partial=true` to match any substring. Returns an `error` when the pattern is malformed.

```rad
matches(_str: str, _pattern: str, *, partial: bool = false) -> bool|error
```

```rad
matches("hello", "h.+o")               // -> true
matches("hello world", "world")        // -> false (default is full-string match)
matches("hello world", "world", partial=true)  // -> true
matches("abc", "(")                    // -> error: invalid regex
```

Unlike `split` and `replace`, `matches` has no `regex` parameter and always treats `_pattern`
as a regex. A literal `matches` would just be `==` (full match) or a substring test (partial),
neither of which needs a function.

See also: `replace`, `split`

### replace

Replaces every occurrence of a literal substring. Pass `regex=true` to treat `_find` as a regex pattern and enable capture-group references in `_replace`. Does not preserve string color attributes.

```rad
replace(_original: str, _find: str, _replace: str, *, regex: bool = false) -> str
```

```rad
replace("hello world", "world", "Rad")           // -> "hello Rad"
replace("1.2.3", ".", "-")                       // -> "1-2-3"
replace("cost: $5", "$5", "$10")                 // -> "cost: $10"
replace("abc123def", "\\d+", "XXX", regex=true)  // -> "abcXXXdef"
replace("Name: Charlie Brown", "Charlie (.*)", "Alice $1", regex=true) // -> "Name: Alice Brown"
```

`_find` is matched literally unless `regex=true`, so metacharacters like `.` and `(` need no
escaping in the default case. In literal mode `_replace` is inserted verbatim, `$` included -
safe for text relayed from elsewhere.

When `regex=true`, a pattern that fails to compile is an error. Patterns use Go's RE2 dialect,
which has no backreferences or lookaround.

**Group references in `_replace` (`regex=true` only):**

| Written       | Expands to                                          |
| ------------- | --------------------------------------------------- |
| `$0`          | The whole match                                     |
| `$N`          | Capture group `N`; `N` is the longest run of digits |
| `${N}`        | Capture group `N`, explicitly delimited             |
| `$$`          | A literal `$`                                       |
| Anything else | Left as written                                     |

A reference to a group that does not exist is left as written rather than expanding to an
empty string, so stray `$` in your replacement text survives intact.

Because `$N` consumes every following digit, use `${N}` when a literal digit has to follow a
group reference: `${1}0` inserts group 1 followed by `0`, while `$10` means group 10.

`${N}` collides with Rad's string interpolation, which would read `{1}` as an expression to
interpolate. Write the replacement as a raw string or escape the brace:

```rad
replace("Name: abc", "a(b)c", r"${1}0", regex=true)   // -> "Name: b0"
replace("Name: abc", "a(b)c", "$\{1}0", regex=true)   // -> "Name: b0"
```

See also: `split`, `matches`

### reverse

Reverses a string or list. Preserves color attributes for strings.

```rad
reverse(_val: str|list) -> str|list
```

```rad
reverse("hello")           // -> "olleh"
reverse([1, 2, 3, 4])      // -> [4, 3, 2, 1]
reverse("racecar")         // -> "racecar"
```

### split

Splits a string on a literal separator. Pass `regex=true` to treat `_sep` as a regex pattern instead. Does not preserve string color attributes.

```rad
split(_val: str, _sep: str, *, limit: int?, regex: bool = false) -> str[]
```

```rad
split("a,b,c", ",")                    // -> ["a", "b", "c"]
split("1.2.3", ".")                    // -> ["1", "2", "3"]
split("word1  word2", "\\s+", regex=true) // -> ["word1", "word2"]
split("abc123def", "\\d+", regex=true) // -> ["abc", "def"]
split("key=val=ue", "=", limit=1)      // -> ["key", "val=ue"]
split("a,b,c,d", ",", limit=2)         // -> ["a", "b", "c,d"]
```

`_sep` is matched literally unless `regex=true`, so metacharacters like `.` and `(` need no
escaping in the default case.

When `regex=true`, a pattern that fails to compile is an error. Patterns use Go's RE2 dialect,
which has no backreferences or lookaround.

When `limit` is provided, it caps the number of splits performed. The final element contains
the unsplit remainder. `limit` must be >= 1.

An empty `_sep` splits between every character.

See also: `split_lines`, `replace`, `matches`

### split_lines

Splits a string by line endings. Handles all common styles: `\n` (Unix), `\r\n` (Windows), and `\r` (legacy Mac).

```rad
split_lines(_val: str) -> str[]
```

```rad
"a\nb\nc".split_lines()          // -> ["a", "b", "c"]
content = read_file("data.txt").content
for line in content.split_lines():
    print(line)
```

Use this instead of `split("\n")` when processing text that may come from different platforms.

Trailing line endings are stripped - `"a\nb\n".split_lines()` returns `["a", "b"]`, not `["a", "b", ""]`.

### starts_with

Checks if a string starts with a given substring.

```rad
starts_with(_val: str, _start: str) -> bool
```

```rad
starts_with("hello world", "hello")  // -> true
starts_with("hello world", "world")  // -> false
```

### trim

Strips all matching characters from both ends of a string. Preserves color attributes.

```rad
trim(_subject: str, _chars: str = " \t\n") -> str
```

```rad
trim("  hello  ")            // -> "hello"
trim("***hello***", "*")     // -> "hello"
trim("abcHELLOabc", "abc")   // -> "HELLO"
```

### trim_left

Strips all matching characters from the start of a string. Preserves color attributes.

```rad
trim_left(_subject: str, _chars: str = " \t\n") -> str
```

```rad
trim_left("  hello  ")          // -> "hello  "
trim_left("***hello***", "*")   // -> "hello***"
trim_left("aaabbb", "a")        // -> "bbb"
```

### trim_prefix

Removes a literal prefix from the start of a string (once). Preserves color attributes.

```rad
trim_prefix(_subject: str, _prefix: str) -> str
```

```rad
trim_prefix("hello world", "hello ")  // -> "world"
trim_prefix("aaabbb", "a")            // -> "aabbb" (one 'a' removed)
trim_prefix("test", "x")              // -> "test" (no match)
```

### trim_right

Strips all matching characters from the end of a string. Preserves color attributes.

```rad
trim_right(_subject: str, _chars: str = " \t\n") -> str
```

```rad
trim_right("  hello  ")         // -> "  hello"
trim_right("***hello***", "*")  // -> "***hello"
trim_right("aaabbb", "b")       // -> "aaa"
```

### trim_suffix

Removes a literal suffix from the end of a string (once). Preserves color attributes.

```rad
trim_suffix(_subject: str, _suffix: str) -> str
```

```rad
trim_suffix("hello world", " world")  // -> "hello"
trim_suffix("aaabbb", "b")            // -> "aaabb" (one 'b' removed)
trim_suffix("test", "x")              // -> "test" (no match)
```

### truncate

Truncates a string to a maximum length, adding an ellipsis if truncated. Requires length of at least 1.

```rad
truncate(_str: str, _len: int) -> error|str
```

```rad
truncate("hello world", 8)   // -> "hello w…"
truncate("short", 10)        // -> "short" (no truncation needed)
truncate("test", 0)          // -> Error: Requires at least 1
```

### upper

Converts a string to uppercase. Preserves color attributes.

```rad
upper(_val: str) -> str
```

```rad
upper("hello")          // -> "HELLO"
upper("Hello World")    // -> "HELLO WORLD"
```

## System

### error

Creates an error object with the given message.

```rad
error(_msg: str) -> error
```

```rad
fn validate(x: int):
    if x < 0:
        return error("Something went wrong")
    return x

result = validate(-1)  // -> Script will exit with this error message
```

`return` at the top level isn't legal Rad - wrap it in a `fn` and
return the error from there, or assign it and propagate via `??` /
`catch:`.

### exit

Exits the script with the given exit code.

```rad
exit(_code: int|bool = 0) -> void
```

```rad
exit()          // -> Exits with code 0
exit(1)         // -> Exits with code 1
exit(true)      // -> Exits with code 1 (bool conversion)
exit(false)     // -> Exits with code 0 (bool conversion)
```

### get_args

Returns the raw command-line arguments passed to the script.

```rad
get_args() -> str[]
```

```rad
// If script was called: rad myscript.rad arg1 arg2 --flag
raw_args = get_args()  // -> ["./myscript.rad", "arg1", "arg2", "--flag"]
```

Returns all arguments after the script name. Unlike parsed args, this gives you raw access to all arguments.

The name `args` is reserved (it's the args-block keyword), so the
local has to be called something else.

### get_env

Retrieves the value of an environment variable.

```rad
get_env(_var: str) -> str
```

```rad
home_dir = get_env("HOME")                    // -> "/Users/username"
api_key = get_env("API_KEY") or "default"     // -> Uses default if not set
missing = get_env("NONEXISTENT")              // -> ""
```

Returns the environment variable value, or empty string if not set.

### get_os

Returns the operating system the script is running on.

```rad
get_os() -> str
```

```rad
os = get_os()
print(os)  // e.g. -> "macos"

config_dir = switch os:
    case "macos" -> "~/Library/Application Support"
    case "windows" -> get_env("APPDATA")
    default -> "~/.config"
```

Returns `"macos"`, `"linux"`, or `"windows"` on the three major platforms.
Other platforms return Go's `runtime.GOOS` (https://pkg.go.dev/runtime#GOOS)
value directly, e.g. `"freebsd"` or `"android"`.

Prefer this over shelling out to `uname`, which doesn't exist on Windows.

### get_path

Gets information about a file or directory path.

```rad
get_path(_path: str) -> { "exists": bool, "full_path": str, "base_name"?: str, "permissions"?: str, "type"?: str, "size_bytes"?: int, "modified_millis"?: int, "accessed_millis"?: int }
```

```rad
info = get_path("config.txt")
if info.exists:
    print("File size:", info.size_bytes, "bytes")
    print("Type:", info.type)
else:
    print("File not found")

// Working with timestamps using parse_epoch()
info = get_path("data.json")
if info.exists:
    mtime = info.modified_millis.parse_epoch()
    print("Last modified:", mtime.date, mtime.time)
```

**Always returns:**

- `exists: bool` - Whether the path exists
- `full_path: str` - Absolute path (a leading `~` in `_path` is expanded to your home directory)

**When path exists, also returns:**

- `base_name?: str` - File/directory name
- `permissions?: str` - Permission string (e.g., "rwxr-xr-x")
- `type?: str` - Either "file" or "dir"
- `size_bytes?: int` - File size (only for files)
- `modified_millis?: int` - Modification time as epoch milliseconds
- `accessed_millis?: int` - Access time as epoch milliseconds (Unix/macOS only)

### get_pid

Returns the process ID (PID) of the running Rad process.

```rad
get_pid() -> int
```

```rad
pid = get_pid()    // -> e.g. 12345
print("My PID: {pid}")
```

### has_stdin

Checks if stdin is piped to the script.

```rad
has_stdin() -> bool
```

```rad
has_stdin()                     // -> true (if piped)
has_stdin()                     // -> false (if not piped)
if has_stdin():
  content = read_stdin()        // Conditional read
```

### is_defined

Checks if a variable with the given name exists in the current scope.

```rad
is_defined(_var: str) -> bool
```

```rad
name = "Alice"
is_defined("name")     // -> true
is_defined("age")      // -> false
```

### signal_ignore

Installs OS-level `SIG_IGN` for one or more signals, so the process is not woken
when they fire. The disposition is inherited by subprocesses. Distinct from a
no-op `signal_trap` handler, which still wakes the process on every delivery.

```rad
signal_ignore(_signal: ["sigint", "sigterm", "sighup", "sigusr1", "sigusr2", "sigpipe", "sigwinch"] | ["sigint", "sigterm", "sighup", "sigusr1", "sigusr2", "sigpipe", "sigwinch"][]) -> void
```

```rad
// Don't crash when a downstream pipe consumer (e.g. `head`) closes early
signal_ignore("sigpipe")

for i in range(0, 1000000):
    print(i)  // safe to pipe into `head` now
```

The primary use case is `sigpipe`: a script that pipes its output (e.g.
`rad script.rad | head`) would otherwise terminate when the consumer closes the
pipe. Ignoring it at the OS level keeps the script alive.

On Windows, only `sigint` and `sigterm` are supported.

### signal_trap

Registers a function to run when one of the named signals is delivered to the
script. The handler receives a single map argument with the signal name and the
conventional `128 + sig` exit code. Re-registering replaces the previous handler.

```rad
signal_trap(_signal: ["sigint", "sigterm", "sighup", "sigusr1", "sigusr2", "sigpipe", "sigwinch"] | ["sigint", "sigterm", "sighup", "sigusr1", "sigusr2", "sigpipe", "sigwinch"][], _handler: fn(any) -> any) -> void
```

```rad
// Cleanup on Ctrl+C
signal_trap("sigint", fn(ctx):
    print_err("Cancelled, cleaning up")
    exit(ctx.exit_code)  // 130
)

// One handler for several signals, dispatching on the name
signal_trap(["sigterm", "sighup"], fn(ctx):
    if ctx.signal == "sighup":
        reload_config()  // no exit() - control continues
    else:
        exit(ctx.exit_code)
)

// Status dump - script keeps running after the handler returns
signal_trap("sigusr1", fn(ctx):
    print("progress: {progress}/{total}")
)
```

The handler is invoked with one **map** argument (the parameter name `ctx` is
conventional; call it whatever you like):

| Field       | Type | Description                                              |
| ----------- | ---- | -------------------------------------------------------- |
| `signal`    | str  | The signal that fired (e.g. `"sigint"`).                 |
| `exit_code` | int  | The conventional `128 + sig` exit code (130 for SIGINT). |

After the handler returns, **execution always continues**. To terminate, the
handler must explicitly call `exit()`. This matches Bash `trap`, Python's
`signal.signal`, Ruby's `Signal.trap`, and Node's `process.on`. The
always-continue rule applies only to a clean return: an **unhandled error in the
handler aborts the script** (exit 1) and runs `defer`/`errdefer`, just like an
unhandled error anywhere else.

There is currently no built-in way to restore the platform default; once a
signal is trapped, it stays trapped for the lifetime of the script.

**Supported signals:**

| Signal     | Trigger                               | Default action  |
| ---------- | ------------------------------------- | --------------- |
| `sigint`   | Ctrl+C from terminal                  | terminate (130) |
| `sigterm`  | `kill <pid>`, systemd/Docker shutdown | terminate (143) |
| `sighup`   | Terminal hangup; convention: "reload" | terminate (129) |
| `sigusr1`  | User-defined; convention: "status"    | terminate (138) |
| `sigusr2`  | User-defined; convention: "toggle"    | terminate (140) |
| `sigpipe`  | Write to closed pipe                  | terminate (141) |
| `sigwinch` | Terminal resized                      | ignore          |

**Caveats:**

- Handlers run at the next statement boundary - they do not preempt
  mid-statement. A signal arriving during a long computation only fires when
  control returns between statements.
- A second SIGINT while a SIGINT handler is in progress force-exits with code
  130, skipping defers - the escape hatch when a handler hangs.
- Subprocesses started with `$` share Rad's process group, so Ctrl+C reaches the
  subprocess directly and it terminates before the Rad handler runs. The handler
  still runs (so temp-file cleanup works), but it cannot influence the already-
  killed subprocess.
- On Windows, only `sigint` and `sigterm` are supported.

### sleep

Pauses execution for the specified duration.

```rad
sleep(_duration: int|float|str, *, title: str?) -> void
```

```rad
sleep(2.5)              // -> Sleep for 2.5 seconds
sleep("1h30m")          // -> Sleep for 1 hour 30 minutes
sleep("500ms")          // -> Sleep for 500 milliseconds
sleep("1d12h")          // -> Sleep for 1 day 12 hours
sleep(5, title="Waiting...") // -> Prints "Waiting..." then sleeps 5 seconds
```

Integer and float values are treated as seconds. String values support duration format like "2h45m", "1.5s", "500ms".
Spaces are allowed in duration strings (e.g. `"5m 30s"`).
If `title` is provided, it's printed before sleeping.

**Duration string suffixes:**

| Suffix       | Description  |
| ------------ | ------------ |
| `d`          | Days         |
| `h`          | Hours        |
| `m`          | Minutes      |
| `s`          | Seconds      |
| `ms`         | Milliseconds |
| `us` or `µs` | Microseconds |
| `ns`         | Nanoseconds  |

### type_of

Returns the type of a value as a string.

```rad
type_of(_var: any) -> ["int", "str", "list", "map", "float", "bool", "null", "error", "function"]
```

```rad
type_of("hi")            // -> "str"
type_of([2])             // -> "list"
type_of(42)              // -> "int"
type_of(3.14)            // -> "float"
type_of({"a": 1})        // -> "map"
type_of(true)            // -> "bool"
type_of(null)            // -> "null"
type_of(fn() 1)          // -> "function"
// Builtins that may fail return an `error` value:
// type_of(parse_int("xx")) // -> "error"
```

## Time

### format_epoch

Formats an epoch timestamp as a string. The inverse of `parse_date()`,
which reads such a string back into an epoch.

```rad
format_epoch(_epoch: int, _format: str, *, tz: str = "local", unit: ["auto", "seconds", "millis", "micros", "nanos"] = "auto") -> error|str
```

```rad
ts = format_epoch(1735689600, "YYYY-MM-DD HH:mm:ss", tz="UTC")
print(ts)  // -> "2025-01-01 00:00:00"

// Timestamped file names from now()
stamp = format_epoch(now().epoch.seconds, "YYYYMMDD-HHmmss")

// Works directly with get_path's modified_millis (unit auto-detected)
info = get_path("data.json")
if info.exists:
    print("Modified:", format_epoch(info.modified_millis, "YYYY-MM-DD"))

// Timezone conversion
print(format_epoch(1735689600, "HH:mm", tz="America/Chicago"))  // -> "18:00"
```

**Parameters:**

| Parameter | Type            | Description                                              |
| --------- | --------------- | -------------------------------------------------------- |
| `_epoch`  | `int`           | The epoch timestamp to format                            |
| `_format` | `str`           | Format string using tokens (see below)                   |
| `tz`      | `str = "local"` | Timezone (e.g., "UTC", "America/Chicago")                |
| `unit`    | `str = "auto"`  | Unit of `_epoch`. Auto-detects by digit count if omitted |

**Format tokens** (same vocabulary as `parse_date()`):

| Token  | Meaning               | Example |
| ------ | --------------------- | ------- |
| `YYYY` | 4-digit year          | `2026`  |
| `MM`   | 2-digit month (01-12) | `03`    |
| `DD`   | 2-digit day (01-31)   | `22`    |
| `HH`   | 2-digit hour, 24h     | `14`    |
| `mm`   | 2-digit minute        | `30`    |
| `ss`   | 2-digit second        | `00`    |

All other characters in the format string are treated as literal separators.
Avoid embedding prose text - tokens like `mm` and `ss` are matched inside
words too.

Note: `MM` (uppercase) is **month**, `mm` (lowercase) is **minute**. Mixing
these up will silently produce wrong output.

**Unit auto-detection** works like `parse_epoch()`: up to 10 digits is
seconds, 13 is millis, 16 is micros, 19 is nanos. Other lengths are ambiguous
and return an error - pass `unit` explicitly to disambiguate.

### now

Returns the current time with various accessible formats.

```rad
now(*, tz: str = "local") -> error|{ "date": str, "year": int, "month": int, "day": int, "weekday": int, "hour": int, "minute": int, "second": int, "time": str, "epoch": { "seconds": int, "millis": int, "nanos": int } }
```

```rad
time = now()
print("Current date:", time.date)          // -> "2024-04-05"
print("Current time:", time.time)          // -> "14:30:25"
print("Year:", time.year)                  // -> 2024

// Use epoch for timestamps
timestamp = now().epoch.seconds
print("Timestamp:", timestamp)             // -> 1712345678

// Different timezone
utc_time = now(tz="UTC")
print("UTC time:", utc_time.time)          // -> Time in UTC
```

**Parameters:**

| Parameter | Type            | Description                               |
| --------- | --------------- | ----------------------------------------- |
| `tz`      | `str = "local"` | Timezone (e.g., "UTC", "America/Chicago") |

Map values:

| Accessor         | Description                           | Type   | Example             |
| ---------------- | ------------------------------------- | ------ | ------------------- |
| `.date`          | Current date YYYY-MM-DD               | string | 2019-12-13          |
| `.year`          | Current calendar year                 | int    | 2019                |
| `.month`         | Current calendar month                | int    | 12                  |
| `.day`           | Current calendar day                  | int    | 13                  |
| `.weekday`       | ISO day of week (Monday=1..Sunday=7)  | int    | 5                   |
| `.hour`          | Current clock hour (24h)              | int    | 14                  |
| `.minute`        | Current minute of the hour            | int    | 15                  |
| `.second`        | Current second of the minute          | int    | 16                  |
| `.time`          | Current time in "hh:mm:ss" format     | string | 14:15:16            |
| `.epoch.seconds` | Seconds since 1970-01-01 00:00:00 UTC | int    | 1576246516          |
| `.epoch.millis`  | Millis since 1970-01-01 00:00:00 UTC  | int    | 1576246516123       |
| `.epoch.nanos`   | Nanos since 1970-01-01 00:00:00 UTC   | int    | 1576246516123456789 |

To render a timestamp as a custom string (e.g. for file names), pass
`.epoch.seconds` to `format_epoch`, e.g.
`format_epoch(now().epoch.seconds, "YYYYMMDD-HHmmss")`.

### parse_date

Parses a date string into the same time map format as `now()` and `parse_epoch()`.

```rad
parse_date(_date: str, *, format: str?, tz: str = "local") -> error|{ "date": str, "year": int, "month": int, "day": int, "weekday": int, "hour": int, "minute": int, "second": int, "time": str, "epoch": { "seconds": int, "millis": int, "nanos": int } }
```

```rad
// Auto-detect common formats
time = parse_date("2026-03-22")
print(time.date)              // -> "2026-03-22"
print(time.epoch.seconds)     // -> epoch at midnight local time

time = parse_date("2026-03-22T14:30:00Z")
print(time.hour)              // -> 14 (or local equivalent)

// Custom format for non-standard date strings
time = parse_date("22/03/2026", format="DD/MM/YYYY")
print(time.date)              // -> "2026-03-22"

time = parse_date("22.03.2026 14:30", format="DD.MM.YYYY HH:mm")
print(time.hour, time.minute) // -> 14 30

// Timezone conversion
time = parse_date("2026-03-22T14:30:00Z", tz="America/Chicago")
print(time.hour)              // -> 9 (CDT = UTC-5)

// Error handling
time = parse_date("bad input") catch:
    print(time)  // error message with format hints
```

**Parameters:**

| Parameter | Type            | Description                                                     |
| --------- | --------------- | --------------------------------------------------------------- |
| `_date`   | `str`           | The date string to parse                                        |
| `format`  | `str?`          | Format string using tokens (see below). Auto-detects if omitted |
| `tz`      | `str = "local"` | Timezone (e.g., "UTC", "America/Chicago")                       |

**Auto-detected formats** (when `format` is omitted):

- `YYYY-MM-DD` (e.g., `2026-03-22`)
- `YYYY-MM-DDTHH:mm:ss` (e.g., `2026-03-22T14:30:00`)
- `YYYY-MM-DDTHH:mm:ssZ` or with offset (e.g., `2026-03-22T14:30:00+05:00`)
- `YYYY-MM-DD HH:mm:ss` (space-separated)
- All of the above with optional fractional seconds (e.g., `.123456`)

**Format tokens** (for the `format` parameter):

| Token  | Meaning               | Example |
| ------ | --------------------- | ------- |
| `YYYY` | 4-digit year          | `2026`  |
| `MM`   | 2-digit month (01-12) | `03`    |
| `DD`   | 2-digit day (01-31)   | `22`    |
| `HH`   | 2-digit hour, 24h     | `14`    |
| `mm`   | 2-digit minute        | `30`    |
| `ss`   | 2-digit second        | `00`    |

All other characters in the format string are treated as literal separators. Format strings should
contain only tokens and separators - avoid embedding prose text, as tokens like `mm` and `ss` will be
matched inside words (e.g., "co**mm**it" or "acce**ss**").

Note: `MM` (uppercase) is **month**, `mm` (lowercase) is **minute**. Mixing these up will produce
wrong results or parse errors.

For strings without timezone information, the time is interpreted in the `tz` timezone (local by
default). For strings with timezone info (e.g., `Z`, `+05:00`), the time is parsed in that timezone
and then converted to the output `tz`.

### parse_epoch

Parses a Unix epoch timestamp into various time formats.

```rad
parse_epoch(_epoch: int|float, *, tz: str = "local", unit: ["auto", "seconds", "millis", "micros", "nanos", "milliseconds", "microseconds", "nanoseconds"] = "auto") -> error|{ "date": str, "year": int, "month": int, "day": int, "weekday": int, "hour": int, "minute": int, "second": int, "time": str, "epoch": { "seconds": int, "millis": int, "nanos": int } }
```

```rad
// Parse seconds epoch (auto-detected)
time = parse_epoch(1712345678)
print(time.date, time.time)  // -> "2024-04-05 22:01:18"

// Parse milliseconds with timezone
time = parse_epoch(1712345678123, tz="America/Chicago")
print(time.hour)  // -> Hour in Chicago timezone

// Explicit unit specification
time = parse_epoch(1712345678000, unit="millis")

// Float epoch with sub-second precision
time = parse_epoch(1712345678.5)  // 1712345678 seconds + 500ms
print(time.epoch.millis)  // -> 1712345678500

// Float with explicit unit (sub-millisecond precision)
time = parse_epoch(1712345678123.25, unit="millis")
print(time.epoch.nanos)  // -> 1712345678123250000

// Handle errors - inside the block, `time` is the error
time = parse_epoch(1712345678, tz="Invalid/Timezone") catch:
    print_err("Invalid timezone: {time}")
    exit(1)
```

**Parameters:**

| Parameter | Type                                                        | Description                                         |
| --------- | ----------------------------------------------------------- | --------------------------------------------------- |
| `_epoch`  | `int|float`                                                 | Unix epoch timestamp (float for sub-unit precision) |
| `tz`      | `str = "local"`                                             | Timezone (e.g., "UTC", "America/Chicago")           |
| `unit`    | `["auto", "seconds", "millis", "micros", "nanos"] = "auto"` | Timestamp unit (auto-detects by default)            |

Converts an epoch timestamp to the same format as `now()`. Auto-detects units from digit count, or specify
explicitly. When using a float, the fractional part provides sub-unit precision (e.g., `1712345678.5` seconds includes
500 milliseconds).

To render an epoch as a formatted string rather than a map, see
`format_epoch`. To go the other way, from a date string to an
epoch, see `parse_date`.

---

# Errors

This page lists every diagnostic code Rad can emit, with examples and fixes.
You can also read any entry from the terminal with `rad docs <code>`,
e.g. `rad docs RAD10001`.

Codes are grouped into bands by the phase that emits them. Retired codes
stay listed: numbers are never reused, so old logs remain greppable.

## Syntax Errors (RAD1xxxx)

### RAD10001: Invalid Syntax

This is a catch-all for syntax that doesn't match any expected pattern. The error
message describes the specific problem.

#### Example

```rad
x = 5

// Wrong - can't assign to an expression
x + 1 = 6

// Correct
y = x + 1
```

#### How to Fix

The caret (`^`) in the error message points to where the parser got confused. Check
for typos, missing punctuation, or mismatched brackets around that location.

If you think this error should have a more specific code, consider filing an issue.

### RAD10002: Missing Colon

A block-opening keyword (`if`, `elif`, `else`, `for`, `while`, `fn`,
`switch`, `case`, `defer`) appeared without the trailing `:` that
introduces its body.

#### Example

```rad
// Wrong - the 'if' header has no colon:
if true
    print("hello")
```

#### Fix

Add the missing `:` at the end of the header line:

```rad
if true:
    print("hello")
```

Every block-opening keyword needs the colon. Rad uses indentation
for block structure, but the colon is what tells the parser
"a block starts on the next line."

### RAD10003: Retired

This error code is no longer in use. Tree-sitter's error recovery
produces ERROR nodes for the shape this code was designed to catch,
so the dispatch in error_messages.go now falls back to **RAD10001**
("Invalid syntax") or **RAD10009** ("Unexpected token") instead.

The number stays reserved per the tombstone rule - we never reuse
retired codes, so old logs that mention RAD10003 remain greppable.

See `rad docs RAD10001` or `rad docs RAD10009` for the
modern equivalents.

### RAD10004: Retired

This error code is no longer in use. Tree-sitter's error recovery
produces ERROR nodes for the shape this code was designed to catch,
so the dispatch in error_messages.go now falls back to **RAD10001**
("Invalid syntax") or **RAD10009** ("Unexpected token") instead.

The number stays reserved per the tombstone rule - we never reuse
retired codes, so old logs that mention RAD10004 remain greppable.

See `rad docs RAD10001` or `rad docs RAD10009` for the
modern equivalents.

### RAD10005: Retired

This error code is no longer in use. Tree-sitter's error recovery
produces ERROR nodes for the shape this code was designed to catch,
so the dispatch in error_messages.go now falls back to **RAD10001**
("Invalid syntax") or **RAD10009** ("Unexpected token") instead.

The number stays reserved per the tombstone rule - we never reuse
retired codes, so old logs that mention RAD10005 remain greppable.

See `rad docs RAD10001` or `rad docs RAD10009` for the
modern equivalents.

### RAD10006: Retired

This error code is no longer in use. Tree-sitter's error recovery
produces ERROR nodes for the shape this code was designed to catch,
so the dispatch in error_messages.go now falls back to **RAD10001**
("Invalid syntax") or **RAD10009** ("Unexpected token") instead.

The number stays reserved per the tombstone rule - we never reuse
retired codes, so old logs that mention RAD10006 remain greppable.

See `rad docs RAD10001` or `rad docs RAD10009` for the
modern equivalents.

### RAD10007: Retired

This error code is no longer in use. Tree-sitter's error recovery
produces ERROR nodes for the shape this code was designed to catch,
so the dispatch in error_messages.go now falls back to **RAD10001**
("Invalid syntax") or **RAD10009** ("Unexpected token") instead.

The number stays reserved per the tombstone rule - we never reuse
retired codes, so old logs that mention RAD10007 remain greppable.

See `rad docs RAD10001` or `rad docs RAD10009` for the
modern equivalents.

### RAD10008: Reserved Keyword

A reserved keyword was used where an identifier was expected.

#### Example

```rad
// Wrong
args = 5

// Correct
arguments = 5
```

Currently `args` is reserved for declaring command-line arguments. Choose a
different name for your variable.

### RAD10009: Unexpected Token

The parser found a token that doesn't make sense in the current context.

#### Example

```rad
// Wrong
x = + 5

// Correct
x = 5
```

The caret (`^`) in the error message points to the unexpected token. Look for
extra symbols, misplaced keywords, or copy-paste errors around that location.

### RAD10010: Retired

This error code is no longer in use. Tree-sitter's error recovery
produces ERROR nodes for the shape this code was designed to catch,
so the dispatch in error_messages.go now falls back to **RAD10001**
("Invalid syntax") or **RAD10009** ("Unexpected token") instead.

The number stays reserved per the tombstone rule - we never reuse
retired codes, so old logs that mention RAD10010 remain greppable.

See `rad docs RAD10001` or `rad docs RAD10009` for the
modern equivalents.

### RAD10011: Retired

This error code is no longer in use. Tree-sitter's error recovery
produces ERROR nodes for the shape this code was designed to catch,
so the dispatch in error_messages.go now falls back to **RAD10001**
("Invalid syntax") or **RAD10009** ("Unexpected token") instead.

The number stays reserved per the tombstone rule - we never reuse
retired codes, so old logs that mention RAD10011 remain greppable.

See `rad docs RAD10001` or `rad docs RAD10009` for the
modern equivalents.

### RAD10012: Retired

This error code is no longer in use. Tree-sitter's error recovery
produces ERROR nodes for the shape this code was designed to catch,
so the dispatch in error_messages.go now falls back to **RAD10001**
("Invalid syntax") or **RAD10009** ("Unexpected token") instead.

The number stays reserved per the tombstone rule - we never reuse
retired codes, so old logs that mention RAD10012 remain greppable.

See `rad docs RAD10001` or `rad docs RAD10009` for the
modern equivalents.

### RAD10013: Retired

This error code is no longer in use. Tree-sitter's error recovery
produces ERROR nodes for the shape this code was designed to catch,
so the dispatch in error_messages.go now falls back to **RAD10001**
("Invalid syntax") or **RAD10009** ("Unexpected token") instead.

The number stays reserved per the tombstone rule - we never reuse
retired codes, so old logs that mention RAD10013 remain greppable.

See `rad docs RAD10001` or `rad docs RAD10009` for the
modern equivalents.

### RAD10014: Retired

This error code is no longer in use. Tree-sitter's error recovery
produces ERROR nodes for the shape this code was designed to catch,
so the dispatch in error_messages.go now falls back to **RAD10001**
("Invalid syntax") or **RAD10009** ("Unexpected token") instead.

The number stays reserved per the tombstone rule - we never reuse
retired codes, so old logs that mention RAD10014 remain greppable.

See `rad docs RAD10001` or `rad docs RAD10009` for the
modern equivalents.

### RAD10015: Retired

This error code is no longer in use. Tree-sitter's error recovery
produces ERROR nodes for the shape this code was designed to catch,
so the dispatch in error_messages.go now falls back to **RAD10001**
("Invalid syntax") or **RAD10009** ("Unexpected token") instead.

The number stays reserved per the tombstone rule - we never reuse
retired codes, so old logs that mention RAD10015 remain greppable.

See `rad docs RAD10001` or `rad docs RAD10009` for the
modern equivalents.

### RAD10016: Retired

This error code is no longer in use. Tree-sitter's error recovery
produces ERROR nodes for the shape this code was designed to catch,
so the dispatch in error_messages.go now falls back to **RAD10001**
("Invalid syntax") or **RAD10009** ("Unexpected token") instead.

The number stays reserved per the tombstone rule - we never reuse
retired codes, so old logs that mention RAD10016 remain greppable.

See `rad docs RAD10001` or `rad docs RAD10009` for the
modern equivalents.

### RAD10017: Retired

This error code is no longer in use. Tree-sitter's error recovery
produces ERROR nodes for the shape this code was designed to catch,
so the dispatch in error_messages.go now falls back to **RAD10001**
("Invalid syntax") or **RAD10009** ("Unexpected token") instead.

The number stays reserved per the tombstone rule - we never reuse
retired codes, so old logs that mention RAD10017 remain greppable.

See `rad docs RAD10001` or `rad docs RAD10009` for the
modern equivalents.

### RAD10018: Missing Indent

A block-opening header (`if x:`, `for ... :`, `fn name(...):`)
appeared but the next line wasn't indented relative to the header.
Rad uses indentation for block structure - the colon promises a
body, and the body has to live one indent level deeper.

#### Example

```rad
// Wrong - the 'if' body is at the same indent as the header:
if true:
y = 5
```

#### Fix

Indent the body. Convention is 4 spaces:

```rad
if true:
    y = 5
```

Tabs and spaces both work, but stay consistent within a file -
mixing them confuses the indentation tracker.

### RAD10019: Retired

This error code is no longer in use. Tree-sitter's error recovery
produces ERROR nodes for the shape this code was designed to catch,
so the dispatch in error_messages.go now falls back to **RAD10001**
("Invalid syntax") or **RAD10009** ("Unexpected token") instead.

The number stays reserved per the tombstone rule - we never reuse
retired codes, so old logs that mention RAD10019 remain greppable.

See `rad docs RAD10001` or `rad docs RAD10009` for the
modern equivalents.

### RAD10020: Unterminated String

A string literal opened with a quote but reached end-of-line (or
end-of-file) without a matching closing quote.

#### Example

```rad
// Wrong - no closing quote:
message = "Hello, world
```

#### Fix

Close the string with the same quote character it opened with:

```rad
message = "Hello, world"
```

Rad supports double quotes (`"`), single quotes (`'`), and
backticks (`` ` ``) - the close quote has to match the open. For
strings that genuinely span multiple lines, use backticks: they're
the multi-line string form and don't trip this check.

### RAD10021: Missing Operator

Two values appear next to each other without an operator between them.

#### Example

```rad
// Wrong
result = 5 3

// Correct
result = 5 + 3
```

Add an operator (`+`, `-`, `*`, `/`, `==`, `and`, `or`, etc.) between the values.

### RAD10022: Keyword Misuse

A keyword was used in a context where it doesn't belong.

#### Example

```rad
// Wrong
else:
    print("error")

// Correct
if condition:
    print("if branch")
else:
    print("else branch")
```

Keywords like `else` and `elif` must follow an `if`, `case` and `default` must be
inside a `switch`, and `break` and `continue` must be inside a loop.

### RAD10023: '#' Comment

A `#` was used to start a comment, but Rad comments use `//`.

#### Example

```rad
// Wrong
# compute the total

// Correct
// compute the total
```

The `#` habit usually comes from Python or shell. In Rad, `#` starts a comment
in exactly two places: the shebang line (`#!/usr/bin/env rad`) and inside
`args` blocks, where `# ...` after an argument declaration documents that
argument. Everywhere else, use `//`.

## Runtime Errors (RAD2xxxx)

### RAD20000: Generic Runtime Error

This is a catch-all for runtime errors that don't have a more specific error code. The error message itself describes what went wrong.

Read the error message carefully. If this error seems like it should have its own code, consider filing an issue at https://github.com/amterp/rad/issues

### RAD20001: Parse Int Failed

`parse_int()` couldn't convert the value to an integer.

#### Example

```rad
// These fail
parse_int("hello")   // Not a number
parse_int("12.5")    // Decimals not allowed
parse_int("")        // Empty string

// These work
parse_int("42")      // 42
parse_int("-10")     // -10
```

#### How to Fix

Handle the error or provide a fallback:

```rad
age = parse_int(input) ?? 0

// Or with logging
age = parse_int(input) catch:
    print_err("Invalid number: {age}")
    exit(1)
```

If your input might have decimals, parse as float first:

```rad
x = int(parse_float("12.5") ?? 0)  // 12
```

### RAD20002: Parse Float Failed

`parse_float()` couldn't convert the value to a floating-point number.

#### Example

```rad
// These fail
parse_float("hello")   // Not a number
parse_float("")        // Empty string
parse_float("1.2.3")   // Multiple decimal points

// These work
parse_float("3.14")    // 3.14
parse_float("42")      // 42.0
parse_float("1e10")    // Scientific notation
```

#### How to Fix

Handle the error or provide a fallback:

```rad
value = parse_float(input) ?? 0.0

// Or with logging
value = parse_float(input) catch:
    print_err("Invalid number: {value}")
    exit(1)
```

### RAD20003: File Read Error

Rad couldn't read the file.

#### Common Causes

- **File doesn't exist** - check the path
- **Permission denied** - you don't have read access
- **Path is a directory** - you tried to read a directory as a file

#### Example

```rad
content = read_file("/path/to/file.txt") catch:
    print_err("Could not read file: {content}")
    exit(1)
```

#### How to Fix

Check if the file exists before reading:

```rad
info = get_path("/path/to/file.txt")
if info.exists:
    content = read_file("/path/to/file.txt")
```

Or handle the error with a fallback:

```rad
path = "/path/to/file.txt"
content = read_file(path) ?? ""
```

### RAD20004: File Permission Denied

You don't have permission to access this file or directory.

#### Example

```rad
// Reading a protected file
content = read_file("/etc/shadow")

// Writing to a protected location
write_file("/usr/bin/myfile", "content")
```

#### How to Fix

1. **Check permissions** - use `ls -la` to see file permissions
2. **Use a different location** - write to a directory you control
3. **Handle the error**:

```rad
path = "/etc/shadow"
content = read_file(path) catch:
    print_err("Cannot read file: {content}")
    exit(1)
```

### RAD20005: File Does Not Exist

The file or directory wasn't found at the specified path.

#### Example

```rad
content = read_file("missing.txt")  // File doesn't exist
```

#### How to Fix

Check file existence first:

```rad
filepath = "missing.txt"
info = get_path(filepath)
if info.exists:
    content = read_file(filepath)
else:
    print("File not found: {filepath}")
```

Or handle the error:

```rad
filepath = "missing.txt"
content = read_file(filepath) catch:
    print_err("Could not read: {content}")
    exit(1)
```

Common issues: typos in the path, relative paths resolving to the wrong location, or case sensitivity on some filesystems.

### RAD20006: File Write Error

Rad couldn't write to the file.

#### Common Causes

- **Permission denied** - no write access to file or directory
- **Disk full** - no space left on device
- **Directory doesn't exist** - parent directory is missing

#### How to Fix

```rad
filepath = "out.txt"
content = "hello"
write_file(filepath, content) catch:
    print_err("Failed to write: {filepath}")
    exit(1)
```

Check that:
1. You have write access to the directory
2. The parent directory exists
3. There's enough disk space

### RAD20007: Ambiguous Epoch

The timestamp value is ambiguous - Rad can't tell if it's seconds or milliseconds since epoch.

#### What This Means

Unix timestamps come in two common formats:
- **Seconds** (10 digits): `1700000000`
- **Milliseconds** (13 digits): `1700000000000`

Some values fall in an ambiguous range where they could reasonably be either.

#### How to Fix

Use a timestamp with a clear magnitude, or use explicit parsing that specifies the unit. Timestamps around 10 digits are typically seconds; around 13 digits are typically milliseconds.

### RAD20008: Invalid Time Unit

The time-unit string passed to a time builtin isn't recognized.

#### Example

```rad
// Wrong - 'milliseconds' was renamed in v0.9
a = parse_epoch(1712345678000, unit="milliseconds")

// Correct
a = parse_epoch(1712345678000, unit="millis")
```

#### Valid Units

`parse_epoch` accepts:

- `"auto"` - the default, auto-detects based on magnitude
- `"seconds"`
- `"millis"`
- `"micros"`
- `"nanos"`

The longer aliases (`milliseconds`, `microseconds`, `nanoseconds`) were
removed in v0.9. See `rad docs migrations/v0.9`.

### RAD20009: Invalid Timezone

The timezone string isn't recognized.

#### Example

```rad
// Wrong - abbreviations aren't reliable
t = now(tz="PST")

// Correct - use IANA timezone names
t = now(tz="America/Los_Angeles")
t = now(tz="Europe/London")
t = now(tz="UTC")
```

#### Valid Timezones

Use IANA timezone database names (format: `Continent/City`):

- `UTC`
- `America/New_York`
- `America/Los_Angeles`
- `Europe/London`
- `Asia/Tokyo`

Full list: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones

### RAD20010: User Input Error

An error occurred while reading user input from an interactive prompt - such as `input()`, `confirm()`, or the confirmation prompt shown before a shell command (`confirm $\`...\`` or `--confirm-shell`).

This usually happens in one of two ways:

- **stdin isn't available** - for example, when running a script in a non-interactive context like a cron job or piped command.
- **You aborted the prompt** - pressing Ctrl-C or Esc at an interactive prompt cancels it and raises this error. (This is distinct from declining a shell confirmation by answering "n", which simply doesn't run the command.)

#### How to Fix

Check if interactive input is available:

```rad
if has_stdin():
    data = read_stdin()
else:
    print("No input available")
```

Or handle the error:

```rad
name = input("Enter name: ") catch:
    name = "default"
```

### RAD20011: Parse JSON Failed

`parse_json()` couldn't parse the input as valid JSON.

#### Example

```rad
// These fail (raw strings so {} aren't interpreted as interpolation)
parse_json(r"{invalid}")         // Missing quotes around key
parse_json(r"{'key': 'value'}")  // Single quotes not valid
parse_json(r"{key: value}")      // Unquoted strings

// These work
parse_json(r'{"key": "value"}')
parse_json('[1, 2, 3]')
parse_json('null')
```

#### Common Issues

- JSON requires **double quotes**, not single quotes
- Object keys must be **quoted strings**
- No **trailing commas** allowed
- No **comments** in JSON

#### How to Fix

```rad
text = r'{"key": "value"}'
data = parse_json(text) catch:
    print_err("Invalid JSON: {data}")
    exit(1)
```

### RAD20012: Internal Type Check Bug

This is a bug in Rad itself, not your script.

#### What to Do

Please report this at https://github.com/amterp/rad/issues with:

- The error message
- Your script (or a minimal version that reproduces it)
- Your Rad version (`rad --version`)
- Your operating system

### RAD20013: File Walk Error

An error occurred while traversing a directory with `find_paths()`.

#### Common Causes

- **Permission denied** - can't access a subdirectory
- **Symlink loops** - circular symbolic links
- **Directory removed** - directory deleted during traversal

#### How to Fix

```rad
dir = "."
files = find_paths(dir) catch:
    print_err("Failed to scan directory: {files}")
    exit(1)
```

Check that you have read access to all directories in the tree.

### RAD20014: Mutually Exclusive Arguments

Two command-line arguments that can't be used together were both specified.

#### Example

```rad
args:
    verbose bool
    quiet bool

    quiet excludes verbose
```

Running with `--verbose --quiet` triggers this error.

#### How to Fix

Use only one of the conflicting options. Run `--help` to see which arguments are mutually exclusive.

### RAD20015: Zip Strict Length Mismatch

`zip()` was called with `strict=true` on lists of different lengths.

#### Example

```rad
a = [1, 2, 3]
b = ["a", "b"]

pairs = zip(a, b, strict=true)  // Error: lengths 3 vs 2
```

#### How to Fix

Either make the lists the same length, or use non-strict mode (which truncates to the shortest):

```rad
a = [1, 2, 3]
b = ["a", "b"]
pairs = zip(a, b)  // Stops at shortest list: [[1, "a"], [2, "b"]]
```

### RAD20016: Cast Failed

A value couldn't be converted to the requested type - typically a
non-numeric string passed to `parse_int` / `parse_float`, or a value
of the wrong shape passed to `int(...)` / `float(...)`.

#### Example

```rad
x = parse_int("hello")  // "hello" isn't a number
```

`parse_int` and `parse_float` return an error value on failure, so the
script aborts at the use site unless the error is handled.

#### How to Fix

Handle the error with `??` (default) or `catch:` (block):

```rad
x = parse_int("hello") ?? 0
y = parse_float("3.14") ?? 0.0
```

Or branch on whether the input looks parseable before attempting:

```rad
raw = "hello"
n = parse_int(raw) catch:
    print_err("not a number: {raw}")
    exit(1)
```

### RAD20017: Number Out of Range

A numeric value is outside the valid range accepted by an operation.

#### Example

```rad
x = round(3.14159, -2)  // Error: precision must be non-negative
```

#### How to Fix

Check that values are within the bounds the operation accepts. For example,
`round` requires a non-negative precision, `to_json` a non-negative indent, and
`range` a non-zero step.

(An integer *literal* that doesn't fit in an int64 is a separate, compile-time
error - see RAD40015.)

### RAD20018: Empty List

An operation that requires at least one element was called on an empty list.

#### Example

```rad
items = []
first = items[0]       // No first element
max_val = max(items)   // Nothing to compare
```

#### How to Fix

Check the list length first:

```rad
items = []
if len(items) > 0:
    first = items[0]
else:
    first = "default"
```

Or use a ternary:

```rad
items = []
first = len(items) > 0 ? items[0] : "default"
```

### RAD20019: Argument Constraint Violated

A command-line argument didn't meet its declared constraint.

#### Example

```rad
args:
    level str
    level enum ["low", "medium", "high"]
```

Running with `--level ultra` fails because "ultra" isn't in the allowed values.

#### Constraint Types

- **Enum** - value must be one of the specified options
- **Regex** - value must match a pattern
- **Range** - numeric value must be within bounds

#### How to Fix

Run `--help` to see valid values. Constraints are case-sensitive.

### RAD20020: FID Generator Error

Rad failed to generate a unique identifier (FID). This is a system-level issue, not a problem with your script.

#### How to Fix

Retry the operation. If the error persists, file a bug report at:
https://github.com/amterp/rad/issues

### RAD20021: Decode Error

The input couldn't be decoded because it's not valid for the specified encoding.

#### Example

```rad
// Invalid base64 - contains characters not in base64 alphabet
decode_base64("not valid base64!!!")

// Correct
decoded = decode_base64("SGVsbG8gV29ybGQ=")
```

#### How to Fix

Verify the data matches the encoding you're using. If the data comes from an external source, handle potential errors:

```rad
data = "SGVsbG8gV29ybGQ="
decoded = decode_base64(data) catch:
    print_err("Invalid base64 data")
    exit(1)
```

### RAD20022: Stash ID Not Found

A stash function was called, but the script doesn't declare a stash ID.

Stashes scope persistent data per-script, so Rad needs to know which
script owns the data. Set the stash ID with `@stash_id` in the file
header.

#### Example

```rad
// Wrong: no @stash_id header, so any stash call fails at runtime.
result = load_stash_file("config.json", r'{"theme": "dark"}')
```

#### How to Fix

Add `@stash_id` to the file header:

```rad
---
@stash_id = my_script
---

// Now stash calls work. load_stash_file creates the file with the
// default content if it's not there yet. Pair with write_stash_file
// to update.
result = load_stash_file("config.json", r'{"theme": "dark"}')
```

To see existing stashes, run `rad stash list`.

See also: Stashes guide.

### RAD20023: Invalid Sleep Duration

The `sleep()` function received a duration it doesn't understand.

#### Example

```rad
// Wrong
sleep("abc")      // not a valid duration
sleep("5x")       // unknown unit

// Correct
sleep(1.5)        // 1.5 seconds (numbers are seconds)
sleep("500ms")    // 500 milliseconds
sleep("2s")       // 2 seconds
sleep("1m")       // 1 minute
sleep("1h")       // 1 hour
```

#### Valid Units

| Unit | Meaning      |
| ---- | ------------ |
| ms   | milliseconds |
| s    | seconds      |
| m    | minutes      |
| h    | hours        |

Numbers without units are treated as seconds.

### RAD20024: Invalid Regular Expression

The regex pattern has a syntax error.

#### Example

```rad
// Wrong: unclosed bracket
matches("hello", "[invalid")

// Correct
matches("hello", "[a-z]+")
matches("test123", "\\d+")
```

#### Common Mistakes

- Unclosed `[` or `(`
- Quantifiers (`*`, `+`, `?`) with nothing before them: `"*abc"` should be `".*abc"`
- Missing escape: use `\\d` for digits, `\\.` for literal dot

Rad uses Go's regex syntax. Test complex patterns with an online regex tester.

### RAD20025: Colorize Value Not in Enum

A colorization function received a value that wasn't in its predefined set.

When you configure color-based formatting (such as in table columns), you define which values map to which colors. This error means the data contained a value not in that mapping.

#### How to Fix

Either add the missing value to your color mapping, or ensure your data only contains expected values before colorizing.

### RAD20026: Stdin Read Error

Something went wrong while reading from standard input - the stream may have been closed or corrupted.

#### How to Fix

Check whether stdin is available before reading:

```rad
if has_stdin():
    data = read_stdin()
else:
    print_err("No input provided")
    exit(1)
```

### RAD20027: Invalid Check Duration

An invalid duration was specified for an internal operation.

This error is used internally for testing. If you encounter it unexpectedly, please file an issue at https://github.com/amterp/rad/issues.

### RAD20028: Undefined Identifier

You're referring to an identifier (a variable or function) that
hasn't been defined yet.

#### Example

```rad
username = "alice"
print(usernme)  // Error: typo - 'usernme' doesn't exist
```

#### Common Causes

- **Typos** - Check the spelling. Rad suggests similar names if it finds any.
- **Wrong order** - The variable must be assigned before you use it.
- **Scope** - Variables inside functions aren't visible outside:

```rad
fn setup():
    config = "value"  // only exists inside setup()

setup()
print(config)  // Error: config is not defined here
```

#### Note

Rad is case-sensitive: `MyVar` and `myvar` are different variables.

### RAD20029: Index Out of Bounds

You tried to access an index that doesn't exist in the list or string.

#### Example

```rad
items = ["a", "b", "c"]  // valid indices: 0, 1, 2
print(items[3])  // Error: index 3 out of bounds
```

Lists are 0-indexed, so a list with 3 elements has indices 0, 1, and 2.

#### How to Fix

Check the length before accessing:

```rad
items = ["a", "b", "c"]
index = 3
if len(items) > index:
    print(items[index])
```

Negative indices work too: `-1` is the last element, `-2` is second-to-last. But going past the start (e.g., `items[-10]` on a 3-element list) still causes this error.

### RAD20030: Break Outside Loop

`break` can only be used inside a loop. It exits the loop early.

#### Example

```rad
x = 10

// Wrong
if x > 5:
    break  // not inside a loop

// Correct
for i in range(10):
    if i > 5:
        break
    print(i)
```

#### Alternatives

- To exit a function: use `return`
- To exit the script: use `exit()`

See also: RAD20031 (Continue Outside Loop)

### RAD20031: Continue Outside Loop

`continue` can only be used inside a loop. It skips to the next iteration.

#### Example

```rad
x = 10

// Wrong
if x < 20:
    continue  // not inside a loop

// Correct
for i in range(10):
    if i % 2 == 0:
        continue  // skip even numbers
    print(i)
```

See also: RAD20030 (Break Outside Loop)

### RAD20032: Not Iterable

You tried to use `for` on something that can't be iterated.

#### Example

```rad
// Wrong: can't iterate over an int
for x in 42:
    print(x)

// Correct: iterate over a list, string, map, or range
for x in [1, 2, 3]:
    print(x)
```

#### Iterable Types

| Type   | Iterates over |
| ------ | ------------- |
| List   | elements      |
| String | characters    |
| Map    | keys          |
| Range  | numbers       |

Integers, floats, and booleans are not iterable.

### RAD20033: Unpack Mismatch

The number of variables doesn't match the number of values being unpacked.

#### Example

```rad
// Wrong: 3 values, 2 variables
a, b = [1, 2, 3]

// Correct
a, b, c = [1, 2, 3]
```

#### How to Fix

Either adjust the variable count, or use indexing if you only need some values:

```rad
items = [1, 2, 3]
first = items[0]
last = items[-1]
```

### RAD20034: Switch No Match

The `switch` value didn't match any case, and there's no `default`.

#### Example

```rad
status = "pending"
switch status:
    case "active":
        print("Active")
    case "inactive":
        print("Inactive")
// Error if status is something else like "pending"
```

#### How to Fix

Add a `default` case:

```rad
status = "pending"
switch status:
    case "active":
        print("Active")
    case "inactive":
        print("Inactive")
    default:
        print("Unknown status: {status}")
```

### RAD20035: Switch Multiple Match

The value matched more than one case, and Rad refuses to silently
prefer one over the other.

#### Example

```rad
name = "alice"
switch name:
    case "alice" -> print("ALICE")
    case "bob" -> print("BOB")
    case "charlie", name -> print("CHARLIE")
// Error: "alice" matches both the first and third cases
```

The third case binds `name` as one of its match keys, which makes any
`name` value match - so an input of `"alice"` overlaps with the first
case as well.

#### How to Fix

Make the cases mutually exclusive, or restructure as an `if`/`else
if` chain if you need guard-style logic:

```rad
name = "alice"
if name == "alice":
    print("ALICE")
else if name == "bob":
    print("BOB")
else:
    print("CHARLIE")
```

When the cases are constant literals, the static checker catches the
overlap as RAD40012 (Unreachable Case) before runtime. This runtime
error remains the safety net for overlaps that only show up once the
discriminant value is known.

### RAD20036: Division by Zero

You can't divide or modulo by zero.

#### Example

```rad
x = 10 / 0   // Error
y = 10 % 0   // Error
```

#### How to Fix

Check the divisor before using it:

```rad
value = 10
divisor = 0
if divisor != 0:
    result = value / divisor
else:
    result = 0  // or handle appropriately
```

### RAD20037: Negative Index

A negative index was used where it's not allowed.

Rad generally supports negative indexing (`-1` for the last element), so this error is rare. If you encounter it unexpectedly, please report it at https://github.com/amterp/rad/issues.

### RAD20038: Void Value

You tried to use the result of a function that doesn't return anything.

#### Example

```rad
fn greet():
    print("Hello!")
    // no return statement

result = greet()  // Error: greet() returns void
```

#### How to Fix

Either add a return value to the function:

```rad
fn greet():
    print("Hello!")
    return true
```

Or don't try to capture the result:

```rad
fn greet():
    print("Hello!")

greet()  // just call it
```

### RAD20039: Unsupported Operation

The operation you tried isn't supported for this type.

This is a general error - the message will tell you which operation failed and on what type. Check that you're using the right types and operators for what you're trying to do.

### RAD20040: Retired

This error code is no longer in use. The `assert()` built-in it was
designed to flag was never implemented; this doc previously described
a planned feature that didn't land.

The number stays reserved per the tombstone rule - we never reuse
retired codes, so old logs that mention RAD20040 remain greppable.

For runtime invariant checks today, use an explicit `if` + `exit()`:

```rad
items = [1, 2, 3]
if len(items) == 0:
    print_err("items must not be empty")
    exit(1)
```

### RAD20041: Key Not Found

You tried to access a map key that doesn't exist.

#### Example

```rad
data = {"name": "Alice", "age": 30}
print(data["email"])  // Error: 'email' not found
```

#### How to Fix

Check first, or use a default:

```rad
data = {"name": "Alice", "age": 30}

// Check first
if "email" in data:
    print(data["email"])

// Or use the ?? fallback operator
email = data["email"] ?? "unknown"
```

### RAD20042: Internal Bug

This is a bug in Rad, not your script. Something went wrong inside the interpreter.

#### What to Do

Please report this at https://github.com/amterp/rad/issues with:
- The error message and stack trace
- Your script (or a minimal version that reproduces it)
- Your Rad version (`rad --version`)
- Your OS

As a workaround, try restructuring the problematic code - sometimes a different approach avoids the bug.

### RAD20043: Failed to Parse Duration

A string passed to `parse_duration` could not be interpreted as a valid duration.

#### Example

```rad
parse_duration("invalid!")  // Error: failed to parse
parse_duration("5m23s")     // OK: 5 minutes 23 seconds
parse_duration("1d12h")     // OK: 1 day 12 hours
```

#### Valid Format

Duration strings support these suffixes: `w`, `d`, `h`, `m`, `s`, `ms`, `us`/`µs`, `ns`.
Combine them like `"1w2d"` or `"5m30s"`. Spaces are allowed (`"5m 30s"`).
A leading `-` negates the entire duration.

#### How to Fix

- Ensure the string contains valid duration suffixes
- Check for typos in the unit suffixes
- Use `catch` to handle the error if the input is dynamic

### RAD20044: Failed to Parse Date

A string passed to `parse_date` could not be interpreted as a valid date.

#### Example

```rad
parse_date("not-a-date")                          // Error: unrecognized format
parse_date("2026-03-22")                           // OK: ISO date
parse_date("2026-03-22T14:30:00Z")                 // OK: ISO datetime with timezone
parse_date("22/03/2026", format="DD/MM/YYYY")      // OK: custom format
```

#### Auto-Detected Formats

When no `format` is specified, `parse_date` tries these formats:

- `YYYY-MM-DDTHH:mm:ssZ` or `...+HH:MM` (RFC 3339, with optional fractional seconds)
- `YYYY-MM-DD HH:mm:ss+HH:MM` (space-separated with timezone offset, with optional fractional seconds)
- `YYYY-MM-DDTHH:mm:ss` (ISO datetime, with optional fractional seconds)
- `YYYY-MM-DD HH:mm:ss` (space-separated, with optional fractional seconds)
- `YYYY-MM-DD` (date only)

#### Format Tokens

When using the `format` parameter, these tokens are available:

| Token  | Meaning            | Example |
| ------ | ------------------ | ------- |
| `YYYY` | 4-digit year       | `2026`  |
| `MM`   | 2-digit month      | `03`    |
| `DD`   | 2-digit day        | `22`    |
| `HH`   | 2-digit hour (24h) | `14`    |
| `mm`   | 2-digit minute     | `30`    |
| `ss`   | 2-digit second     | `00`    |

Note: `MM` (uppercase) is month, `mm` (lowercase) is minute. Mixing these
up will produce wrong results or parse errors.

Format tokens are replaced wherever they appear in the format string,
including inside other text. Use format strings that contain only tokens
and separator characters (e.g. `DD/MM/YYYY`, `YYYY-MM-DD HH:mm:ss`).

#### How to Fix

- Check that your date string matches one of the auto-detected formats, or provide an explicit `format`
- Ensure the format tokens match the structure of your date string
- Use `catch` to handle the error if the input is dynamic

### RAD20045: Invalid Shell Command Value

A value used as a shell command, or interpolated into one, has no form Rad can
safely pass to a program.

Inside a shell command, the text you write is shell and the interpolations are
data. Rad quotes each interpolated value so it arrives as exactly one argument.
That only works for values with an obvious one-argument spelling: strings,
numbers and booleans. A map has none, and a null has one that is silently wrong
- it would become the four-character word `null`.

#### Examples

```rad
tag = null
$`git tag {tag}`        // Error: nothing sensible to pass

config = { "depth": 2 }
$`git clone {config}`   // Error: a map is not an argument
```

A list *is* allowed - it expands to one argument per element - but it has to
stand alone as its own argument, because there's no single obvious meaning for
gluing several arguments onto a prefix:

```rad
files = ["a.txt", "b.txt"]

$`rm {files}`           // Fine: rm a.txt b.txt
$`rm --file={files}`    // Error: which element gets the prefix?
```

The same rules apply when the whole command is a list:

```rad
$["git", "commit", "-m", null]   // Error
$[]                              // Error: no program to run
```

#### How to Fix

Give a null an explicit fallback, or leave the argument out entirely:

```rad
tag = null

$`git tag {tag ?? "untagged"}`
```

Build up the arguments as a list when some are conditional. Each element is one
argument, so nothing needs quoting:

```rad
message = "fix the parser"

cmd = ["git", "commit"]
if message:
    cmd += ["-m", message]
$cmd
```

Join a list yourself when you really do want one argument:

```rad
files = ["a.txt", "b.txt"]

$`tar -czf out.tgz {files}`             // three arguments
$`echo --files={files.join(",")}`       // one argument
```

#### Why Rad Works This Way

Bash's defining hazard is that a value carrying a space, a quote or a `$` stops
being a value and becomes syntax. Rad removes that by quoting interpolations for
you - but quoting only has an answer for things that *are* one argument. Rather
than invent a rendering for the rest and let it fail silently at runtime, Rad
asks you to say what you meant.

#### See Also

- `rad docs guide/shell-commands` - the three command forms and when to use each

### RAD20046: Interactive Input Required

The script asks the user something - via `input()`, `confirm()`, `pick()`, `multipick()`, or a `confirm`-gated shell command - but there is no terminal to ask at. Rad stops before running any of the script and tells you what it would have asked.

Rad looks for a terminal in two places: standard input, and `/dev/tty` (the terminal attached to your session, which works even when stdin is a pipe or a here-string). Both being unavailable means nothing interactive can happen: a CI job, a cron run, or an AI agent's tool call.

Nothing in the script has executed at this point. That is deliberate - discovering a prompt halfway through would leave you reasoning about a half-finished run before you could retry.

Rad exits `7` here, so a wrapper can tell "this run needs input" apart from "this run failed" without reading the message.

#### How to Fix

Answer each prompt up front with `--reply`, keyed by the line it sits on. Rad prints your own command back with a `--reply` per prompt: keys in place, answers left blank.

```
rad deploy.rad prod --reply '5:<yes|no>' --reply '6:<value>' --reply '7:<option>'
```

Replace the blanks and run it. Rad never fills them in - whether you mean yes, or which option you want, isn't in the script for it to read:

```
rad deploy.rad prod --reply 5:yes --reply 6:'shipped it' --reply 7:web-1
```

Answers are matched by kind, which is what the blank names. Nothing needs escaping except a `multipick`:

| Prompt                                  | Blank          | Answer                                                          |
| --------------------------------------- | -------------- | --------------------------------------------------------------- |
| `confirm`, `confirm $\`...\``           | `<yes|no>`     | `yes` / `no` (also `y`, `n`, `true`, `false`)                   |
| `input`                                 | `<value>`      | the rest of the value, taken verbatim                           |
| `pick`, `pick_kv`, `pick_from_resource` | `<option>`     | one option, matched exactly                                     |
| `multipick`                             | `<option,...>` | comma-separated; `\,` for a literal comma, `\\` for a backslash |

Only the first colon separates the key from the value, so `--reply 6:https://example.com` needs no quoting. A blank left unreplaced is taken literally: `confirm`, `pick`, and `multipick` reject it, and `input` answers with the text `<value>`.

A `multipick` answer must name each option at most once and satisfy the prompt's `min` and `max`. Give an empty value (`--reply 3:`) to select nothing.

#### Repeating a Prompt

A prompt inside a loop runs more than once. Repeat the key to answer each pass in order:

```
rad cleanup.rad --reply 12:yes --reply 12:no
```

Answers are queued per line rather than globally, so adding a prompt earlier in a script never silently re-targets a later answer. Running out mid-loop stops the script rather than reusing the last answer.

A prompt in a function called from several places repeats too, and then one key stands for several different questions:

```rad
fn ask(label):
    return input("Enter {label}: ")

host = ask("hostname")
user = ask("username")
print("{user}@{host}")
```

Answers bind in the order the calls run. Where rad can account for every execution it lists them, so that order is readable without opening the file:

```
deploy.rad:2  input may run more than once - repeat --reply per run
    reached from:
      4  host = ask("hostname")
      5  user = ask("username")
```

It says nothing where it cannot account for them all - a call inside a loop, a function passed around as a value, a caller that itself runs more than once, or a recursive function. A list missing one call would read exactly like a complete one.

Rad cannot count the passes for you either way; that depends on the script's own data. Where stopping partway would cost you something, read the script and count before you answer.

#### Prompts You Don't Expect To Reach

If a prompt sits on a branch this run won't take, say so instead of inventing a value:

```
rad deploy.rad --dry-run --reply-na 20
```

If the script reaches it anyway, rad fails cleanly (see RAD20047) rather than acting on a guess. Use this for a `pick` given a filter too, since a filtered pick often narrows to a single option and never asks. Where the options and the filter are both literal, rad works out the survivor itself and writes the `--reply-na` for you; where either is computed while the script runs, that call is yours to make.

#### Secret Inputs

A secret `input` cannot be answered this way at all. Command-line arguments are visible to other processes on the machine, so a password there would leak. Run the script where a terminal is available, or use `--reply-na` if this run won't reach it. Rad refuses the answer whether `secret` is a literal or computed while the script runs, though only a literal can be reported here rather than at the prompt.

#### Interactive Functions Used As Values

One shape takes no `--reply`: an interactive function passed around as a value rather than called.

```rad
ask = pick
answer = ask(["dev", "prod"])
```

Answers are keyed by the position of the call, and rad can't see where such a value ends up or how often it runs, so there is nothing for a value to attach to. Use `--reply-na` on its line to assert this run never invokes it - which is the usual answer for a handler map whose interactive entry isn't the one selected. If that assertion is wrong, the script stops at the prompt (see RAD20047) rather than guessing.

#### Scripts That Disable Global Options

A script setting `@enable_global_options = 0` removes `--reply` along with every other global flag, so its prompts can't be answered from the command line. Rad says so rather than suggesting a command the script would reject. Run it where a terminal is available, or re-enable global options in the script.

#### Related

- **RAD20047** - a prompt was reached that couldn't be answered.
- **RAD20010** - an interactive prompt failed or was canceled.

### RAD20047: Prompt Reached Without A Usable Answer

The script reached a prompt that `--reply` couldn't answer. Unlike RAD20046, this one fires mid-run, because it depends on something rad could not know before starting.

Whichever way you got here, the script ran up to this point. Check what it already did before you re-run it: a retry starts from the top.

#### The Prompt Was Marked Unreachable

You passed `--reply-na` for this line, asserting the run wouldn't reach it, and it did:

```
rad deploy.rad --reply-na 20
```

That assertion is a promise, not a fallback, so rad stops rather than guessing an answer. Either the branch you expected to skip was taken, or the assertion was aimed at the wrong line. Replace it with a real `--reply`, or work out why the branch ran.

#### The Answers Ran Out

A prompt inside a loop consumed every answer supplied for its line and was reached again:

```
rad cleanup.rad --reply 12:yes --reply 12:yes    # ran a third time
```

Rad does not reuse the last answer. One `yes` silently approving five hundred deletions is exactly the accident worth failing over. Supply as many answers as the loop has passes, or narrow what the loop iterates over.

A second shape lands here too, and rad cannot tell it from the first. A script that re-asks until it gets a value it accepts spends an answer on every attempt:

```rad
env = ""
while env not in ["prod", "staging"]:
    env = input("Environment? ")
```

`--reply 3:dev` is rejected, the loop comes back around, and there is nothing left to give it. Adding flags cannot fix this one - `--reply 3:dev --reply 3:dev` fails in exactly the same place. Answer with a value the script takes.

The message names both readings because only you can tell which applies. Count the passes if the prompt sits in a loop; check the value if the script validates it.

#### The Answer Matched No Option

A `pick` or `multipick` over runtime data - a fetched list, a resource file, a computed set - got an answer that isn't in it:

```rad
fn fetch_servers():
    return ["web-1", "web-2"]

server = pick(fetch_servers())
```

Rad can't check that up front, because the options don't exist until the script builds them. The error lists the real options, so the next run can name one exactly. Matching is exact by design: a near-miss fails rather than quietly acting on the wrong choice.

#### The Filter Already Chose

A `pick` given a filter that leaves one option takes it without asking. An answer naming anything else is a disagreement, and rad won't settle it by picking a side:

```rad
services = ["api", "worker", "scheduler"]
target = pick(services, "api", prefer_exact=true)
```

Here `--reply 2:worker` asks for one service and the script's own filter chose another. Usually the filter is the thing to change - it is normally built from an arg, so `worker` belongs there rather than in the answer.

An answer that names the option the filter settled on is consumed and the run carries on. Consuming it either way is what keeps a loop's answers in step with its passes, so a pick that settles on some passes and asks on others still lines up.

#### The Input Was Secret

`input` with `secret` set can't be answered from the command line at all - other processes on the machine can read your arguments. Where `secret` is written literally, RAD20046 says so before the script runs. Where it's computed, rad only finds out on reaching the prompt:

```rad
env = input("Environment")
needs_secret = env == "prod"
token = input("Token", secret=needs_secret)
```

Run it where a terminal is available, or use `--reply-na` if this run shouldn't reach it.

#### The Answer Broke A multipick's Rules

A `multipick` answer named an option twice, or gave more or fewer selections than the prompt allows. Where the bounds are literal, RAD20046 catches this up front; where they're computed, it surfaces here.

#### How to Fix

Rad prints the remaining prompts along with the failure, so a single re-run with the corrected `--reply` usually finishes the job.

#### Related

- **RAD20046** - prompts need answers, raised before the script runs.
- **RAD20010** - an interactive prompt failed or was canceled.

### RAD20048: Shell Command Exited Non-Zero

A shell command finished with a non-zero exit code and nothing handled it.

Shell commands are *critical by default* in Rad: a command that fails raises an
error, and an error nobody handles ends the script. That's the opposite of
bash, where a failing command is ignored unless you opt into `set -e`.

#### Examples

```rad
$`false`            // Error: Command exited with code 1
print("unreached")
```

The exit code carries through from whatever ran, so it tells you what happened:

```rad
$`grep nothing /etc/hosts`   // Error: Command exited with code 1 - grep found no match
```

#### How to Fix

Decide whether the failure is fatal. If it is, you may want a better message
than the default:

```rad
$`make build` catch:
    print_err("Build failed - is the toolchain installed?")
    exit(1)
```

If it isn't, say so. `catch: pass` continues without comment:

```rad
$`rm -f /tmp/scratch` catch:
    pass
```

If the exit code is *data* rather than a failure - `grep` exiting 1 means "no
match", not "something went wrong" - capture it. Capturing the code doesn't stop
the error, so pair it with `catch:`:

```rad
code, stdout = $`grep hello /etc/hosts` catch:
    stdout = ""

if code == 0:
    print("found: {stdout.trim()}")
else:
    print("no match")
```

#### Two Failures That Aren't The Command's

Two cases report through this error even though the command never produced the
code itself:

- **You declined a `confirm`.** Declining reports exit code 1, so a declined
  command behaves exactly like one that ran and failed. Capture targets are set
  to empty output rather than left undefined.
- **The command couldn't be started at all.** A binary that isn't installed
  reports 127, and one that isn't executable reports 126 - the same numbers a
  POSIX shell uses. A line on stderr names what went wrong.

```rad
$["definitely_not_installed"] catch:
    print("not available, skipping")
```

#### See Also

- `rad docs guide/shell-commands` - capture, modifiers, and the three command forms
- `rad docs guide/error-handling` - `??`, the `catch` operator, and `catch:` blocks

### RAD20049: Construct Not Available In The REPL

You typed an `args` block, a command block, or a file header at the REPL. All
three describe how a *script* is invoked from the command line, and a REPL
session was never invoked from anywhere.

An `args` block declares the flags and positionals rad parses out of `argv`
before the script runs. A command block declares a subcommand. A file header is
the docstring rad prints in that script's usage. None of them has a meaning at
a prompt, and the REPL says so rather than accepting them and doing nothing.

#### Examples

```rad
args:
    name str
    count int = 1
```

```rad
command greet:
    name str
    calls do_greet

fn do_greet():
    print("hello {name}")
```

#### How to Fix

Put the script in a file, then load it:

```
:load ./greet.rad
```

`:load` runs the file's statements against your session, so functions and
variables it defines are yours to use afterwards. Its `args` block is skipped,
because there are still no command-line arguments to parse.

To work on the values an `args` block would have produced, assign them:

```rad
name = "world"
count = 3
```

To try the real argument parsing, run the script:

```
rad greet.rad --name world
```

#### See Also

- `rad docs guide/repl` - what a session can and cannot do
- `rad docs guide/args` - declaring a script's command-line interface

## Type Errors (RAD3xxxx)

### RAD30001: Type Mismatch

A value of one type was used where a different type was expected.

#### Example

```rad
fn double(n: int) -> int:
    return n * 2

x = "42"
double(x)  // Error: expected int, got string
```

#### How to Fix

Use the right type, or fix the function/variable annotation:

```rad
fn double(n: int) -> int:
    return n * 2

x = 42        // use int directly
double(x)
```

If you must convert from another type, note that the conversion
functions (`int`, `float`, etc.) can fail and return `T|error`, so
you need to handle the error case before using the result:

```rad
x = "42"
n = int(x) catch:
    print_err("Not a number: {x}")
    exit(1)
print(n)
```

#### Type Conversion Functions

| Function       | Description                     |
| -------------- | ------------------------------- |
| `int(value)`   | Convert to integer (or `error`) |
| `float(value)` | Convert to float (or `error`)   |
| `str(value)`   | Convert to string               |
| `bool(value)`  | Convert to boolean              |

### RAD30002: Invalid Type for Operation

An operator was used with types that don't support that operation.

#### Example

```rad
count = 5

// Wrong: can't add int to string
x = "count: " + count

// Correct: use interpolation (preferred)
x = "count: {count}"

// Correct: explicit conversion
x = "count: " + str(count)
```

#### Supported Type Combinations

| Operator             | Works with                                                                  |
| -------------------- | --------------------------------------------------------------------------- |
| `+`                  | int+int, float+float, str+str, str+error, error+str, error+error, list+list |
| `-`, `*`, `/`        | int, float                                                                  |
| `%`                  | int                                                                         |
| `==`, `!=`           | any types                                                                   |
| `<`, `>`, `<=`, `>=` | int, float, str                                                             |
| `and`, `or`          | any (uses truthiness)                                                       |

#### How to Fix

Use interpolation to mix types in strings - it handles any type automatically:
`"Value: {x}"`. Alternatively, convert types explicitly with `int()`, `float()`, or `str()`.

> **v0.9 Migration Note:** The `+` operator no longer coerces types. If you're seeing this
> error after upgrading, see `rad docs migrations/v0.9`.

### RAD30003: Cannot Format

A value couldn't be formatted with the given format specifier.

#### Example

```rad
x = "hello"
print("{x:.2}")  // Error: precision (.2) needs a number, got string

// Fix: use a compatible specifier or convert first
print("{x}")               // Default works for any type
print("{parse_int('42'):,}")  // Convert before formatting
```

#### Format Specifiers

| Specifier  | Requires | Example                       |
| ---------- | -------- | ----------------------------- |
| `{x}`      | any type | Default formatting            |
| `{x:10}`   | any type | Right-align, width 10         |
| `{x:<10}`  | any type | Left-align, width 10          |
| `{x:*>10}` | any type | Fill with `*`, right-align    |
| `{x:.<10}` | any type | Fill with `.`, left-align     |
| `{x:05}`   | any type | Zero-pad shorthand, width 5   |
| `{x:<05}`  | any type | Zero-pad, left-align          |
| `{x:0>5}`  | any type | Explicit zero fill (any type) |
| `{x:.2}`   | number   | Precision (2 decimals)        |
| `{x:,}`    | number   | Thousands separator           |
| `{x:010,}` | number   | Zero-pad + thousands          |

The zero-pad shorthand (`{x:05}`) works on any type. For numbers,
it is sign-aware (negative signs placed before zeros). For other
types, it simply prepends zeros (same as `{x:0>5}`).

### RAD30004: Cannot Index

Indexing was attempted on a type that doesn't support it.

#### Example

```rad
// Wrong: can't index an integer
x = 42
print(x[0])

// Correct: index lists, strings, or maps
items = [1, 2, 3]
print(items[0])      // 1

text = "hello"
print(text[0])       // "h"

data = {"a": 1}
print(data["a"])     // 1
```

#### Indexable Types

| Type    | Syntax                                |
| ------- | ------------------------------------- |
| Lists   | `items[0]`, `items[-1]`, `items[1:3]` |
| Strings | `text[0]`, `text[-1]`, `text[1:3]`    |
| Maps    | `data["key"]`                         |

To index a number's digits, convert it first: `str(12345)[0]` gives `"1"`.

### RAD30005: Cannot Assign

Assignment was attempted to something that can't be assigned to.

#### Example

```rad
items = [1, 2, 3]
data = {"k": "value"}

// Wrong
5 = x
get_value() = 5

// Right: assign to variables or index expressions
x = 5
items[0] = 10
data["key"] = "value"
a, b = [1, 2]
```

The left side of `=` must be a variable, index expression, or unpacking pattern.

### RAD30006: Invalid Argument Type

A function received an argument of the wrong type.

#### Example

```rad
// Wrong: len() expects a collection
len(42)

// Correct
len([1, 2, 3])  // 3
len("hello")    // 5
```

The error message tells you what type was expected. Convert with `int()`,
`str()`, `list()`, etc. if needed.

### RAD30007: Wrong Argument Count

A function was called with too few or too many arguments.

#### Example

```rad
fn add(a, b):
    return a + b

add(5)        // Error: missing argument 'b'
add(1, 2, 3)  // Error: too many arguments
```

#### How to Fix

Check the function signature. Use `rad docs reference/functions` to see the
expected arguments for built-in functions.

```rad
fn add(a, b):
    return a + b

add(5, 10)  // Correct: two arguments
```

Named arguments can help clarify which is which:

```rad
fn process(input, output):
    print("Processing {input} -> {output}")

value = "in.txt"
dest = "out.txt"
process(input=value, output=dest)
```

### RAD30008: Cannot Compare

Two values cannot be compared with the given comparison operator.

This error code is reserved and may not currently appear in practice. Most
types can be compared for equality, and ordering comparisons work on compatible
types.

If you encounter this error, please report it: https://github.com/amterp/rad/issues

### RAD30009: Cannot Convert

A type conversion is not possible between the given types.

This error code is reserved and may not currently appear in practice. Most
conversions use dedicated functions like `int()`, `str()`, etc. which have
their own error handling.

If you encounter this error, please report it: https://github.com/amterp/rad/issues

### RAD30010: Collection Element Mismatch

A list element or map value was assigned a value that doesn't match
the collection's declared element/value type. Indexed assignment
(`xs[i] = v` or `m[k] = v`) is the only static mutation surface on
typed collections today, so this is where the gap shows up.

#### Example

```rad
xs: int[] = [1, 2, 3]
xs[0] = "wrong"        // Error: 'str' not assignable to element 'int'

m: { str: int } = { "a": 1 }
m["b"] = "nope"        // Error: 'str' not assignable to value 'int'
```

#### How to Fix

Use a value of the declared element type:

```rad
xs: int[] = [1, 2, 3]
m: { str: int } = { "a": 1 }

xs[0] = 99             // int into int[]
m["b"] = 2             // int into { str: int }
```

Or, if the collection genuinely holds mixed values, widen the
declared type so the assignment lands in scope:

```rad
xs: (int|str)[] = [1, "two", 3]
xs[0] = "wrong"        // ok: 'str' is in the (int|str) element type
```

#### When the Check Skips

The check is opt-in via annotation. Untyped locals (`xs = [1, 2]`)
infer a non-narrow element type and don't trigger this diagnostic.
Containers typed as the open `list` or `map` (no element type) also
skip - they're already "any element goes."

### RAD30011: Unhandled Fallible Call

Calling a function that can fail (returns `... | error`) without handling the
error case.

```rad
port_str = "8080"
port = parse_int(port_str)   // RAD30011: this call can fail; the error isn't handled
print(port + 1)
```

#### Why this happens

Functions like `parse_int`, `parse_float`, and `parse_json` return a union of a
success type and `error` (e.g. `int | error`). At runtime, if the call fails and
nothing handles the error, the script halts. The checker points this out so the
failure path is a deliberate choice rather than an accident.

Note this is a hint, not an error: the script still runs, and succeeds whenever
the call succeeds. The success type flows on (`port` above is `int`), so later
uses type-check normally.

#### How to fix it

Handle the error with `catch` to supply a fallback value:

```rad
port_str = "8080"
port = parse_int(port_str) catch 8080
print(port + 1)
```

Or use `??` for the same effect more tersely:

```rad
port_str = "8080"
port = parse_int(port_str) ?? 8080
print(port + 1)
```

Use a `catch` block when the recovery needs more than a single fallback value:

```rad
port_str = "8080"
port = parse_int(port_str) catch:
    print("invalid port, using default")
    yield 8080
print(port + 1)
```

## Validation & Lint Errors (RAD4xxxx)

### RAD40001: Scientific Notation Not a Whole Number

Scientific notation was used where an integer is required, but the result has
a fractional part.

#### Example

```rad
args:
    count int = 1.5e1  # Error: 15.0 is not a whole number
```

These produce whole numbers and are fine:

```rad
args:
    count int = 1e3    # 1000
    batch int = 2e2    # 200
```

#### What This Means

Scientific notation like `1e3` means 1 x 10^3 = 1000. When used where an integer
is expected, the result must be a whole number. `1.5e1` produces 15.0, which
has an implicit decimal part.

Use plain integers (`1000`) or ensure the notation produces an exact integer.

### RAD40002: Function Shadows Argument

A function has the same name as a command-line argument.

#### Example

```rad
args:
    count int

fn count():  // Error: shadows the 'count' argument
    return 5
```

Rad hoists function definitions to the top of the scope, so this would hide
the argument value and make it inaccessible.

#### How to Fix

Rename either the function or the argument:

```rad
args:
    count int

fn get_count():  // Renamed function
    return count
```

### RAD40003: Unknown Function

A function was called that hasn't been defined.

#### Example

```rad
greet("Alice")  // Error: 'greet' is not defined

// Fix: define the function first
fn greet(name):
    print("Hello, {name}!")

greet("Alice")
```

#### How to Fix

1. **Check spelling** - Rad suggests similar names if any exist
2. **Define the function** - Add the function definition before the call
3. **Check scope** - Ensure the function is visible where you're calling it

Built-in functions like `print`, `len`, and `int` are always available.

### RAD40004: Return Outside Function

A `return` statement appeared outside of a function body.

#### Example

```rad
// Wrong
x = 10
return x  // Error: not inside a function

// Correct
fn get_value():
    return 10

result = get_value()
```

#### How to Fix

- **To end the script early**, use `exit()`: `exit(1)` for failure, `exit(0)`
  for success
- **Check indentation** - The return might be accidentally de-indented outside
  the function body
- **Wrap in a function** if you need return semantics at top level

### RAD40005: Yield Outside Switch Case

A `yield` statement appeared outside of a switch-case block. `yield` is
how a multi-statement switch arm returns its result to the surrounding
switch expression.

#### Example

```rad
// Wrong - yield at top level
yield 5  // Error: not inside a switch case

// Correct - yield inside a switch-case block
value = "a"
result = switch value:
    case "a":
        x = 10
        yield x * 2
    case "b" -> 20
    default -> 0
```

In single-expression switch arms you use `->` instead; `yield` is only
needed when an arm has multiple statements and wants to return a value.

### RAD40006: Invalid Assignment Target

The left side of an assignment isn't something that can be assigned to.

#### Example

```rad
items = [1, 2, 3]
data = {"k": "v"}

// Wrong
5 = x
a + b = 10

// Valid assignment targets
x = 5              // Variable
items[0] = 10      // List element
data["key"] = "v"  // Map entry
a, b = [1, 2]      // Unpacking
x += 1             // Compound
```

The left side of `=` must be a variable, index expression, or unpacking pattern.

### RAD40007: Rad Option Has No Effect

A rad block option was used in a context where it has no effect.

#### Example

```rad
// 'insecure' and 'quiet' only apply to URL sources, so using them
// on a sourceless rad block is pointless.
rad:
    insecure    // Warning: no URL to apply this to
    quiet       // Warning: no URL to apply this to
    fields Name

// 'noprint' has no effect without a source because sourceless rad
// blocks use a save/restore pattern -- mutations aren't preserved.
rad:
    noprint     // Warning: mutations aren't preserved anyway
    fields Name
```

Note: when a source expression is provided (e.g. `rad data:`), the source
could resolve to either a URL or a list/map at runtime, so no static
warning is emitted -- both code paths are legitimate.

#### How to Fix

1. **Remove the option** if it's not needed
2. **Use a URL source** if you need `insecure` or `quiet`
3. **Add a source** if you need `noprint` to suppress printing

### RAD40008: Deprecated Block Keyword

The `request` and `display` block keywords have been removed in v0.9.
All rad block variants now use the unified `rad` keyword.

#### Migration

Replace `request` and `display` with `rad`:

```rad
data = [{"name": "Alice", "age": 30}]
Name = json[].name
Age = json[].age

// Before (no longer works)
request "https://api.example.com/data":
    fields Name, Age

display data:
    fields Name, Age

// After
rad "https://api.example.com/data":
    noprint
    fields Name, Age

rad data:
    fields Name, Age
```

**Important:** `request` blocks never printed a table - they only fetched
data and populated fields. The unified `rad` block prints by default, so
add `noprint` when migrating from `request` if you don't want table output.

The `rad` keyword now handles all source types:

- **URL source**: `rad "https://...":` (replaces `request` - add `noprint` to keep old behavior)
- **List/map source**: `rad myData:` (replaces `display`)
- **No source**: `rad:` (replaces `display` with no argument)

See `rad docs migrations/v0.9` for full details.

### RAD40009: Duplicate Parameter

A function or lambda has two parameters with the same name. Parameter
names must be unique within a single parameter list so the body can
refer to each one unambiguously.

#### Example

```rad
// This is an error: 'x' is declared twice.
fn add(x, x):
    return x + x
```

#### Fix

Rename one of the parameters so each binding has a distinct name:

```rad
fn add(a, b):
    return a + b
```

Shadowing an outer-scope name with a parameter is fine - that's a
common pattern. This error only fires when two parameters of the
same function or lambda collide with each other.

### RAD40010: Non-Exhaustive Switch

A `switch` over a closed type (today: string-enum) doesn't cover
every value in the type, and there's no `default` arm to catch the
rest. At runtime the unmatched values would fail with
`ErrSwitchNoMatch` (RAD20034); the static check surfaces the gap
before the script runs.

#### Example

```rad
// 'c' is not covered.
fn render(name: ["a", "b", "c"]):
    switch name:
        case "a":
            print("AAA")
        case "b":
            print("BBB")
```

#### Fix

Either add a case for the missing value:

```rad
fn render(name: ["a", "b", "c"]):
    switch name:
        case "a":
            print("AAA")
        case "b":
            print("BBB")
        case "c":
            print("CCC")
```

...or add a `default` arm to catch the rest:

```rad
fn render(name: ["a", "b", "c"]):
    switch name:
        case "a":
            print("AAA")
        default:
            print("other")
```

Open-typed discriminants (plain `str`, `int`, etc.) never trigger
this warning. Exhaustiveness only applies when the static type is a
finite set the checker can enumerate.

### RAD40011: Duplicate Typed Declaration

A name was declared with a type annotation (`x: T = ...`) when `x`
was already declared in the same scope. The declared type is part of
the binding's contract: re-declaring would either silently change
the type out from under earlier assignments or duplicate information
the reader has to reconcile. Either way it's a refactor hazard, so
the static checker rejects it.

#### Example

```rad
// This is an error: 'bb' was already declared on line 1.
bb: int = 5
bb: str = "hi"
```

Same-type re-declarations are flagged for the same reason - they're
almost always leftover scaffolding from an edit:

```rad
// Also an error.
bb: int = 5
bb: int = 6
```

#### Fix

If you want to reassign, drop the annotation. The original declared
type still applies, and the checker enforces it:

```rad
bb: int = 5
bb = 6
```

If you really meant to introduce a new variable, give it a fresh
name. Rad doesn't currently support intentional re-declaration in
the same scope.

### RAD40012: Unreachable Case

A `switch` case key matches a value that was already matched by an
earlier arm. The later arm can never be reached at runtime, so it's
almost always dead code - either a copy-paste mistake or leftover
scaffolding from an edit.

#### Example

```rad
name = "a"

// This is an error: 'a' is matched by the first case.
switch name:
    case "a":
        print("first")
    case "a":
        print("second")
```

Multi-key cases get the same treatment - any single key that
collides with an earlier arm is flagged:

```rad
name = "b"

// 'b' on line 4 is unreachable.
switch name:
    case "a", "b":
        print("first")
    case "b", "c":
        print("second")
```

#### Fix

Remove the redundant key. If you wanted both branches to execute
the same body, merge them:

```rad
name = "a"
switch name:
    case "a", "b":
        print("matched")
```

Or, if the second arm was supposed to match a different value,
correct the key:

```rad
name = "a"
switch name:
    case "a":
        print("first")
    case "b":
        print("second")
```

Only static literals are checked (strings, ints, floats, bools).
Cases keyed by variables, function calls, or other expressions
are left alone - the analyzer can't prove they collide.

### RAD40013: Case Key Not In Discriminant Type

A `switch` case key has a value that the discriminant can never
hold. The arm is unreachable not because of an earlier `case`
(that's `RAD40012`), but because the discriminant's
*type* statically forbids the value.

This typically surfaces after a refactor: an enum variant gets
renamed and the old spelling lingers in a switch.

#### Example

```rad
fn classify(name: ["a", "b", "c"]):
    // 'wat' is not in the closed type ["a", "b", "c"];
    // `name` can never equal it.
    switch name:
        case "a":
            print("first")
        case "b":
            print("second")
        case "c":
            print("third")
        case "wat":           // RAD40013
            print("unreachable")
```

#### Fix

Drop the stale arm:

```rad
fn classify(name: ["a", "b", "c"]):
    switch name:
        case "a":
            print("first")
        case "b":
            print("second")
        case "c":
            print("third")
```

Or correct the key to one of the type's allowed values:

```rad
fn classify(name: ["a", "b", "c"]):
    switch name:
        case "a":
            print("first")
        case "b":
            print("second")
        case "c":
            print("third")
```

#### When the check fires

The check only fires when the discriminant has a closed value
set the analyzer can enumerate. Today that means string-enum
types (e.g. `["a", "b", "c"]`). Open `str` / `int` discriminants
have no enumerable domain, so the check stays silent.

Only static literal keys are checked. Cases keyed by
identifiers, calls, or other expressions are left alone - the
analyzer can't prove they fall outside the domain.

### RAD40014: Unknown Map Key

A map access reads a key that the map's *type* doesn't declare. The
access is guaranteed to fail at runtime (`RAD20041`,
key not found), so the analyzer flags it statically.

This fires only when the receiver has a closed map shape the
analyzer can enumerate - typically a builtin's typed-map return
value (e.g. `get_path`) or an explicitly annotated struct-typed
map. Untyped `map` values have no declared keys, so the check
stays silent for them.

#### Example

```rad
gp = get_path("README.md")
print(gp.full_path)   // ok: 'full_path' is a declared key
print(gp.fjull_path)  // RAD40014: typo - no such key
```

#### Fix

Use a declared key:

```rad
gp = get_path("README.md")
print(gp.full_path)
```

If the key you want is optional (marked `?` in the type, e.g.
`get_path`'s `size_bytes?`), it's a valid key and won't fire this -
but it may be absent at runtime. Guard the access so a missing key
doesn't error (`RAD20041`).

#### When the check fires

Only reads are checked. Writing a key that isn't declared
(`gp.extra = 1`) is allowed - it adds the key at runtime - so it
does not fire.

Both dot access (`gp.full_path`) and string-literal index access
(`gp["full_path"]`) are checked. Dynamic keys (`gp[k]`) and keys
built from interpolation can't be resolved statically, so they're
left alone.

Optional keys (declared with `?`, e.g. `get_path`'s `size_bytes?`)
are considered valid keys: accessing one resolves its type and does
not fire here, even though the key may be absent at runtime.

### RAD40015: Integer Literal Out of Range

An integer literal was written whose value does not fit in a signed 64-bit
integer. Rad integers are 64-bit, so a literal must be in the range
-9223372036854775808 to 9223372036854775807.

#### Example

```rad
x = 9223372036854775808   // Error: one past the maximum int64
```

These are fine:

```rad
biggest = 9223372036854775807   // the maximum int64
million = 1_000_000             // underscores are allowed as digit separators
print(biggest, million)
```

#### What This Means

The literal's magnitude exceeds what an `int` can hold. Note that the most
negative value cannot be written directly as `-9223372036854775808`, because the
literal `9223372036854775808` is parsed (and range-checked) on its own before the
unary minus applies.

Write the minimum value as `-9223372036854775807 - 1`, or use a `float` if you
need to represent larger magnitudes (with reduced precision).

### RAD40016: Regex Pattern Without regex=true

You passed something that reads like a regex to `split()` or `replace()`, but
neither treats its pattern as a regex unless you ask.

```rad
line = "alice   30   admin"

// Warns: '\s+' is a regex, but split() is looking for that literal text
fields = split(line, "\s+")

// Correct
fields = split(line, "\s+", regex=true)
```

#### Why This Exists

Before v0.12, `split()` and `replace()` always treated their pattern as a regex.
That default was backwards - most calls want literal text - and it failed
silently in the dangerous direction: a `.` in a pattern quietly matched every
character.

The default is now literal. The catch is that scripts written for the old
behavior keep running. They just stop matching:

```rad
print(split("a b  c", "\s+"))   // -> ["a b  c"], not ["a", "b", "c"]
```

No error, no crash, only a wrong answer. This warning is the tap on the shoulder.

#### How to Fix It

If you meant a regex, add `regex=true`:

```rad
text = "order 66 shipped"
print(replace(text, "\d+", "N", regex=true))   // -> "order N shipped"
```

If the text really is literal, you can ignore the warning - the call already does
what you want, and you no longer need to escape anything:

```rad
version = "1.2.3"
print(replace(version, ".", "-"))   // -> "1-2-3", no escaping needed
```

#### Ignore It When

The heuristic looks for constructs that rarely appear in literal text: `\d`,
`\s`, a bracketed class, a group, a quantifier, alternation with branches on both
sides, or a leading `^` / trailing `$`. Real text does sometimes contain those -
`"C++"` and `"a|b"` are perfectly good literal separators. The warning is advice,
not a verdict.

See `rad docs migrations/v0.12` for the full picture, and
`rad check --from-logs all` to sweep every script you've run recently.

### RAD40017: Interpolating a Constant Literal

An interpolation contains a literal value, so it produces exactly the text
you already wrote. `"{4}"` and `"4"` are the same string.

This is almost always a literal brace that got read as an interpolation.

#### Example

```rad
// Wrong: {4} interpolates the number 4, so this is the regex \d4
pattern = "\d{4}"

// Correct: escape the brace
pattern = "\d\{4}"

// Correct: a raw string, where nothing interpolates
pattern = r"\d{4}"
```

Regex quantifiers are where this bites. `\d{4}` looks like "four digits"
and parses as "a digit, then the number 4". Wider quantifiers like
`\d{2,3}` are a syntax error instead, so the single-number form is the only
one that fails quietly.

#### How to Fix

1. **Escape the brace** with `\{` if you meant a literal `{`
2. **Use a raw string** (`r"..."`) if the text is brace-heavy - regexes and
   JSON templates usually are
3. **Write the value directly** if you really did mean to interpolate a
   constant

Note that `r"..."` turns off *all* interpolation and escapes for that
string, so it is the wrong tool if you also need `{name}` to expand.

#### Why This Is a Warning

The rule is syntactic: it fires only when the interpolated expression is
itself a literal. Interpolating a variable that happens to hold a constant
is fine and stays quiet.

```rad
digits = 4
name = "ana"
print("{digits}")      // no warning
print("{2 + 2}")       // no warning
print("{name:<12}|")   // no warning - 12 is a format width, not the value
```

### RAD40018: Misleading Shell Capture Name

A shell capture target is named after one stream but receives another.

```rad
// Warns: 'output' isn't a reserved name, so the whole statement is
// positional - and position 0 is stdout, so 'code' gets the output.
code, output = $`git status --porcelain`

// Correct - all three names are reserved, so assignment goes by name
stdout, code = $`git status --porcelain`
```

#### The Two Rules

Shell commands produce three things: stdout, stderr, and an exit code. How your
variables receive them depends on what you called them.

**Named** - when *every* target is spelled exactly `code`, `stdout`, or
`stderr`, each one gets the stream it's named after and order doesn't matter:

```rad
stderr = $`cmd`               // just stderr
code, stdout = $`cmd`         // exit code and stdout
stderr, stdout, code = $`cmd` // all three, any order
```

**Positional** - the moment one target isn't a reserved name, the whole
statement switches to filling `(stdout, stderr, code)` in order:

```rad
out = $`cmd`             // out = stdout
out, err = $`cmd`        // out = stdout, err = stderr
out, err, c = $`cmd`     // out = stdout, err = stderr, c = exit code
```

This warning fires where those two rules collide: you used a reserved name, but
something else in the statement dropped you into positional mode, so the name
means nothing and the slot decides.

#### How to Fix It

Either name every target so assignment goes by name:

```rad
// Before
code, output = $`cmd`
// After
code, stdout = $`cmd`
```

Or drop the reserved names and let position do the work:

```rad
// Before
code, output = $`cmd`
// After - now positional throughout, and reads as it behaves
output, _, code = $`cmd`
```

The first form is usually what you want. It's a rename, and it captures exactly
the same streams.

#### Migrating From v0.11

Before v0.12, positional captures filled `(code, stdout, stderr)` - the exit
code first. They now fill `(stdout, stderr, code)`.

Scripts written against the old order still parse and still run. They just bind
different variables:

```rad
// v0.11: version = stdout.   v0.12: version = stderr.
_, version = $`rad -v`
```

When the warning mentions v0.12, that's the case it found. The fix is usually to
drop a slot, because what used to need two targets now needs one:

```rad
version = $`rad -v`
```

The exit code moved last because Rad already turns a non-zero exit into an
error - you reach for `catch:` rather than for the code - and because a single
capture binding the exit code was the least useful thing it could bind.

#### What This Warning Cannot Catch

It reads names, so a positional capture whose names give no signal is invisible
to it:

```rad
a, b = $`cmd`   // no warning possible
```

Sweep every script you've run recently with `rad check --from-logs all`, and see
`rad docs migrations/v0.12` for the full picture.

### RAD40019: Two Default Commands At One Level

Only one command per level runs when the user names none, so two `default`
markers among siblings leave nothing to decide between them.

```rad
command add:
    tokens str
    default
    calls do_add

command edit:
    tokens str
    default          // Error: 'add' is already the default here
    calls do_edit
```

#### How to Fix

Keep the marker on whichever command should run when none is named, and drop
the other:

```rad
command add:
    tokens str
    default
    calls do_add

command edit:
    tokens str
    calls do_edit
```

Nesting scopes this: each namespace picks its own default independently, so
`remote` and `image` can each have one.

```rad
command remote:
    command add:
        name str
        default
        calls do_remote_add

command image:
    command build:
        tag str
        default
        calls do_image_build
```

#### See Also

- `rad docs guide/script-commands` - commands, nesting and defaults

### RAD40020: Command Does Nothing

A command either runs something or routes to sub-commands. This one does
neither: it has no `calls` line and no nested command blocks, so invoking it
could only ever do nothing.

```rad
command deploy:
    env str          // Error: nothing to run
```

#### How to Fix

Add a `calls` line naming the function to run:

```rad
command deploy:
    env str
    calls do_deploy

fn do_deploy():
    print("Deploying to {env}...")
```

For a short body, an inline lambda avoids naming a function you only use once:

```rad
command deploy:
    env str
    calls fn():
        print("Deploying to {env}...")
```

Or nest command blocks inside it, which makes it a namespace that routes to
them instead of running itself:

```rad
command deploy:
    timeout int = 30     // shared with every sub-command

    command staging:
        calls do_staging

    command prod:
        calls do_prod
```

#### See Also

- `rad docs guide/script-commands` - commands, nesting and defaults

### RAD40021: Namespace Has A Callback

A command containing sub-commands is a namespace: it groups them and shares its
args with them, and the sub-command the user names is what runs. So a `calls`
line on it would never fire.

```rad
command remote:
    calls do_remote      // Error: 'remote' routes to its sub-commands

    command add:
        name str
        calls do_add
```

#### How to Fix

Drop the `calls` line. Args declared on the namespace still reach every
descendant, which is usually what the callback was reaching for:

```rad
command remote:
    timeout int = 30     // inherited by add, and by anything nested deeper

    command add:
        name str
        calls do_add
```

If you wanted `tool remote` on its own to do something, mark one of its
sub-commands `default` - that is the command it runs when none is named:

```rad
command remote:
    command list:
        default
        calls do_list

    command add:
        name str
        calls do_add
```

#### Why Rad Works This Way

Shape decides role, so there is no keyword to remember and no way for the
declaration and the behavior to disagree. A block with `calls` runs; a block
with commands inside routes.

#### See Also

- `rad docs guide/script-commands` - commands, nesting and defaults

### RAD40022: Default On A Namespace

`default` marks the command to run when the user names none. A namespace does
not run - it routes - so marking one leaves the question unanswered.

```rad
command remote:
    default              // Error: 'remote' contains sub-commands

    command add:
        name str
        calls do_add
```

#### How to Fix

Mark the sub-command that should run:

```rad
command remote:
    command add:
        name str
        default
        calls do_add

    command remove:
        name str
        calls do_remove
```

`tool remote origin` now runs `do_add`, and so does `tool remote add origin`.
The full form stays available, which is how you pass a value that happens to
match a sibling's name - `tool remote add remove` adds a remote called
"remove". `tool remote -- remove` does the same.

#### See Also

- `rad docs guide/script-commands` - commands, nesting and defaults

### RAD40023: Quoted Interpolation In A Shell Command

An interpolated value in a shell command is wrapped in quotes the script wrote
itself. Rad already quotes interpolated values, so these quotes are no longer
protecting anything - they end up inside the argument as literal characters.

```rad
message = "hello"

$`git commit -m "{message}"`   // Error: the quotes land in the message
```

#### How to Fix

Delete the quotes. Rad quotes the value for you, whatever it contains:

```rad
message = "hello"

$`git commit -m {message}`
```

When the argument is literal text plus a value, build the string first and
interpolate that. The quotes were holding the two halves together as one
argument; a single interpolation does that on its own:

```rad
version = "1.2.3"

// Wrong - the quotes become part of the commit message
$`git commit -m "Bump to {version}"`

// Correct
message = "Bump to {version}"
$`git commit -m {message}`
```

#### Why Rad Works This Way

Hand-written quotes could never be correct for every value. Double quotes still
expand `$HOME` and `$(whoami)`; single quotes cannot contain an apostrophe at
all. So a command that worked for `hello` would break, or worse silently
misbehave, on `it's` or `100% of $USERS`.

Rad quotes each interpolated value at the point it knows what the value is, so
the argument the program receives is exactly the value you had:

```rad
message = "it's fine"

$`git commit -m {message}`
// runs: git commit -m 'it'\''s fine'
```

The rule is that the text you write is shell - pipes, redirects, `&&` and all -
and interpolations are data.

#### See Also

- `rad docs guide/shell-commands` - the three command forms
- `rad docs RAD20045` - values that have no single-argument form

### RAD40024: Constraint Does Not Fit The Arg's Type

An arg carries a constraint its type cannot be checked against - an `enum` or
`regex` on a number, or a `range` on a string.

```rad
args:
    scores int[]
    scores enum ["low", "high"]   // Error: scores holds ints
```

#### How to Fix

Use the constraint that matches the type:

| Constraint | Works on             |
| ---------- | -------------------- |
| `enum`     | `str`                |
| `regex`    | `str`                |
| `range`    | `int`, `float`       |
| `len`      | any list or variadic |

So the example above wants either a string arg:

```rad
args:
    levels str[]
    levels enum ["low", "high"]
```

or a numeric bound:

```rad
args:
    scores int[]
    scores range [0, 100]
```

A list or variadic takes the same constraints as the type it holds, because the
constraint describes each element. `scores int[]` is checked with `range`, the
same as a plain `scores int` - every value has to be in range, not the list as a
whole. To bound how many values arrive instead, use `len`.

#### Why Rad Works This Way

Rad used to accept these declarations and ignore them. A script could say
`scores range [0, 100]` on an `int[]`, pass `--scores 500`, and get no
complaint - the constraint reached the parser and was dropped there. That is
worse than rejecting it: the script reads as though it validates its input, so
whoever wrote it stops checking by hand, and the values flow on unexamined.

A constraint that cannot be applied is a mistake in the script rather than a
preference, so Rad reports it instead of guessing at what was meant.

#### See Also

- `rad docs guide/args` - declaring args and their constraints

### RAD40025: Shell Command Used Without a Result Accessor

A shell command was used where a value is wanted, but nothing said *which*
result. Add `.stdout`, `.stderr`, `.code`, or `.ok`.

```rad
if $`git status --porcelain`:      // Error: which result?
    print_err("Uncommitted changes!")
```

#### How to Fix

Pick the accessor that matches the question you're asking:

```rad
// "did it print anything?"
if $`git status --porcelain`.stdout.trim():
    print_err("Uncommitted changes!")

// "did it succeed?"
if not $`which docker`.ok:
    exit(1)
```

#### Which Accessor

| Accessor  | Type   | Fails on non-zero exit |
| --------- | ------ | ---------------------- |
| `.stdout` | `str`  | yes                    |
| `.stderr` | `str`  | yes                    |
| `.code`   | `int`  | no                     |
| `.ok`     | `bool` | no                     |

`.stdout` and `.stderr` fail because output a failed command never produced
isn't an answer. `.code` and `.ok` never fail - asking about the outcome *is*
handling it, which is what makes them the right choice for testing a command.

Capture follows the accessor, exactly as it follows target names in a named
assignment: reading `.stdout` still lets stderr through to the terminal.

#### Why There's No Default

A bare command is ambiguous in a way that bites. In shell, `if cmd` tests the
exit code, but `if $(cmd)` tests whether it printed anything - two different
questions that look nearly identical. Requiring the accessor means the reader
never has to guess which one you meant.

#### Running a Command, Not Reading One

If you only want to *run* the command, it's already a statement - no accessor
needed:

```rad
$`make build`
stdout = $`make build`
```

#### See Also

- `rad docs guide/shell-commands` - capture, modifiers, and the three command forms
- `rad docs RAD40026` - postfix that isn't an accessor

### RAD40026: Postfix After a Shell Command Isn't a Result Accessor

`$` takes only the command, so whatever follows reads the command's *result*.
The only things that can follow are `.stdout`, `.stderr`, `.code`, and `.ok`.

This fires on three shapes, and the first two used to mean something else.

#### An Index or a Call on the Command

```rad
cmds = ["echo a", "echo b"]
$cmds[1]                  // Error
```

`$` used to swallow the whole expression, so this indexed `cmds` *first* and ran
whatever came back. Now `$` takes `cmds` as the command, and `[1]` is postfix
with nothing to index. Wrap the command in parentheses to get the old meaning:

```rad
$(cmds[1])
```

That form has always parsed and always run, so this is a mechanical fix. The
same applies to any computed command:

```rad
$(parts.join(" "))
```

#### A Method on the Command

```rad
$`echo hi`.upper()        // Error
```

This one ran `ECHO HI` - the method transformed the command text before it ran,
not the output afterwards, and nothing reported it. Read a result first:

```rad
$`echo hi`.stdout.upper()
```

#### A Name That Isn't a Result

```rad
$`echo hi`.output         // Error: did you mean 'stdout'?
```

There are four results and no others. See `rad docs RAD40025` for what each one
gives you.

#### Why This Is an Error, Not a Warning

Every one of these shapes either did something other than what it reads like, or
has no meaning at all. There's no version of them worth keeping working.

#### See Also

- `rad docs migrations/v0.12` - the full change and its rationale
- `rad docs RAD40025` - using a command as a value with no accessor
- `rad docs guide/shell-commands` - the three command forms