glualint: Attempts to fix your syntax erroring Lua files.

[ language, lgpl, library ] [ Propose Tags ]
Versions [RSS] 1.24.6, 1.25.0, 1.26.0, 1.27.0, 1.28.0
Dependencies aeson (>=2 && <3), base (>=4.5 && <5), bytestring (>=0.11 && <1), containers (>=0.6 && <1), deepseq (>=1.4 && <2), directory (>=1.3 && <2), effectful (>=2.2 && <3), filemanip (>=0.3 && <0.4), filepath, glualint, optparse-applicative (>=0.17 && <1), parsec (>=3 && <4), pretty (>=1.1 && <1.2), signal (>=0.1 && <0.2), uuagc (>=0.9.40.3 && <0.10), uuagc-cabal (>=1.0.3.0 && <2) [details]
License LGPL-2.1-or-later
Copyright Falco Peijnenburg
Author Falco Peijnenburg
Maintainer fpeijnenburg@gmail.com
Category Language
Home page https://github.com/FPtje/GLuaFixer
Bug tracker https://github.com/FPtje/GLuaFixer/issues
Source repo head: git clone git@github.com:FPtje/GLuaFixer.git
Uploaded by FPtje at 2024-01-01T13:39:50Z
Distributions
Executables glualint
Downloads 169 total (16 in the last 30 days)
Rating (no votes yet) [estimated by Bayesian average]
Your Rating
  • λ
  • λ
  • λ
Status Docs available [build log]
Last success reported on 2024-01-01 [all 1 reports]

Readme for glualint-1.28.0

[back to package description]

glualint

glualint - Linter and pretty printer for Garry's Mod's variant of Lua.

Installing

  1. Download the latest version of glualint from the releases page OR compile it yourself. If you download for Linux, make sure to run the right version. Most computers will need the x86_64 version. Embedded systems like a Raspberry pi will need the aarch64-linux version.
  2. Place the glualint executable inside some folder.
  3. Add the folder you put glualint in to your PATH. How this is done differs per operating system. If you're not sure how to do this, please Google "Add to path <YOUR OS>".
  4. Make sure you restart any terminals or text editors you currently have open.

After performing these steps, you can run glualint from the terminal or let your text editor use it as your linter. Failing to specifically perform the third step will make glualint very unlikely to work.

Command line parameters

Parameter Description
--version Returns the version of glualint.
--config Set to a glualint.json file for glualint configuration. See "Configuring glualint".
--pretty-print Will pretty-print (re-structure/re-indent) all code given in stdin. When entering code in terminal, press Ctrl+D to finish the input.
--pretty-print-files As above but pretty-prints the specified file or directory instead of stdin.
--indentation='something' For pretty-print: indents all pretty-printed code with the given string. Four spaces by default, should probably some amount of tabs or spaces.
--stdin Process stdin instead of specified file or directory when linting.
--analyse-globals Show global variables/functions that this file defines.
--test For debugging: test whether glualint works correctly on the given files and/or folders. Tries to parse with the two available parsers, then pretty prints and tries to parse the pretty printed result. It will show errors when it fails.

Configuring glualint

glualint Allows some configuration. This is done through a file called glualint.json or .glualint.json. glualint looks for this file in three places (in order of priority)

  • The file you give to the --config parameter (when using the terminal)
  • Any folder above the file you're working in (e.g. the root of your project)
  • Your home folder, which is C:\users\yourusername\.glualint.json on Windows or /home/yourusername/.glualint.json on Unix.

Note: The file must either be called glualint.json or .glualint.json.

Example glualint.json with the default options:

