import { Tab, Tabs } from '@rspress/core/theme';

# Placeholders

## Placeholder Namespaces

The three namespaces are fully isolated:

| Namespace | Syntax | Description |
|-----------|--------|-------------|
| Named placeholders | `{xxx}` | Matches the value that directly follows `xxx` in the input |
| Optional pass-through | `{{xxx}}` | Rendered as-is when `xxx` is present; disappears otherwise |
| System placeholders | `${...}` | Fixed semantics provided by the system |

:::note Variables (expanded first)
`${byk_dir}` / `${file_dir}` / `${deps_dir}` and any `$var`-declared variables are substituted with literals by byk **before** placeholder resolution. They are not part of the argument namespaces above — they consume no argument positions and accept no input values. `${args}` / `${N}` / `${...args}` are still handled by the argument layer. See [Variables](/cli/alias/config.md).
:::

## Placeholder Reference

| Placeholder | Description | Positions consumed |
|-------------|-------------|--------------------|
| `{xxx}` | Matches the value directly following `xxx` in the input | 2 (xxx + value) |
| `{{xxx}}` | Optional pass-through; renders as `xxx value` when present, disappears otherwise | 2 (when present) |
| `{xxx?}` | Conditional rendering (simplest); renders as `xxx` when present, disappears otherwise | 1 |
| `{xxx?render1:render2}` | Conditional rendering (ternary) | 1 |
| `${N}` | The Nth raw argument (0-based) | 1 (position N) |
| `${args}` | All raw arguments | None |
| `${...args}` | Remaining arguments (excluding those already consumed by other placeholders) | None |

## Consumption Rules

* `{xxx}` / `{{xxx}}` consume `xxx` and the value directly following it (2 positions in total)
* `{xxx?}` / `{xxx?render1}` / `{xxx?render1:render2}` consume only `xxx` itself (1 position)
* `${N}` consumes position N
* A placeholder that appears multiple times is consumed only once; its value is reused
* The remainder for `${...args}` = all raw arguments − already-consumed positions, joined in original order

## Missing Values / No Placeholders

:::tip No placeholders
When an alias contains no placeholders, all raw arguments are appended automatically — equivalent to an implicit `${args}` at the end. Bare `{}` in commands like find (e.g. `find . -exec ... {} +`) stays compatible: it is never parsed or substituted.
:::

:::note Missing values
When a placeholder finds no corresponding value, it **silently disappears** — no error is raised. Errors caused by missing arguments are handled at runtime by the underlying command.
:::

## Argument Fidelity

The command is ultimately interpreted by `sh -c`, so every argument is single-quoted when it is spliced in — the quotes hold the boundary instead of letting the shell re-split it:

| You type | The command receives |
|----------|----------------------|
| `byk probe "my file.json"` | one argument `my file.json` |
| `byk probe ""` | one argument (empty) |
| `byk probe 'a; echo INJECTED'` | one argument `a; echo INJECTED`; `echo` never runs |
| `byk probe "*.json"` | one argument `*.json`, no globbing |
| `byk probe 'C:\tmp\x'` | one argument `C:\tmp\x`, backslash intact |

Only plain values (letters, digits and `- _ . / : = @ + ,`) go in bare, so the hint line still reads `cp src dst`; you see quotes only when they are needed: `cp 'my file.json' dst`.

:::warning Arguments are not expanded again
`*`, `~` and `$VAR` were already handled by your own shell before byk saw them — the `*` in `byk probe *.json` has been expanded to a file list by then. Passing them through literally is fidelity, not loss.
:::

:::note Windows
The `cmd` side uses double quotes. The one known gap is `%VAR%`: cmd expands environment variables even inside quotes, and there is no reliable escape at the command line (`%%` only works inside batch files).
:::

## Named Placeholder Examples

<Tabs>
  <Tab label="Long options">
    ```bash
    # "copy": "cp {--src} {--dest}"
    byk copy --src foo.txt --dest bar.txt
    # runs: cp foo.txt bar.txt
    ```
  </Tab>

  <Tab label="Short options">
    ```bash
    # "copy": "cp {-s} {-d}"
    byk copy -s foo.txt -d bar.txt
    # runs: cp foo.txt bar.txt
    ```
  </Tab>
</Tabs>

## Optional Pass-Through Examples

```bash
# "build": "vite build {{--mode}}"
byk build --mode production
# runs: vite build --mode production

byk build
# runs: vite build
```

## Conditional Rendering Examples

<Tabs>
  <Tab label="Simplest form">
    ```bash
    # "dev": "vite {--open?--open}"
    byk dev --open
    # runs: vite --open

    byk dev
    # runs: vite
    ```
  </Tab>

  <Tab label="Ternary form">
    ```bash
    # "test": "jest {--coverage?--coverage:--no-coverage}"
    byk test --coverage
    # runs: jest --coverage

    byk test
    # runs: jest --no-coverage
    ```
  </Tab>
</Tabs>

## Positional Argument Examples

<Tabs>
  <Tab label="Absolute position">
    ```bash
    # "echo": "echo ${0} ${2}"
    byk echo aaa bbb ccc
    # runs: echo aaa ccc
    ```
  </Tab>

  <Tab label="Repeated use">
    ```bash
    # "repeat": "echo ${0} ${0} ${0}"
    byk repeat Hello
    # runs: echo Hello Hello Hello
    ```
  </Tab>

  <Tab label="Remaining arguments">
    ```bash
    # "cmd": "run {--src} ${...args}"
    byk cmd --src foo aaa bbb
    # {--src} consumes --src and foo
    # ${...args} → aaa bbb
    # runs: run foo aaa bbb
    ```
  </Tab>
</Tabs>

***

byk v0.8.2 · this page may lag behind HEAD; `byk __api__` and `byk -v` are authoritative.
