# EmmyLua Formatter 文档索引

[English](./README_EN.md)

本文档是 EmmyLua Formatter 文档目录的入口，用于说明格式化器的目标、布局行为、配置模型，以及推荐的阅读顺序。

## 范围

格式化器当前负责以下内容：

- Lua 与 EmmyLua 源码格式化
- 基于行宽的换行决策
- 受控的尾随注释对齐
- EmmyLua 文档标签的规范化与对齐
- CLI 与库 API 两种使用方式

格式化器在注释和语法歧义附近采取保守策略。当重写存在风险时，会优先保持结构稳定，而不是强行追求更激进的美化结果。

## 文档导航

- [格式化效果示例](./examples_CN.md)：常见格式化决策的前后对比例子
- [格式化选项](./options_CN.md)：配置分组、默认值，以及每个选项影响的行为
- [推荐配置方案](./profiles_CN.md)：面向不同团队风格的建议配置
- [格式化教程](./tutorial_CN.md)：配置方式、CLI 工作流、以及常见前后对比示例

其中 [格式化选项](./options_CN.md) 现在包含完整默认配置块，可直接作为公开配置参考，也覆盖了 `output.simple_lambda_single_line` 这类新增选项。

## 布局模型

近期的格式化器工作引入了面向序列结构的候选布局选择机制，覆盖以下场景：

- 调用参数
- 函数参数
- 表字段
- 二元表达式链
- 赋值右侧、`return`、循环头部等语句表达式列表

对于这些结构，格式化器可以在多种候选布局之间进行比较：

- 单行布局
- progressive fill 紧凑换行
- 更均衡的 packed 布局
- 一项一行布局
- 在输入已经体现对齐意图时启用的 aligned 布局

最终结果不是由固定优先级硬编码决定，而是先渲染候选结果，再比较是否溢出、总行数、目标场景的行均衡度、样式偏好以及剩余行宽。

## 推荐阅读顺序

如果你是第一次使用 formatter：

1. 先读 [格式化教程](./tutorial_CN.md)，了解安装、配置发现规则和日常用法。
2. 需要调节行为时，再读 [格式化选项](./options_CN.md)。

如果你是在做工具集成：

1. 先看 `crates/emmylua_formatter/README.md`。
2. 再把 [格式化选项](./options_CN.md) 作为公开配置参考。