{
    "lint_maxScopeDepth": 7,
    "lint_syntaxErrors": true,
    "lint_syntaxInconsistencies": true,
    "lint_deprecated": true,
    "lint_trailingWhitespace": true,
    "lint_whitespaceStyle": true,
    "lint_beginnerMistakes": true,
    "lint_emptyBlocks": true,
    "lint_shadowing": true,
    "lint_gotos": true,
    "lint_goto_identifier": true,
    "lint_doubleNegations": true,
    "lint_redundantIfStatements": true,
    "lint_redundantParentheses": true,
    "lint_duplicateTableKeys": true,
    "lint_profanity": true,
    "lint_unusedVars": true,
    "lint_unusedParameters": false,
    "lint_unusedLoopVars": false,
    "lint_inconsistentVariableStyle": false,
    "lint_spaceBetweenParens": false,
    "lint_spaceBetweenBrackets": false,
    "lint_spaceBetweenBraces": false,
    "lint_ignoreFiles": [],
    "lint_spaceBeforeComma": false,
    "lint_spaceAfterComma": false,
    "lint_maxLineLength": 0,

    "prettyprint_spaceBetweenParens": false,
    "prettyprint_spaceBetweenBrackets": false,
    "prettyprint_spaceBetweenBraces": false,
    "prettyprint_spaceEmptyParens": false,
    "prettyprint_spaceEmptyBraces": false,
    "prettyprint_spaceAfterLabel": false,
    "prettyprint_spaceBeforeComma": false,
    "prettyprint_spaceAfterComma": true,
    "prettyprint_semicolons": false,
    "prettyprint_cStyle": false,
    "prettyprint_removeRedundantParens": true,
    "prettyprint_minimizeParens": false,
    "prettyprint_assumeOperatorAssociativity": true,
    "prettyprint_indentation": "    ",

    "log_format": "auto"
}

All options explained

Linter options

