LuaFormatter Documentation

repository·master·Indexed 21 days ago

A tool for formatting Lua code according to specific style rules. It provides a CLI via the lua-format binary, supports in-place reformatting, and allows customization through YAML configuration files (.lua-format). Features include control over indentation, table alignment, function call layout, and string literal quotes.

Tokens: 5.6K
Snippets: 9
Records: 15
Agent score: 70%

What's inside LuaFormatter

Style configuration file format
master
The style configuration file uses a YAML-like format. You can include comments using the # character.
```
key: "string"
key2: 123
key3: true
# comment
```
https://github.com/koihik/luaformatter/blob/master/docs/Style-Config.md
Use LuaFormatter CLI
master
Run the lua-format binary to reformat Lua scripts. You can pass multiple files as arguments. Use the -i flag to reformat files in-place.
Configuration Priority:
1. Command-line options
2. Configuration files (.lua-format or $XDG_CONFIG_HOME/luaformatter/config.yaml on Linux)
3. Hard-coded default values
```
./lua-format [Lua scripts...] {OPTIONS}
```
https://github.com/koihik/luaformatter/blob/master/README.md
Install LuaFormatter via LuaRocks
master
The easiest way to install LuaFormatter is using LuaRocks.
Requirements:
- c++ 17 compiler
- luarocks 3.3.0+
```
luarocks install --server=https://luarocks.org/dev luaformatter
```
https://github.com/koihik/luaformatter/blob/master/README.md
Format Lua files with a style configuration file
master
To format a Lua source file using a specific configuration file, use the lua-format command with the -c flag.
```
lua-format {your_source_file} -c {your_config_file}
```
```
```bash
lua-format {your_source_file} -c {your_config_file}
```埋
```
https://github.com/koihik/luaformatter/blob/master/docs/Style-Config.md
Build LuaFormatter from source
master
If you prefer to build from source, follow these steps.
Requirements:
- cmake 3.9+
- c++ 17 compiler
Steps:
```
git clone --recurse-submodules https://github.com/Koihik/LuaFormatter.git
cd LuaFormatter
cmake .
make
make install
```
https://github.com/koihik/luaformatter/blob/master/README.md
Disable formatting for a specific code block
master
To prevent LuaFormatter from touching a specific block of code, wrap it in -- LuaFormatter off and -- LuaFormatter on comments.
```
-- LuaFormatter off
matrix = {
   {1, 0, 0, 0},
   {1, 1, 0, 0},
   {1, 1, 1, 0},
   {1, 1, 1, 1}
}
-- LuaFormatter on
```
https://github.com/koihik/luaformatter/blob/master/README.md

Configure LuaFormatter with a YAML file

master

You can use a .lua-format file to define your style. The program looks for this file in the current directory, or recursively in parent directories. On Linux, it also checks $XDG_CONFIG_HOME/luaformatter/config.yaml.

column_limit: 80
indent_width: 4
use_tab: false
tab_width: 4
continuation_indent_width: 4
spaces_before_call: 1
keep_simple_control_block_one_line: true
keep_simple_function_one_line: true
align_args: true
break_after_functioncall_lp: false
break_before_functioncall_rp: false
spaces_inside_functioncall_parens: false
spaces_inside_functiondef_parens: false
align_parameter: true
chop_down_parameter: false
break_after_functiondef_lp: false
break_before_functiondef_rp: false
align_table_field: true
break_after_table_lb: true
break_before_table_rb: true
chop_down_table: false
chop_down_kv_table: true
table_sep: ","
column_table_limit: 0
extra_sep_at_table_end: false
spaces_inside_table_braces: false
break_after_operator: true
double_quote_to_single_quote: false
single_quote_to_double_quote: false
spaces_around_equals_in_field: true
line_breaks_after_function_body: 1
line_separator: input

Use the lua-format CLI
master
The lua-format command is used to reformat Lua source code. It can operate on specific files, multiple files, or via standard input (stdin).
Key behaviors:
- Standard Input: If no files are provided as arguments, the tool reads from stdin and outputs the formatted code to stdout.
- In-place formatting: Use the --in-place flag to overwrite the original files with the formatted version.
- Check mode: Use the --check flag to verify if files need formatting. If formatting is required, it prints the filenames and returns a non-zero exit code (specifically 2 if any files require changes), making it suitable for CI/CD pipelines.
- Configuration discovery: The tool automatically searches for a .lua-format file in the current directory or parent directories. On Unix/macOS, it also checks XDG_CONFIG_HOME/luaformatter/config.yaml or ~/.config/luaformatter/config.yaml.
```
# Format a single file and print to stdout
lua-format script.lua

# Format files in-place
lua-format --in-place script.lua

# Check if files need formatting (useful for CI)
lua-format --check script.lua

# Pipe content via stdin
cat script.lua | lua-format
```
https://github.com/koihik/luaformatter/blob/master/src/main.cpp
Known limitations of LuaFormatter
master
Be aware of the following limitations:
- The formatter will not work if the source file contains syntax errors.
- It does not support 'Format selection' (formatting only a highlighted portion of a file).
https://github.com/koihik/luaformatter/blob/master/README.md

Reference: General indentation and layout options

master

These options control the basic whitespace, indentation, and line length rules for the formatter.

# The column limit of one line (default: 80)
column_limit: 80

# The number of spaces used for indentation (default: 4)
indent_width: 4

# Use tab for indent (default: false)
use_tab: false

# Indent width for continuations line (default: 4)
continuation_indent_width: 4

# Allow format simple control block (e.g., if, while, for, ...) to one line (default: true)
keep_simple_control_block_one_line: true

# Allow format simple function to one line (default: true)
keep_simple_function_one_line: true

Reference: String and operator formatting options

master

These options control how strings, operators, and spacing around symbols are handled.

# Put break after operators if columns greater than column_limit. If false, put break before (default: true)
break_after_operator: true

# Transform string literals to use double quotes (default: false)
single_quote_to_double_quote: false

# Transform string literals to use a single quote (default: false)
double_quote_to_single_quote: false

# Inserts a space on function calls with parentheses omitted (default: 1)
spaces_before_call: 1

# Inserts spaces inside the parenthesis in a function header (default: false)
spaces_inside_functiondef_parens: false

# Inserts spaces inside the parenthesis in a function call (default: false)
spaces_inside_functioncall_parens: false

# Inserts spaces inside the braces in a table constructor (default: false)
spaces_inside_table_braces: false

# Inserts spaces around the equal sign in key/value fields (default: true)
spaces_around_equals_in_field: true

# Line breaks after the function body (default: 1)
line_breaks_after_function_body: 1

# Determine line separator. Options: input (default), os, lf, cr, crlf
line_separator: "input"

Reference: Table formatting options

master

These options control the layout, alignment, and breaking of Lua tables.

# Align fields of a table if there is a line break. If false, use indent_width (default: true)
align_table_field: true

# Break after '{' of a table if columns greater than column_limit (default: true)
break_after_table_lb: true

# Break before '}' of a table if columns greater than column_limit (default: true)
break_before_table_rb: true

# Chop down any table (default: false)
chop_down_table: false

# Chop down table if a table contains a key (default: true)
chop_down_kv_table: true

# The column limit of each line of a table. If 0, uses column_limit (default: 0)
column_table_limit: 0

# The column limit of each line of a k = v table. If 0, uses column_table_limit (default: 0)
column_table_limit_kv: 0

# Define character to separate table fields (default: ',')
table_sep: ','

# Add an extra field separator after the last field unless the table is in a single line (default: false)
extra_sep_at_table_end: false