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

# 参数处理

## 占位符命名空间

三个命名空间完全隔离：

| 命名空间 | 语法 | 说明 |
|---------|------|------|
| 具名占位符 | `{xxx}` | 匹配输入中 `xxx` 后面紧跟的值 |
| 可选透传 | `{{xxx}}` | 有 `xxx` 则原样渲染，无则消失 |
| 系统占位符 | `${...}` | 固定语义，由系统提供 |

:::note 变量（先行展开）
`${byk_dir}` / `${file_dir}` / `${deps_dir}` 以及 `$var` 声明的变量，在占位符解析**之前**由 byk 替换为字面量，不属于上述参数命名空间——它们不消耗任何参数位置，也不接受输入值。`${args}` / `${N}` / `${...args}` 仍由参数层处理。详见 [变量](/zh/cli/alias/config.md)。
:::

## 占位符一览

| 占位符 | 说明 | 消耗位置数 |
|--------|------|-----------|
| `{xxx}` | 匹配输入中 `xxx` 后面紧跟的值 | 2（xxx + 值） |
| `{{xxx}}` | 可选透传，有则渲染为 `xxx value`，无则消失 | 2（有值时） |
| `{xxx?}` | 条件渲染（最简），有 `xxx` 则渲染为 `xxx`，无则消失 | 1 |
| `{xxx?渲染1:渲染2}` | 条件渲染（三元） | 1 |
| `${N}` | 原始参数第 N 个（从 0 开始） | 1（位置 N） |
| `${args}` | 所有原始参数 | 不消耗 |
| `${...args}` | 剩余参数（去除已被其他占位符消耗的） | 不消耗 |

## 消耗规则

* `{xxx}` / `{{xxx}}` 消耗 `xxx` 及其紧跟的值（共 2 个位置）
* `{xxx?}` / `{xxx?渲染1}` / `{xxx?渲染1:渲染2}` 只消耗 `xxx` 本身（1 个位置）
* `${N}` 消耗位置 N
* 同一占位符多次出现，只消耗一次，值复用
* `${...args}` 的剩余 = 所有原始参数 - 已被消耗的位置，按原始顺序拼接

## 无值 / 无占位符行为

:::tip 无占位符行为
别名中不含任何占位符时，自动追加所有原始参数，等价于末尾隐式追加 `${args}`。兼容 find 命令中的裸 `{}`（如 `find . -exec ... {} +`），不会被解析或替换。
:::

:::note 无值行为
任何占位符取不到对应的值时，**静默消失**，不报错。参数缺失导致的错误由底层命令的运行时处理。
:::

## 参数保真

命令最终交给 `sh -c` 解释，所以每个参数在拼进命令时都会被单引号包裹——边界由引号守住，不再交给 shell 重新切分：

| 你输入 | 命令收到 |
|--------|----------|
| `byk probe "my file.json"` | 1 个参数 `my file.json` |
| `byk probe ""` | 1 个参数（空） |
| `byk probe 'a; echo INJECTED'` | 1 个参数 `a; echo INJECTED`，`echo` 不会执行 |
| `byk probe "*.json"` | 1 个参数 `*.json`，不做通配展开 |
| `byk probe 'C:\tmp\x'` | 1 个参数 `C:\tmp\x`，反斜杠保留 |

只有纯字母数字（外加 `- _ . / : = @ + ,`）的值不加引号，所以提示行里 `cp src dst` 依然是原样；需要引号时才会看到 `cp 'my file.json' dst`。

:::warning 参数不会再被 shell 展开
`*`、`~`、`$VAR` 都在你敲命令时由你自己的 shell 处理过一次了——`byk probe *.json` 里的 `*` 在 byk 拿到之前就已经展开成文件列表。所以 byk 侧按字面传，是保真而不是丢失。
:::

:::note Windows
`cmd` 侧用双引号包裹，已知不保真的只剩 `%VAR%`：cmd 在引号内照样展开环境变量，命令行上也没有可靠的转义写法（`%%` 只在批处理文件里有效）。
:::

## 具名占位符示例

<Tabs>
  <Tab label="长选项">
    ```bash
    # "copy": "cp {--src} {--dest}"
    byk copy --src foo.txt --dest bar.txt
    # 执行：cp foo.txt bar.txt
    ```
  </Tab>

  <Tab label="短选项">
    ```bash
    # "copy": "cp {-s} {-d}"
    byk copy -s foo.txt -d bar.txt
    # 执行：cp foo.txt bar.txt
    ```
  </Tab>
</Tabs>

## 可选透传示例

```bash
# "build": "vite build {{--mode}}"
byk build --mode production
# 执行：vite build --mode production

byk build
# 执行：vite build
```

## 条件渲染示例

<Tabs>
  <Tab label="最简形式">
    ```bash
    # "dev": "vite {--open?--open}"
    byk dev --open
    # 执行：vite --open

    byk dev
    # 执行：vite
    ```
  </Tab>

  <Tab label="三元形式">
    ```bash
    # "test": "jest {--coverage?--coverage:--no-coverage}"
    byk test --coverage
    # 执行：jest --coverage

    byk test
    # 执行：jest --no-coverage
    ```
  </Tab>
</Tabs>

## 位置参数示例

<Tabs>
  <Tab label="绝对位置">
    ```bash
    # "echo": "echo ${0} ${2}"
    byk echo aaa bbb ccc
    # 执行：echo aaa ccc
    ```
  </Tab>

  <Tab label="重复使用">
    ```bash
    # "repeat": "echo ${0} ${0} ${0}"
    byk repeat Hello
    # 执行：echo Hello Hello Hello
    ```
  </Tab>

  <Tab label="剩余参数">
    ```bash
    # "cmd": "run {--src} ${...args}"
    byk cmd --src foo aaa bbb
    # {--src} 消耗 --src 和 foo
    # ${...args} → aaa bbb
    # 执行：run foo aaa bbb
    ```
  </Tab>
</Tabs>

***

byk v0.8.2 · 本页可能落后于 HEAD，以 `byk __api__` 与 `byk -v` 为准。
