plcc-ng 0.1.2__tar.gz

plcc_ng-0.1.2/PKG-INFO

@@ -0,0 +1,63 @@
+Metadata-Version: 2.1
+Name: plcc-ng
+Version: 0.1.2
+Summary: Programming Languages Compiler Compiler — experimental rewrite of PLCC
+Keywords: compiler,parser,education,plcc,teaching,programming-languages
+Author-Email: PLCC Community <https://discord.gg/EVtNSxS9E2>
+License: AGPL-3.0-or-later
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Education
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Compilers
+Classifier: Topic :: Education
+Project-URL: Homepage, https://github.com/ourPLCC/plcc-ng
+Project-URL: Repository, https://github.com/ourPLCC/plcc-ng
+Project-URL: Issues, https://github.com/ourPLCC/plcc-ng/issues
+Requires-Python: >=3.12
+Requires-Dist: docopt-ng>=0.9.0
+Requires-Dist: jinja2>=3.1.0
+Description-Content-Type: text/markdown
+
+# plcc-ng
+
+PLCC is designed for teaching and learning programming language concepts.
+plcc-ng is a reimagining and reimplementation of PLCC.
+
+This is currently under development.
+
+## Install
+
+```bash
+pip install plcc-ng
+```
+
+> This package has a separate identity from the original `plcc` package.
+> `plcc-ng` is experimental — no compatibility guarantees with `plcc` until a stable 1.0 release.
+
+## Licensing
+
+Developers license contributions under [AGPL-3.0-or-later](LICENSES/AGPL-3.0-or-later.txt) and sign off on the
+[DCO-1.1](DCO-1.1.txt)
+
+## Community
+
+- [Code of conduct](CODE_OF_CONDUCT.md)
+- [Discord server]((https://discord.gg/EVtNSxS9E2))
+
+## Development
+
+- Python
+- PDM
+- Codespaces
+- Dev Containers
+- Clean code
+- TDD
+- Open Source Values
+- Continuously run unit tests (^C to stop)
+
+    ```bash
+    pdm ctest
+    ```

plcc_ng-0.1.2/README.md

@@ -0,0 +1,40 @@
+# plcc-ng
+
+PLCC is designed for teaching and learning programming language concepts.
+plcc-ng is a reimagining and reimplementation of PLCC.
+
+This is currently under development.
+
+## Install
+
+```bash
+pip install plcc-ng
+```
+
+> This package has a separate identity from the original `plcc` package.
+> `plcc-ng` is experimental — no compatibility guarantees with `plcc` until a stable 1.0 release.
+
+## Licensing
+
+Developers license contributions under [AGPL-3.0-or-later](LICENSES/AGPL-3.0-or-later.txt) and sign off on the
+[DCO-1.1](DCO-1.1.txt)
+
+## Community
+
+- [Code of conduct](CODE_OF_CONDUCT.md)
+- [Discord server]((https://discord.gg/EVtNSxS9E2))
+
+## Development
+
+- Python
+- PDM
+- Codespaces
+- Dev Containers
+- Clean code
+- TDD
+- Open Source Values
+- Continuously run unit tests (^C to stop)
+
+    ```bash
+    pdm ctest
+    ```

plcc_ng-0.1.2/pyproject.toml

@@ -0,0 +1,102 @@
+[project]
+name = "plcc-ng"
+dynamic = []
+description = "Programming Languages Compiler Compiler — experimental rewrite of PLCC"
+authors = [
+    { name = "PLCC Community", email = "https://discord.gg/EVtNSxS9E2" },
+]
+dependencies = [
+    "docopt-ng>=0.9.0",
+    "jinja2>=3.1.0",
+]
+requires-python = ">=3.12"
+readme = "README.md"
+keywords = [
+    "compiler",
+    "parser",
+    "education",
+    "plcc",
+    "teaching",
+    "programming-languages",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Education",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Compilers",
+    "Topic :: Education",
+]
+version = "0.1.2"
+
+[project.license]
+text = "AGPL-3.0-or-later"
+
+[project.urls]
+Homepage = "https://github.com/ourPLCC/plcc-ng"
+Repository = "https://github.com/ourPLCC/plcc-ng"
+Issues = "https://github.com/ourPLCC/plcc-ng/issues"
+
+[project.scripts]
+plcc-spec = "plcc.spec.plcc_spec_cli:main"
+plcc-tokens = "plcc.tokens.tokens_cli:main"
+plcc-tree = "plcc.tree.tree_cli:main"
+plcc-model = "plcc.model.model_cli:main"
+plcc-plantuml-diagram = "plcc.diagram.plantuml.emit:main"
+plcc-lang-emit = "plcc.lang.emit:main"
+plcc-diagram = "plcc.diagram.dispatch:main"
+plcc-lang-build = "plcc.lang.build:main"
+plcc-lang-list = "plcc.lang.list:main"
+plcc-diagram-list = "plcc.diagram.list:main"
+plcc-make = "plcc.cmd.make:main"
+plcc-scan = "plcc.cmd.scan:main"
+plcc-parse = "plcc.cmd.parse:main"
+plcc-rep = "plcc.cmd.rep:main"
+plcc-ll1 = "plcc.ll1.ll1_cli:main"
+plcc-parser-table = "plcc.parser.table_cli:main"
+plcc-parser-list = "plcc.parser.list_cli:main"
+plcc-python-emit = "plcc.lang.ext.python.emit:main"
+plcc-lang-run = "plcc.lang.run:main"
+plcc-python-run = "plcc.lang.ext.python.run:main"
+plcc-java-emit = "plcc.lang.ext.java.emit:main"
+plcc-java-build = "plcc.lang.ext.java.build:main"
+plcc-java-run = "plcc.lang.ext.java.run:main"
+
+[build-system]
+requires = [
+    "pdm-backend",
+]
+build-backend = "pdm.backend"
+
+[tool.pdm]
+distribution = true
+
+[tool.pdm.build]
+package-dir = "src"
+
+[tool.pdm.version]
+source = "scm"
+fallback_version = "0.0.0"
+
+[tool.pdm.scripts]
+test = "pytest -qq -rfEsxXP --cov=plcc --cov-branch --cov-report term-missing:skip-covered"
+ctest = "pytest-watch --runner \"bin/test/units.bash\""
+
+[tool.semantic_release]
+tag_format = "v{version}"
+version_variables = []
+version_toml = []
+major_on_zero = false
+
+[dependency-groups]
+dev = [
+    "pytest>=8.2.0",
+    "pyfakefs>=5.4.1",
+    "pytest-cov>=5.0.0",
+    "pytest-watch>=4.2.0",
+    "check-jsonschema>=0.29.0",
+    "python-semantic-release>=9.0.0",
+    "twine>=5.0.0",
+]

plcc_ng-0.1.2/src/plcc/cmd/make.py

@@ -0,0 +1,140 @@
+import contextlib
+import enum
+import json
+import os
+import re
+import shutil
+import subprocess
+import sys
+
+from docopt import docopt
+
+from plcc.verbose import VerboseContext, VERBOSE_OPTIONS
+
+__doc__ = """plcc-make
+    Build a PLCC project from a grammar file.
+
+Usage:
+    plcc-make [options] GRAMMAR
+
+Arguments:
+    GRAMMAR     Path to the PLCC grammar file.
+
+Options:
+    -h --help   Show this message.
+""" + VERBOSE_OPTIONS
+
+_TOOL_NAME_RE = re.compile(r'^[a-zA-Z0-9_-]+$')
+
+
+class Events(enum.Enum):
+    STARTED = "started"
+    PHASE = "phase"
+    FINISHED = "finished"
+
+
+def main(argv=None):
+    if argv is None:
+        argv = sys.argv[1:]
+    args = docopt(__doc__, argv)
+    verbose = VerboseContext.from_args("plcc-make", Events, args)
+    grammar = args['GRAMMAR']
+    build_dir = 'build'
+
+    verbose.emit(Events.STARTED, message=f"building {grammar}")
+
+    # 1. Clean
+    if os.path.exists(build_dir):
+        shutil.rmtree(build_dir)
+    os.makedirs(build_dir)
+
+    child_flags = verbose.child_flags_for_orchestrator(min_level=0)
+
+    # 2. Spec
+    verbose.emit(Events.PHASE, message="spec")
+    spec_json = os.path.join(build_dir, 'spec.json')
+    _run_or_die(['plcc-spec', grammar] + child_flags, stdout_file=spec_json, verbose=verbose)
+
+    # 3. LL(1)
+    verbose.emit(Events.PHASE, message="ll1")
+    ll1_json = os.path.join(build_dir, 'll1.json')
+    _run_or_die(['plcc-ll1'] + child_flags, stdin_file=spec_json, stdout_file=ll1_json, verbose=verbose)
+    with open(ll1_json) as f:
+        ll1 = json.load(f)
+    if not ll1.get("is_ll1", True):
+        _report_ll1_failure(ll1, ll1_json, verbose)
+        sys.exit(1)
+
+    # 4. Model
+    verbose.emit(Events.PHASE, message="model")
+    model_json = os.path.join(build_dir, 'model.json')
+    _run_or_die(['plcc-model', spec_json] + child_flags, stdout_file=model_json, verbose=verbose)
+
+    # 5 & 6. Emit and build per semantic section
+    with open(spec_json) as f:
+        spec = json.load(f)
+    for section in spec.get('semantics', []):
+        tool = section['tool']
+        lang = section['language']
+        try:
+            validate_tool_name(tool)
+        except ValueError as e:
+            print(f"plcc-make: {e}", file=sys.stderr)
+            sys.exit(1)
+        output_dir = os.path.join(build_dir, tool)
+        os.makedirs(output_dir, exist_ok=True)
+        verbose.emit(Events.PHASE, message=f"emit {lang} -> {tool}")
+        _run_or_die(
+            ['plcc-lang-emit', f'--target={lang}', f'--output={output_dir}'] + child_flags,
+            stdin_file=model_json,
+            verbose=verbose,
+        )
+        verbose.emit(Events.PHASE, message=f"build {lang} -> {tool}")
+        _run_or_die(
+            ['plcc-lang-build', f'--target={lang}', f'--output={output_dir}'] + child_flags,
+            verbose=verbose,
+        )
+
+    verbose.emit(Events.FINISHED, message="done")
+
+
+def validate_tool_name(name):
+    if not name or not _TOOL_NAME_RE.match(name):
+        raise ValueError(
+            f"Invalid tool name '{name}'. "
+            "Tool names must match [a-zA-Z0-9_-]+ to prevent path traversal."
+        )
+
+
+def _report_ll1_failure(ll1, path, verbose):
+    print(
+        f"plcc-make: error: grammar is not LL(1); see {path}",
+        file=sys.stderr,
+    )
+    for conflict in ll1.get("conflicts", []):
+        print(
+            f"plcc-make: error: conflict at "
+            f"{conflict.get('nonterminal', '?')} on "
+            f"{conflict.get('lookahead', '?')}: "
+            f"{conflict.get('productions', [])}",
+            file=sys.stderr,
+        )
+    for entry in ll1.get("left_recursion", []):
+        cycle = entry.get("cycle", [])
+        print(
+            f"plcc-make: error: left-recursion cycle: {' -> '.join(cycle)}",
+            file=sys.stderr,
+        )
+
+
+def _run_or_die(cmd, stdout_file=None, stdin_file=None, verbose=None):
+    with contextlib.ExitStack() as stack:
+        stdin = stack.enter_context(open(stdin_file)) if stdin_file else None
+        stdout = stack.enter_context(open(stdout_file, 'w')) if stdout_file else None
+        result = subprocess.run(cmd, stdin=stdin, stdout=stdout, stderr=subprocess.PIPE)
+    if verbose and result.stderr:
+        events = verbose.parse_child_events(result.stderr.decode("utf-8", errors="replace"))
+        verbose.reformat_child_events(events)
+    if result.returncode != 0:
+        print(f"plcc-make: {cmd[0]} failed (exit {result.returncode})", file=sys.stderr)
+        sys.exit(result.returncode)

plcc_ng-0.1.2/src/plcc/cmd/make_test.py

@@ -0,0 +1,74 @@
+import pytest
+import docopt
+
+from .make import main as run_main, validate_tool_name, _report_ll1_failure
+
+
+def test_no_args_prints_usage():
+    with pytest.raises((docopt.DocoptExit, SystemExit)):
+        run_main([])
+
+
+def test_help(capsys):
+    with pytest.raises(SystemExit):
+        run_main(['--help'])
+    out, err = capsys.readouterr()
+    assert 'Usage' in out
+
+
+def test_validate_tool_name_accepts_valid():
+    validate_tool_name('diagram')
+    validate_tool_name('Java')
+    validate_tool_name('my-tool')
+    validate_tool_name('tool_123')
+
+
+def test_validate_tool_name_rejects_path_traversal():
+    with pytest.raises(ValueError):
+        validate_tool_name('../etc')
+    with pytest.raises(ValueError):
+        validate_tool_name('foo/bar')
+    with pytest.raises(ValueError):
+        validate_tool_name('/absolute')
+
+
+def test_validate_tool_name_rejects_empty():
+    with pytest.raises(ValueError):
+        validate_tool_name('')
+
+
+def test_report_ll1_failure_prints_error_and_conflicts(capsys):
+    ll1 = {
+        "is_ll1": False,
+        "conflicts": [
+            {"nonterminal": "E", "lookahead": "+", "competing": ["E + T", "E"]}
+        ],
+        "left_recursion": [],
+    }
+    _report_ll1_failure(ll1, "build/ll1.json", verbose=None)
+    _, err = capsys.readouterr()
+    assert "plcc-make: error:" in err
+    assert "build/ll1.json" in err
+    assert "E" in err
+    assert "+" in err
+
+
+def test_report_left_recursion_cycle(capsys):
+    ll1 = {
+        "conflicts": [],
+        "left_recursion": [{"cycle": ["A", "B", "A"]}],
+    }
+    _report_ll1_failure(ll1, "build/ll1.json", None)
+    _, err = capsys.readouterr()
+    assert "A -> B -> A" in err
+
+
+def test_report_conflict(capsys):
+    ll1 = {
+        "conflicts": [{"nonterminal": "E", "lookahead": "PLUS", "productions": []}],
+        "left_recursion": [],
+    }
+    _report_ll1_failure(ll1, "build/ll1.json", None)
+    _, err = capsys.readouterr()
+    assert "E" in err
+    assert "PLUS" in err

plcc_ng-0.1.2/src/plcc/cmd/parse.py

@@ -0,0 +1,146 @@
+import enum
+import json
+import os
+import subprocess
+import sys
+import tempfile
+
+from docopt import docopt
+
+from plcc.verbose import VerboseContext, VERBOSE_OPTIONS, reap_pipeline
+
+__doc__ = """plcc-parse
+    Parse source input and print parse tree in human-readable format.
+
+Usage:
+    plcc-parse [options] GRAMMAR [SOURCE ...]
+
+Arguments:
+    GRAMMAR     Path to the PLCC grammar file.
+    SOURCE      Source files to parse. Reads stdin if none given.
+
+Options:
+    -h --help   Show this message.
+""" + VERBOSE_OPTIONS
+
+
+class Events(enum.Enum):
+    STARTED = "started"
+    FINISHED = "finished"
+
+
+def _location_str(source):
+    file = source.get("file")
+    line = source.get("line", "?")
+    col = source.get("column", "?")
+    if file and file != "<stdin>":
+        return f"{file}:{line}:{col}"
+    return f"{line}:{col}"
+
+
+def main(argv=None):
+    if argv is None:
+        argv = sys.argv[1:]
+    args = docopt(__doc__, argv)
+    verbose = VerboseContext.from_args("plcc-parse", Events, args)
+    grammar = args["GRAMMAR"]
+    sources = args["SOURCE"]
+
+    verbose.emit(Events.STARTED, message=f"parsing with {grammar}")
+    child_flags = verbose.child_flags_for_orchestrator(min_level=0)
+
+    spec_path = tempfile.mktemp(suffix=".json")
+    ll1_path = tempfile.mktemp(suffix=".json")
+    try:
+        # plcc-spec
+        _run_child(["plcc-spec", grammar] + child_flags, stdout_file=spec_path, verbose=verbose, label="plcc-spec")
+        # plcc-ll1
+        _run_child(["plcc-ll1"] + child_flags, stdin_file=spec_path, stdout_file=ll1_path, verbose=verbose, label="plcc-ll1")
+
+        # Build input
+        input_data = b""
+        for src in sources:
+            with open(src, "rb") as sf:
+                input_data += sf.read()
+        if not sources:
+            input_data = sys.stdin.buffer.read()
+
+        # plcc-tokens | plcc-tree
+        tokens_proc = subprocess.Popen(
+            ["plcc-tokens", spec_path] + child_flags,
+            stdin=subprocess.PIPE,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+        )
+        tree_proc = subprocess.Popen(
+            ["plcc-tree", f"--ll1={ll1_path}"] + child_flags,
+            stdin=tokens_proc.stdout,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+        )
+        tokens_proc.stdout.close()
+        tokens_proc.stdin.write(input_data)
+        tokens_proc.stdin.close()
+
+        tree_out, tree_err = tree_proc.communicate()
+        tokens_err = tokens_proc.stderr.read()
+        tokens_proc.wait()
+        tokens_proc.stderr_captured = tokens_err
+        tree_proc.stderr_captured = tree_err
+
+        result = reap_pipeline([
+            (tokens_proc, "plcc-tokens"),
+            (tree_proc, "plcc-tree"),
+        ])
+        verbose.reformat_child_events(result.events_to_render)
+        if result.failed_stage:
+            sys.exit(result.exit_code)
+
+        # Print tree in human-readable format
+        for line in tree_out.decode("utf-8").splitlines():
+            if not line.strip():
+                continue
+            tree = json.loads(line)
+            _print_tree(tree, indent=0)
+    finally:
+        for p in (spec_path, ll1_path):
+            if os.path.exists(p):
+                os.unlink(p)
+
+    verbose.emit(Events.FINISHED, message="done")
+
+
+def _run_child(cmd, stdout_file, verbose, label, stdin_file=None):
+    with open(stdout_file, "w") as out:
+        stdin = open(stdin_file) if stdin_file else None
+        result = subprocess.run(cmd, stdin=stdin, stdout=out, stderr=subprocess.PIPE)
+        if stdin:
+            stdin.close()
+    if result.stderr:
+        events = verbose.parse_child_events(result.stderr.decode("utf-8", errors="replace"))
+        verbose.reformat_child_events(events)
+    if result.returncode != 0:
+        print(f"plcc-parse: {label} failed (exit {result.returncode})", file=sys.stderr)
+        sys.exit(result.returncode)
+
+
+def _print_tree(node, indent):
+    prefix = "  " * indent
+    kind = node.get("kind", "?")
+    if kind == "tree":
+        rule = node.get("rule", "?")
+        print(f"{prefix}{rule}")
+        for _field, child in node.get("children", []):
+            _print_tree(child, indent + 1)
+    elif kind == "token":
+        name = node.get("name", "?")
+        lexeme = node.get("lexeme", "?")
+        source = node.get("source", {})
+        loc = _location_str(source)
+        print(f"{prefix}{name} '{lexeme}' [{loc}]")
+    # forward-looking: plcc-tree may emit error records inline in a future protocol
+    elif kind == "error":
+        source = node.get("source", {})
+        loc = _location_str(source)
+        message = node.get("message", "unknown error")
+        print(f"{prefix}{loc}: error: {message}")