本文档是 EmmyLua Formatter 文档目录的入口，用于说明格式化器的目标、布局行为、配置模型，以及推荐的阅读顺序。
格式化器当前负责以下内容：
- Lua 与 EmmyLua 源码格式化
- 基于行宽的换行决策
- 受控的尾随注释对齐
- EmmyLua 文档标签的规范化与对齐
- CLI 与库 API 两种使用方式
格式化器在注释和语法歧义附近采取保守策略。当重写存在风险时，会优先保持结构稳定，而不是强行追求更激进的美化结果。
- 格式化效果示例：常见格式化决策的前后对比例子
- 格式化选项：配置分组、默认值，以及每个选项影响的行为
- 推荐配置方案：面向不同团队风格的建议配置
- 格式化教程：配置方式、CLI 工作流、以及常见前后对比示例
其中 格式化选项 现在包含完整默认配置块，可直接作为公开配置参考，也覆盖了 output.simple_lambda_single_line 这类新增选项。
近期的格式化器工作引入了面向序列结构的候选布局选择机制，覆盖以下场景：
- 调用参数
- 函数参数
- 表字段
- 二元表达式链
- 赋值右侧、
return、循环头部等语句表达式列表
对于这些结构，格式化器可以在多种候选布局之间进行比较：
- 单行布局
- progressive fill 紧凑换行
- 更均衡的 packed 布局
- 一项一行布局
- 在输入已经体现对齐意图时启用的 aligned 布局
最终结果不是由固定优先级硬编码决定，而是先渲染候选结果，再比较是否溢出、总行数、目标场景的行均衡度、样式偏好以及剩余行宽。
如果你是第一次使用 formatter：
如果你是在做工具集成：
- 先看
crates/emmylua_formatter/README.md。 - 再把 格式化选项 作为公开配置参考。