# GDScript Toolkit
[![](https://github.com/Scony/godot-gdscript-toolkit/workflows/Tests/badge.svg?branch=master)](https://github.com/Scony/godot-gdscript-toolkit/actions)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](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.*"
```
### Godot 3
```
pip3 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
```
## 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@v3
- 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": "",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "",
"keywords": "GODOT,GDSCRIPT,PARSER,LINTER,FORMATTER",
"author": "Pawel Lampe",
"author_email": "pawel.lampe@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/76/34/b132307d74f5fcb1250a9a29c2b0479a701b0fab9425acd0af3eba6453e8/gdtoolkit-4.2.2.tar.gz",
"platform": null,
"description": "# GDScript Toolkit\n[![](https://github.com/Scony/godot-gdscript-toolkit/workflows/Tests/badge.svg?branch=master)](https://github.com/Scony/godot-gdscript-toolkit/actions)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](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```\n\n### Godot 3\n\n```\npip3 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```\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@v3\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.2.2",
"project_urls": {
"Homepage": "https://github.com/Scony/godot-gdscript-toolkit"
},
"split_keywords": [
"godot",
"gdscript",
"parser",
"linter",
"formatter"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "80f208745e13f1a90b8bae2b74c6aa599f68fd4f1d0fab9a3081382b8825b74f",
"md5": "7f4c31684c42c888456f8b1b5866d1b6",
"sha256": "f55df3cd6172fd925a6b2e78380b1a90b529586aab0128c01229979c4cd4d266"
},
"downloads": -1,
"filename": "gdtoolkit-4.2.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "7f4c31684c42c888456f8b1b5866d1b6",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 56762,
"upload_time": "2023-12-11T21:49:35",
"upload_time_iso_8601": "2023-12-11T21:49:35.401955Z",
"url": "https://files.pythonhosted.org/packages/80/f2/08745e13f1a90b8bae2b74c6aa599f68fd4f1d0fab9a3081382b8825b74f/gdtoolkit-4.2.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "7634b132307d74f5fcb1250a9a29c2b0479a701b0fab9425acd0af3eba6453e8",
"md5": "5a84f0e25563d6df0b7933fa76705bcb",
"sha256": "2f85fde94b9dceb5d602361c2a00c75e15ae3145d84f3971f34f7479de4eec39"
},
"downloads": -1,
"filename": "gdtoolkit-4.2.2.tar.gz",
"has_sig": false,
"md5_digest": "5a84f0e25563d6df0b7933fa76705bcb",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 42661,
"upload_time": "2023-12-11T21:49:36",
"upload_time_iso_8601": "2023-12-11T21:49:36.651004Z",
"url": "https://files.pythonhosted.org/packages/76/34/b132307d74f5fcb1250a9a29c2b0479a701b0fab9425acd0af3eba6453e8/gdtoolkit-4.2.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-12-11 21:49:36",
"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"
}