sattline-parser 2026.8__tar.gz

sattline_parser-2026.8/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Søren H. Johansen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

sattline_parser-2026.8/PKG-INFO

@@ -0,0 +1,175 @@
+Metadata-Version: 2.4
+Name: sattline-parser
+Version: 2026.8
+Summary: Standalone parser, AST, and transformer for the SattLine PLC language
+Author: Søren H. Johansen
+License: MIT
+Project-URL: Homepage, https://github.com/SorenHJohansen/sattline-parser
+Project-URL: Repository, https://github.com/SorenHJohansen/sattline-parser
+Project-URL: Issues, https://github.com/SorenHJohansen/sattline-parser/issues
+Keywords: sattline,parser,transformer,ast,plc
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Compilers
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: lark[interegular]<2,>=1.3.1
+Requires-Dist: regex>=2024.0.0
+Provides-Extra: fuzz
+Requires-Dist: atheris>=2.3.0; extra == "fuzz"
+Provides-Extra: test
+Requires-Dist: pytest>=7.0.0; extra == "test"
+Requires-Dist: pytest-cov>=4.0.0; extra == "test"
+Requires-Dist: pytest-mock>=3.10.0; extra == "test"
+Requires-Dist: pytest-timeout>=2.3.1; extra == "test"
+Requires-Dist: pytest-xdist>=3.0.0; extra == "test"
+Requires-Dist: pytest-benchmark>=4.0.0; extra == "test"
+Provides-Extra: dev
+Requires-Dist: sattline-parser[fuzz,test]; extra == "dev"
+Requires-Dist: ruff==0.15.20; extra == "dev"
+Requires-Dist: pyright>=1.1.380; extra == "dev"
+Requires-Dist: build>=1.2.2; extra == "dev"
+Requires-Dist: bandit>=1.8.0; extra == "dev"
+Requires-Dist: pip-audit>=2.8.0; extra == "dev"
+Requires-Dist: twine>=5.1.1; extra == "dev"
+Requires-Dist: vulture>=2.11; extra == "dev"
+Requires-Dist: pre-commit>=4.0; extra == "dev"
+Dynamic: license-file
+
+# sattline-parser
+
+Standalone parser, AST, and transformer for ABB SattLine.
+
+This package owns the Lark grammar, the strict single-file syntax behavior, the AST models, and the `SLTransformer`, all in one self-contained, installable package.
+
+## Features
+
+- Lark LALR parser for SattLine sources (grammar in `grammar/sattline.lark`)
+- Parses plain text and files (`.s`, `.g`, `.l`, `.x`, `.y`, `.z` and any other extension; the parser is content-based, not extension-based)
+- Strict, no-silent-fallback parsing
+- Structural comments (`(* ... *)`, nested) preserved as role-tagged AST nodes
+- Automatic compressed-source decoding (`preprocess_sl_text`, `is_compressed`)
+- Error reporting with line/column locations in the original source (`describe_parse_error`)
+- AST models in `sattline_parser.models`
+- `SLTransformer` tree transformer in `sattline_parser.transformer`
+- Standalone fuzz harness with timeout protection and corpus regression
+- Zero runtime dependencies beyond `lark` and `regex`
+
+## Install
+
+```bash
+pip install sattline-parser
+```
+
+Requires Python 3.13+.
+
+## Usage
+
+### Parse a source file
+
+```python
+from pathlib import Path
+from sattline_parser import parse_source_file
+
+basepicture = parse_source_file(Path("program.s"))
+```
+
+### Parse source text
+
+```python
+from sattline_parser import parse_source_text
+
+source = open("program.x", encoding="utf-8").read()
+basepicture = parse_source_text(source)
+```
+
+`parse_source_file` and `parse_source_text` both return a `BasePicture` (the module-level model) with the full AST attached.
+
+### Choosing an entry point
+
+`parse_source_file` is for when you have a path on disk. It handles the file I/O for you: it reads the file with an encoding fallback (`utf-8`, then `cp1252`, then `latin-1`) and passes the path along so error messages can name the source file.
+
+`parse_source_text` is for when you already hold the source as a string: a snippet, an editor buffer, a response from an API, or content read by your own code. The two are interchangeable in behavior; `parse_source_file(path)` is equivalent to `parse_source_text(path.read_text(...))` plus the encoding fallback and path-aware error reporting. Start with `parse_source_file` when you have a path, `parse_source_text` otherwise.
+
+Both entry points handle cleanup automatically, so you do not need to pre-process the source:
+
+- **Comments are parsed structurally** (`(* ... *)`, including nested ones) and preserved on the AST as `CodeComment` nodes.
+- **Compressed sources are detected and decoded** automatically.
+
+The exposed helpers below exist for the rare case where you are building tooling that needs the intermediate stages (for example, to tokenize, diff, or re-emit sources). For ordinary parsing you can ignore them.
+
+### For power users: handle compressed sources
+
+```python
+from sattline_parser import is_compressed, preprocess_sl_text
+
+if is_compressed(source):
+    decoded, mapping = preprocess_sl_text(source)
+```
+
+`is_compressed` answers whether the text uses the compressed encoding, and `preprocess_sl_text` decodes it, returning the decoded text plus a mapping back to the original. Since both parse entry points already detect and decode compressed sources, these are only needed by tooling that must decode without parsing (for example, saving a plain-text copy) or by the fuzz harness that drives `preprocess_sl_text` with adversarial inputs.
+
+### Report errors with source locations
+
+```python
+from sattline_parser import create_parser, describe_parse_error, parse_source_text
+
+parser = create_parser()
+try:
+    parse_source_text(source, parser=parser)
+except Exception as exc:
+    details = describe_parse_error(exc, source)
+    print(f"{details.line}:{details.column} {details.message}")
+```
+
+### What is the AST good for?
+
+`parse_source_file` and `parse_source_text` return a `BasePicture`, a tree of Python objects that mirrors the structure of the program. Once you have it, you can inspect and walk the program *as data* instead of as text.
+
+For readers new to ASTs (abstract syntax trees): the parser does not give you the flat file back; it gives you structured objects. `basepicture.program_name` is the program name, `basepicture.moduletype_defs` is the list of type definitions, `basepicture.submodules` is the tree of nested modules, and so on. You can read fields, iterate lists, and check conditions directly in Python. For a small program this prints:
+
+```python
+from pathlib import Path
+from sattline_parser import parse_source_file
+
+basepicture = parse_source_file(Path("program.s"))
+print(basepicture.program_name)
+print([submodule.header.name for submodule in basepicture.submodules])
+print(len(basepicture.submodules), "submodules")
+```
+
+```text
+program
+['Controller1', 'Controller2']
+2 submodules
+```
+
+Think of the AST as a structured, machine-readable view of the program, that tools (a linter, a refactorer, an editor, a report generator) can walk without re-parsing the text. Since an AST is just nested objects, answering questions about the program becomes ordinary Python.
+
+## Development
+
+```bash
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+pytest tests/parser -q
+ruff check src tests
+pyright src tests
+```
+
+## Project layout
+
+- `src/sattline_parser/grammar/` : Lark grammar and constants
+- `src/sattline_parser/models/` : AST models
+- `src/sattline_parser/transformer/` : transformer mixins and `SLTransformer`
+- `src/sattline_parser/api.py` : public entry points
+- `src/sattline_parser/fuzz_harness.py` : standalone fuzzing
+
+## License
+
+MIT. Copyright (c) 2025 Søren H. Johansen.

