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.
Files changed (71) hide show
  1. sipl_lang-0.1.0/.gitignore +27 -0
  2. sipl_lang-0.1.0/CHANGELOG.md +24 -0
  3. sipl_lang-0.1.0/PKG-INFO +198 -0
  4. sipl_lang-0.1.0/README.md +176 -0
  5. sipl_lang-0.1.0/docs/cli.md +118 -0
  6. sipl_lang-0.1.0/docs/diagnostics.md +72 -0
  7. sipl_lang-0.1.0/docs/images/power-tree.png +0 -0
  8. sipl_lang-0.1.0/docs/language.md +60 -0
  9. sipl_lang-0.1.0/examples/divmod.sipl +12 -0
  10. sipl_lang-0.1.0/examples/gcd.sipl +7 -0
  11. sipl_lang-0.1.0/examples/infinite_loop.sipl +7 -0
  12. sipl_lang-0.1.0/examples/power.sipl +10 -0
  13. sipl_lang-0.1.0/examples/sign.sipl +10 -0
  14. sipl_lang-0.1.0/pyproject.toml +65 -0
  15. sipl_lang-0.1.0/src/sipl/__init__.py +40 -0
  16. sipl_lang-0.1.0/src/sipl/__main__.py +7 -0
  17. sipl_lang-0.1.0/src/sipl/analysis.py +55 -0
  18. sipl_lang-0.1.0/src/sipl/ast.py +218 -0
  19. sipl_lang-0.1.0/src/sipl/cli.py +292 -0
  20. sipl_lang-0.1.0/src/sipl/diagnostics.py +102 -0
  21. sipl_lang-0.1.0/src/sipl/grammar/sipl.lark +112 -0
  22. sipl_lang-0.1.0/src/sipl/interpreter/__init__.py +44 -0
  23. sipl_lang-0.1.0/src/sipl/interpreter/events.py +154 -0
  24. sipl_lang-0.1.0/src/sipl/interpreter/machine.py +276 -0
  25. sipl_lang-0.1.0/src/sipl/interpreter/trace.py +49 -0
  26. sipl_lang-0.1.0/src/sipl/parser.py +316 -0
  27. sipl_lang-0.1.0/src/sipl/printer.py +62 -0
  28. sipl_lang-0.1.0/src/sipl/productions.py +61 -0
  29. sipl_lang-0.1.0/src/sipl/py.typed +0 -0
  30. sipl_lang-0.1.0/src/sipl/source.py +82 -0
  31. sipl_lang-0.1.0/src/sipl/visualization/__init__.py +12 -0
  32. sipl_lang-0.1.0/src/sipl/visualization/parse_tree.py +220 -0
  33. sipl_lang-0.1.0/tests/conftest.py +18 -0
  34. sipl_lang-0.1.0/tests/grammar/invalid/01_empty.sipl +0 -0
  35. sipl_lang-0.1.0/tests/grammar/invalid/02_missing_begin.sipl +1 -0
  36. sipl_lang-0.1.0/tests/grammar/invalid/03_trailing_semicolon.sipl +3 -0
  37. sipl_lang-0.1.0/tests/grammar/invalid/04_eq_instead_of_assign.sipl +1 -0
  38. sipl_lang-0.1.0/tests/grammar/invalid/05_if_without_else.sipl +3 -0
  39. sipl_lang-0.1.0/tests/grammar/invalid/06_less_than.sipl +1 -0
  40. sipl_lang-0.1.0/tests/grammar/invalid/07_division.sipl +1 -0
  41. sipl_lang-0.1.0/tests/grammar/invalid/08_missing_semicolon.sipl +4 -0
  42. sipl_lang-0.1.0/tests/grammar/invalid/09_keyword_as_variable.sipl +1 -0
  43. sipl_lang-0.1.0/tests/grammar/invalid/10_unclosed_paren.sipl +1 -0
  44. sipl_lang-0.1.0/tests/grammar/invalid/11_missing_end.sipl +3 -0
  45. sipl_lang-0.1.0/tests/grammar/invalid/12_and_operator.sipl +1 -0
  46. sipl_lang-0.1.0/tests/grammar/invalid/13_unary_minus_on_variable.sipl +1 -0
  47. sipl_lang-0.1.0/tests/grammar/invalid/14_text_after_program.sipl +2 -0
  48. sipl_lang-0.1.0/tests/grammar/invalid/15_sequence_in_branch.sipl +1 -0
  49. sipl_lang-0.1.0/tests/grammar/invalid/16_condition_as_value.sipl +1 -0
  50. sipl_lang-0.1.0/tests/grammar/invalid/expected.json +18 -0
  51. sipl_lang-0.1.0/tests/grammar/valid/01_minimal.sipl +1 -0
  52. sipl_lang-0.1.0/tests/grammar/valid/02_assign.sipl +1 -0
  53. sipl_lang-0.1.0/tests/grammar/valid/03_negative_numbers.sipl +6 -0
  54. sipl_lang-0.1.0/tests/grammar/valid/04_precedence.sipl +2 -0
  55. sipl_lang-0.1.0/tests/grammar/valid/05_nested_blocks.sipl +1 -0
  56. sipl_lang-0.1.0/tests/grammar/valid/06_if_else_chain.sipl +5 -0
  57. sipl_lang-0.1.0/tests/grammar/valid/07_while_block.sipl +8 -0
  58. sipl_lang-0.1.0/tests/grammar/valid/08_bool_unicode.sipl +2 -0
  59. sipl_lang-0.1.0/tests/grammar/valid/09_bool_ascii.sipl +2 -0
  60. sipl_lang-0.1.0/tests/grammar/valid/10_comments_whitespace.sipl +6 -0
  61. sipl_lang-0.1.0/tests/grammar/valid/11_identifiers.sipl +2 -0
  62. sipl_lang-0.1.0/tests/grammar/valid/12_while_single_stmt.sipl +2 -0
  63. sipl_lang-0.1.0/tests/test_analysis.py +42 -0
  64. sipl_lang-0.1.0/tests/test_cli.py +186 -0
  65. sipl_lang-0.1.0/tests/test_events.py +162 -0
  66. sipl_lang-0.1.0/tests/test_grammar.py +75 -0
  67. sipl_lang-0.1.0/tests/test_interpreter.py +153 -0
  68. sipl_lang-0.1.0/tests/test_parser.py +213 -0
  69. sipl_lang-0.1.0/tests/test_printer.py +67 -0
  70. sipl_lang-0.1.0/tests/test_visualization.py +93 -0
  71. 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
