How to Use the Command 'stylua' (with examples)

Stylua is an opinionated code formatter for the Lua programming language. It ensures that your Lua scripts are uniformly formatted, improving readability, and maintaining consistency across codebases. Whether you’re working solo or as part of a team, using a standardized code style aids collaboration and minimizes friction during code reviews. Stylua automates the process of code formatting, allowing you to focus on the logic and functionality of your code instead.

Use case 1: Auto-format a file or an entire directory

Code:

stylua path/to/file_or_directory

Motivation:

The primary purpose of auto-formatting is to maintain consistent code styles across different files or projects. As projects grow, maintaining a clean and consistent codebase becomes crucial. Manually formatting code is time-consuming and prone to error, so utilizing Stylua’s auto-format feature can significantly increase productivity and eliminate discrepancies across code files.

Explanation:

• stylua: Invokes the Stylua command-line tool.
• path/to/file_or_directory: Specifies the file or directory you wish to format. If a directory is provided, Stylua will recursively format all .lua files within that directory.

Example Output:

Running the command on a directory with several Lua files might yield output such as:

Formatted `file1.lua`
Formatted `file2.lua`
Formatted `file3.lua`

Each line indicates a successfully formatted file, showing which files were altered.

Use case 2: Check if a specific file has been formatted

Code:

stylua --check path/to/file

Motivation:

Before committing code to a shared repository, it’s essential to ensure that it adheres to the agreed-upon style guide. The --check option allows developers to verify compliance without making changes, which is useful in continuous integration environments where automation involves verifying code style compliance.

Explanation:

• stylua: Invokes the Stylua command-line tool.
• --check: Runs a check to see if the file is correctly formatted according to Stylua’s rules without altering it.
• path/to/file: The specific Lua file you want to check for correct formatting.

Example Output:

If the file isn’t properly formatted, you might see output like:

Check failed: `path/to/file` needs formatting

Use case 3: Run with a specific configuration file

Code:

stylua --config-path path/to/config_file path/to/file

Motivation:

Stylua allows customization by using configuration files, which define specific formatting rules or settings. This feature is particularly useful when working on different projects that have unique style requirements. Developers can maintain these unique styles without altering their global settings.

Explanation:

• stylua: Runs the Stylua command-line tool.
• --config-path path/to/config_file: Directs Stylua to use the specified configuration file, which contains preferred formatting rules and settings.
• path/to/file: The Lua file you wish to format with the rules defined in the provided configuration file.

Example Output:

Upon execution, output might state:

Formatted `file.lua` using provided configuration

This indicates that the file was formatted according to the rules in the specified configuration file.

Use case 4: Format code from stdin and output to stdout

Code:

stylua - < path/to/file.lua

Motivation:

Formatting code from stdin to stdout is useful for integration in scripts or tools that handle code manipulation in pipelines. It allows real-time formatting during script execution without affecting the original file and is useful in development environments requiring quick formatting checks or transformations.

Explanation:

• stylua: Invokes the Stylua command-line tool.
• -: Tells Stylua to read from standard input (stdin) instead of a file directly.
• < path/to/file.lua: Directs the contents of a Lua file into Stylua’s input for formatting.

Example Output:

The formatted Lua code is displayed directly in the terminal, allowing developers to preview changes immediately without modifying the original file:

Formatted output of `path/to/file.lua` will appear here

Use case 5: Format a file or directory using spaces and preferring single quotes

Code:

stylua --indent-type Spaces --quote-style AutoPreferSingle path/to/file_or_directory

Motivation:

Different projects or coding standards may require specific formatting preferences, such as using spaces instead of tabs for indentation or preferring single quotes over double quotes. Stylua offers such flexibility, allowing you to format files per custom style guides without manually editing every instance.

Explanation:

• stylua: Begins the Stylua application.
• --indent-type Spaces: Sets spaces as the preferred indentation method rather than tabs.
• --quote-style AutoPreferSingle: Configures Stylua to automatically prefer single quotes for strings, aiding readability and style conformity.
• path/to/file_or_directory: The file or directory you wish to format, subjected to the specified stylistic preferences.

Example Output:

A feedback message indicating formatted files, such as:

Formatted `file1.lua` using spaces and single quotes

This demonstrates that formatting was applied using customized settings.

Conclusion:

Stylua is a powerful tool that helps maintain uniformity and readability across Lua codebases. With its various features and flexible configurations, using Stylua ensures that code adheres to predefined standards, facilitates teamwork by providing consistent code style, and increases workflow efficiency by automating the formatting process. By adapting it into different stages of development, developers can fully leverage its capabilities to improve both individual and collaborative projects.