sattline_parser-2026.8/README.md

@@ -0,0 +1,131 @@
+# sattline-parser
+
+Standalone parser, AST, and transformer for ABB SattLine.
+
+This package owns the Lark grammar, the strict single-file syntax behavior, the AST models, and the `SLTransformer`, all in one self-contained, installable package.
+
+## Features
+
+- Lark LALR parser for SattLine sources (grammar in `grammar/sattline.lark`)
+- Parses plain text and files (`.s`, `.g`, `.l`, `.x`, `.y`, `.z` and any other extension; the parser is content-based, not extension-based)
+- Strict, no-silent-fallback parsing
+- Structural comments (`(* ... *)`, nested) preserved as role-tagged AST nodes
+- Automatic compressed-source decoding (`preprocess_sl_text`, `is_compressed`)
+- Error reporting with line/column locations in the original source (`describe_parse_error`)
+- AST models in `sattline_parser.models`
+- `SLTransformer` tree transformer in `sattline_parser.transformer`
+- Standalone fuzz harness with timeout protection and corpus regression
+- Zero runtime dependencies beyond `lark` and `regex`
+
+## Install
+
+```bash
+pip install sattline-parser
+```
+
+Requires Python 3.13+.
+
+## Usage
+
+### Parse a source file
+
+```python
+from pathlib import Path
+from sattline_parser import parse_source_file
+
+basepicture = parse_source_file(Path("program.s"))
+```
+
+### Parse source text
+
+```python
+from sattline_parser import parse_source_text
+
+source = open("program.x", encoding="utf-8").read()
+basepicture = parse_source_text(source)
+```
+
+`parse_source_file` and `parse_source_text` both return a `BasePicture` (the module-level model) with the full AST attached.
+
+### Choosing an entry point
+
+`parse_source_file` is for when you have a path on disk. It handles the file I/O for you: it reads the file with an encoding fallback (`utf-8`, then `cp1252`, then `latin-1`) and passes the path along so error messages can name the source file.
+
+`parse_source_text` is for when you already hold the source as a string: a snippet, an editor buffer, a response from an API, or content read by your own code. The two are interchangeable in behavior; `parse_source_file(path)` is equivalent to `parse_source_text(path.read_text(...))` plus the encoding fallback and path-aware error reporting. Start with `parse_source_file` when you have a path, `parse_source_text` otherwise.
+
+Both entry points handle cleanup automatically, so you do not need to pre-process the source:
+
+- **Comments are parsed structurally** (`(* ... *)`, including nested ones) and preserved on the AST as `CodeComment` nodes.
+- **Compressed sources are detected and decoded** automatically.
+
+The exposed helpers below exist for the rare case where you are building tooling that needs the intermediate stages (for example, to tokenize, diff, or re-emit sources). For ordinary parsing you can ignore them.
+
+### For power users: handle compressed sources
+
+```python
+from sattline_parser import is_compressed, preprocess_sl_text
+
+if is_compressed(source):
+    decoded, mapping = preprocess_sl_text(source)
+```
+
+`is_compressed` answers whether the text uses the compressed encoding, and `preprocess_sl_text` decodes it, returning the decoded text plus a mapping back to the original. Since both parse entry points already detect and decode compressed sources, these are only needed by tooling that must decode without parsing (for example, saving a plain-text copy) or by the fuzz harness that drives `preprocess_sl_text` with adversarial inputs.
+
+### Report errors with source locations
+
+```python
+from sattline_parser import create_parser, describe_parse_error, parse_source_text
+
+parser = create_parser()
+try:
+    parse_source_text(source, parser=parser)
+except Exception as exc:
+    details = describe_parse_error(exc, source)
+    print(f"{details.line}:{details.column} {details.message}")
+```
+
+### What is the AST good for?
+
+`parse_source_file` and `parse_source_text` return a `BasePicture`, a tree of Python objects that mirrors the structure of the program. Once you have it, you can inspect and walk the program *as data* instead of as text.
+
+For readers new to ASTs (abstract syntax trees): the parser does not give you the flat file back; it gives you structured objects. `basepicture.program_name` is the program name, `basepicture.moduletype_defs` is the list of type definitions, `basepicture.submodules` is the tree of nested modules, and so on. You can read fields, iterate lists, and check conditions directly in Python. For a small program this prints:
+
+```python
+from pathlib import Path
+from sattline_parser import parse_source_file
+
+basepicture = parse_source_file(Path("program.s"))
+print(basepicture.program_name)
+print([submodule.header.name for submodule in basepicture.submodules])
+print(len(basepicture.submodules), "submodules")
+```
+
+```text
+program
+['Controller1', 'Controller2']
+2 submodules
+```
+
+Think of the AST as a structured, machine-readable view of the program, that tools (a linter, a refactorer, an editor, a report generator) can walk without re-parsing the text. Since an AST is just nested objects, answering questions about the program becomes ordinary Python.
+
+## Development
+
+```bash
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+pytest tests/parser -q
+ruff check src tests
+pyright src tests
+```
+
+## Project layout
+
+- `src/sattline_parser/grammar/` : Lark grammar and constants
+- `src/sattline_parser/models/` : AST models
+- `src/sattline_parser/transformer/` : transformer mixins and `SLTransformer`
+- `src/sattline_parser/api.py` : public entry points
+- `src/sattline_parser/fuzz_harness.py` : standalone fuzzing
+
+## License
+
+MIT. Copyright (c) 2025 Søren H. Johansen.