@@ -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
+ [![CI](https://github.com/RHrynchak/sipl-toolkit/actions/workflows/ci.yml/badge.svg)](https://github.com/RHrynchak/sipl-toolkit/actions/workflows/ci.yml)
26
+ [![PyPI](https://img.shields.io/pypi/v/sipl-lang)](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
+ ![Дерево виводу power.sipl](https://raw.githubusercontent.com/RHrynchak/sipl-toolkit/main/docs/images/power-tree.png)
121
+
122
+ ## VS Code
123
+
124
+ Розширення [vscode-sipl](vscode-sipl/): підсвітка синтаксису, сніпети, команди **Run SIPL**
125
+ (▶) і **Check SIPL**, підкреслення помилок з точним місцем. Розширення — лише клієнт CLI
126
+ `sipl`: власного парсера чи інтерпретатора в ньому немає.
127
+
128
+ ![Помилка в редакторі](https://raw.githubusercontent.com/RHrynchak/sipl-toolkit/main/vscode-sipl/images/diagnostics.png)
129
+
130
+ ![Run SIPL](https://raw.githubusercontent.com/RHrynchak/sipl-toolkit/main/vscode-sipl/images/run.png)
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
+ [![CI](https://github.com/RHrynchak/sipl-toolkit/actions/workflows/ci.yml/badge.svg)](https://github.com/RHrynchak/sipl-toolkit/actions/workflows/ci.yml)
4
+ [![PyPI](https://img.shields.io/pypi/v/sipl-lang)](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
+ ![Дерево виводу power.sipl](https://raw.githubusercontent.com/RHrynchak/sipl-toolkit/main/docs/images/power-tree.png)
99
+
100
+ ## VS Code
101
+
102
+ Розширення [vscode-sipl](vscode-sipl/): підсвітка синтаксису, сніпети, команди **Run SIPL**
103
+ (▶) і **Check SIPL**, підкреслення помилок з точним місцем. Розширення — лише клієнт CLI
104
+ `sipl`: власного парсера чи інтерпретатора в ньому немає.
105
+
106
+ ![Помилка в редакторі](https://raw.githubusercontent.com/RHrynchak/sipl-toolkit/main/vscode-sipl/images/diagnostics.png)
107
+
108
+ ![Run SIPL](https://raw.githubusercontent.com/RHrynchak/sipl-toolkit/main/vscode-sipl/images/run.png)
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`.