Option Description
lint_maxScopeDepth Maximum depth of scopes in your code. Any terrible scripter can build the most atrocious sideways code pyramids, usually without knowing. The number here is at which step the linter will start calling you out on it. Set to 0 if you're king Tut and want to disable it.
lint_syntaxErrors Whether syntax errors should be reported. This is off by default because gluac shows nicer syntax errors.
lint_syntaxInconsistencies Warn for syntax inconsistencies (using both && and and, that kind of stuff)
lint_deprecated Warn for deprecated functions. These functions are taken from the GMod wiki, don't blame me for the things that are on there.
lint_trailingWhitespace Warn for whitespace at the end of a line. Your editor should have an option to automatically trim trailing whitespace.
lint_whitespaceStyle Warn for bad whitespace behaviour (e.g. lack of spaces around operators and keywords)
lint_beginnerMistakes Warn for typical beginner mistakes (using self in non-metafunction, net.WriteEntity(LocalPlayer()) in a net message, using self.Weapon in a SWEP etc.)
lint_emptyBlocks Warn for empty blocks
lint_shadowing Warn for variable shadowing
lint_gotos Warn for inappropriate gotos (i.e. the ones not used to jump out of a double loop)
lint_goto_identifier Warn when goto is used as an identifier (e.g. a = {goto = 1}). This warning exists because goto being allowed as identifier is actually a bug. You should not be able to use goto like that for the same reason you're not allowed to use any other keyword as identifier.
lint_doubleNegations Warn for double negations (things like not (a == b))
lint_redundantIfStatements Warn for nested if-statements that can be combined with and
lint_redundantParentheses Warn for unneeded parentheses around expressions.
lint_duplicateTableKeys Warn for duplicate table keys (e.g. {a = 1, a = 2})
lint_profanity Warn for profanity (bitch, cock, cocks, cunt, dick, dicks, fuck, fucking, goddamnit, knob, knobs, motherfucker, nipple, shit)
lint_unusedVars Warn for variables that are never used
lint_unusedParameters Warn for function parameters that are never used. NOTE: Only has effect when lint_unusedVars is enabled!
lint_unusedLoopVars Warn for loop variables that are never used (for k,v in ...). NOTE: Only has effect when lint_unusedVars is enabled!
lint_ignoreFiles Files to ignore when linting. You can use glob patterns (e.g. "**.lua", "*.lua" or libraries/*.lua)
lint_inconsistentVariableStyle Whether to warn about inconsistent styles in naming local variables (e.g. lowercase and uppercase variables)
lint_spaceBetweenParens Whether to warn about there being spaces between parentheses. This option used to be named lint_spaceAfterParens. For backwards compatibility that option still works.
lint_spaceBetweenBrackets Whether to warn about there being spaces between brackets. This option used to be named lint_spaceAfterBrackets. For backwards compatibility that option still works.
lint_spaceBetweenBraces Whether to warn about there being spaces between braces. This option used to be named lint_spaceAfterBraces. For backwards compatibility that option still works.
lint_spaceBeforeComma Whether to warn about spaces before the comma. This option depends on prettyprint_spaceBeforeComma on whether the space is wanted.
lint_spaceAfterComma Whether to warn about spaces after the comma. This option depends on prettyprint_spaceAfterComma on whether the space is wanted.
lint_maxLineLength Warn for lines longer than the given number. Set to 0 to disable.

Pretty print options

These options affect the pretty printing functionality of glualint.

Option Description
prettyprint_spaceBetweenParens Put a space between all parentheses
prettyprint_spaceBetweenBrackets Put a space between all brackets
prettyprint_spaceBetweenBraces Put a space between all curly braces
prettyprint_spaceEmptyParens Put a space between empty parentheses (e.g. ( )). Only applies when prettyprint_spaceBetweenParens is set
prettyprint_spaceEmptyBraces Put a space between empty braces (e.g. { }). Only applies when prettyprint_spaceBetweenBraces is set
prettyprint_spaceAfterLabel Put a space after a ::label:: statement
prettyprint_semicolons Clutter the script with semicolons after every damn statement
prettyprint_cStyle Use C style operators and comments everywhere
prettyprint_indentation What to use for indentation. Any string is valid, but some amount of spaces or "\t" is recommended
prettyprint_spaceBeforeComma Whether to place a space before every comma
prettyprint_spaceAfterComma Whether to place a space after every comma
prettyprint_removeRedundantParens Whether to remove unnecessary parentheses (e.g. x = (1 + 2), if ((1) + (2) == 3) then)
prettyprint_minimizeParens Removes parentheses which are unnecessary due to operator precedence (e.g. (1 * 2) + 3). This option also removes redundant parameters, regardless of whether prettyprint_removeRedundantParens is enabled.
prettyprint_assumeOperatorAssociativity Only takes effect when prettyprint_minimizeParens is true. It decides whether parameters can be removed when the involved operators are assumed associative. Examples: a * (b * c), a and (b and c). This assumption is generally true, except for floating point numbers, where removing parentheses can actually change the outcome of the calculation. See Stack Overflow. This option is set to true by default, because the expectation is that this will not be problematic even if it affects your code. In a very rare case, this might cause trouble, though. You might want to consider turning this off if you have floating point code that heavily relies on evaluation order. You may also choose to leave this option on and ensure evaluation order by explicitly setting variables.

Other options

  • log_format: Decides how to format linter warnings and error messages. Possible values are "auto", "standard" and "github". The "github" output format is specifically designed for usage with GitHub actions. The default value is "auto", With "auto", the log format will be "github" when the environment variables GITHUB_ACTIONS and GITHUB_WORKFLOW are both present, and "standard" otherwise.

In-code directives

If you add a comment containing the text format: multiline, the next statement will be forced to be pretty printed as multiline. Example:

-- format: multiline
a = {1, 2, 3}

Will be turned into:

-- format: multiline
a = {
  1,
  2,
  3
}

Editor Plugins

Through community support, GLuaFixer is supported across a wide variety of popular editors.

Here's a list of plugins we recommend (PRs for more tools welcome!):

Sublime

Atom

VS Code

Vim

Reusable Workflow

You can easily run GLuaFixer in your own Workflows using the included Reusable Workflow.

Setup

To run GLuaFixer on all of your PRs, create a new file in your repository: .github/workflows/glualint.yml with the following contents:

name: GLuaFixer

on:
  pull_request:

jobs:
  Lint:
    uses: FPtje/GLuaFixer/.github/workflows/glualint.yml@master

Now, every time you make or update a PR, GLuaFixer will run and report any linting violations right on your PR!

Configuration

The GLuaFixer Workflow can be configured, too.

You have two options for configuration:

  • Include a file in your repository containing the GLuaFixer config
  • Upload your GLuaFixer config somewhere (gist.github.com, pastebin/hastebin, etc.)

Then, modify your Workflow like so:

name: GLuaLint

on:
  pull_request:

jobs:
  Lint:
    uses: FPtje/GLuaFixer/.github/workflows/glualint.yml@master
    with:
      config: "<link or relative path to config file>"