flowscript-vm 0.1.0__py3-none-any.whl

flowscript/printer.py

@@ -0,0 +1,225 @@
+"""AST (visual model) -> canonical FlowScript source."""
+
+from .parser import BINARY_LEVELS, COMPARE_OPS
+
+INDENT = "  "
+
+_LEVEL = {}
+for _i, _ops in enumerate(BINARY_LEVELS):
+    if _ops:
+        for _op in _ops:
+            _LEVEL[_op] = _i
+NOT_LEVEL = 3
+UNARY_LEVEL = len(BINARY_LEVELS)
+ATOM_LEVEL = 100
+
+
+def prec(e):
+    t = e["type"]
+    if t == "binary":
+        return _LEVEL[e["op"]]
+    if t == "unary":
+        return NOT_LEVEL if e["op"] == "not" else UNARY_LEVEL
+    if t == "num" and (e["value"] < 0 or str(e["value"]).startswith("-")):
+        return UNARY_LEVEL
+    return ATOM_LEVEL
+
+
+def _quote(s):
+    return '"' + s.replace("\\", "\\\\").replace('"', '\\"').replace("\n", "\\n").replace("\t", "\\t") + '"'
+
+
+def _num_text(e):
+    text = e.get("text")
+    if text:
+        try:
+            from .lexer import tokenize
+            toks = [t for t in tokenize(text.lstrip("-")) if t.kind in ("NUM", "FLOAT")]
+            v = toks[0].value if toks else None
+            if text.startswith("-") and v is not None:
+                v = -v
+            if v == e["value"]:
+                return text
+        except Exception:
+            pass
+    v = e["value"]
+    if isinstance(v, float):
+        r = repr(v)
+        return r if ("e" in r or "." in r or "n" in r) else r + ".0"
+    return str(v)
+
+
+def expr_to_str(e):
+    t = e["type"]
+    if t == "num":
+        return _num_text(e)
+    if t == "bool":
+        return "true" if e["value"] else "false"
+    if t == "str":
+        return _quote(e["value"])
+    if t == "name":
+        return e["name"]
+    if t in ("callx", "call"):
+        return "%s(%s)" % (e["name"], ", ".join(expr_to_str(a) for a in e["args"]))
+    if t == "unary":
+        op = e["op"]
+        inner = e["operand"]
+        s = expr_to_str(inner)
+        need = NOT_LEVEL if op == "not" else UNARY_LEVEL
+        if prec(inner) < need:
+            s = "(" + s + ")"
+        return ("not " + s) if op == "not" else (op + s)
+    if t == "binary":
+        lvl = _LEVEL[e["op"]]
+        ls = expr_to_str(e["left"])
+        rs = expr_to_str(e["right"])
+        lmin = lvl + 1 if e["op"] in COMPARE_OPS else lvl
+        if prec(e["left"]) < lmin:
+            ls = "(" + ls + ")"
+        if prec(e["right"]) <= lvl:
+            rs = "(" + rs + ")"
+        return "%s %s %s" % (ls, e["op"], rs)
+    raise ValueError("unknown expression type %r" % t)
+
+
+class Printer:
+    def __init__(self):
+        self.lines = []
+
+    def emit(self, depth, text):
+        self.lines.append(INDENT * depth + text if text else "")
+
+    def blank(self):
+        if self.lines and self.lines[-1] != "":
+            self.lines.append("")
+
+    def note(self, depth, node):
+        n = node.get("note")
+        if n:
+            for ln in str(n).split("\n"):
+                self.emit(depth, ("# " + ln) if ln else "#")
+
+    @staticmethod
+    def params(ps, types=None):
+        if types:
+            ps = ["%s %s" % (t, p) for t, p in zip(types, ps)]
+        return "(" + ", ".join(ps) + ")"
+
+    @staticmethod
+    def returns(it):
+        return (" -> " + it["returns"]) if it.get("returns") else ""
+
+    @staticmethod
+    def decl(it):
+        v = it.get("value")
+        return "%s %s%s" % (it.get("vtype") or "int", it["name"], (" = " + expr_to_str(v)) if v is not None else "")
+
+    def program(self, prog):
+        for c in prog.get("pre") or []:
+            self.note(0, {"note": c.get("text", "")})
+            self.blank()
+        self.note(0, prog)
+        if prog.get("name"):
+            v = prog.get("version") or 0
+            self.emit(0, "flow %s%s" % (prog["name"], (" version %d" % v) if v else ""))
+        prev = None
+        for item in prog.get("items", []):
+            kind = item["type"]
+            block = kind in ("func", "on", "state", "any_state")
+            if self.lines and (block or prev is None or prev in ("func", "on", "state", "any_state") or prev != kind):
+                self.blank()
+            self.item(0, item)
+            prev = kind
+        return "\n".join(self.lines) + "\n"
+
+    def item(self, d, it):
+        t = it["type"]
+        if t == "comment":
+            self.note(d, {"note": it.get("text", "")})
+            self.blank()
+            return
+        self.note(d, it)
+        if t == "extern":
+            self.emit(d, "extern %s%s%s" % (it["name"], self.params(it.get("params", []), it.get("ptypes")),
+                                            self.returns(it)))
+        elif t == "event":
+            ps = it.get("params") or []
+            self.emit(d, "event %s%s" % (it["name"], self.params(ps, it.get("ptypes")) if ps else ""))
+        elif t == "timer":
+            self.emit(d, "timer %s" % it["name"])
+        elif t == "const":
+            self.emit(d, "const %s = %s" % (it["name"], expr_to_str(it["value"])))
+        elif t == "var":
+            self.emit(d, self.decl(it))
+        elif t == "func":
+            self.emit(d, "func %s%s%s:" % (it["name"], self.params(it.get("params", []), it.get("ptypes")),
+                                          self.returns(it)))
+            self.block(d + 1, it.get("body", []))
+        elif t == "on":
+            ps = it.get("params")
+            self.emit(d, "on %s%s:" % (it["event"], self.params(ps) if ps else ""))
+            self.block(d + 1, it.get("body", []))
+        elif t in ("state", "any_state"):
+            self.emit(d, ("%sstate %s:" % ("initial " if it.get("initial") else "", it["name"]))
+                      if t == "state" else "any_state:")
+            vs = it.get("vars") or []
+            for v in vs:
+                self.item(d + 1, v)
+            hs = it.get("handlers", [])
+            for i, h in enumerate(hs):
+                if i or vs:
+                    self.blank()
+                self.item(d + 1, h)
+            if not vs and not any(h["type"] != "comment" for h in hs):
+                self.emit(d + 1, "pass")
+        else:
+            raise ValueError("unknown item type %r" % t)
+
+    def block(self, d, body):
+        body = body or []
+        for s in body:
+            self.stmt(d, s)
+        if not any(s["type"] != "comment" for s in body):
+            self.emit(d, "pass")
+
+    def stmt(self, d, s):
+        t = s["type"]
+        if t == "comment":
+            self.note(d, {"note": s.get("text", "")})
+            self.blank()
+            return
+        self.note(d, s)
+        if t == "assign":
+            self.emit(d, "%s = %s" % (s["target"], expr_to_str(s["value"])))
+        elif t == "local":
+            self.emit(d, self.decl(s))
+        elif t == "call":
+            self.emit(d, expr_to_str(s))
+        elif t == "if":
+            for i, br in enumerate(s["branches"]):
+                self.emit(d, ("if " if i == 0 else "elif ") + expr_to_str(br["cond"]) + ":")
+                self.block(d + 1, br.get("body", []))
+            if s.get("else_body") is not None:
+                self.emit(d, "else:")
+                self.block(d + 1, s["else_body"])
+        elif t == "while":
+            self.emit(d, "while " + expr_to_str(s["cond"]) + ":")
+            self.block(d + 1, s.get("body", []))
+        elif t == "goto":
+            self.emit(d, "goto_state " + s["state"])
+        elif t == "emit":
+            args = s.get("args") or []
+            self.emit(d, "raise_event %s%s" % (s["event"], ("(" + ", ".join(expr_to_str(a) for a in args) + ")") if args else ""))
+        elif t == "start":
+            self.emit(d, "start %s %s%s" % (s["timer"], "every " if s.get("every") else "", expr_to_str(s["ms"])))
+        elif t == "stop":
+            self.emit(d, "stop " + s["timer"])
+        elif t == "return":
+            v = s.get("value")
+            self.emit(d, "return" + ((" " + expr_to_str(v)) if v is not None else ""))
+        else:
+            raise ValueError("unknown statement type %r" % t)
+
+
+def to_source(prog):
+    return Printer().program(prog)

