sipl-lang 0.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- sipl_lang-0.1.0/.gitignore +27 -0
- sipl_lang-0.1.0/CHANGELOG.md +24 -0
- sipl_lang-0.1.0/PKG-INFO +198 -0
- sipl_lang-0.1.0/README.md +176 -0
- sipl_lang-0.1.0/docs/cli.md +118 -0
- sipl_lang-0.1.0/docs/diagnostics.md +72 -0
- sipl_lang-0.1.0/docs/images/power-tree.png +0 -0
- sipl_lang-0.1.0/docs/language.md +60 -0
- sipl_lang-0.1.0/examples/divmod.sipl +12 -0
- sipl_lang-0.1.0/examples/gcd.sipl +7 -0
- sipl_lang-0.1.0/examples/infinite_loop.sipl +7 -0
- sipl_lang-0.1.0/examples/power.sipl +10 -0
- sipl_lang-0.1.0/examples/sign.sipl +10 -0
- sipl_lang-0.1.0/pyproject.toml +65 -0
- sipl_lang-0.1.0/src/sipl/__init__.py +40 -0
- sipl_lang-0.1.0/src/sipl/__main__.py +7 -0
- sipl_lang-0.1.0/src/sipl/analysis.py +55 -0
- sipl_lang-0.1.0/src/sipl/ast.py +218 -0
- sipl_lang-0.1.0/src/sipl/cli.py +292 -0
- sipl_lang-0.1.0/src/sipl/diagnostics.py +102 -0
- sipl_lang-0.1.0/src/sipl/grammar/sipl.lark +112 -0
- sipl_lang-0.1.0/src/sipl/interpreter/__init__.py +44 -0
- sipl_lang-0.1.0/src/sipl/interpreter/events.py +154 -0
- sipl_lang-0.1.0/src/sipl/interpreter/machine.py +276 -0
- sipl_lang-0.1.0/src/sipl/interpreter/trace.py +49 -0
- sipl_lang-0.1.0/src/sipl/parser.py +316 -0
- sipl_lang-0.1.0/src/sipl/printer.py +62 -0
- sipl_lang-0.1.0/src/sipl/productions.py +61 -0
- sipl_lang-0.1.0/src/sipl/py.typed +0 -0
- sipl_lang-0.1.0/src/sipl/source.py +82 -0
- sipl_lang-0.1.0/src/sipl/visualization/__init__.py +12 -0
- sipl_lang-0.1.0/src/sipl/visualization/parse_tree.py +220 -0
- sipl_lang-0.1.0/tests/conftest.py +18 -0
- sipl_lang-0.1.0/tests/grammar/invalid/01_empty.sipl +0 -0
- sipl_lang-0.1.0/tests/grammar/invalid/02_missing_begin.sipl +1 -0
- sipl_lang-0.1.0/tests/grammar/invalid/03_trailing_semicolon.sipl +3 -0
- sipl_lang-0.1.0/tests/grammar/invalid/04_eq_instead_of_assign.sipl +1 -0
- sipl_lang-0.1.0/tests/grammar/invalid/05_if_without_else.sipl +3 -0
- sipl_lang-0.1.0/tests/grammar/invalid/06_less_than.sipl +1 -0
- sipl_lang-0.1.0/tests/grammar/invalid/07_division.sipl +1 -0
- sipl_lang-0.1.0/tests/grammar/invalid/08_missing_semicolon.sipl +4 -0
- sipl_lang-0.1.0/tests/grammar/invalid/09_keyword_as_variable.sipl +1 -0
- sipl_lang-0.1.0/tests/grammar/invalid/10_unclosed_paren.sipl +1 -0
- sipl_lang-0.1.0/tests/grammar/invalid/11_missing_end.sipl +3 -0
- sipl_lang-0.1.0/tests/grammar/invalid/12_and_operator.sipl +1 -0
- sipl_lang-0.1.0/tests/grammar/invalid/13_unary_minus_on_variable.sipl +1 -0
- sipl_lang-0.1.0/tests/grammar/invalid/14_text_after_program.sipl +2 -0
- sipl_lang-0.1.0/tests/grammar/invalid/15_sequence_in_branch.sipl +1 -0
- sipl_lang-0.1.0/tests/grammar/invalid/16_condition_as_value.sipl +1 -0
- sipl_lang-0.1.0/tests/grammar/invalid/expected.json +18 -0
- sipl_lang-0.1.0/tests/grammar/valid/01_minimal.sipl +1 -0
- sipl_lang-0.1.0/tests/grammar/valid/02_assign.sipl +1 -0
- sipl_lang-0.1.0/tests/grammar/valid/03_negative_numbers.sipl +6 -0
- sipl_lang-0.1.0/tests/grammar/valid/04_precedence.sipl +2 -0
- sipl_lang-0.1.0/tests/grammar/valid/05_nested_blocks.sipl +1 -0
- sipl_lang-0.1.0/tests/grammar/valid/06_if_else_chain.sipl +5 -0
- sipl_lang-0.1.0/tests/grammar/valid/07_while_block.sipl +8 -0
- sipl_lang-0.1.0/tests/grammar/valid/08_bool_unicode.sipl +2 -0
- sipl_lang-0.1.0/tests/grammar/valid/09_bool_ascii.sipl +2 -0
- sipl_lang-0.1.0/tests/grammar/valid/10_comments_whitespace.sipl +6 -0
- sipl_lang-0.1.0/tests/grammar/valid/11_identifiers.sipl +2 -0
- sipl_lang-0.1.0/tests/grammar/valid/12_while_single_stmt.sipl +2 -0
- sipl_lang-0.1.0/tests/test_analysis.py +42 -0
- sipl_lang-0.1.0/tests/test_cli.py +186 -0
- sipl_lang-0.1.0/tests/test_events.py +162 -0
- sipl_lang-0.1.0/tests/test_grammar.py +75 -0
- sipl_lang-0.1.0/tests/test_interpreter.py +153 -0
- sipl_lang-0.1.0/tests/test_parser.py +213 -0
- sipl_lang-0.1.0/tests/test_printer.py +67 -0
- sipl_lang-0.1.0/tests/test_visualization.py +93 -0
- sipl_lang-0.1.0/vscode-sipl/README.md +81 -0
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
# Python
|
|
2
|
+
__pycache__/
|
|
3
|
+
*.py[cod]
|
|
4
|
+
.venv/
|
|
5
|
+
venv/
|
|
6
|
+
*.egg-info/
|
|
7
|
+
build/
|
|
8
|
+
dist/
|
|
9
|
+
.pytest_cache/
|
|
10
|
+
.mypy_cache/
|
|
11
|
+
.ruff_cache/
|
|
12
|
+
.coverage
|
|
13
|
+
coverage.xml
|
|
14
|
+
htmlcov/
|
|
15
|
+
|
|
16
|
+
# Generated visualizations
|
|
17
|
+
out/
|
|
18
|
+
|
|
19
|
+
# VS Code extension build
|
|
20
|
+
vscode-sipl/node_modules/
|
|
21
|
+
vscode-sipl/out/
|
|
22
|
+
vscode-sipl/*.vsix
|
|
23
|
+
|
|
24
|
+
# Editors / OS
|
|
25
|
+
.idea/
|
|
26
|
+
.DS_Store
|
|
27
|
+
Thumbs.db
|
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
Формат — [Keep a Changelog](https://keepachangelog.com/uk/1.1.0/),
|
|
4
|
+
версії — [Semantic Versioning](https://semver.org/lang/uk/).
|
|
5
|
+
|
|
6
|
+
## [0.1.0] - 2026-11-16
|
|
7
|
+
|
|
8
|
+
Перший реліз.
|
|
9
|
+
|
|
10
|
+
### Added
|
|
11
|
+
|
|
12
|
+
- Граматика SIPL у Lark за БНФ курсу, опис лексики й граматичних рішень (`docs/language.md`); 12 позитивних і 16 негативних тестів (CORE-01).
|
|
13
|
+
- Парсер у типізоване AST з `SourceSpan`; діагностики з кодами, позицією та підказками (CORE-02).
|
|
14
|
+
- Інтерпретатор: усі оператори SIPL, ліміт кроків, помилка R201 для невизначених змінних (CORE-03).
|
|
15
|
+
- Подієва модель виконання та trace, доступні з Python і як JSON (CORE-04).
|
|
16
|
+
- CLI `sipl parse | check | run | trace` з режимом `--json` і стабільними кодами завершення (CORE-05).
|
|
17
|
+
- `sipl tree`: дерево синтаксичного виводу у форматах text, JSON, DOT, SVG (VIS-01).
|
|
18
|
+
- VS Code extension: підсвітка синтаксису, коментарі, дужки, відступи, сніпети (IDE-01).
|
|
19
|
+
- VS Code extension: команди Run SIPL / Check SIPL, панель результатів, підкреслення помилок (IDE-02).
|
|
20
|
+
- CI на GitHub Actions: ruff, mypy, pytest на Python 3.10, 3.12, 3.14, збірка пакета й `.vsix` (REL-01).
|
|
21
|
+
- Автоматичний реліз за тегом: GitHub Release і публікація на PyPI (REL-02, REL-03).
|
|
22
|
+
- `.vsix` прикріплюється до GitHub Release; README extension зі скріншотами та сумісністю (REL-04).
|
|
23
|
+
|
|
24
|
+
[0.1.0]: https://github.com/RHrynchak/sipl-toolkit/releases/tag/v0.1.0
|
sipl_lang-0.1.0/PKG-INFO
ADDED
|
@@ -0,0 +1,198 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: sipl-lang
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: SIPL (SImple Programming Language) toolkit: grammar, parser, typed AST, interpreter, trace and CLI
|
|
5
|
+
Project-URL: Homepage, https://github.com/RHrynchak/sipl-toolkit
|
|
6
|
+
Project-URL: Issues, https://github.com/RHrynchak/sipl-toolkit/issues
|
|
7
|
+
Author: Роман Гринчак
|
|
8
|
+
Keywords: education,interpreter,parser,programming-languages,sipl
|
|
9
|
+
Classifier: Intended Audience :: Education
|
|
10
|
+
Classifier: Operating System :: OS Independent
|
|
11
|
+
Classifier: Programming Language :: Python :: 3
|
|
12
|
+
Classifier: Topic :: Software Development :: Interpreters
|
|
13
|
+
Requires-Python: >=3.10
|
|
14
|
+
Requires-Dist: lark<2,>=1.1.9
|
|
15
|
+
Provides-Extra: dev
|
|
16
|
+
Requires-Dist: build>=1.2; extra == 'dev'
|
|
17
|
+
Requires-Dist: mypy>=1.10; extra == 'dev'
|
|
18
|
+
Requires-Dist: pytest-cov>=5; extra == 'dev'
|
|
19
|
+
Requires-Dist: pytest>=8; extra == 'dev'
|
|
20
|
+
Requires-Dist: ruff>=0.5; extra == 'dev'
|
|
21
|
+
Description-Content-Type: text/markdown
|
|
22
|
+
|
|
23
|
+
# SIPL Toolkit
|
|
24
|
+
|
|
25
|
+
[](https://github.com/RHrynchak/sipl-toolkit/actions/workflows/ci.yml)
|
|
26
|
+
[](https://pypi.org/project/sipl-lang/)
|
|
27
|
+
|
|
28
|
+
Набір інструментів для навчальної мови **SIPL** (SImple Programming Language) з курсу
|
|
29
|
+
«Теорія програмування»: формальна граматика, парсер у типізоване AST, інтерпретатор
|
|
30
|
+
з подієвим trace, CLI, візуалізація дерева виводу та розширення для VS Code.
|
|
31
|
+
|
|
32
|
+
Курсовий проєкт, автор — Роман Гринчак.
|
|
33
|
+
|
|
34
|
+
## Обрані завдання
|
|
35
|
+
|
|
36
|
+
| ID | Завдання | Бали | Де |
|
|
37
|
+
|---|---|---|---|
|
|
38
|
+
| CORE-01 | Формальна граматика SIPL (Lark), опис лексики, 12 позитивних і 16 негативних тестів | 0.5 | [sipl.lark](src/sipl/grammar/sipl.lark), [docs/language.md](docs/language.md), [tests/grammar](tests/grammar) |
|
|
39
|
+
| CORE-02 | Парсер → типізоване AST із `SourceSpan`, діагностики синтаксичних помилок | 1.5 | [parser.py](src/sipl/parser.py), [ast.py](src/sipl/ast.py), [docs/diagnostics.md](docs/diagnostics.md) |
|
|
40
|
+
| CORE-03 | Інтерпретатор, ліміт кроків, покриття тестами ≥ 80% | 2.0 | [interpreter/machine.py](src/sipl/interpreter/machine.py) |
|
|
41
|
+
| CORE-04 | Подієва модель виконання та trace (Python API + JSON) | 1.0 | [interpreter/events.py](src/sipl/interpreter/events.py), `sipl trace` |
|
|
42
|
+
| CORE-05 | CLI `parse`, `check`, `run`, `trace`, режим `--json`, стабільні коди завершення | 1.0 | [cli.py](src/sipl/cli.py), [docs/cli.md](docs/cli.md) |
|
|
43
|
+
| VIS-01 | Дерево синтаксичного виводу: text, JSON, DOT, SVG | 1.5 | [visualization/](src/sipl/visualization/), `sipl tree` |
|
|
44
|
+
| IDE-01 | VS Code: підсвітка, коментарі, дужки, відступи, сніпети, `.vsix` | 1.0 | [vscode-sipl/](vscode-sipl/) |
|
|
45
|
+
| IDE-02 | VS Code: команди Run/Check, панель результатів, diagnostics | 1.0 | [vscode-sipl/extension.js](vscode-sipl/extension.js) |
|
|
46
|
+
| REL-01 | CI: ruff, mypy, pytest, збірка пакета й `.vsix` на кожен push/PR | 0.5 | [ci.yml](.github/workflows/ci.yml) |
|
|
47
|
+
| REL-02 | GitHub Releases + SemVer + CHANGELOG | 0.5 | [release.yml](.github/workflows/release.yml), [CHANGELOG.md](CHANGELOG.md) |
|
|
48
|
+
| REL-03 | Публікація пакета в PyPI (`sipl-lang`) | 0.5 | [release.yml](.github/workflows/release.yml) |
|
|
49
|
+
| REL-04 | Публікація `.vsix` у GitHub Release, README зі скріншотами та сумісністю | 0.5 | [vscode-sipl/README.md](vscode-sipl/README.md) |
|
|
50
|
+
| | **Разом заявлено** (оцінка обмежується 10.0) | **11.5** | |
|
|
51
|
+
|
|
52
|
+
## Встановлення
|
|
53
|
+
|
|
54
|
+
Потрібен Python ≥ 3.10.
|
|
55
|
+
|
|
56
|
+
```bash
|
|
57
|
+
pip install sipl-lang
|
|
58
|
+
sipl --version
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
Для розробки (з тестами й лінтерами):
|
|
62
|
+
|
|
63
|
+
```bash
|
|
64
|
+
git clone https://github.com/RHrynchak/sipl-toolkit.git
|
|
65
|
+
cd sipl-toolkit
|
|
66
|
+
python -m venv .venv
|
|
67
|
+
# Windows: .venv\Scripts\activate Linux/macOS: source .venv/bin/activate
|
|
68
|
+
pip install -e ".[dev]"
|
|
69
|
+
pytest
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
## Використання
|
|
73
|
+
|
|
74
|
+
```bash
|
|
75
|
+
sipl run examples/power.sipl -s X=2 -s Y=10 # виконати, надрукувати кінцевий стан
|
|
76
|
+
sipl check examples/gcd.sipl # перевірити синтаксис, показати вхідні змінні
|
|
77
|
+
sipl trace examples/gcd.sipl -s A=4 -s B=6 # усі події виконання
|
|
78
|
+
sipl parse examples/sign.sipl --json # AST у JSON
|
|
79
|
+
sipl tree examples/power.sipl --format svg -o power.svg # дерево виводу як картинка
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
```
|
|
83
|
+
$ sipl run examples/power.sipl -s X=2 -s Y=10
|
|
84
|
+
X = 2
|
|
85
|
+
Y = 0
|
|
86
|
+
R = 1024
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
Помилки показують місце й підказку:
|
|
90
|
+
|
|
91
|
+
```
|
|
92
|
+
$ sipl check bad.sipl
|
|
93
|
+
bad.sipl:3:1: error[E102]: unexpected 'end', expected statement
|
|
94
|
+
3 | end
|
|
95
|
+
| ^^^
|
|
96
|
+
hint: ';' separates statements in SIPL; remove the ';' before 'end'
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
Опції, коди завершення, JSON-формат — [docs/cli.md](docs/cli.md); коди помилок —
|
|
100
|
+
[docs/diagnostics.md](docs/diagnostics.md); мова й граматичні рішення — [docs/language.md](docs/language.md).
|
|
101
|
+
|
|
102
|
+
### З Python
|
|
103
|
+
|
|
104
|
+
```python
|
|
105
|
+
from sipl import parse, run, trace
|
|
106
|
+
|
|
107
|
+
program = parse(open("examples/power.sipl", encoding="utf-8").read())
|
|
108
|
+
result = run(program, {"X": 2, "Y": 10})
|
|
109
|
+
print(result.status, result.state) # ok {'X': 2, 'Y': 0, 'R': 1024}
|
|
110
|
+
|
|
111
|
+
events, result = trace(program, {"X": 2, "Y": 1})
|
|
112
|
+
print(events.to_json()) # події виконання в JSON
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
### Дерево синтаксичного виводу
|
|
116
|
+
|
|
117
|
+
`sipl tree examples/power.sipl --format svg` — вузли підписані правилами БНФ курсу
|
|
118
|
+
(`S (S4)` = `S ::= while b do S`); при наведенні на вузол у SVG видно його фрагмент коду.
|
|
119
|
+
|
|
120
|
+

|
|
121
|
+
|
|
122
|
+
## VS Code
|
|
123
|
+
|
|
124
|
+
Розширення [vscode-sipl](vscode-sipl/): підсвітка синтаксису, сніпети, команди **Run SIPL**
|
|
125
|
+
(▶) і **Check SIPL**, підкреслення помилок з точним місцем. Розширення — лише клієнт CLI
|
|
126
|
+
`sipl`: власного парсера чи інтерпретатора в ньому немає.
|
|
127
|
+
|
|
128
|
+

|
|
129
|
+
|
|
130
|
+

|
|
131
|
+
|
|
132
|
+
Встановлення: завантажте `sipl-X.Y.Z.vsix` зі сторінки
|
|
133
|
+
[Releases](https://github.com/RHrynchak/sipl-toolkit/releases) → у VS Code *Extensions* → `…` →
|
|
134
|
+
*Install from VSIX…*. Потрібен встановлений `sipl-lang`. Деталі й сумісність —
|
|
135
|
+
[vscode-sipl/README.md](vscode-sipl/README.md).
|
|
136
|
+
|
|
137
|
+
## Архітектура
|
|
138
|
+
|
|
139
|
+
```
|
|
140
|
+
текст ──parser──▶ дерево виводу (Lark) ──▶ AST (sipl.ast) ──interpreter──▶ події ──▶ кінцевий стан
|
|
141
|
+
│ │ │
|
|
142
|
+
sipl tree sipl parse sipl run / trace
|
|
143
|
+
│
|
|
144
|
+
CLI --json ──▶ VS Code extension
|
|
145
|
+
```
|
|
146
|
+
|
|
147
|
+
```
|
|
148
|
+
src/sipl/
|
|
149
|
+
├── grammar/sipl.lark # формальна граматика (входить до пакета)
|
|
150
|
+
├── parser.py # текст -> дерево виводу -> AST, синтаксичні діагностики
|
|
151
|
+
├── ast.py # типізовані вузли AST з SourceSpan
|
|
152
|
+
├── source.py # SourceSpan — позиція у тексті
|
|
153
|
+
├── diagnostics.py # коди помилок, формат повідомлень
|
|
154
|
+
├── interpreter/ # інтерпретатор, події виконання, trace
|
|
155
|
+
├── analysis.py # вхідні змінні програми
|
|
156
|
+
├── visualization/ # дерево виводу: text / JSON / DOT / SVG
|
|
157
|
+
├── productions.py # відповідність вузлів дерева правилам БНФ курсу
|
|
158
|
+
├── printer.py # AST -> текст (підписи в trace)
|
|
159
|
+
└── cli.py # командний рядок
|
|
160
|
+
examples/ # приклади SIPL-програм
|
|
161
|
+
tests/ # pytest; tests/grammar — позитивні/негативні програми
|
|
162
|
+
docs/ # мова, CLI, діагностики
|
|
163
|
+
vscode-sipl/ # VS Code extension (клієнт CLI)
|
|
164
|
+
```
|
|
165
|
+
|
|
166
|
+
Граматика лежить у `src/sipl/grammar/`, а не в корені, щоб потрапляти в пакет на PyPI.
|
|
167
|
+
|
|
168
|
+
## Тести та якість
|
|
169
|
+
|
|
170
|
+
```bash
|
|
171
|
+
pytest # 183 тести, покриття ≥ 80% (зараз ~97%)
|
|
172
|
+
ruff check src tests # стиль
|
|
173
|
+
mypy # типи (strict)
|
|
174
|
+
cd vscode-sipl && npm ci && npm test # тести підсвітки й логіки extension
|
|
175
|
+
```
|
|
176
|
+
|
|
177
|
+
Те саме запускає CI на Python 3.10, 3.12, 3.14 для кожного push і Pull Request.
|
|
178
|
+
|
|
179
|
+
## Релізи
|
|
180
|
+
|
|
181
|
+
Версія — у `src/sipl/__init__.py` і `vscode-sipl/package.json` (SemVer), зміни — у
|
|
182
|
+
[CHANGELOG.md](CHANGELOG.md). Реліз:
|
|
183
|
+
|
|
184
|
+
```bash
|
|
185
|
+
git tag v0.1.0
|
|
186
|
+
git push origin v0.1.0
|
|
187
|
+
```
|
|
188
|
+
|
|
189
|
+
Workflow [release.yml](.github/workflows/release.yml) перевіряє, що тег збігається з версіями,
|
|
190
|
+
проганяє тести, публікує пакет у PyPI й створює GitHub Release з `.whl`, `.tar.gz` і `.vsix`.
|
|
191
|
+
|
|
192
|
+
## Обмеження
|
|
193
|
+
|
|
194
|
+
* Парсер повідомляє лише першу синтаксичну помилку.
|
|
195
|
+
* Інтерпретатор не визначає, чи завершиться програма: від зациклення захищає лише ліміт
|
|
196
|
+
кроків (`--max-steps`).
|
|
197
|
+
* `;` зв'язує слабше за `if`/`while`, тож кілька операторів у тілі треба брати в
|
|
198
|
+
`begin … end` — див. [docs/language.md](docs/language.md).
|
|
@@ -0,0 +1,176 @@
|
|
|
1
|
+
# SIPL Toolkit
|
|
2
|
+
|
|
3
|
+
[](https://github.com/RHrynchak/sipl-toolkit/actions/workflows/ci.yml)
|
|
4
|
+
[](https://pypi.org/project/sipl-lang/)
|
|
5
|
+
|
|
6
|
+
Набір інструментів для навчальної мови **SIPL** (SImple Programming Language) з курсу
|
|
7
|
+
«Теорія програмування»: формальна граматика, парсер у типізоване AST, інтерпретатор
|
|
8
|
+
з подієвим trace, CLI, візуалізація дерева виводу та розширення для VS Code.
|
|
9
|
+
|
|
10
|
+
Курсовий проєкт, автор — Роман Гринчак.
|
|
11
|
+
|
|
12
|
+
## Обрані завдання
|
|
13
|
+
|
|
14
|
+
| ID | Завдання | Бали | Де |
|
|
15
|
+
|---|---|---|---|
|
|
16
|
+
| CORE-01 | Формальна граматика SIPL (Lark), опис лексики, 12 позитивних і 16 негативних тестів | 0.5 | [sipl.lark](src/sipl/grammar/sipl.lark), [docs/language.md](docs/language.md), [tests/grammar](tests/grammar) |
|
|
17
|
+
| CORE-02 | Парсер → типізоване AST із `SourceSpan`, діагностики синтаксичних помилок | 1.5 | [parser.py](src/sipl/parser.py), [ast.py](src/sipl/ast.py), [docs/diagnostics.md](docs/diagnostics.md) |
|
|
18
|
+
| CORE-03 | Інтерпретатор, ліміт кроків, покриття тестами ≥ 80% | 2.0 | [interpreter/machine.py](src/sipl/interpreter/machine.py) |
|
|
19
|
+
| CORE-04 | Подієва модель виконання та trace (Python API + JSON) | 1.0 | [interpreter/events.py](src/sipl/interpreter/events.py), `sipl trace` |
|
|
20
|
+
| CORE-05 | CLI `parse`, `check`, `run`, `trace`, режим `--json`, стабільні коди завершення | 1.0 | [cli.py](src/sipl/cli.py), [docs/cli.md](docs/cli.md) |
|
|
21
|
+
| VIS-01 | Дерево синтаксичного виводу: text, JSON, DOT, SVG | 1.5 | [visualization/](src/sipl/visualization/), `sipl tree` |
|
|
22
|
+
| IDE-01 | VS Code: підсвітка, коментарі, дужки, відступи, сніпети, `.vsix` | 1.0 | [vscode-sipl/](vscode-sipl/) |
|
|
23
|
+
| IDE-02 | VS Code: команди Run/Check, панель результатів, diagnostics | 1.0 | [vscode-sipl/extension.js](vscode-sipl/extension.js) |
|
|
24
|
+
| REL-01 | CI: ruff, mypy, pytest, збірка пакета й `.vsix` на кожен push/PR | 0.5 | [ci.yml](.github/workflows/ci.yml) |
|
|
25
|
+
| REL-02 | GitHub Releases + SemVer + CHANGELOG | 0.5 | [release.yml](.github/workflows/release.yml), [CHANGELOG.md](CHANGELOG.md) |
|
|
26
|
+
| REL-03 | Публікація пакета в PyPI (`sipl-lang`) | 0.5 | [release.yml](.github/workflows/release.yml) |
|
|
27
|
+
| REL-04 | Публікація `.vsix` у GitHub Release, README зі скріншотами та сумісністю | 0.5 | [vscode-sipl/README.md](vscode-sipl/README.md) |
|
|
28
|
+
| | **Разом заявлено** (оцінка обмежується 10.0) | **11.5** | |
|
|
29
|
+
|
|
30
|
+
## Встановлення
|
|
31
|
+
|
|
32
|
+
Потрібен Python ≥ 3.10.
|
|
33
|
+
|
|
34
|
+
```bash
|
|
35
|
+
pip install sipl-lang
|
|
36
|
+
sipl --version
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
Для розробки (з тестами й лінтерами):
|
|
40
|
+
|
|
41
|
+
```bash
|
|
42
|
+
git clone https://github.com/RHrynchak/sipl-toolkit.git
|
|
43
|
+
cd sipl-toolkit
|
|
44
|
+
python -m venv .venv
|
|
45
|
+
# Windows: .venv\Scripts\activate Linux/macOS: source .venv/bin/activate
|
|
46
|
+
pip install -e ".[dev]"
|
|
47
|
+
pytest
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
## Використання
|
|
51
|
+
|
|
52
|
+
```bash
|
|
53
|
+
sipl run examples/power.sipl -s X=2 -s Y=10 # виконати, надрукувати кінцевий стан
|
|
54
|
+
sipl check examples/gcd.sipl # перевірити синтаксис, показати вхідні змінні
|
|
55
|
+
sipl trace examples/gcd.sipl -s A=4 -s B=6 # усі події виконання
|
|
56
|
+
sipl parse examples/sign.sipl --json # AST у JSON
|
|
57
|
+
sipl tree examples/power.sipl --format svg -o power.svg # дерево виводу як картинка
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
```
|
|
61
|
+
$ sipl run examples/power.sipl -s X=2 -s Y=10
|
|
62
|
+
X = 2
|
|
63
|
+
Y = 0
|
|
64
|
+
R = 1024
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
Помилки показують місце й підказку:
|
|
68
|
+
|
|
69
|
+
```
|
|
70
|
+
$ sipl check bad.sipl
|
|
71
|
+
bad.sipl:3:1: error[E102]: unexpected 'end', expected statement
|
|
72
|
+
3 | end
|
|
73
|
+
| ^^^
|
|
74
|
+
hint: ';' separates statements in SIPL; remove the ';' before 'end'
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
Опції, коди завершення, JSON-формат — [docs/cli.md](docs/cli.md); коди помилок —
|
|
78
|
+
[docs/diagnostics.md](docs/diagnostics.md); мова й граматичні рішення — [docs/language.md](docs/language.md).
|
|
79
|
+
|
|
80
|
+
### З Python
|
|
81
|
+
|
|
82
|
+
```python
|
|
83
|
+
from sipl import parse, run, trace
|
|
84
|
+
|
|
85
|
+
program = parse(open("examples/power.sipl", encoding="utf-8").read())
|
|
86
|
+
result = run(program, {"X": 2, "Y": 10})
|
|
87
|
+
print(result.status, result.state) # ok {'X': 2, 'Y': 0, 'R': 1024}
|
|
88
|
+
|
|
89
|
+
events, result = trace(program, {"X": 2, "Y": 1})
|
|
90
|
+
print(events.to_json()) # події виконання в JSON
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
### Дерево синтаксичного виводу
|
|
94
|
+
|
|
95
|
+
`sipl tree examples/power.sipl --format svg` — вузли підписані правилами БНФ курсу
|
|
96
|
+
(`S (S4)` = `S ::= while b do S`); при наведенні на вузол у SVG видно його фрагмент коду.
|
|
97
|
+
|
|
98
|
+

|
|
99
|
+
|
|
100
|
+
## VS Code
|
|
101
|
+
|
|
102
|
+
Розширення [vscode-sipl](vscode-sipl/): підсвітка синтаксису, сніпети, команди **Run SIPL**
|
|
103
|
+
(▶) і **Check SIPL**, підкреслення помилок з точним місцем. Розширення — лише клієнт CLI
|
|
104
|
+
`sipl`: власного парсера чи інтерпретатора в ньому немає.
|
|
105
|
+
|
|
106
|
+

|
|
107
|
+
|
|
108
|
+

|
|
109
|
+
|
|
110
|
+
Встановлення: завантажте `sipl-X.Y.Z.vsix` зі сторінки
|
|
111
|
+
[Releases](https://github.com/RHrynchak/sipl-toolkit/releases) → у VS Code *Extensions* → `…` →
|
|
112
|
+
*Install from VSIX…*. Потрібен встановлений `sipl-lang`. Деталі й сумісність —
|
|
113
|
+
[vscode-sipl/README.md](vscode-sipl/README.md).
|
|
114
|
+
|
|
115
|
+
## Архітектура
|
|
116
|
+
|
|
117
|
+
```
|
|
118
|
+
текст ──parser──▶ дерево виводу (Lark) ──▶ AST (sipl.ast) ──interpreter──▶ події ──▶ кінцевий стан
|
|
119
|
+
│ │ │
|
|
120
|
+
sipl tree sipl parse sipl run / trace
|
|
121
|
+
│
|
|
122
|
+
CLI --json ──▶ VS Code extension
|
|
123
|
+
```
|
|
124
|
+
|
|
125
|
+
```
|
|
126
|
+
src/sipl/
|
|
127
|
+
├── grammar/sipl.lark # формальна граматика (входить до пакета)
|
|
128
|
+
├── parser.py # текст -> дерево виводу -> AST, синтаксичні діагностики
|
|
129
|
+
├── ast.py # типізовані вузли AST з SourceSpan
|
|
130
|
+
├── source.py # SourceSpan — позиція у тексті
|
|
131
|
+
├── diagnostics.py # коди помилок, формат повідомлень
|
|
132
|
+
├── interpreter/ # інтерпретатор, події виконання, trace
|
|
133
|
+
├── analysis.py # вхідні змінні програми
|
|
134
|
+
├── visualization/ # дерево виводу: text / JSON / DOT / SVG
|
|
135
|
+
├── productions.py # відповідність вузлів дерева правилам БНФ курсу
|
|
136
|
+
├── printer.py # AST -> текст (підписи в trace)
|
|
137
|
+
└── cli.py # командний рядок
|
|
138
|
+
examples/ # приклади SIPL-програм
|
|
139
|
+
tests/ # pytest; tests/grammar — позитивні/негативні програми
|
|
140
|
+
docs/ # мова, CLI, діагностики
|
|
141
|
+
vscode-sipl/ # VS Code extension (клієнт CLI)
|
|
142
|
+
```
|
|
143
|
+
|
|
144
|
+
Граматика лежить у `src/sipl/grammar/`, а не в корені, щоб потрапляти в пакет на PyPI.
|
|
145
|
+
|
|
146
|
+
## Тести та якість
|
|
147
|
+
|
|
148
|
+
```bash
|
|
149
|
+
pytest # 183 тести, покриття ≥ 80% (зараз ~97%)
|
|
150
|
+
ruff check src tests # стиль
|
|
151
|
+
mypy # типи (strict)
|
|
152
|
+
cd vscode-sipl && npm ci && npm test # тести підсвітки й логіки extension
|
|
153
|
+
```
|
|
154
|
+
|
|
155
|
+
Те саме запускає CI на Python 3.10, 3.12, 3.14 для кожного push і Pull Request.
|
|
156
|
+
|
|
157
|
+
## Релізи
|
|
158
|
+
|
|
159
|
+
Версія — у `src/sipl/__init__.py` і `vscode-sipl/package.json` (SemVer), зміни — у
|
|
160
|
+
[CHANGELOG.md](CHANGELOG.md). Реліз:
|
|
161
|
+
|
|
162
|
+
```bash
|
|
163
|
+
git tag v0.1.0
|
|
164
|
+
git push origin v0.1.0
|
|
165
|
+
```
|
|
166
|
+
|
|
167
|
+
Workflow [release.yml](.github/workflows/release.yml) перевіряє, що тег збігається з версіями,
|
|
168
|
+
проганяє тести, публікує пакет у PyPI й створює GitHub Release з `.whl`, `.tar.gz` і `.vsix`.
|
|
169
|
+
|
|
170
|
+
## Обмеження
|
|
171
|
+
|
|
172
|
+
* Парсер повідомляє лише першу синтаксичну помилку.
|
|
173
|
+
* Інтерпретатор не визначає, чи завершиться програма: від зациклення захищає лише ліміт
|
|
174
|
+
кроків (`--max-steps`).
|
|
175
|
+
* `;` зв'язує слабше за `if`/`while`, тож кілька операторів у тілі треба брати в
|
|
176
|
+
`begin … end` — див. [docs/language.md](docs/language.md).
|
|
@@ -0,0 +1,118 @@
|
|
|
1
|
+
# CLI `sipl`
|
|
2
|
+
|
|
3
|
+
```
|
|
4
|
+
sipl parse FILE [--json]
|
|
5
|
+
sipl check FILE [--json]
|
|
6
|
+
sipl run FILE [-s NAME=VALUE ...] [--max-steps N] [--json]
|
|
7
|
+
sipl trace FILE [-s NAME=VALUE ...] [--max-steps N] [--json]
|
|
8
|
+
sipl tree FILE [--format text|dot|svg] [-o OUT] [--json]
|
|
9
|
+
sipl --version
|
|
10
|
+
```
|
|
11
|
+
|
|
12
|
+
`FILE` — шлях до `.sipl`-файлу або `-` (читати зі stdin). Те саме доступне як `python -m sipl ...`.
|
|
13
|
+
|
|
14
|
+
| Команда | Що робить |
|
|
15
|
+
|---|---|
|
|
16
|
+
| `parse` | друкує AST програми (вузол + позиція `рядок:колонка`) |
|
|
17
|
+
| `check` | перевіряє синтаксис і показує **вхідні змінні** — ті, що треба задати через `-s` |
|
|
18
|
+
| `run` | виконує програму й друкує кінцевий стан |
|
|
19
|
+
| `trace` | виконує програму й друкує всі події виконання |
|
|
20
|
+
| `tree` | друкує дерево синтаксичного виводу (див. нижче) |
|
|
21
|
+
|
|
22
|
+
Опції `run` / `trace`:
|
|
23
|
+
|
|
24
|
+
* `-s NAME=VALUE`, `--set` — початкове значення змінної (можна повторювати): `-s X=2 -s Y=10`;
|
|
25
|
+
* `--max-steps N` — ліміт кроків (за замовчуванням 100000), захист від нескінченних циклів.
|
|
26
|
+
|
|
27
|
+
## Приклади
|
|
28
|
+
|
|
29
|
+
```
|
|
30
|
+
$ sipl run examples/power.sipl -s X=2 -s Y=10
|
|
31
|
+
X = 2
|
|
32
|
+
Y = 0
|
|
33
|
+
R = 1024
|
|
34
|
+
|
|
35
|
+
$ sipl check examples/gcd.sipl
|
|
36
|
+
examples/gcd.sipl: OK
|
|
37
|
+
input variables: A, B
|
|
38
|
+
|
|
39
|
+
$ sipl trace examples/gcd.sipl -s A=4 -s B=6
|
|
40
|
+
0 step 0 start A=4, B=6
|
|
41
|
+
1 step 0 before 4:3 while ¬(A = B) do …
|
|
42
|
+
2 step 1 condition 4:3 ¬(A = B) → true
|
|
43
|
+
...
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
## Дерево виводу (`tree`)
|
|
47
|
+
|
|
48
|
+
Внутрішні вузли — правила БНФ курсу (`S (S1)` = `S ::= x := a`), листки — лексеми програми.
|
|
49
|
+
|
|
50
|
+
* `--format text` (за замовчуванням) — дерево в консолі;
|
|
51
|
+
* `--format dot` — для Graphviz (`dot -Tpng tree.dot -o tree.png`);
|
|
52
|
+
* `--format svg` — готова картинка, Graphviz не потрібен; при наведенні на вузол видно
|
|
53
|
+
правило, позицію та фрагмент коду;
|
|
54
|
+
* `--json` — дерево в JSON: `{"label", "rule", "rhs", "text", "span", "children"}`;
|
|
55
|
+
* `-o OUT` — записати у файл.
|
|
56
|
+
|
|
57
|
+
```
|
|
58
|
+
$ sipl tree examples/power.sipl
|
|
59
|
+
P [P1: P ::= begin S end] 3:1-10:4
|
|
60
|
+
├─ 'begin'
|
|
61
|
+
├─ S [S2: S ::= S1 ; S2] 4:3-9:6
|
|
62
|
+
│ ├─ S [S1: S ::= x := a] 4:3-4:9
|
|
63
|
+
│ │ ├─ x [NV: x ::= M | N | ...] 4:3-4:4
|
|
64
|
+
│ │ │ └─ 'R'
|
|
65
|
+
...
|
|
66
|
+
$ sipl tree examples/power.sipl --format svg -o power.svg
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
## Коди завершення
|
|
70
|
+
|
|
71
|
+
| Код | Значення |
|
|
72
|
+
|---|---|
|
|
73
|
+
| `0` | успіх |
|
|
74
|
+
| `1` | синтаксична помилка (`E1xx`) |
|
|
75
|
+
| `2` | помилка виконання (`R201`) |
|
|
76
|
+
| `3` | перевищено ліміт кроків (`R202`) |
|
|
77
|
+
| `4` | некоректні вхідні дані: файл не знайдено, поганий `-s`, неправильні аргументи (`I301`) |
|
|
78
|
+
|
|
79
|
+
## JSON-режим (`--json`)
|
|
80
|
+
|
|
81
|
+
Усі команди друкують у stdout один JSON-об'єкт зі спільними полями:
|
|
82
|
+
|
|
83
|
+
```json
|
|
84
|
+
{
|
|
85
|
+
"version": 1,
|
|
86
|
+
"command": "run",
|
|
87
|
+
"file": "examples/power.sipl",
|
|
88
|
+
"ok": true,
|
|
89
|
+
"diagnostics": []
|
|
90
|
+
}
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
* `version` — версія формату; змінюється лише при несумісних змінах;
|
|
94
|
+
* `ok` — `false`, якщо є помилка (тоді вона в `diagnostics`, формат — у [diagnostics.md](diagnostics.md));
|
|
95
|
+
* для помилок синтаксису та вхідних даних інших полів немає.
|
|
96
|
+
|
|
97
|
+
Додаткові поля за командою:
|
|
98
|
+
|
|
99
|
+
| Команда | Поля |
|
|
100
|
+
|---|---|
|
|
101
|
+
| `parse` | `ast` — дерево: `{"kind": "Assign", "target": {...}, "value": {...}, "span": {...}}` |
|
|
102
|
+
| `check` | `variables` — `{"inputs": [...], "assigned": [...], "all": [...]}` |
|
|
103
|
+
| `run` | `initial_state`, `result` — `{"status": "ok" \| "runtime_error" \| "step_limit", "state": {...}, "steps": N, "diagnostic": ... }` |
|
|
104
|
+
| `trace` | `initial_state`, `events` (список подій), `result` (як у `run`) |
|
|
105
|
+
| `tree` | `tree` — дерево виводу |
|
|
106
|
+
|
|
107
|
+
Подія trace:
|
|
108
|
+
|
|
109
|
+
```json
|
|
110
|
+
{"index": 6, "event": "variable_changed", "step": 3,
|
|
111
|
+
"node": {"kind": "Assign", "span": {...}, "label": "B := B - A"},
|
|
112
|
+
"name": "B", "old": 6, "new": 2}
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
Види подій: `program_start`, `before_statement`, `after_statement`, `variable_changed`
|
|
116
|
+
(`name`, `old` — `null`, якщо змінна ще не існувала, `new`), `condition_evaluated`
|
|
117
|
+
(`condition`, `value`), `program_end` (`status`, `state`, `diagnostic`).
|
|
118
|
+
Події є для `:=`, `skip`, `if`, `while`; `;` і `begin … end` окремих подій не мають.
|
|
@@ -0,0 +1,72 @@
|
|
|
1
|
+
# Діагностики SIPL
|
|
2
|
+
|
|
3
|
+
Кожна помилка в SIPL має **стабільний код**, **позицію** у вихідному тексті (`SourceSpan`)
|
|
4
|
+
і, де можливо, **підказку** (`hint`) — як виправити.
|
|
5
|
+
|
|
6
|
+
| Префікс | Джерело |
|
|
7
|
+
|---|---|
|
|
8
|
+
| `E1xx` | синтаксичні помилки (парсер) |
|
|
9
|
+
| `R2xx` | помилки виконання (інтерпретатор) |
|
|
10
|
+
| `I3xx` | некоректні вхідні дані (початковий стан, файли) |
|
|
11
|
+
|
|
12
|
+
## Коди
|
|
13
|
+
|
|
14
|
+
| Код | Назва | Коли виникає | Приклад |
|
|
15
|
+
|---|---|---|---|
|
|
16
|
+
| `E101` | unexpected character | символ, якого немає в лексиці SIPL | `X := 1 < 2`, `X / 2`, `X : 1` |
|
|
17
|
+
| `E102` | unexpected token | лексема на місці, де граматика її не допускає | `X = 1` замість `X := 1`, `;` перед `end` |
|
|
18
|
+
| `E103` | unexpected end of input | текст закінчився посеред програми | `begin X := 1` (немає `end`) |
|
|
19
|
+
| `R201` | undefined variable | читання змінної, яка ще не має значення | `begin X := Y end` без `Y` у початковому стані |
|
|
20
|
+
| `R202` | step limit exceeded | виконано більше кроків, ніж дозволяє ліміт | нескінченний цикл `while X = X do ...` |
|
|
21
|
+
| `I301` | invalid input | некоректний початковий стан або файл | `-s X=abc` |
|
|
22
|
+
|
|
23
|
+
Парсер зупиняється на **першій** синтаксичній помилці (LALR без відновлення).
|
|
24
|
+
|
|
25
|
+
## Підказки
|
|
26
|
+
|
|
27
|
+
Для типових помилок парсер додає `hint`:
|
|
28
|
+
|
|
29
|
+
| Ситуація | Підказка |
|
|
30
|
+
|---|---|
|
|
31
|
+
| `;` перед `end` | `;` розділяє оператори, після останнього його не ставлять |
|
|
32
|
+
| `=` замість `:=` | присвоєння пишеться `:=`, `=` — порівняння |
|
|
33
|
+
| `if` без `else`, кілька операторів у гілці | `if` завжди має `else`; кілька операторів — у `begin ... end` |
|
|
34
|
+
| пропущено `;` між операторами | `missing ';' between statements?` |
|
|
35
|
+
| ключове слово як змінна | `'while' is a reserved word ...` |
|
|
36
|
+
| `<`, `/`, `&&`, `and` | у SIPL є лише `=`, `>`, `+ - *`, `∨`/`or`, `¬`/`not` |
|
|
37
|
+
| `-Y` | унарного мінуса немає: `-1` — це літерал, для змінної `0 - Y` |
|
|
38
|
+
| текст після останнього `end` | програма — один блок `begin ... end` |
|
|
39
|
+
|
|
40
|
+
## Текстовий формат
|
|
41
|
+
|
|
42
|
+
```
|
|
43
|
+
prog.sipl:3:1: error[E102]: unexpected 'end', expected statement
|
|
44
|
+
3 | end
|
|
45
|
+
| ^^^
|
|
46
|
+
hint: ';' separates statements in SIPL; remove the ';' before 'end'
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
Формат першого рядка — `файл:рядок:колонка: рівень[код]: повідомлення` (рядки й колонки з 1),
|
|
50
|
+
тому редактори (зокрема VS Code) розпізнають його як посилання на місце помилки.
|
|
51
|
+
|
|
52
|
+
## JSON-формат
|
|
53
|
+
|
|
54
|
+
```json
|
|
55
|
+
{
|
|
56
|
+
"code": "E102",
|
|
57
|
+
"severity": "error",
|
|
58
|
+
"message": "unexpected 'end', expected statement",
|
|
59
|
+
"span": {
|
|
60
|
+
"start": {"line": 3, "column": 1},
|
|
61
|
+
"end": {"line": 3, "column": 4},
|
|
62
|
+
"start_offset": 16,
|
|
63
|
+
"end_offset": 19
|
|
64
|
+
},
|
|
65
|
+
"hint": "';' separates statements in SIPL; remove the ';' before 'end'"
|
|
66
|
+
}
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
* `severity` — `error` | `warning` | `info`;
|
|
70
|
+
* `span.end` — позиція одразу **після** останнього символу;
|
|
71
|
+
* `span` може бути `null`, якщо помилка не прив'язана до тексту (напр. `I301`);
|
|
72
|
+
* `hint` може бути `null`.
|
|
Binary file
|