GDScript Toolkit
This project provides a set of tools for daily work with GDScript. At the moment it provides:
- A parser that produces a parse tree for debugging and educational purposes.
- A linter that performs a static analysis according to some predefined configuration.
- A formatter that formats the code according to some predefined rules.
Installation
To install this project you need python3 and pip.
Use this command in your terminal to install from this git repository:
pip3 install gdtoolkit
Linting with gdlint
To run a linter you need to perform installation first. Once done, you can run e.g.:
$ gdlint misc/MarkovianPCG.gd
Which outputs messages like:
misc/MarkovianPCG.gd:96: Error: Function argument name "aOrigin" is not valid (function-argument-name)
misc/MarkovianPCG.gd:96: Error: Function argument name "aPos" is not valid (function-argument-name)
To tweak the default check settings, you can dump the default config to a file:
$ gdlint -d
$ cat gdlintrc
class-load-variable-name: (([A-Z][a-z0-9]*)+|_?[a-z][a-z0-9]*(_[a-z0-9]+)*)
class-name: ([A-Z][a-z0-9]*)+
class-variable-name: _?[a-z][a-z0-9]*(_[a-z0-9]+)*
constant-name: '[A-Z][A-Z0-9]*(_[A-Z0-9]+)*'
disable: []
enum-element-name: '[A-Z][A-Z0-9]*(_[A-Z0-9]+)*'
enum-name: ([A-Z][a-z0-9]*)+
function-argument-name: _?[a-z][a-z0-9]*(_[a-z0-9]+)*
function-arguments-number: 10
function-preload-variable-name: ([A-Z][a-z0-9]*)+
function-name: (_on_([A-Z][a-z0-9]*)+(_[a-z0-9]+)*|_?[a-z][a-z0-9]*(_[a-z0-9]+)*)
function-variable-name: '[a-z][a-z0-9]*(_[a-z0-9]+)*'
load-constant-name: (([A-Z][a-z0-9]*)+|[A-Z][A-Z0-9]*(_[A-Z0-9]+)*)
loop-variable-name: _?[a-z][a-z0-9]*(_[a-z0-9]+)*
signal-name: '[a-z][a-z0-9]*(_[a-z0-9]+)*'
sub-class-name: _?([A-Z][a-z0-9]*)+
Once the dump is performed, you can modify the gdlintrc file and optionally rename it to .gdlintrc. From now on, linter will use this config file to override the default config.
Formatting with gdformat
Formatting may lead to data loss, so it's highly recommended to use it along with Version Control System (VCS) e.g. git
gdformat is the uncompromising GDScript code formatter. The only configurable thing is max line length allowed (--line-length). The rest will be taken care of by gdformat in a one, consistent way.
To run a formatter you need to perform installation first. Once done, given a test.gd file:
class X:
var x=[1,2,{'a':1}]
var y=[1,2,3,] # trailing comma
func foo(a:int,b,c=[1,2,3]):
if a in c and \
b > 100:
print('foo')
func bar():
print('bar')
when you run gdformat test.gd, the test.gd file will be reformatted as follows:
class X:
var x = [1, 2, {'a': 1}]
var y = [
1,
2,
3,
] # trailing comma
func foo(a: int, b, c = [1, 2, 3]):
if a in c and b > 100:
print('foo')
func bar():
print('bar')
If the program formats your files successfully, it will return the exit code 0. Non-zero code will be returned otherwise.
Parsing with gdparse
To parse a file, use the gdparse program:
gdparse tests/valid-gd-scripts/recursive_tool.gd -p
The parser outputs a tree that represents your code's structure:
start
class_def
X
class_body
tool_stmt
signal_stmt sss
class_def
Y
class_body
tool_stmt
signal_stmt sss
tool_stmt
If the program parses your file sucessfully, it will return the exit code 0.
Running tests
To run tests you need tox, a tool to automate testing in Python.
Install it with:
pip3 install tox
To invoke entire test suite, in the godot-gdscript-toolkit project directory, run:
tox
You can run only selected test cases:
tox -e py3 -- -k lint
For manual testing, you can consider installing package in editable mode:
pip3 install -e .
