# Macros and data files

## Macro files

One file per macro in `paths.macros`. The filename is the macro's name. A macro cannot contain `clip`, `marks` or `callouts`.

| Key | Default | Effect |
| --- | --- | --- |
| `steps` | required | The steps to run |
| `defaults` | `{}` | Values the macro reads, overridable by the caller |

screenshots/macros/sign-in.yaml

```
defaults:
  who: sam@example.com
steps:
  - fill: { label: Email }
    value: $who
  - click: { role: button, name: Sign in }
```

Call it from a recipe or another macro with the `use` step:

screenshots/recipes/dashboard.yaml

```
setup:
  - use: sign-in
    with: { who: admin@example.com }
```

## Data files

Every file in `paths.data` is in scope, named after its filename: `orders.yaml` is `$orders`. A filename must contain only letters, digits and underscores, because a reference stops at a hyphen.

screenshots/data/orders.yaml

```
open:
  - name: Acme Corp
    reference: INV-1042
shipped:
  - name: Globex
    reference: INV-1043
```

screenshots/recipes/orders.yaml

```
setup:
  - each: $orders.open
    as: order
    steps:
      - fill: { label: Search }
        value: ${order.name}
```

## References

| Form | Meaning |
| --- | --- |
| `$name` | The value bound to `name` |
| `{"${name}"}` | The same, delimited |
| `$a.b` | A path into the value bound to `a` |
| `{"${env.NAME}"}` | An environment variable the run was allowed to read |

A name continues through letters, digits, underscores and dots, so braces are required where the reference runs into text that could belong to it: `Order ${order.name}.` ends the reference before the full stop, while `Order $order.name.` looks for a path ending in a dot.

### Where values come from

- data files, by filename
- `with` on a `use` step, for the macro it calls
- `readValue: … as: name`, for the steps that follow it
- `each: … as: name`, for its own steps only

### Rules

- A reference that is the whole value keeps that value's type. A reference inside a longer string becomes text.
- References are substituted in steps only, never in `clip`, `marks` or `callouts`.
- A reference that matches nothing is an error, not an empty string.
- A literal `$` inside a longer string is left alone.
- `__proto__`, `constructor` and `prototype` resolve to nothing.
- `${env.NAME}` resolves only for names given to `--allow-env` or listed in `SHOTLIST_ENV`; an `--untrusted` run resolves none.

Written by Nicola Mustone · Applies to shotlist 0.6.0 · Maintained by Nicola Mustone

Published date unavailable · Updated date unavailable · [View source](https://github.com/SirDarcanos/shotlist.dev/blob/main/src/pages/docs/reference/macros-and-data.astro) · [Propose a correction](https://github.com/SirDarcanos/shotlist.dev/edit/main/src/pages/docs/reference/macros-and-data.astro)