plcc-ng 0.1.2__py3-none-any.whl

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/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/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}")

plcc/cmd/rep.py

@@ -0,0 +1,190 @@
+import enum
+import json
+import os
+import subprocess
+import sys
+
+from docopt import docopt
+
+from plcc.verbose import VerboseContext, VERBOSE_OPTIONS
+
+__doc__ = """plcc-rep
+    REPL — read, eval, print loop for a PLCC grammar.
+
+Usage:
+    plcc-rep [options] GRAMMAR [SOURCE ...]
+
+Arguments:
+    GRAMMAR     Path to the PLCC grammar file (build/ is resolved from the current directory).
+    SOURCE      Source files to evaluate before entering interactive mode.
+
+Options:
+    --tool=NAME         Semantic section to run (inferred if only one exists).
+    -h --help           Show this message.
+""" + VERBOSE_OPTIONS
+
+
+class Events(enum.Enum):
+    STARTED = "started"
+    FINISHED = "finished"
+
+
+def main(argv=None):
+    if argv is None:
+        argv = sys.argv[1:]
+    args = docopt(__doc__, argv)
+    verbose = VerboseContext.from_args("plcc-rep", Events, args)
+    sources = args['SOURCE']
+    tool_name = args['--tool']
+    verbose_format = args['--verbose-format'] or 'text'
+
+    verbose.emit(Events.STARTED, message='starting rep')
+
+    spec_path = os.path.join('build', 'spec.json')
+    ll1_path = os.path.join('build', 'll1.json')
+
+    if not os.path.exists(spec_path) or not os.path.exists(ll1_path):
+        print('plcc-rep: build/ not found. Run plcc-make first.', file=sys.stderr)
+        sys.exit(1)
+
+    with open(spec_path) as f:
+        spec = json.load(f)
+
+    tool_name, language = _resolve_tool(spec, tool_name)
+    tool_dir = os.path.join('build', tool_name)
+
+    if not os.path.exists(tool_dir):
+        print(f'plcc-rep: build/{tool_name}/ not found. Run plcc-make first.', file=sys.stderr)
+        sys.exit(1)
+
+    interpreter = subprocess.Popen(
+        ['plcc-lang-run', f'--target={language}', f'--output={tool_dir}'],
+        stdin=subprocess.PIPE,
+        stdout=subprocess.PIPE,
+        stderr=None,
+    )
+
+    try:
+        for src in sources:
+            with open(src, 'rb') as f:
+                chunk = f.read()
+            _eval_chunk(chunk, interpreter, spec_path, ll1_path, verbose_format)
+
+        if not sources:
+            interactive = sys.stdin.isatty()
+            if interactive:
+                while True:
+                    try:
+                        print('>>> ', end='', flush=True, file=sys.stderr)
+                        line = sys.stdin.readline()
+                        if not line:
+                            break
+                        chunk = line.encode()
+                        _eval_chunk(chunk, interpreter, spec_path, ll1_path, verbose_format)
+                    except KeyboardInterrupt:
+                        print(file=sys.stderr)
+                        break
+            else:
+                chunk = sys.stdin.buffer.read()
+                _eval_chunk(chunk, interpreter, spec_path, ll1_path, verbose_format)
+    finally:
+        try:
+            interpreter.stdin.close()
+        except BrokenPipeError:
+            pass
+        interpreter.wait()
+
+    verbose.emit(Events.FINISHED, message='done')
+
+
+def _resolve_tool(spec, tool_name):
+    sections = spec.get('semantics', [])
+    if tool_name:
+        for s in sections:
+            if s['tool'] == tool_name:
+                return s['tool'], s['language']
+        print(f"plcc-rep: no semantic section with tool '{tool_name}'", file=sys.stderr)
+        sys.exit(1)
+
+    if len(sections) == 0:
+        print("plcc-rep: no semantic sections found. Run plcc-make first.", file=sys.stderr)
+        sys.exit(1)
+
+    if len(sections) == 1:
+        return sections[0]['tool'], sections[0]['language']
+
+    names = [s['tool'] for s in sections]
+    print(f"plcc-rep: multiple semantic sections: {names}. Use --tool=NAME.", file=sys.stderr)
+    sys.exit(1)
+
+
+def _eval_chunk(chunk, interpreter, spec_path, ll1_path, verbose_format):
+    tokens_proc = subprocess.Popen(
+        ['plcc-tokens', spec_path],
+        stdin=subprocess.PIPE,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+    )
+    tree_proc = subprocess.Popen(
+        ['plcc-tree', f'--ll1={ll1_path}'],
+        stdin=tokens_proc.stdout,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+    )
+    tokens_proc.stdout.close()
+    tokens_proc.stdin.write(chunk)
+    tokens_proc.stdin.close()
+
+    tree_out, tree_err = tree_proc.communicate()
+    tokens_err = tokens_proc.stderr.read()
+    tokens_proc.wait()
+
+    if tokens_proc.returncode != 0 or tree_proc.returncode != 0:
+        for msg in [tokens_err, tree_err]:
+            if msg:
+                sys.stderr.buffer.write(msg)
+        return
+
+    tree_line = tree_out.strip()
+    if not tree_line:
+        return
+
+    try:
+        interpreter.stdin.write(tree_line + b'\n')
+        interpreter.stdin.flush()
+    except BrokenPipeError:
+        print('plcc-rep: interpreter exited unexpectedly', file=sys.stderr)
+        sys.exit(1)
+
+    _read_response(interpreter.stdout, verbose_format)
+
+
+def _read_response(stdout, verbose_format):
+    while True:
+        raw = stdout.readline()
+        if not raw:
+            print('plcc-rep: interpreter exited unexpectedly', file=sys.stderr)
+            sys.exit(1)
+        line = raw.decode('utf-8', errors='replace').rstrip('\n')
+        try:
+            record = json.loads(line)
+        except json.JSONDecodeError:
+            print(line)
+            continue
+        if 'kind' not in record:
+            print(line)
+            continue
+        _render_record(record, verbose_format)
+        return
+
+
+def _render_record(record, verbose_format):
+    if verbose_format == 'json':
+        print(json.dumps(record))
+        return
+    if record['kind'] == 'result':
+        value = record.get('value')
+        if value is not None:
+            print(value)
+    elif record['kind'] == 'error':
+        print(f"error: {record.get('type')}: {record.get('message')}", file=sys.stderr)

