EmmyLua Analyzer Rust

EmmyLua Code Analysis is a static analysis tool designed for Lua code. It provides the underlying logic for advanced IDE features, including:

• Code Completion: Suggesting valid Lua syntax and members.
• Type Checking: Verifying that types match their definitions.
• Static Analysis: Identifying potential issues in Lua source code without executing it.

The EmmyLua Formatter is designed to format Lua and EmmyLua source code. Its primary responsibilities include:

• Line-width based wrapping decisions: Managing how code breaks across lines.
• Controlled trailing comment alignment: Aligning comments at the end of lines.
• EmmyLua annotation normalization: Standardizing and aligning EmmyLua documentation tags.
• Dual usage modes: Available as both a Command Line Interface (CLI) and a library API.

Note on Safety: The formatter employs a conservative strategy near comments and syntax ambiguities. It prioritizes maintaining structural stability over aggressive beautification when rewriting poses a risk.

The EmmyLua Formatter is a tool designed for formatting Lua and EmmyLua source code. It focuses on width-aware line breaking, controlled trailing-comment alignment, and EmmyLua doc-tag normalization and alignment. It supports both CLI and library-based workflows.

Key Behavior: The formatter is intentionally conservative. If a rewrite of comments or ambiguous syntax is deemed risky, it will prioritize preserving the existing structure over forcing a specific aesthetic result.

The @see annotation is used to create references to related classes, functions, or external documentation. This helps with code navigation, API association, and automated documentation generation.

Syntax

---@see <symbol_name_or_url>

Capabilities

• Symbol Referencing: Link to specific classes or functions within your codebase.
• Documentation Links: Link to external URLs (e.g., official Lua manuals).
• Code Navigation: Enables tools to jump to the referenced definition.
• API Association: Connects related pieces of logic in documentation.

---@see User
---@see createUser
---@param userData table 用户数据
function validateUser(userData)
    -- 验证用户数据
end

The formatter uses several layout strategies depending on line width and structure:

• Flat: Keeps simple structures on a single line (e.g., local point = { x = 1, y = 2 }).
• Progressive fill: Compactly fills multiple lines for function arguments or parameters.
• Balanced packed layout: Used for sequence-like structures (e.g., complex if conditions or for loop expressions).
• One item per line: Used for builder patterns or when narrow layouts are more readable (e.g., method chaining).

Note on Comment Alignment: The formatter is conservative. It does not manufacture wide alignment blocks in files that weren't originally written that way. Standalone comments will break alignment groups.

When reading EmmyLua annotation documentation, the following syntax markers are used to describe the structure and requirements of annotations:

• <name>: A required placeholder that must be replaced with an actual value.
• [value]: An optional item.
• [value...]: An optional and repeatable item.
• value1 | value2: A choice between values (e.g., using either the left or right value).
• <type[|type...]>: A type expression that supports union types.
• [(modifier)]: An optional modifier, such as (exact) or (key).
• #: A comment marker followed by descriptive text.

Paths defined in workspace and resource sections are automatically expanded. Use the following syntax for path resolution:

Example configuration for libraries and workspace roots:

{
  "workspace": {
    "library": [
      "${workspaceFolder}/types",
      "{env:HOME}/.lua",
      "{luarocks}"
    ],
    "workspaceRoots": [
      "./src",
      "./test"
    ]
  }
}

The EmmyLua Formatter does not force all code into a single uniform style. Instead, it dynamically chooses between several layout modes based on the code's structure and line width:

• flat: Single-line representation for small, stable structures.
• fill: Progressive filling of lines to maintain compactness.
• packed: Balanced distribution of elements across multiple lines (used for binary chains and expression lists).
• aligned: Used for specific alignment needs (e.g., trailing comments).
• one-per-line: A fallback mode used when other modes result in poor readability (e.g., long method chains).

EmmyLua provides precise document highlighting that goes beyond standard editor syntax coloring, focusing on variable relationships and structural blocks.

Reference Highlighting

• Variable References: Highlights all instances where the same variable is used.
• Scope Tracking: Shows the effective scope of variables.
• Real-time Tracking: Updates highlighting in real-time as the cursor moves.

Keyword and Block Groups

• Paired Highlighting: Visual pairing for structures like if-then-end.
• Loop Blocks: Highlighting for for-do-end structures.
• Conditional Blocks: Complete highlighting for if-elseif-else-end structures.

Use the @enum annotation to mark a Lua table as an enumeration type. This provides runtime-available enum values and enables type checking for functions that consume these values.

There are two primary modes of enumeration:

1. Value Enumeration: The enum values are the values stored in the table.
2. Key Enumeration: The enum values are the keys of the table (using the (key) modifier).

Syntax

-- Value enumeration (uses the table's values)
---@enum <EnumName>

-- Key enumeration (uses the table's keys)
---@enum (key) <EnumName>

-- Value enumeration
---@enum HTTPStatus
local HTTPStatus = {
    OK = 200,
    NOT_FOUND = 404
}

-- Key enumeration
---@enum (key) Permission
local Permission = {
    READ = true,
    WRITE = true
}

The @module annotation is used to declare or reference a Lua module. This enables type propagation between different modules, allowing the analyzer to understand the structure and types exported by a specific module when it is required or loaded.

---@module 'module_name'
local myModule = require('module_name')

When reading EmmyLua documentation, the following notation symbols are used to describe the expected syntax:

• <name>: A required placeholder that must be replaced with an actual value.
• [value]: An optional item; content within brackets is not required.
• [value...]: An optional and repeatable item.
• value1 | value2: A choice item; you must use either the left or the right value.
• <type[|type...]>: A type expression that supports union types.
• [(modifier)]: An optional modifier (e.g., (exact), (key)).
• #: A comment marker followed by description text.