EmmyLua Formatter Guide

中文文档

This document is the entry point for the EmmyLua formatter documentation. It summarizes the formatter's goals, behavior, configuration model, and the recommended reading path for users who want either a quick setup or a deeper understanding of layout decisions.

Scope

The formatter is responsible for:

• Lua and EmmyLua source formatting
• width-aware line breaking
• controlled trailing-comment alignment
• EmmyLua doc-tag normalization and alignment
• CLI and library-based formatting workflows

The formatter is intentionally conservative around comments and ambiguous syntax. When a rewrite would be risky, the implementation prefers preserving structure over forcing a prettier result.

Documentation Map

• Formatting Examples: before-and-after examples for common formatter decisions
• Formatter Options: configuration groups, defaults, and what each option changes
• Recommended Profiles: suggested formatter configurations for common team styles
• Formatter Tutorial: practical setup, CLI workflows, and before/after examples

The options reference now includes a complete default config block, so it can be used as the canonical formatter config reference when wiring editor integration or reviewing new options such as output.simple_lambda_single_line.

Layout Model

Recent formatter work introduced candidate-based layout selection for sequence-like constructs such as call arguments, parameters, table fields, binary-expression chains, and statement expression lists.

For these constructs, the formatter can compare multiple candidates:

• flat
• progressive fill
• balanced packed layout
• one item per line
• aligned variants when comment alignment is enabled and justified by the input

The selected result is based on rendered output rather than a fixed priority chain. Overflow is penalized first, then line count, then optional line-balance scoring for targeted sites, then style preference, and finally remaining line slack.

Recommended Reading

If you are new to the formatter:

1. Read Formatter Tutorial for installation, config discovery, and day-to-day usage.
2. Read Formatter Options when you need to tune width, spacing, comments, or doc-tag behavior.

If you are integrating the formatter into tooling:

1. Start with the crate README at crates/emmylua_formatter/README.md.
2. Use Formatter Options as the public configuration reference.