How to use the command stylua (with examples)

Stylua is an opinionated Lua code formatter. It automatically formats Lua code according to a specific set of rules and conventions. This can help improve code readability, maintainability, and consistency.

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

Code:

stylua path/to/file_or_directory

Motivation: Automatically formatting a file or directory with Stylua ensures that the Lua code is consistently styled and follows the defined rules. This can be especially useful when working on a codebase with multiple developers, as it helps maintain a uniform code style.

Explanation:

• stylua: The command to run Stylua.
• path/to/file_or_directory: The path to the file or directory to be formatted. This can be a single file or a directory containing multiple files.

Example output: The file or directory specified will be formatted according to the rules defined by Stylua. The output will display the changes made to each file, if any.

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

Code:

stylua --check path/to/file

Motivation: When working with a large codebase, it may not be feasible or necessary to format all files at once. This command allows you to check the formatting of a specific file without actually modifying it. It can be useful to ensure that the code follows the defined style rules before committing changes or making modifications.

Explanation:

• --check: An option that tells Stylua to only check the formatting without modifying the file.
• path/to/file: The path to the file to be checked.

Example output: The output will indicate whether the specified file is correctly formatted according to the rules defined by Stylua.

Use case 3: Run with a specific configuration file

Code:

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

Motivation: Stylua allows users to define their own configuration files to customize the formatting rules. This command allows you to specify the path to a specific configuration file, enabling you to use custom rules or override the default ones.

Explanation:

• --config-path: An option that specifies the path to the configuration file to be used.
• path/to/config_file: The path to the custom configuration file.
• path/to/file: The path to the file to be formatted using the specified configuration file.

Example output: The specified file will be formatted according to the rules defined in the custom configuration file. The output will display the changes made to the file, if any.

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

Code:

stylua - < path/to/file.lua

Motivation: This command allows you to format Lua code directly from the standard input (stdin) and output the formatted code to the standard output (stdout). It can be useful when integrating Stylua with other tools or scripts that read from or write to stdin and stdout.

Explanation:

• -: The dash symbol represents the standard input (stdin). It tells Stylua to read the Lua code from the stdin instead of a file.
• path/to/file.lua: The path to the input file containing the Lua code. This argument is only used for reference and does not affect the actual formatting process.

Example output: The formatted Lua code will be displayed in the standard output (stdout).

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: This command allows you to customize the way code is formatted by specifying different options. In this example, the formatting will use spaces for indentation and prefer single quotes for string literals.

Explanation:

• --indent-type Spaces: An option that specifies using spaces for indentation. Other possible values are “Tabs” and “Auto” to automatically determine the indentation type based on existing code.
• --quote-style AutoPreferSingle: An option that specifies using single quotes for string literals. Other possible values are “AutoPreferDouble” and “AlwaysDouble” to automatically determine the quote style based on existing code or always use double quotes.
• path/to/file_or_directory: The path to the file or directory to be formatted.

Example output: The file or directory specified will be formatted using spaces for indentation and preferring single quotes for string literals, according to the rules defined by Stylua. The output will display the changes made to each file, if any.

Conclusion:

The stylua command provides a convenient way to automatically format Lua code according to a specific set of rules and conventions. By using various options and arguments, you can customize the formatting behavior to suit your preferences. Whether you need to format a single file, check the formatting of a specific file, or format an entire directory, stylua has you covered.