flowscript-vm 0.1.0__py3-none-any.whl

flowscript/debugger/static/style.css

@@ -0,0 +1,216 @@
+:root {
+  --bg: #15181e; --bg2: #1c2028; --bg3: #252a34; --line: #303643; --fg: #d7dce5; --muted: #7d8696;
+  --accent: #5aa9ff; --cur: #ffcc4d; --cur-bg: rgba(255, 204, 77, .16); --stmt-bg: rgba(90, 169, 255, .09);
+  --ok: #4fd18b; --bad: #ff6b6b; --warn: #ffb454; --kw: #c792ea; --num: #f78c6c; --str: #c3e88d;
+  --cmt: #697386; --fn: #82aaff; --ev: #ffcb6b;
+  --n-proc: #2b3a55; --n-io: #2f4a3a; --n-sub: #3b3357; --n-dec: #4a3b22; --n-goto: #5a2c3a;
+  --n-emit: #2a4b55; --n-timer: #3d4423; --n-ret: #3a3a3a; --n-ev: #55401f; --n-note: #2a2d33;
+  --mono: ui-monospace, "SF Mono", Menlo, Consolas, monospace;
+}
+* { box-sizing: border-box; }
+html, body { margin: 0; height: 100%; background: var(--bg); color: var(--fg);
+  font: 13px/1.4 -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; }
+body { display: flex; flex-direction: column; overflow: hidden; }
+button, select, input { font: inherit; color: var(--fg); background: var(--bg3); border: 1px solid var(--line);
+  border-radius: 5px; padding: 3px 8px; }
+button { cursor: pointer; white-space: nowrap; }
+button:hover { border-color: var(--accent); }
+button.primary { background: #1f4e86; border-color: #2f6db5; }
+button.small { padding: 1px 6px; font-size: 11px; }
+button:disabled { opacity: .45; cursor: default; }
+input:focus, select:focus, textarea:focus { outline: 1px solid var(--accent); }
+.muted { color: var(--muted); font-weight: normal; }
+.hidden { display: none !important; }
+.chk { display: inline-flex; align-items: center; gap: 3px; color: var(--muted); font-size: 12px; }
+
+#toolbar { display: flex; flex-wrap: wrap; gap: 6px 14px; align-items: center; padding: 6px 10px;
+  background: var(--bg2); border-bottom: 1px solid var(--line); }
+#toolbar .group { display: flex; gap: 4px; align-items: center; }
+.brand { font-weight: 600; letter-spacing: .3px; }
+.logo { color: var(--accent); }
+.status { margin-left: auto; font-family: var(--mono); font-size: 12px; padding: 2px 8px; border-radius: 4px; }
+.status.ok { color: var(--ok); } .status.bad { color: var(--bad); } .status.run { color: var(--cur); }
+
+#views { flex: 1; display: grid; grid-template-columns: 1fr 5px .8fr 5px 1.4fr; min-height: 0; }
+.splitter { background: var(--line); cursor: col-resize; }
+.splitter:hover { background: var(--accent); }
+.pane { display: flex; flex-direction: column; min-width: 0; min-height: 0; position: relative; }
+.pane-head { display: flex; gap: 10px; align-items: center; padding: 4px 8px; background: var(--bg2);
+  border-bottom: 1px solid var(--line); min-height: 30px; flex-wrap: wrap; }
+.pane-title { font-weight: 600; }
+.seg { display: inline-flex; }
+.seg button { border-radius: 0; margin-left: -1px; padding: 1px 8px; }
+.seg button:first-child { border-radius: 5px 0 0 5px; }
+.seg button:last-child { border-radius: 0 5px 5px 0; }
+.seg button.on { background: #1f4e86; }
+
+/* --- source editor --- */
+.editor { flex: 1; display: flex; overflow: auto; font: 13px/19px var(--mono); position: relative; min-height: 0; }
+.gutter { flex: none; min-width: 46px; padding: 6px 0; text-align: right; color: var(--muted); user-select: none;
+  background: var(--bg2); border-right: 1px solid var(--line); position: sticky; left: 0; z-index: 2; }
+.gutter div { padding: 0 8px 0 16px; height: 19px; cursor: pointer; position: relative; }
+.gutter div.bp::before { content: ""; position: absolute; left: 4px; top: 5px; width: 9px; height: 9px;
+  border-radius: 50%; background: var(--bad); }
+.gutter div.cur { color: var(--cur); font-weight: bold; }
+.gutter div.err { color: var(--bad); }
+.code-wrap { position: relative; flex: 1; min-width: max-content; }
+.code-hl, #code { margin: 0; padding: 6px 10px; font: inherit; white-space: pre; tab-size: 2; border: 0; }
+.code-hl { pointer-events: none; color: var(--fg); min-height: 100%; }
+#code { position: absolute; inset: 0; width: 100%; height: 100%; resize: none; background: transparent;
+  color: transparent; caret-color: var(--fg); overflow: hidden; outline: none; }
+#code::selection { background: rgba(90, 169, 255, .35); }
+.code-hl .ln { display: block; height: 19px; }
+.code-hl .ln.cur { background: var(--cur-bg); box-shadow: inset 3px 0 0 var(--cur); }
+.code-hl .ln.err { background: rgba(255, 107, 107, .15); }
+.code-hl .ln.hov { background: rgba(255, 255, 255, .05); }
+.code-hl .tk-kw { color: var(--kw); } .code-hl .tk-num { color: var(--num); } .code-hl .tk-str { color: var(--str); }
+.code-hl .tk-cmt { color: var(--cmt); font-style: italic; } .code-hl .tk-fn { color: var(--fn); }
+.code-hl .tk-op { color: #89ddff; } .code-hl .tk-ev { color: var(--ev); }
+.code-hl .seg-cur { background: rgba(255, 204, 77, .35); border-radius: 2px; }
+#errors { font-family: var(--mono); font-size: 12px; color: var(--bad); padding: 0 8px; max-height: 80px; overflow: auto; }
+#errors div { padding: 4px 0; cursor: pointer; }
+
+/* --- bytecode --- */
+.bytecode { flex: 1; overflow: auto; font: 12px/18px var(--mono); padding: 4px 0; }
+.bytecode .lbl { color: var(--ev); padding: 8px 8px 2px; font-weight: bold; }
+.bytecode .ins { display: grid; grid-template-columns: 14px 42px 118px 64px 1fr; padding: 0 8px; cursor: default; white-space: nowrap; }
+.bytecode .ins .pcx { color: var(--muted); }
+.bytecode .ins .hex { color: #5f6a7c; overflow: hidden; text-overflow: ellipsis; }
+.bytecode .ins .op { color: var(--kw); }
+.bytecode .ins .arg { color: var(--fg); overflow: hidden; text-overflow: ellipsis; }
+.bytecode .ins .arg i { color: var(--cmt); font-style: normal; }
+.bytecode .ins.stmt { background: var(--stmt-bg); }
+.bytecode .ins.cur { background: var(--cur-bg); box-shadow: inset 3px 0 0 var(--cur); }
+.bytecode .ins.cur .mk::before { content: "▶"; color: var(--cur); }
+.bytecode .ins.hov { background: rgba(255, 255, 255, .06); }
+.bytecode .header { color: var(--muted); padding: 2px 8px 6px; border-bottom: 1px solid var(--line); margin-bottom: 4px; }
+
+/* --- flowchart --- */
+.chart-wrap { flex: 1; overflow: auto; background:
+  radial-gradient(circle, #232833 1px, transparent 1px) 0 0 / 18px 18px; min-height: 0; }
+#chart svg { display: block; }
+#chart text { font: 12px var(--mono); fill: var(--fg); pointer-events: none; }
+#chart .small { font-size: 10px; fill: var(--muted); }
+#chart .lbl-yes { fill: var(--ok); font-size: 10px; } #chart .lbl-no { fill: var(--bad); font-size: 10px; }
+#chart .edge { stroke: #6d7789; stroke-width: 1.4; fill: none; }
+#chart .edge.back { stroke-dasharray: 4 3; }
+#chart .wire { stroke: #8792a5; stroke-width: 1.2; fill: none; }
+#chart .wire.t { stroke: var(--ok); } #chart .wire.f { stroke: var(--bad); }
+#chart .nd { cursor: pointer; }
+#chart .nd > .sh { stroke: #8a94a8; stroke-width: 1.2; }
+#chart .nd:hover > .sh, #chart .nd.hov > .sh { stroke: #fff; }
+#chart .nd.sel > .sh { stroke: var(--accent); stroke-width: 2.5; }
+#chart .nd.cur > .sh { stroke: var(--cur); stroke-width: 3; filter: drop-shadow(0 0 6px rgba(255, 204, 77, .7)); }
+#chart .nd.bp > .sh { stroke-dasharray: 5 2; }
+#chart .bpdot { fill: var(--bad); }
+#chart .k-proc > .sh { fill: var(--n-proc); } #chart .k-io > .sh { fill: var(--n-io); }
+#chart .k-sub > .sh { fill: var(--n-sub); } #chart .k-dec > .sh { fill: var(--n-dec); }
+#chart .k-goto > .sh { fill: var(--n-goto); } #chart .k-emit > .sh { fill: var(--n-emit); }
+#chart .k-timer > .sh { fill: var(--n-timer); } #chart .k-ret > .sh { fill: var(--n-ret); }
+#chart .k-ev > .sh { fill: var(--n-ev); } #chart .k-end > .sh { fill: #444; }
+#chart .k-note > .sh { fill: var(--n-note); stroke-dasharray: 3 2; }
+#chart .k-note text { fill: var(--cmt); font-style: italic; }
+#chart .k-leaf > .sh { fill: #222833; }
+#chart .k-gate > .sh { fill: #2a303c; }
+#chart .t > .sh { fill: #1d4430 !important; stroke: var(--ok); }
+#chart .f > .sh { fill: #4a2228 !important; stroke: var(--bad); }
+#chart .val { font-size: 10px; fill: var(--cur); }
+#chart .note-line { stroke: var(--cmt); stroke-dasharray: 2 3; fill: none; }
+#chart .state-box { fill: rgba(90, 169, 255, .04); stroke: #3d5a80; stroke-width: 1.5; }
+#chart .state-box.cur { stroke: var(--cur); fill: rgba(255, 204, 77, .05); }
+#chart .state-title { font: bold 14px var(--mono); fill: #9ec5ff; }
+#chart .state-box.cur + .state-title { fill: var(--cur); }
+#chart .sec-title { font: bold 13px var(--mono); fill: var(--muted); }
+#chart .decl-box { fill: #1b1f27; stroke: var(--line); }
+#chart .decl-k { fill: var(--kw); } #chart .decl-n { fill: var(--fg); }
+#chart .plus { cursor: pointer; }
+#chart .plus circle { fill: #1f4e86; stroke: var(--accent); }
+#chart .plus text { fill: #fff; font-weight: bold; text-anchor: middle; }
+#chart .plus:hover circle { fill: var(--accent); }
+#chart .sd-state > .sh { fill: #22324a; stroke: #5a7fb0; stroke-width: 2; }
+#chart .sd-state.cur > .sh { fill: #4a3d1a; stroke: var(--cur); stroke-width: 3; }
+#chart .sd-edge { stroke: #8792a5; stroke-width: 1.5; fill: none; }
+#chart .sd-label { font-size: 11px; fill: var(--ev); }
+#chart .initial { fill: var(--fg); }
+#chart .addbtn { cursor: pointer; }
+#chart .addbtn rect { fill: #1f3555; stroke: var(--accent); stroke-dasharray: 3 2; }
+#chart .addbtn text { fill: var(--accent); }
+
+.inspector { position: absolute; right: 10px; top: 40px; width: 330px; max-height: calc(100% - 50px); overflow: auto;
+  background: var(--bg2); border: 1px solid var(--line); border-radius: 8px; padding: 10px; box-shadow: 0 8px 30px rgba(0,0,0,.5); z-index: 5; }
+.inspector h4 { margin: 0 0 8px; display: flex; justify-content: space-between; align-items: center; }
+.inspector label { display: block; color: var(--muted); font-size: 11px; margin: 6px 0 2px; }
+.inspector input[type=text], .inspector textarea, .inspector select { width: 100%; font-family: var(--mono); font-size: 12px;
+  background: var(--bg); border: 1px solid var(--line); border-radius: 4px; color: var(--fg); padding: 4px 6px; }
+.inspector textarea { resize: vertical; min-height: 40px; }
+.inspector .row { display: flex; gap: 4px; flex-wrap: wrap; margin-top: 8px; }
+.inspector .err { color: var(--bad); font-size: 12px; margin-top: 6px; }
+.inspector .hint { color: var(--muted); font-size: 11px; margin-top: 6px; }
+.inspector .danger { border-color: #7a3030; }
+
+.menu { position: fixed; background: var(--bg2); border: 1px solid var(--line); border-radius: 6px; padding: 4px; z-index: 20;
+  box-shadow: 0 8px 24px rgba(0,0,0,.5); min-width: 170px; }
+.menu div { padding: 4px 10px; border-radius: 4px; cursor: pointer; white-space: nowrap; }
+.menu div:hover { background: var(--bg3); }
+.menu div .muted { font-family: var(--mono); font-size: 11px; margin-left: 8px; }
+
+/* --- bottom panels --- */
+#bottom { display: flex; gap: 1px; background: var(--line); border-top: 1px solid var(--line); height: 190px; flex: none; }
+#bottom .panel { background: var(--bg2); padding: 6px 8px; overflow: auto; min-width: 150px; flex: 0 1 220px; }
+#bottom .panel.grow { flex: 1 1 300px; }
+#bottom h3 { margin: 0 0 4px; font-size: 11px; text-transform: uppercase; letter-spacing: .6px; color: var(--muted);
+  display: flex; gap: 8px; align-items: center; }
+.kv { display: grid; grid-template-columns: auto 1fr; gap: 1px 10px; font: 12px/17px var(--mono); }
+.kv .k { color: var(--muted); }
+.kv .v { color: var(--fg); }
+.kv .v.chg { color: var(--cur); }
+.kv input { width: 80px; padding: 0 4px; font: 12px var(--mono); }
+#log { font: 12px/17px var(--mono); }
+#log .call { color: var(--ok); } #log .emit { color: #7fdbff; } #log .state { color: var(--cur); font-weight: bold; }
+#log .fault { color: var(--bad); font-weight: bold; } #log .dispatch { color: var(--ev); } #log .sys { color: var(--muted); }
+#log .post, #log .tick { color: var(--kw); }
+.stackv { font: 12px var(--mono); color: var(--fg); }
+.frame { margin-bottom: 4px; }
+.frame b { color: var(--ev); font-weight: normal; }
+
+/* size view (bytecode pane, "Size" tab) */
+.sizeview { flex: 1; overflow: auto; padding: 4px 10px 16px; font-size: 12px; }
+.sizeview h4 { margin: 14px 0 4px; font-size: 12px; font-weight: 600; }
+.sizeview h4 b { color: var(--accent); margin: 0 6px 0 2px; }
+.sizeview h4 .muted { font-size: 11px; }
+table.sz { border-collapse: collapse; width: 100%; }
+table.sz td { padding: 1px 6px 1px 0; vertical-align: middle; white-space: nowrap; }
+table.sz td:last-child { white-space: normal; }
+table.sz td.n { text-align: right; font-variant-numeric: tabular-nums; width: 1%; }
+table.sz .mono, .sz-flags code { font-family: var(--mono); }
+.sz-bar { display: inline-block; width: 90px; height: 7px; background: var(--bg3); border-radius: 2px; vertical-align: middle; }
+.sz-bar > span { display: block; height: 100%; background: var(--accent); border-radius: 2px; }
+tr.sz-rt { cursor: pointer; }
+tr.sz-rt:hover td { background: var(--bg3); }
+.sz-flags { margin-top: 6px; }
+.sz-flags code { display: block; margin-top: 2px; padding: 4px 6px; background: var(--bg3); border-radius: 4px;
+  white-space: pre-wrap; word-break: break-all; user-select: all; }
+.sz-hints { margin: 2px 0; padding-left: 18px; }
+.sz-hints li { margin: 2px 0; }
+
+/* any_state */
+#chart .any-box { fill: rgba(160, 130, 255, .04); stroke: #7a68b8; stroke-dasharray: 6 4; }
+#chart .any-title { font: bold 14px var(--mono); fill: #c3b5ff; }
+#chart .any-frame { fill: rgba(160, 130, 255, .025); stroke: #7a68b8; stroke-width: 1.5; stroke-dasharray: 6 4; }
+#chart .any-tag { fill: #2c2742; stroke: #7a68b8; }
+#chart text.any-tag-text { font: bold 12px var(--mono); fill: #c3b5ff; }
+/* state x event table (States view) */
+.se-wrap { padding: 4px 16px 24px; font-size: 12px; }
+.se-title { font-weight: 600; margin: 4px 0 6px; }
+.se-table { border-collapse: collapse; }
+.se-table th, .se-table td { border: 1px solid var(--line); padding: 3px 10px; text-align: center; white-space: nowrap; }
+.se-table th { background: var(--bg2); font-family: var(--mono); font-weight: 600; }
+.se-table td.se-ev { text-align: left; font-family: var(--mono); }
+.se-table td.se-own { color: #9ec5ff; cursor: pointer; }
+.se-table td.se-over { background: rgba(255, 204, 77, .08); }
+.se-table td.se-over span { color: var(--cur); font-size: 11px; }
+.se-table td.se-any { color: #c3b5ff; cursor: pointer; }
+.se-table td.se-none { color: var(--muted); }
+.se-table td[data-sel]:hover { background: var(--bg3); }
+.se-table td.sel { outline: 2px solid var(--accent); }
+#errors div.warn { color: var(--cur); }

flowscript/intops.py

@@ -0,0 +1,63 @@
+"""32-bit integer semantics shared by the compiler (constant folding) and the Python VM.
+
+They match the C VM exactly: wrap-around, truncating division, masked shifts.
+"""
+
+
+class DivZero(Exception):
+    pass
+
+
+def wrap(v):
+    v &= 0xFFFFFFFF
+    return v - 0x100000000 if v & 0x80000000 else v
+
+
+def div(a, b):
+    if b == 0:
+        raise DivZero()
+    q = abs(a) // abs(b)
+    return wrap(-q if (a < 0) != (b < 0) else q)
+
+
+def mod(a, b):
+    if b == 0:
+        raise DivZero()
+    return wrap(a - div(a, b) * b)
+
+
+def shl(a, b):
+    return wrap((a & 0xFFFFFFFF) << (b & 31))
+
+
+def shr(a, b):
+    return wrap(a >> (b & 31))
+
+
+BINARY = {
+    "+": lambda a, b: wrap(a + b),
+    "-": lambda a, b: wrap(a - b),
+    "*": lambda a, b: wrap(a * b),
+    "/": div,
+    "%": mod,
+    "&": lambda a, b: wrap(a & b),
+    "|": lambda a, b: wrap(a | b),
+    "^": lambda a, b: wrap(a ^ b),
+    "<<": shl,
+    ">>": shr,
+    "==": lambda a, b: int(a == b),
+    "!=": lambda a, b: int(a != b),
+    "<": lambda a, b: int(a < b),
+    "<=": lambda a, b: int(a <= b),
+    ">": lambda a, b: int(a > b),
+    ">=": lambda a, b: int(a >= b),
+    "and": lambda a, b: int(bool(a) and bool(b)),
+    "or": lambda a, b: int(bool(a) or bool(b)),
+    "xor": lambda a, b: int(bool(a) != bool(b)),
+}
+
+UNARY = {
+    "-": lambda a: wrap(-a),
+    "~": lambda a: wrap(~a),
+    "not": lambda a: int(not a),
+}

flowscript/lexer.py

@@ -0,0 +1,265 @@
+"""FlowScript lexer: source text -> list of tokens."""
+
+KEYWORDS = {
+    "flow", "version", "extern", "event", "timer", "const", "func", "on",
+    "int", "float", "str", "time",
+    "state", "initial", "any_state", "pass", "if", "elif", "else", "while", "goto_state", "raise_event", "start", "every",
+    "stop", "return", "and", "or", "xor", "not", "true", "false",
+}
+
+TYPE_KEYWORDS = ("int", "float", "str", "time")
+
+TIME_UNITS = {"ms": 1, "s": 1000, "min": 60000, "h": 3600000}
+
+# longest first
+OPERATORS = ["->", "<<", ">>", "==", "!=", "<=", ">=", "+", "-", "*", "/", "%", "&", "|",
+             "^", "~", "<", ">", "=", "(", ")", ",", ":"]
+
+
+class FlowError(Exception):
+    def __init__(self, msg, line=0, col=0):
+        super().__init__(msg)
+        self.msg = msg
+        self.line = line
+        self.col = col
+
+    def __str__(self):
+        if self.line:
+            return "line %d:%d: %s" % (self.line, self.col, self.msg)
+        return self.msg
+
+    def to_dict(self):
+        return {"msg": self.msg, "line": self.line, "col": self.col}
+
+
+class Token:
+    __slots__ = ("kind", "value", "line", "col", "text")
+
+    def __init__(self, kind, value, line, col, text=None):
+        self.kind = kind      # NAME KW NUM FLOAT STR OP NEWLINE COMMENT INDENT DEDENT EOF
+        self.value = value
+        self.line = line
+        self.col = col
+        self.text = text      # original spelling (numbers)
+
+    def __repr__(self):
+        return "Token(%s,%r,%d:%d)" % (self.kind, self.value, self.line, self.col)
+
+
+def tokenize(src):
+    """Tokens including INDENT/DEDENT (blocks are delimited by indentation)."""
+    return _layout(*_raw_tokens(src))
+
+
+def _raw_tokens(src):
+    toks = []
+    indents = {}      # line -> indentation width of that line
+    i = 0
+    line = 1
+    col = 1
+    n = len(src)
+
+    def add(kind, value, l, c, text=None):
+        toks.append(Token(kind, value, l, c, text))
+
+    while i < n:
+        ch = src[i]
+        if col == 1:
+            j = i
+            while j < n and src[j] in " \t\r":
+                j += 1
+            if j < n and src[j] != "\n":
+                if "\t" in src[i:j]:
+                    raise FlowError("tab used for indentation; indent with spaces", line, 1)
+                indents[line] = j - i
+        if ch == "\n":
+            add("NEWLINE", None, line, col)
+            i += 1
+            line += 1
+            col = 1
+            continue
+        if ch in " \t\r":
+            i += 1
+            col += 1
+            continue
+        if ch == "#":
+            j = src.find("\n", i)
+            if j < 0:
+                j = n
+            text = src[i + 1:j]
+            if text.startswith(" "):
+                text = text[1:]
+            add("COMMENT", text.rstrip(), line, col)
+            col += j - i
+            i = j
+            continue
+        if ch.isdigit():
+            j = i
+            if src.startswith(("0x", "0X"), i):
+                j = i + 2
+                while j < n and (src[j] in "0123456789abcdefABCDEF_"):
+                    j += 1
+                base = 16
+                digits = src[i + 2:j]
+            elif src.startswith(("0b", "0B"), i):
+                j = i + 2
+                while j < n and src[j] in "01_":
+                    j += 1
+                base = 2
+                digits = src[i + 2:j]
+            else:
+                while j < n and (src[j].isdigit() or src[j] == "_"):
+                    j += 1
+                base = 10
+                digits = src[i:j]
+                # float literal: 1.5, 2.0e-3, 1e6
+                k = j
+                if k + 1 < n and src[k] == "." and src[k + 1].isdigit():
+                    k += 1
+                    while k < n and (src[k].isdigit() or src[k] == "_"):
+                        k += 1
+                if k < n and src[k] in "eE":
+                    m = k + 1
+                    if m < n and src[m] in "+-":
+                        m += 1
+                    if m < n and src[m].isdigit():
+                        k = m
+                        while k < n and src[k].isdigit():
+                            k += 1
+                if k > j:
+                    if k < n and (src[k].isalpha() or src[k] == "_"):
+                        raise FlowError("time units need an integer: write %s as a whole number of ms"
+                                        % src[i:k], line, col)
+                    text = src[i:k]
+                    add("FLOAT", float(text.replace("_", "")), line, col, text)
+                    col += k - i
+                    i = k
+                    continue
+            digits = digits.replace("_", "")
+            if not digits:
+                raise FlowError("malformed number", line, col)
+            value = int(digits, base)
+            # time unit suffix
+            k = j
+            while k < n and (src[k].isalpha() or src[k] == "_" or src[k].isdigit()):
+                k += 1
+            unit = src[j:k]
+            if unit:
+                if base != 10 or unit not in TIME_UNITS:
+                    raise FlowError("bad number suffix '%s' (allowed: ms, s, min, h)" % unit, line, col)
+                value *= TIME_UNITS[unit]
+            text = src[i:k]
+            add("NUM", value, line, col, text)
+            col += k - i
+            i = k
+            continue
+        if ch.isalpha() or ch == "_":
+            j = i
+            while j < n and (src[j].isalnum() or src[j] == "_"):
+                j += 1
+            word = src[i:j]
+            add("KW" if word in KEYWORDS else "NAME", word, line, col)
+            col += j - i
+            i = j
+            continue
+        if ch == '"':
+            j = i + 1
+            out = []
+            while True:
+                if j >= n or src[j] == "\n":
+                    raise FlowError("unterminated string", line, col)
+                c = src[j]
+                if c == '"':
+                    break
+                if c == "\\":
+                    j += 1
+                    esc = src[j] if j < n else ""
+                    out.append({"n": "\n", "t": "\t", '"': '"', "\\": "\\"}.get(esc, esc))
+                else:
+                    out.append(c)
+                j += 1
+            add("STR", "".join(out), line, col)
+            col += j + 1 - i
+            i = j + 1
+            continue
+        for op in OPERATORS:
+            if src.startswith(op, i):
+                add("OP", op, line, col)
+                i += len(op)
+                col += len(op)
+                break
+        else:
+            raise FlowError("unexpected character %r" % ch, line, col)
+    add("NEWLINE", None, line, col)
+    return toks, indents, line, col
+
+
+def _layout(toks, indents, last_line, last_col):
+    """Insert INDENT/DEDENT tokens, Python style.
+
+    Blank and comment-only lines do not open or close blocks. A comment group directly
+    above a code line is placed after that line's INDENT/DEDENT tokens (it becomes the
+    line's note). Other comment groups stay in the innermost block that their own
+    indentation allows.
+    """
+    # split into physical lines (each ends with NEWLINE)
+    lines = []
+    cur = []
+    for t in toks:
+        cur.append(t)
+        if t.kind == "NEWLINE":
+            lines.append(cur)
+            cur = []
+    out = []
+    stack = [0]
+    pending = []
+
+    def dedent_to(width, tok):
+        while stack[-1] > width:
+            stack.pop()
+            out.append(Token("DEDENT", None, tok.line, 1))
+
+    def flush_standalone(group, floor):
+        for ln in group:
+            if ln[0].kind == "COMMENT":
+                dedent_to(max(indents.get(ln[0].line, 0), floor), ln[0])
+            out.extend(ln)
+
+    for ln in lines:
+        first = ln[0]
+        if first.kind in ("NEWLINE", "COMMENT"):
+            pending.append(ln)
+            continue
+        width = indents.get(first.line, 0)
+        # the comment group directly above this line (no blank line between) is its note
+        k = len(pending)
+        while k > 0 and pending[k - 1][0].kind == "COMMENT":
+            k -= 1
+        standalone, note = pending[:k], pending[k:]
+        continuation = first.kind == "KW" and first.value in ("elif", "else")
+        if continuation:
+            standalone, note = pending, []
+        floor = width
+        if continuation:
+            deeper = [w for w in stack if w > width]
+            floor = min(deeper) if deeper else width
+        pending = []
+        if width > stack[-1]:
+            # blank lines / comments between a header and its block belong to the block
+            stack.append(width)
+            out.append(Token("INDENT", None, first.line, 1))
+            flush_standalone(standalone, width)
+        else:
+            flush_standalone(standalone, floor)
+        if width < stack[-1]:
+            dedent_to(width, first)
+            if stack[-1] != width:
+                raise FlowError("indentation does not match any outer block", first.line, width + 1)
+        for nl in note:
+            out.extend(nl)
+        out.extend(ln)
+    end = Token("EOF", None, last_line, last_col)
+    flush_standalone(pending, 0)
+    dedent_to(0, end)
+    out.append(end)
+    return out

flowscript/mermaid.py

@@ -0,0 +1,109 @@
+"""Export the visual model as a Mermaid flowchart (for docs, wikis, PRs)."""
+
+from .printer import expr_to_str
+
+
+def _q(s):
+    return '"' + s.replace('"', "#quot;") + '"'
+
+
+class _M:
+    def __init__(self):
+        self.lines = ["flowchart TD"]
+        self.n = 0
+
+    def node(self, shape, text):
+        self.n += 1
+        nid = "n%d" % self.n
+        l, r = {"proc": ("[", "]"), "io": ("[/", "/]"), "sub": ("[[", "]]"), "dec": ("{", "}"),
+                "term": ("([", "])"), "ev": ("{{", "}}"), "goto": ("((", "))"), "emit": (">", "]")}[shape]
+        self.lines.append("  %s%s%s%s" % (nid, l, _q(text), r))
+        return nid
+
+    def edge(self, a, b, label=None):
+        self.lines.append("  %s -->%s %s" % (a, ("|%s|" % label) if label else "", b))
+
+    def block(self, stmts, prev, funcs, label=None):
+        """Returns list of (node, label) dangling exits."""
+        exits = [(prev, label)]
+        for s in stmts:
+            if s["type"] == "comment":
+                continue
+            entry, outs = self.stmt(s, funcs)
+            for p, lb in exits:
+                self.edge(p, entry, lb)
+            exits = outs
+        return exits
+
+    def stmt(self, s, funcs):
+        t = s["type"]
+        if t == "if":
+            first = None
+            exits = []
+            prev_no = None
+            for br in s["branches"]:
+                d = self.node("dec", expr_to_str(br["cond"]))
+                if prev_no:
+                    self.edge(prev_no, d, "no")
+                first = first or d
+                exits += self.block(br["body"], d, funcs, "yes")
+                prev_no = d
+            if s.get("else_body"):
+                exits += self.block(s["else_body"], prev_no, funcs, "no")
+            else:
+                exits.append((prev_no, "no"))
+            return first, exits
+        if t == "while":
+            d = self.node("dec", "while " + expr_to_str(s["cond"]))
+            for p, lb in self.block(s["body"], d, funcs, "yes"):
+                self.edge(p, d, lb)
+            return d, [(d, "no")]
+        if t == "goto":
+            return self.node("goto", "goto_state " + s["state"]), []
+        if t == "return":
+            return self.node("term", "return" + (" " + expr_to_str(s["value"]) if s.get("value") else "")), []
+        if t == "assign":
+            n = self.node("proc", "%s = %s" % (s["target"], expr_to_str(s["value"])))
+        elif t == "local":
+            n = self.node("proc", "%s %s" % (s.get("vtype") or "int", s["name"]) + (" = " + expr_to_str(s["value"]) if s.get("value") else ""))
+        elif t == "call":
+            n = self.node("sub" if s["name"] in funcs else "io", expr_to_str(s))
+        elif t == "emit":
+            n = self.node("emit", "raise_event " + s["event"])
+        elif t == "start":
+            n = self.node("proc", "start %s %s%s" % (s["timer"], "every " if s.get("every") else "", expr_to_str(s["ms"])))
+        else:
+            n = self.node("proc", "stop " + s["timer"])
+        return n, [(n, None)]
+
+    def routine(self, r, funcs, title):
+        head = self.node("ev" if r["type"] == "on" else "sub", title)
+        exits = self.block(r["body"], head, funcs)
+        if exits:
+            end = self.node("term", "end")
+            for p, lb in exits:
+                self.edge(p, end, lb)
+
+
+def to_mermaid(ast):
+    m = _M()
+    funcs = {i["name"] for i in ast["items"] if i["type"] == "func"}
+    for it in ast["items"]:
+        if it["type"] == "func":
+            params = ", ".join("%s %s" % (t, p) for t, p in zip(it.get("ptypes") or ["int"] * len(it["params"]), it["params"]))
+            m.routine(it, funcs, "func %s(%s)%s" % (it["name"], params, (" -> " + it["returns"]) if it.get("returns") else ""))
+        elif it["type"] == "on":
+            m.routine(it, funcs, "on " + it["event"])
+        elif it["type"] == "any_state":
+            m.lines.append("  subgraph any_state [any_state]")
+            for h in it["handlers"]:
+                if h["type"] == "on":
+                    m.routine(h, funcs, "on " + h["event"])
+            m.lines.append("  end")
+        elif it["type"] == "state":
+            m.lines.append("  subgraph %s [state %s]" % ("s_" + it["name"], it["name"]))
+            for h in it["handlers"]:
+                if h["type"] == "on":
+                    m.routine(h, funcs, "%s: on %s" % (it["name"], h["event"]))
+            m.lines.append("  end")
+    return "\n".join(m.lines) + "\n"