sattline_parser-2026.8/pyproject.toml

@@ -0,0 +1,147 @@
+[build-system]
+requires = ["setuptools>=82.0.1", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "sattline-parser"
+dynamic = ["version"]
+description = "Standalone parser, AST, and transformer for the SattLine PLC language"
+readme = "README.md"
+license = { text = "MIT" }
+authors = [{ name = "S\u00f8ren H. Johansen" }]
+requires-python = ">=3.13"
+keywords = ["sattline", "parser", "transformer", "ast", "plc"]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Compilers",
+    "Topic :: Software Development :: Quality Assurance",
+]
+dependencies = [
+    "lark[interegular]>=1.3.1,<2",
+    "regex>=2024.0.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/SorenHJohansen/sattline-parser"
+Repository = "https://github.com/SorenHJohansen/sattline-parser"
+Issues = "https://github.com/SorenHJohansen/sattline-parser/issues"
+
+[project.optional-dependencies]
+fuzz = [
+    "atheris>=2.3.0",
+]
+
+test = [
+    "pytest>=7.0.0",
+    "pytest-cov>=4.0.0",
+    "pytest-mock>=3.10.0",
+    "pytest-timeout>=2.3.1",
+    "pytest-xdist>=3.0.0",
+    "pytest-benchmark>=4.0.0",
+]
+
+dev = [
+    "sattline-parser[test,fuzz]",
+    "ruff==0.15.20",
+    "pyright>=1.1.380",
+    "build>=1.2.2",
+    "bandit>=1.8.0",
+    "pip-audit>=2.8.0",
+    "twine>=5.1.1",
+    "vulture>=2.11",
+    "pre-commit>=4.0",
+]
+
+[tool.pytest.ini_options]
+minversion = "7.0"
+testpaths = ["tests"]
+python_files = ["test_*.py", "*_test.py"]
+python_classes = ["Test*"]
+python_functions = ["test_*"]
+timeout = 60
+timeout_method = "thread"
+addopts = [
+    "--strict-markers",
+    "--strict-config",
+    "--cov=src",
+    "--cov-report=term-missing",
+    "--cov-report=xml:coverage.xml",
+    "--cov-report=html:htmlcov",
+]
+markers = [
+    "slow: marks tests as slow (deselect with '-m \"not slow\"')",
+    "parser: marks tests related to parser functionality",
+    "quarantine: marks flaky tests that should be skipped in CI",
+]
+
+[tool.coverage.report]
+precision = 2
+exclude_lines = [
+    "if TYPE_CHECKING:",
+    "if not fitting_tokens:",
+    'encoding="latin-1"',
+]
+fail_under = 100
+
+[tool.ruff]
+line-length = 120
+target-version = "py313"
+
+[tool.ruff.lint]
+select = [
+    "E",     # pycodestyle errors
+    "F",     # pyflakes
+    "W",     # pycodestyle warnings
+    "I",     # isort
+    "N",     # pep8-naming
+    "UP",    # pyupgrade
+    "B",     # flake8-bugbear
+    "BLE",   # blind except Exception handlers
+    "C4",    # flake8-comprehensions
+    "PLC0415", # imports outside top-level
+    "PLR0915", # too many statements
+    "S101",  # disallow assert-based error handling
+    "SIM",   # flake8-simplify
+    "RUF",   # ruff-specific rules
+]
+ignore = [
+    "E501",
+]
+
+[tool.ruff.lint.per-file-ignores]
+"src/sattline_parser/models/ast_model.py" = ["N801"]
+"src/sattline_parser/transformer/sl_transformer.py" = ["N802"]
+"src/sattline_parser/transformer/_modules_mixin.py" = ["N802"]
+"src/sattline_parser/transformer/_tokens_mixin.py" = ["N802"]
+"tests/*.py" = ["S101"]
+"tests/**/*.py" = ["S101"]
+
+[tool.ruff.lint.pylint]
+max-statements = 50
+
+[tool.pyright]
+include = ["src", "tests"]
+typeCheckingMode = "strict"
+pythonVersion = "3.13"
+venvPath = "."
+venv = ".venv"
+extraPaths = ["src"]
+reportMissingTypeStubs = false
+
+[tool.bandit]
+exclude_dirs = ["tests"]
+skips = ["B404", "B603"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.dynamic]
+version = { attr = "sattline_parser.__version__.__version__" }
+
+[tool.setuptools.package-data]
+sattline_parser = ["grammar/*.lark"]

sattline_parser-2026.8/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

sattline_parser-2026.8/src/sattline_parser/__init__.py

@@ -0,0 +1,116 @@
+"""Reusable SattLine parser-core package."""
+
+from __future__ import annotations
+
+from importlib import import_module
+from types import ModuleType
+from typing import TYPE_CHECKING, Any
+
+from sattline_parser.models.ast_model import BasePicture, SourceSpan
+from sattline_parser.models.expressions import (
+    Assignment,
+    BinOp,
+    BoolOp,
+    Compare,
+    FuncCall,
+    FuncCallStmt,
+    IfStmt,
+    NotOp,
+    SLExpression,
+    SLStmt,
+    TernaryOp,
+    UnaryOp,
+    VarRef,
+)
+from sattline_parser.preprocessing import is_compressed, preprocess_sl_text
+from sattline_parser.transformer.sl_transformer import SLTransformer
+
+from .__version__ import __version__
+from .api import create_parser, create_sl_parser, describe_parse_error, parse_source_file, parse_source_text
+from .grammar import constants
+
+if TYPE_CHECKING:
+    from . import fuzz_harness as fuzz_harness
+    from .fuzz_harness import (
+        FuzzResult,
+        assert_no_crashes,
+        assert_no_timeouts,
+        collect_corpus_inputs,
+        fuzz_parse_text,
+        generate_random_text,
+        run_corpus_regression,
+        run_random_fuzz,
+    )
+
+_FUZZ_EXPORTS = (
+    "FuzzResult",
+    "assert_no_crashes",
+    "assert_no_timeouts",
+    "collect_corpus_inputs",
+    "fuzz_harness",
+    "fuzz_parse_text",
+    "generate_random_text",
+    "run_corpus_regression",
+    "run_random_fuzz",
+)
+_FUZZ_EXPORT_SET = frozenset(_FUZZ_EXPORTS)
+
+
+def _load_fuzz_harness() -> ModuleType:
+    module = import_module(".fuzz_harness", __name__)
+    globals()["fuzz_harness"] = module
+    for export_name in _FUZZ_EXPORTS:
+        if export_name == "fuzz_harness":
+            continue
+        globals()[export_name] = getattr(module, export_name)
+    return module
+
+
+def __getattr__(name: str) -> Any:
+    if name not in _FUZZ_EXPORT_SET:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+    module = _load_fuzz_harness()
+    if name == "fuzz_harness":
+        return module
+    return getattr(module, name)
+
+
+def __dir__() -> list[str]:
+    return sorted(set(globals()) | _FUZZ_EXPORT_SET)
+
+
+__all__ = [
+    "Assignment",
+    "BasePicture",
+    "BinOp",
+    "BoolOp",
+    "Compare",
+    "FuncCall",
+    "FuncCallStmt",
+    "FuzzResult",
+    "IfStmt",
+    "NotOp",
+    "SLExpression",
+    "SLStmt",
+    "SLTransformer",
+    "SourceSpan",
+    "TernaryOp",
+    "UnaryOp",
+    "VarRef",
+    "__version__",
+    "assert_no_crashes",
+    "assert_no_timeouts",
+    "collect_corpus_inputs",
+    "constants",
+    "create_parser",
+    "create_sl_parser",
+    "describe_parse_error",
+    "fuzz_parse_text",
+    "generate_random_text",
+    "is_compressed",
+    "parse_source_file",
+    "parse_source_text",
+    "preprocess_sl_text",
+    "run_corpus_regression",
+    "run_random_fuzz",
+]

sattline_parser-2026.8/src/sattline_parser/__version__.py

@@ -0,0 +1,3 @@
+"""Package version metadata."""
+
+__version__ = "2026.8"