1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
|
.. Copyright (c) 2017-2026 Juancarlo Añez (apalala@gmail.com)
.. SPDX-License-Identifier: BSD-4-Clause
.. include:: links.rst
Contributing
------------
The source code for |TatSu| is posted to it's repository_ on GitHub. Bug reports, patches,
suggestions, and improvements are welcome.
.. _repository : https://github.com/neogeny/TatSu
If you want to contribute to the development of |TatSu|, follow the
instructions below to create an environment in which |TatSu| can
be tested.
Programming |TatSu|
~~~~~~~~~~~~~~~~~~~
prerequisites
^^^^^^^^^^^^^
Before creating an environment for |TatSu| these must be available:
* Python >= 3.12 (use your preferred way of installing it)
* uv_ as project environment manager (see the `uv installation instructions`_).
* optional installation of Invoke_ on the system's ``python3``
.. _uv installation instructions: https://docs.astral.sh/uv/getting-started/installation/
|TatSu| relies on Invoke_'s ``tasks.py`` to run the tasks for static analysis,
testing, building, documentation, and publishing the project. ``tasks.py`` resides
in ``./tatsu/tasks.py`` and there is a symbolic link to it at the project's repository
root, ``./tasks.py``.
To run the tasks use:
.. code:: bash
$ uv run inv
Or fun ``inv`` directly if it's installed on the system's ``python3``:
.. code:: bash
$ inv
bootstrap
^^^^^^^^^
Clone the |TatSu| repository and switch to the created directory:
.. code:: bash
$ git clone git@github.com:neogeny/TatSu.git
$ cd tatsu
There will be at least these directories under the main project directory:
* **./tatsu/** the top level package for the project
* **./tests/** unit and integration tests
* **./grammar/** grammars used by the project
* **./docs/** the Sphinx_ documentation
* **./examples/** example projects
* **./etc/** configuration files and templates
.. code:: console
.
├── docs
│ └── _static
│ ├── css
│ └── images
├── etc
│ ├── sublime
│ └── vim
│ ├── ftdetect
│ └── syntax
├── examples
│ ├── calc
│ │ └── grammars
│ └── g2e
│ └── grammar
├── grammar
├── media
├── scripts
├── tatsu
│ ├── codegen
│ ├── collections
│ ├── g2e
│ ├── mixins
│ ├── ngcodegen
│ └── util
└── tests
├── grammar
└── zzz_bootstrap
environment
^^^^^^^^^^^
Use uv_ to create and configure a Python_ environment with the libraries required
for development and testing:
.. code:: bash
$ uv sync
testing
^^^^^^^
The ``tasks.py`` runs all static analysis (linting), typing, unit test,
documentation, and build tasks by default.
as the default:
.. code:: bash
$ uv run inv
────────────────────────────────────────────────────────
-> clean
-> ruff
-> ty
-> pyright
──── ✔ lint ────────────────────────────────────────────
-> pytest
──── ✔ test ────────────────────────────────────────────
-> docs
──── ✔ docs ────────────────────────────────────────────
-> examples/g2e
-> examples/calc
──── ✔ examples ────────────────────────────────────────
-> build
──── ✔ build ───────────────────────────────────────────
-> requirements.txt
-> requirements-dev.txt
-> requirements-test.txt
-> requirements-doc.txt
──── ✔ requirements ────────────────────────────────────
──── ✔ all ─────────────────────────────────────────────
Sponsorship
~~~~~~~~~~~
| |sponsor|
| |paypal|
If you'd like to contribute to the future development of |TatSu|,
please `make a donation`_ to the project.
Among the planned new features a unified intermediate model for parsing and
translating programming languages.
.. |sponsor| image:: https://img.shields.io/badge/Sponsor-EA4AAA?label=TatSu
:target: https://github.com/sponsors/neogeny
.. |paypal| image:: https://img.shields.io/badge/Ko--fi-F16061?style=for-the-badge&logo=ko-fi&logoColor=white&label=TatSu
:target: https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=2TW56SV6WNJV6
:height: 20
|
