# GDScript Toolkit
[](https://github.com/Scony/godot-gdscript-toolkit/actions)
[](https://opensource.org/licenses/MIT)
[](https://github.com/psf/black)
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.
- A code metrics calculator which calculates cyclomatic complexity of functions and classes.
## Installation
To install this project you need `python3` and `pip`.
Regardless of the target version, installation is done by `pip3` command and for stable releases, it downloads the package from PyPI.
### Godot 4
```
pip3 install "gdtoolkit==4.*"
# or
pipx install "gdtoolkit==4.*"
```
### Godot 3
```
pip3 install "gdtoolkit==3.*"
# or
pipx install "gdtoolkit==3.*"
```
### `master` (latest)
Latest version (potentially unstable) can be installed directly from git:
```
pip3 install git+https://github.com/Scony/godot-gdscript-toolkit.git
# or
pipx install git+https://github.com/Scony/godot-gdscript-toolkit.git
```
## Linting with gdlint [(more)](https://github.com/Scony/godot-gdscript-toolkit/wiki/3.-Linter)
To run a linter you need to execute `gdlint` command like:
```
$ 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)
```
## Formatting with gdformat [(more)](https://github.com/Scony/godot-gdscript-toolkit/wiki/4.-Formatter)
**Formatting may lead to data loss, so it's highly recommended to use it along with Version Control System (VCS) e.g. `git`**
To run a formatter you need to execute `gdformat` on the file you want to format. So, 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 execute `gdformat test.gd` command, 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')
```
## Parsing with gdparse [(more)](https://github.com/Scony/godot-gdscript-toolkit/wiki/2.-Parser)
To run a parser you need to execute the `gdparse` command like:
```
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
```
## Calculating cyclomatic complexity with gdradon
To run cyclomatic complexity calculator you need to execute the `gdradon` command like:
```
gdradon cc tests/formatter/input-output-pairs/simple-function-statements.in.gd tests/gd2py/input-output-pairs/
```
The command outputs calculated metrics just like [Radon cc command](https://radon.readthedocs.io/en/latest/commandline.html#the-cc-command) does for Python code:
```
tests/formatter/input-output-pairs/simple-function-statements.in.gd
C 1:0 X - A (2)
F 2:1 foo - A (1)
tests/gd2py/input-output-pairs/class-level-statements.in.gd
F 22:0 foo - A (1)
F 24:0 bar - A (1)
C 18:0 C - A (1)
tests/gd2py/input-output-pairs/func-level-statements.in.gd
F 1:0 foo - B (8)
```
## Using gdtoolkit's GitHub action
In order to setup a simple action with gdtoolkit's static checks, the base action from this repo can be used:
```
name: Static checks
on:
push:
branches: [ "main" ]
pull_request:
branches: [ "main" ]
jobs:
static-checks:
name: 'Static checks'
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: Scony/godot-gdscript-toolkit@master
- run: gdformat --check source/
- run: gdlint source/
```
See the discussion in https://github.com/Scony/godot-gdscript-toolkit/issues/239 for more details.
## Development [(more)](https://github.com/Scony/godot-gdscript-toolkit/wiki/5.-Development)
Everyone is free to fix bugs or introduce new features. For that, however, please refer to existing issue or create one before starting implementation.
Raw data
{
"_id": null,
"home_page": "https://github.com/Scony/godot-gdscript-toolkit",
"name": "gdtoolkit",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "GODOT, GDSCRIPT, PARSER, LINTER, FORMATTER",
"author": "Pawel Lampe",
"author_email": "pawel.lampe@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/5e/71/0563b7f812c4db67ead1d47cf6710c3e9c6e1a7d505321240efc7638c08b/gdtoolkit-4.3.3.tar.gz",
"platform": null,
"description": "# GDScript Toolkit\n[](https://github.com/Scony/godot-gdscript-toolkit/actions)\n[](https://opensource.org/licenses/MIT)\n[](https://github.com/psf/black)\n\nThis project provides a set of tools for daily work with `GDScript`. At the moment it provides:\n\n- A parser that produces a parse tree for debugging and educational purposes.\n- A linter that performs a static analysis according to some predefined configuration.\n- A formatter that formats the code according to some predefined rules.\n- A code metrics calculator which calculates cyclomatic complexity of functions and classes.\n\n## Installation\n\nTo install this project you need `python3` and `pip`.\nRegardless of the target version, installation is done by `pip3` command and for stable releases, it downloads the package from PyPI.\n\n### Godot 4\n\n```\npip3 install \"gdtoolkit==4.*\"\n# or\npipx install \"gdtoolkit==4.*\"\n```\n\n### Godot 3\n\n```\npip3 install \"gdtoolkit==3.*\"\n# or\npipx install \"gdtoolkit==3.*\"\n```\n\n### `master` (latest)\n\nLatest version (potentially unstable) can be installed directly from git:\n```\npip3 install git+https://github.com/Scony/godot-gdscript-toolkit.git\n# or\npipx install git+https://github.com/Scony/godot-gdscript-toolkit.git\n```\n\n## Linting with gdlint [(more)](https://github.com/Scony/godot-gdscript-toolkit/wiki/3.-Linter)\n\nTo run a linter you need to execute `gdlint` command like:\n\n```\n$ gdlint misc/MarkovianPCG.gd\n```\n\nWhich outputs messages like:\n\n```\nmisc/MarkovianPCG.gd:96: Error: Function argument name \"aOrigin\" is not valid (function-argument-name)\nmisc/MarkovianPCG.gd:96: Error: Function argument name \"aPos\" is not valid (function-argument-name)\n```\n\n## Formatting with gdformat [(more)](https://github.com/Scony/godot-gdscript-toolkit/wiki/4.-Formatter)\n\n**Formatting may lead to data loss, so it's highly recommended to use it along with Version Control System (VCS) e.g. `git`**\n\nTo run a formatter you need to execute `gdformat` on the file you want to format. So, given a `test.gd` file:\n\n```\nclass X:\n\tvar x=[1,2,{'a':1}]\n\tvar y=[1,2,3,] # trailing comma\n\tfunc foo(a:int,b,c=[1,2,3]):\n\t\tif a in c and \\\n\t\t b > 100:\n\t\t\tprint('foo')\nfunc bar():\n\tprint('bar')\n```\n\nwhen you execute `gdformat test.gd` command, the `test.gd` file will be reformatted as follows:\n\n```\nclass X:\n\tvar x = [1, 2, {'a': 1}]\n\tvar y = [\n\t\t1,\n\t\t2,\n\t\t3,\n\t] # trailing comma\n\n\tfunc foo(a: int, b, c = [1, 2, 3]):\n\t\tif a in c and b > 100:\n\t\t\tprint('foo')\n\n\nfunc bar():\n\tprint('bar')\n```\n\n## Parsing with gdparse [(more)](https://github.com/Scony/godot-gdscript-toolkit/wiki/2.-Parser)\n\nTo run a parser you need to execute the `gdparse` command like:\n\n```\ngdparse tests/valid-gd-scripts/recursive_tool.gd -p\n```\n\nThe parser outputs a tree that represents your code's structure:\n\n```\nstart\n class_def\n X\n class_body\n tool_stmt\n signal_stmt\tsss\n class_def\n Y\n class_body\n tool_stmt\n signal_stmt\tsss\n tool_stmt\n```\n\n## Calculating cyclomatic complexity with gdradon\n\nTo run cyclomatic complexity calculator you need to execute the `gdradon` command like:\n\n```\ngdradon cc tests/formatter/input-output-pairs/simple-function-statements.in.gd tests/gd2py/input-output-pairs/\n```\n\nThe command outputs calculated metrics just like [Radon cc command](https://radon.readthedocs.io/en/latest/commandline.html#the-cc-command) does for Python code:\n```\ntests/formatter/input-output-pairs/simple-function-statements.in.gd\n C 1:0 X - A (2)\n F 2:1 foo - A (1)\ntests/gd2py/input-output-pairs/class-level-statements.in.gd\n F 22:0 foo - A (1)\n F 24:0 bar - A (1)\n C 18:0 C - A (1)\ntests/gd2py/input-output-pairs/func-level-statements.in.gd\n F 1:0 foo - B (8)\n```\n\n## Using gdtoolkit's GitHub action\n\nIn order to setup a simple action with gdtoolkit's static checks, the base action from this repo can be used:\n\n```\nname: Static checks\n\non:\n push:\n branches: [ \"main\" ]\n pull_request:\n branches: [ \"main\" ]\n\njobs:\n static-checks:\n name: 'Static checks'\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@v4\n - uses: Scony/godot-gdscript-toolkit@master\n - run: gdformat --check source/\n - run: gdlint source/\n```\n\nSee the discussion in https://github.com/Scony/godot-gdscript-toolkit/issues/239 for more details.\n\n## Development [(more)](https://github.com/Scony/godot-gdscript-toolkit/wiki/5.-Development)\n\nEveryone is free to fix bugs or introduce new features. For that, however, please refer to existing issue or create one before starting implementation.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Independent set of tools for working with GDScript - parser, linter and formatter",
"version": "4.3.3",
"project_urls": {
"Homepage": "https://github.com/Scony/godot-gdscript-toolkit"
},
"split_keywords": [
"godot",
" gdscript",
" parser",
" linter",
" formatter"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "5bd75393b3c65359741e2f679c23884033acc4650007caf96f158426f501809d",
"md5": "880590c4388fc1bee097c20ef4c140fc",
"sha256": "0296f4f2211668ddcb827455d58eda00a3fc4d334fea8da2f9da49c5578d77fa"
},
"downloads": -1,
"filename": "gdtoolkit-4.3.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "880590c4388fc1bee097c20ef4c140fc",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 59886,
"upload_time": "2024-11-02T11:34:57",
"upload_time_iso_8601": "2024-11-02T11:34:57.134705Z",
"url": "https://files.pythonhosted.org/packages/5b/d7/5393b3c65359741e2f679c23884033acc4650007caf96f158426f501809d/gdtoolkit-4.3.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "5e710563b7f812c4db67ead1d47cf6710c3e9c6e1a7d505321240efc7638c08b",
"md5": "3d6c09ae2cc63ceb1527a397339452f4",
"sha256": "f17089c3e33d0053ab229a637a9faabc0fb8ebb07412fe719ed00b2e66adc343"
},
"downloads": -1,
"filename": "gdtoolkit-4.3.3.tar.gz",
"has_sig": false,
"md5_digest": "3d6c09ae2cc63ceb1527a397339452f4",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 44956,
"upload_time": "2024-11-02T11:34:58",
"upload_time_iso_8601": "2024-11-02T11:34:58.367460Z",
"url": "https://files.pythonhosted.org/packages/5e/71/0563b7f812c4db67ead1d47cf6710c3e9c6e1a7d505321240efc7638c08b/gdtoolkit-4.3.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-02 11:34:58",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Scony",
"github_project": "godot-gdscript-toolkit",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "gdtoolkit"
}
JSON
