Code Formatting

Professional code formatting system based on EmmyLuaCodeStyle, providing consistent code style across your entire project.

Overview

EmmyLua’s formatting system provides automatic code formatting with extensive customization options. It supports both document-level and selection-level formatting, with intelligent handling of Lua syntax and EmmyDoc annotations.

Document Formatting

Format entire files with a single command

Selection Formatting

Format only selected code regions

Code Folding

Collapse code blocks for better navigation

Custom Regions

Define custom folding regions with comments

Document Formatting

Format entire Lua files to maintain consistent code style.

Format Document
Format on Save
Format on Type

Shift + Alt + F (Windows/Linux) or Shift + Option + F (macOS)

-- Before formatting
local function test(x,y,z)
if x>0 then
return y+z
end
end

-- After formatting
local function test(x, y, z)
    if x > 0 then
        return y + z
    end
end

Features:

Fixes common formatting issues
Applies consistent indentation
Adjusts spacing around operators
Aligns table fields

Enable automatic formatting when saving files:VS Code settings.json:

{
  "[lua]": {
    "editor.formatOnSave": true
  }
}

Benefits:

Always maintain consistent style
No manual formatting needed
Team-wide consistency

Format code as you type (optional):

{
  "[lua]": {
    "editor.formatOnType": true
  }
}

Automatically formats:

After typing semicolons
After completing blocks (end)
After line breaks

Incremental Formatting

The formatter uses intelligent diff algorithms to minimize changes:

Diff-based Formatting

Only modified parts are reformatted, preserving unchanged regions:

-- Only the changed function is reformatted
local function unchanged()
    return true  -- This stays as-is
end

local function modified(x,y)  -- This gets reformatted
    return x+y
end

Configuration:

{
  "format": {
    "useDiff": true
  }
}

Replace All Threshold

Controls when to use full-file replacement vs. line-based diff:

{
  "format": {
    "useDiff": true,
    "replaceAllThreshold": 50
  }
}

Below threshold: Line-based diff
Above threshold: Full file replacement
Default: 50 lines

Selection Formatting

Format only selected code regions.

Format Selection
Style Consistency
Smart Indentation

Select the code you want to format
Right-click → Format Selection
Or use Ctrl + K, Ctrl + F (Windows/Linux) or Cmd + K, Cmd + F (macOS)

local function example()
    -- Select this messy code
    local x=1+2
    local y=3+4
    return x*y
    -- After formatting:
    -- local x = 1 + 2
    -- local y = 3 + 4
    -- return x * y
end

Selection formatting maintains the same style rules as document formatting:

-- Selected region
local config={timeout=30,retries=3,enabled=true}

-- After formatting
local config = {
    timeout = 30,
    retries = 3,
    enabled = true
}

Automatically adjusts indentation levels based on context:

function outer()
    -- Paste poorly indented code here
function inner()
local x=1
return x
end
end

-- Format selection to fix indentation
function outer()
    function inner()
        local x = 1
        return x
    end
end

Formatting Options

Customize formatting behavior through configuration.

Basic Options

{
  "format": {
    "enable": true,
    "defaultConfig": {
      "indent_size": 4,
      "indent_style": "space",
      "quote_style": "double",
      "continuation_indent": 4,
      "max_line_length": 120
    }
  }
}

Indentation
Line Length
Quote Style
Spacing

{
  "indent_size": 4,        // Number of spaces per indent
  "indent_style": "space", // "space" or "tab"
  "continuation_indent": 4 // Indent for continued lines
}

Examples:

-- indent_size: 4, indent_style: "space"
function example()
    if condition then
        doSomething()
    end
end

-- indent_size: 2, indent_style: "space"
function example()
  if condition then
    doSomething()
  end
end

{
  "max_line_length": 120
}

Controls automatic line breaking:

-- Before (exceeds 120 characters)
local result = someVeryLongFunctionName(param1, param2, param3, param4, param5)

-- After
local result = someVeryLongFunctionName(
    param1,
    param2,
    param3,
    param4,
    param5
)

{
  "quote_style": "double" // or "single"
}

Normalizes string quote style:

-- quote_style: "double"
local message = "Hello, world!"
local path = "./config/settings.lua"

-- quote_style: "single"
local message = 'Hello, world!'
local path = './config/settings.lua'

{
  "space_around_table_field_list": true,
  "space_before_function_open_parenthesis": false,
  "space_before_open_square_bracket": false
}

Fine-tune spacing:

-- space_around_table_field_list: true
local t = { a = 1, b = 2 }

-- space_before_function_open_parenthesis: false
function test()
end

-- space_before_open_square_bracket: false
local value = array[index]

Code Folding

Collapse code blocks for better navigation and readability.

Standard Folding

Functions

function example()
    -- Foldable region
    local x = 1
    return x
end

Control Flow

if condition then
    -- Foldable region
elseif other then
    -- Foldable region
end

Loops

for i = 1, 10 do
    -- Foldable region
end

while condition do
    -- Foldable region
end

Tables

local config = {
    -- Foldable region
    timeout = 30,
    retries = 3
}