flowscript/runner.py

@@ -0,0 +1,164 @@
+r"""Scenario runner with a canonical trace format.
+
+The C runner (c/fsrun.c) implements the exact same format; the conformance test
+compares the two traces line by line.
+
+Scenario file (one command per line, '#' comments outside quotes):
+    extern NAME VALUE     set the return value of a stubbed extern (default: zero of its type)
+    post EVENT [ARGS...]  queue an event, then run until idle
+    tick MS               advance timers and the clock, then run until idle
+    clock TIME            set the clock now() reads (YYYY-MM-DDTHH:MM:SS[.mmm]Z or ms; default 0)
+    dump                  print all globals
+    host_timers           (anywhere) the host runs the timers: start/stop requests are
+                          traced and `tick` does nothing
+    fire TIMER            host timers: the host's timer fired, then run until idle
+
+Values are written by type: int 12, float 2.5 (also 1e-07, nan, inf), str "a b\n"
+(quoted, escapes \" \\ \n \t \xNN), time 2026-11-01T12:00:00.000Z (or ms in a scenario).
+
+Trace lines:
+    call NAME(a,b) -> r                             (call NAME(a,b) when it returns nothing)
+    emit NAME(a,b)
+    state NAME
+    fault CODE at PC
+    global[i] = v
+    timer start|every NAME MS / timer stop NAME     (host_timers only)
+    fire NAME ignored                               (timer was stopped meanwhile)
+"""
+
+from .vm import VM, IDLE
+from . import values as V
+
+WS = " \t\n\r\x0b\x0c\x1c\x1d\x1e\x1f"
+
+
+def split_words(line):
+    """Words separated by whitespace; a word starting with '"' runs to the closing quote
+    (backslash escapes the next character). '#' outside quotes starts a comment."""
+    words = []
+    i, n = 0, len(line)
+    while i < n:
+        c = line[i]
+        if c in WS:
+            i += 1
+            continue
+        if c == "#":
+            break
+        j = i
+        if c == '"':
+            j += 1
+            while j < n and line[j] != '"':
+                j += 2 if line[j] == "\\" else 1
+            j = min(j + 1, n)
+        while j < n and line[j] not in WS and line[j] != "#":
+            j += 1
+        words.append(line[i:j])
+        i = j
+    return words
+
+
+def parse_scenario(text):
+    cmds = []
+    for raw in text.splitlines():
+        parts = split_words(raw)
+        if not parts:
+            continue
+        cmds.append((parts[0], parts[1:]))
+    return cmds
+
+
+def show_args(args):
+    return ",".join(V.show(a) for a in args)
+
+
+def run_scenario(prog, scenario_text, out):
+    stubs = {}
+    clock = [0]
+
+    def make_stub(name, ret):
+        def stub(vm, args):
+            if ret == V.NONE_TYPE:
+                out("call %s(%s)" % (name, show_args(args)))
+                return 0
+            r = stubs.get(name, V.zero(ret))
+            out("call %s(%s) -> %s" % (name, show_args(args), V.show(r)))
+            if name in stubs and isinstance(r, V.Str):
+                return r.b              # a host string: the VM copies it into a slot
+            return r
+        return stub
+
+    externs = {e[0]: make_stub(e[0], e[3]) for e in prog.externs}
+    ext_types = {e[0]: e[3] for e in prog.externs}
+
+    def on_emit(vm, name, args):
+        out("emit %s(%s)" % (name, show_args(args)))
+
+    def on_fault(vm, code, pc):
+        out("fault %d at %d" % (code, pc))
+
+    def on_timer(vm, i, start, ms, periodic):
+        name = prog.events[prog.timers[i]][0]
+        if start:
+            out("timer %s %s %d" % ("every" if periodic else "start", name, ms))
+        else:
+            out("timer stop %s" % name)
+
+    cmds = parse_scenario(scenario_text)
+    host_timers = any(c == "host_timers" for c, _a in cmds)
+
+    vm = VM(prog, externs, on_emit=on_emit, on_fault=on_fault,
+            on_timer=on_timer if host_timers else None, clock=lambda vm: clock[0])
+    last_state = [None]
+
+    def run():
+        while True:
+            r = vm.step()
+            if vm.state != last_state[0]:
+                last_state[0] = vm.state
+                out("state %s" % prog.states[vm.state])
+            if r == IDLE:
+                break
+
+    def dump():
+        for i, v in enumerate(vm.globals):
+            out("global[%d] = %s" % (i, V.show(v)))
+
+    vm.start()
+    run()
+    for cmd, args in cmds:
+        if cmd == "extern":
+            t = ext_types.get(args[0])
+            if t is not None and t != V.NONE_TYPE:
+                stubs[args[0]] = V.parse_literal(t, args[1])
+        elif cmd == "post":
+            ev = prog.event_index(args[0])
+            if ev < 0:
+                raise ValueError("unknown event %r" % args[0])
+            ptypes = prog.events[ev][2]
+            vals = [V.parse_literal(t, a) for t, a in zip(ptypes, args[1:])]
+            vm.post(ev, *[v.b if isinstance(v, V.Str) else v for v in vals])
+            run()
+        elif cmd == "tick":
+            ms = int(args[0], 0)
+            if not -2 ** 31 <= ms < 2 ** 31:
+                raise ValueError("tick value out of int32 range")
+            clock[0] = V.wrap64(clock[0] + ms)
+            vm.tick(ms)
+            run()
+        elif cmd == "clock":
+            clock[0] = V.parse_literal(V.TIME, args[0]).ms
+        elif cmd == "dump":
+            dump()
+        elif cmd == "host_timers":
+            pass
+        elif cmd == "fire":
+            idx = vm.timer_index(args[0])
+            if vm.timers[idx][0]:
+                vm.timer_expired(idx)
+            else:
+                out("fire %s ignored" % args[0])
+            run()
+        else:
+            raise ValueError("unknown scenario command %r" % cmd)
+    dump()
+    return vm