plcc/cmd/scan.py

@@ -0,0 +1,112 @@
+import enum
+import json
+import os
+import subprocess
+import sys
+import tempfile
+
+from docopt import docopt
+
+from plcc.verbose import VerboseContext, VERBOSE_OPTIONS
+
+
+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}"
+
+
+__doc__ = """plcc-scan
+    Tokenize source input and print tokens in human-readable format.
+
+Usage:
+    plcc-scan [options] GRAMMAR [SOURCE ...]
+
+Arguments:
+    GRAMMAR     Path to the PLCC grammar file.
+    SOURCE      Source files to tokenize. Reads stdin if none given.
+
+Options:
+    -h --help   Show this message.
+""" + VERBOSE_OPTIONS
+
+
+class Events(enum.Enum):
+    STARTED = "started"
+    FINISHED = "finished"
+
+
+def main(argv=None):
+    if argv is None:
+        argv = sys.argv[1:]
+    args = docopt(__doc__, argv)
+    verbose = VerboseContext.from_args("plcc-scan", Events, args)
+    grammar = args["GRAMMAR"]
+    sources = args["SOURCE"]
+
+    verbose.emit(Events.STARTED, message=f"scanning with {grammar}")
+    child_flags = verbose.child_flags_for_orchestrator(min_level=0)
+
+    with tempfile.NamedTemporaryFile(mode="w", suffix=".json", delete=False) as f:
+        spec_path = f.name
+    try:
+        # plcc-spec grammar > spec.json
+        with open(spec_path, "w") as spec_out:
+            result = subprocess.run(
+                ["plcc-spec", grammar] + child_flags,
+                stdout=spec_out,
+                stderr=subprocess.PIPE,
+            )
+        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-scan: plcc-spec failed (exit {result.returncode})", file=sys.stderr)
+            sys.exit(result.returncode)
+
+        # Build input: concatenate source files, then stdin
+        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 spec.json < input
+        result = subprocess.run(
+            ["plcc-tokens", spec_path] + child_flags,
+            input=input_data,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+        )
+        if result.stderr:
+            events = verbose.parse_child_events(result.stderr.decode("utf-8", errors="replace"))
+            verbose.reformat_child_events(events)
+        if result.returncode != 0:
+            # lex error: plcc-tokens already emitted the error to stderr via verbose;
+            # treat as non-fatal — pipeline completed with an error in-band
+            pass
+        else:
+            for line in result.stdout.decode("utf-8").splitlines():
+                if not line.strip():
+                    continue
+                record = json.loads(line)
+                if record.get("kind") == "token":
+                    name = record.get("name", "?")
+                    lexeme = record.get("lexeme", "?")
+                    source = record.get("source", {})
+                    loc = _location_str(source)
+                    print(f"{loc} {name} '{lexeme}'")
+                # forward-looking: plcc-tokens may emit error records inline in a future protocol
+                elif record.get("kind") == "error":
+                    source = record.get("source", {})
+                    loc = _location_str(source)
+                    message = record.get("message", "unknown error")
+                    print(f"{loc}: error: {message}")
+    finally:
+        os.unlink(spec_path)
+
+    verbose.emit(Events.FINISHED, message="done")