Supported Folding Regions

Functions
Control Structures
Tables & Strings
Comments

-- Function declarations
function globalFunction()
    -- Foldable content
end

-- Local functions
local function localFunction()
    -- Foldable content
end

-- Anonymous functions
local callback = function()
    -- Foldable content
end

-- If statements
if condition then
    -- Foldable
elseif other then
    -- Foldable
else
    -- Foldable
end

-- For loops
for i = 1, 10 do
    -- Foldable
end

-- While loops
while condition do
    -- Foldable
end

-- Repeat loops
repeat
    -- Foldable
until condition

-- Table constructors
local config = {
    -- Foldable content
    key1 = value1,
    key2 = value2
}

-- Multi-line strings
local text = [[
    Foldable
    multi-line
    string
]]

--[[
    Foldable
    multi-line
    comment
]]

-- Consecutive single-line comments
-- are grouped and
-- become foldable
-- as a block

--- EmmyDoc comments
---@class Example
---@field value number

Custom Folding Regions

Define custom folding regions using special comments.

Region Syntax
Nested Regions
Use Cases

--region Custom Region Name
local config = {
    timeout = 30,
    retries = 3,
    enabled = true
}

local defaults = {
    mode = "production",
    verbose = false
}
--endregion

Features:

Group related code
Custom region names
Nestable regions
Better code organization

--region Application Configuration
    --region Database Settings
    local db = {
        host = "localhost",
        port = 5432
    }
    --endregion

    --region Cache Settings
    local cache = {
        enabled = true,
        ttl = 3600
    }
    --endregion
--endregion

--region Imports
local json = require("json")
local http = require("http")
local utils = require("utils")
--endregion

--region Constants
local MAX_RETRIES = 3
local TIMEOUT = 30
local API_VERSION = "v1"
--endregion

--region Helper Functions
local function validate(data)
    -- Implementation
end

local function transform(data)
    -- Implementation
end
--endregion

--region Main Logic
local function main()
    -- Implementation
end
--endregion

External Formatter Integration

Integrate external formatting tools for advanced formatting needs.

{
  "format": {
    "externalTool": {
      "command": "stylua",
      "args": ["--stdin-filepath", "${file}", "-"]
    }
  }
}

StyLua
lua-format

StyLua integration:

{
  "format": {
    "externalTool": {
      "command": "stylua",
      "args": ["--stdin-filepath", "${file}", "-"]
    }
  }
}

lua-format integration:

{
  "format": {
    "externalTool": {
      "command": "lua-format",
      "args": ["--stdin"]
    }
  }
}

EmmyLuaCodeStyle

The built-in formatter is powered by EmmyLuaCodeStyle, which provides:

.editorconfig Support

Respects .editorconfig files in your project

.lua-format Support

Compatible with .lua-format configuration files

Custom Rules

Extensive customization options

Fast Performance

High-performance Rust implementation

Configuration File

Create a .editorconfig or .lua-format file in your project root:

# .editorconfig
[*.lua]
indent_style = space
indent_size = 4
quote_style = double
continuation_indent = 4
max_line_length = 120

For detailed formatting configuration options, refer to the EmmyLuaCodeStyle Documentation.

Best Practices

Enable Format on Save

Configure your editor to format on save for consistent style:

{
  "[lua]": {
    "editor.formatOnSave": true
  }
}

Use Project Configuration

Create a .editorconfig file in your project root to ensure team-wide consistency.

Test Format Rules

Test formatting rules on a sample file before applying to entire project.

Commit Formatting Changes Separately

When reformatting existing code, commit formatting changes separately from functional changes.

Formatting will not be applied to files with syntax errors. Fix syntax errors before formatting.

Getting Started

CLI Tools

Configuration

Features

Overview

Document Formatting

Selection Formatting

Code Folding

Custom Regions

Document Formatting

Incremental Formatting

Selection Formatting

Formatting Options

Basic Options

Code Folding

Standard Folding

Functions

Control Flow

Loops

Tables

Supported Folding Regions

Custom Folding Regions

External Formatter Integration

EmmyLuaCodeStyle

.editorconfig Support

.lua-format Support

Custom Rules

Fast Performance

Configuration File

Best Practices

Build docs developers (and LLMs) love

Getting Started

CLI Tools

Configuration

Features

​Overview

Document Formatting

Selection Formatting

Code Folding

Custom Regions

​Document Formatting

​Incremental Formatting

​Selection Formatting

​Formatting Options

​Basic Options

​Code Folding

​Standard Folding

Functions

Control Flow

Loops

Tables

​Supported Folding Regions

​Custom Folding Regions

​External Formatter Integration

​EmmyLuaCodeStyle

.editorconfig Support

.lua-format Support

Custom Rules

Fast Performance

​Configuration File

​Best Practices

Build docs developers (and LLMs) love

Overview

Document Formatting

Incremental Formatting

Selection Formatting

Formatting Options

Basic Options

Code Folding

Standard Folding

Supported Folding Regions

Custom Folding Regions

External Formatter Integration

EmmyLuaCodeStyle

Configuration File

Best Practices