ranger-compiler 3.5.0 → 3.5.2

package/dist/lib/evg/EVGTreeJson.rgr

@@ -0,0 +1,721 @@
+; SPDX-License-Identifier: MIT
+
+; ==============================================================================
+; EVGTreeJson — a tree on disk, in exactly the set that can be edited
+; ==============================================================================
+;
+; The display list has had `toJson` for a long time, because a GPU backend and
+; a remote viewer both read it. The TREE never did: it was always built in
+; code, laid out, drawn, and thrown away. An agent editing a document needs it
+; to survive between two processes, so here it is.
+;
+; --- THE FORMAT IS THE PATCHABLE SET ------------------------------------------
+;
+; A node says its tag, its identity, its text, and then `props` — and `props`
+; is exactly `EVGPatch.patchableNames()`, nothing more. That is not a shortcut,
+; it is the invariant worth having: **what can be written down is what can be
+; edited, and what can be edited can be undone.** A property outside that set
+; cannot appear in a file, so no file can carry a value an edit would silently
+; drop.
+;
+; The cost is stated plainly: this is not a lossless container for an arbitrary
+; EVG tree. A `path` element's `d`, an image's `alt`, a viewBox — the engine
+; has them and this format does not. Converting a document INTO this format
+; (from JSX, from a `.fig`) therefore loses what the patchable set does not
+; cover, and a converter has to say so rather than round-trip through here and
+; call it identity.
+;
+; --- ONLY DEFAULTS ARE OMITTED ------------------------------------------------
+;
+; A property is written when it differs from what a FRESH ELEMENT OF THE SAME
+; TAG reads — not from a fixed table of defaults, because a span and a div do
+; not agree about all of them. `EVGPatch.readProp` answers both sides, so the
+; comparison is between two answers from one reader and cannot drift.
+;
+; --- THE READER READS WHAT THIS WRITER WRITES ---------------------------------
+;
+; The scanner below is deliberately not a general JSON parser. It handles the
+; escapes this file emits (quote, backslash, newline, return, tab) and no
+; others, because a general parser here would be a second, unrelated thing to
+; get right and to test. A file from somewhere else is not this format.
+; ==============================================================================
+
+Import "EVGCodepoint.rgr"
+Import "EVGElement.rgr"
+Import "EVGPatch.rgr"
+
+class EVGTreeJson {
+
+    ; --- writing --------------------------------------------------------------
+
+    sfn toText:string (root:EVGElement) {
+        def w (new EVGTreeJson())
+        def out:string "{\"evg\":1"
+        ; The stylesheet first, because it is the document talking about
+        ; itself and a reader opening the file should meet it before the tree.
+        if ((strlen root.documentCss) > 0) {
+            out = ((out + ",\"css\":") + (EVGTreeJson.str(root.documentCss)))
+        }
+        out = (out + ",\"root\":")
+        out = (out + (w.node(root 1)))
+        out = (out + "}")
+        return out
+    } doc {
+        description "Writes a tree as JSON carrying every patchable property that differs from a fresh element."
+        param root "The tree to write."
+        returns "The document text."
+    }
+
+    sfn withCss@(optional):EVGElement (root@(optional):EVGElement css:string) {
+        if (null? root) {
+            return root
+        }
+        if ((strlen css) == 0) {
+            return root
+        }
+        def el:EVGElement (unwrap root)
+        el.documentCss = css
+        def out@(optional):EVGElement el
+        return out
+    }
+
+    fn node:string (el:EVGElement depth:int) {
+        def pad:string (EVGTreeJson.indent(depth))
+        def inner:string (EVGTreeJson.indent((depth + 1)))
+        def out:string "{"
+        out = (((out + "\"tag\":") + (EVGTreeJson.str(el.tagName))))
+        if ((strlen el.id) > 0) {
+            out = (((out + ",\"id\":") + (EVGTreeJson.str(el.id))))
+        }
+        if ((strlen el.key) > 0) {
+            out = (((out + ",\"key\":") + (EVGTreeJson.str(el.key))))
+        }
+        if ((strlen el.textContent) > 0) {
+            out = (((out + ",\"text\":") + (EVGTreeJson.str(el.textContent))))
+        }
+        ; WHAT THE NODE IS, not how it looks. A document that carries a real
+        ; control has to be able to say so: without this a switch is a pill
+        ; with a knob in it, indistinguishable from one somebody drew, and
+        ; everything reading the document afterwards — the accessibility tree,
+        ; the layout check that names drawn controls — has to guess.
+        if ((strlen el.role) > 0) {
+            out = (((out + ",\"role\":") + (EVGTreeJson.str(el.role))))
+        }
+        if ((strlen el.a11yLabel) > 0) {
+            out = (((out + ",\"label\":") + (EVGTreeJson.str(el.a11yLabel))))
+        }
+        if (el.a11yHidden) {
+            out = (out + ",\"hidden\":true")
+        }
+        ; 0 not applicable, 1 no, 2 yes — the tri-state a checkbox needs.
+        if (el.a11yChecked > 0) {
+            out = ((out + ",\"checked\":") + (to_string el.a11yChecked))
+        }
+        def props:string (this.props(el))
+        if ((strlen props) > 0) {
+            out = ((((out + ",\"props\":{") + props) + "}"))
+        }
+        def n:int (array_length el.children)
+        if (n > 0) {
+            out = (out + ",\"children\":[")
+            def i:int 0
+            while (i < n) {
+                if (i > 0) {
+                    out = (out + ",")
+                }
+                out = (out + "\n")
+                out = (out + inner)
+                def kid:EVGElement (itemAt el.children i)
+                out = (out + (this.node(kid (depth + 1))))
+                i = (i + 1)
+            }
+            out = (out + "\n")
+            out = (out + pad)
+            out = (out + "]")
+        }
+        out = (out + "}")
+        return out
+    }
+
+    ; What this node says that a fresh one of its tag does not.
+    fn props:string (el:EVGElement) {
+        def fresh@(optional):EVGElement (EVGPatch.create(el.tagName))
+        if (null? fresh) {
+            return ""
+        }
+        def blank:EVGElement (unwrap fresh)
+        def names:[string] (EVGPatch.patchableNames())
+        def out:string ""
+        def wrote:int 0
+        def i:int 0
+        while (i < (array_length names)) {
+            def name:string (itemAt names i)
+            def mine:string (EVGPatch.readProp(el name))
+            def theirs:string (EVGPatch.readProp(blank name))
+            ; A value the sheet put there belongs to the sheet. Writing it
+            ; down as well would copy the rule onto every node it matched and
+            ; leave the document saying the same thing twice.
+            if ((mine != theirs) && ((el.fromCss(name)) == false)) {
+                if (wrote > 0) {
+                    out = (out + ",")
+                }
+                out = (out + (EVGTreeJson.str(name)))
+                out = (out + ":")
+                out = (out + (EVGTreeJson.str(mine)))
+                wrote = (wrote + 1)
+            }
+            i = (i + 1)
+        }
+        ; `evg-fx-*` is a family, not a list: the names belong to whichever
+        ; plugin reads them, so `patchableNames` cannot carry them and this
+        ; asks the element what it has. A fresh element has none, so anything
+        ; here is by definition something the document must say.
+        def fx:[string] (EVGPatch.fxNamesOf(el))
+        def k:int 0
+        while (k < (array_length fx)) {
+            def fxName:string (itemAt fx k)
+            if (el.fromCss(fxName)) {
+                k = (k + 1)
+            } {
+            if (wrote > 0) {
+                out = (out + ",")
+            }
+            out = (out + (EVGTreeJson.str(fxName)))
+            out = (out + ":")
+            out = (out + (EVGTreeJson.str((EVGPatch.readProp(el fxName)))))
+            wrote = (wrote + 1)
+            k = (k + 1)
+            }
+        }
+        return out
+    }
+
+    sfn indent:string (depth:int) {
+        def s:string ""
+        def i:int 0
+        while (i < depth) {
+            s = (s + "  ")
+            i = (i + 1)
+        }
+        return s
+    }
+
+    ; Quote, backslash and the three control characters a document actually
+    ; contains. Everything else goes out as it came in — UTF-8 is valid JSON.
+    sfn str:string (v:string) {
+        def out:string "\""
+        def i:int 0
+        def n:int (strlen v)
+        while (i < n) {
+            def c:int (charAt v i)
+            if (c == 34) {
+                out = (out + "\\\"")
+            } {
+                if (c == 92) {
+                    out = (out + "\\\\")
+                } {
+                    if (c == 10) {
+                        out = (out + "\\n")
+                    } {
+                        if (c == 13) {
+                            out = (out + "\\r")
+                        } {
+                            if (c == 9) {
+                                out = (out + "\\t")
+                            } {
+                                out = (out + (substring v i (i + 1)))
+                            }
+                        }
+                    }
+                }
+            }
+            i = (i + 1)
+        }
+        return (out + "\"")
+    }
+
+
+    ; One node, without its subtree — what `query` answers with.
+    ;
+    ; `EVGInspect.nodeJson` exists and is NOT what to use here. It reports
+    ; every computed property including the resolved pixels, which is right for
+    ; an inspector looking at a laid-out frame and wrong for a query: nothing
+    ; has run layout, so it would report `padding-left: 0.00px` for a document
+    ; that plainly says 16px. This answers with what the document says.
+    sfn brief:string (path:string el:EVGElement) {
+        def w (new EVGTreeJson())
+        def out:string "{\"at\":"
+        out = (out + (EVGTreeJson.str(path)))
+        out = ((out + ",\"tag\":") + (EVGTreeJson.str(el.tagName)))
+        if ((strlen el.id) > 0) {
+            out = ((out + ",\"id\":") + (EVGTreeJson.str(el.id)))
+        }
+        if ((strlen el.key) > 0) {
+            out = ((out + ",\"key\":") + (EVGTreeJson.str(el.key)))
+        }
+        if ((strlen el.textContent) > 0) {
+            out = ((out + ",\"text\":") + (EVGTreeJson.str(el.textContent)))
+        }
+        def props:string (w.props(el))
+        if ((strlen props) > 0) {
+            out = (((out + ",\"props\":{") + props) + "}")
+        }
+        out = ((out + ",\"children\":") + (to_string (array_length el.children)))
+        return (out + "}")
+    }
+
+    ; --- reading --------------------------------------------------------------
+
+    sfn fromText@(optional):EVGElement (text:string) {
+        def c (new EVGJsonCursor())
+        c.src = text
+        c.at = 0
+        c.skipWs()
+        if ((c.take()) != 123) {
+            def bad@(optional):EVGElement
+            return bad
+        }
+        def root@(optional):EVGElement
+        ; `css` may be written before or after `root`, so it is held until the
+        ; object closes rather than assumed to arrive second.
+        def css:string ""
+        def guard:int 0
+        while ((c.ok) && (guard < 64)) {
+            c.skipWs()
+            def ch:int (c.peek())
+            if (ch == 125) {
+                def closing:int (c.take())
+                return (EVGTreeJson.withCss(root css))
+            }
+            if (ch == 44) {
+                def comma:int (c.take())
+            } {
+                def key:string (c.readString())
+                c.skipWs()
+                def colon:int (c.take())
+                if (key == "root") {
+                    root = (c.readNode())
+                } {
+                    if (key == "css") {
+                        css = (c.readString())
+                    } {
+                        c.skipValue()
+                    }
+                }
+            }
+            guard = (guard + 1)
+        }
+        return (EVGTreeJson.withCss(root css))
+    } doc {
+        description "Reads a tree back from the format `write` produces."
+        param text "The document text."
+        returns "The root element, or nothing when the text is not this format."
+    }
+}
+
+; A scanner over one document. `ok` goes false at the first thing the format
+; does not allow and never goes back: a half-read tree is not a tree, and the
+; caller gets nothing rather than something plausible.
+class EVGJsonCursor {
+    def src:string ""
+    def at:int 0
+    def ok:boolean true
+
+    Constructor () {}
+
+    fn peek:int () {
+        if (at >= (strlen src)) {
+            return 0
+        }
+        return (charAt src at)
+    }
+
+    fn take:int () {
+        def c:int (this.peek())
+        at = (at + 1)
+        return c
+    }
+
+    fn skipWs:void () {
+        while (at < (strlen src)) {
+            def c:int (charAt src at)
+            if ((((c == 32) || (c == 10)) || (c == 13)) || (c == 9)) {
+                at = (at + 1)
+            } {
+                return
+            }
+        }
+    }
+
+    fn readString:string () {
+        this.skipWs()
+        if ((this.peek()) != 34) {
+            ok = false
+            return ""
+        }
+        def opening:int (this.take())
+        def out:string ""
+        while (at < (strlen src)) {
+            def c:int (this.take())
+            if (c == 34) {
+                return out
+            }
+            if (c == 92) {
+                def e:int (this.take())
+                if (e == 110) {
+                    out = (out + "\n")
+                } {
+                    if (e == 114) {
+                        out = (out + "\r")
+                    } {
+                        if (e == 116) {
+                            out = (out + "\t")
+                        } {
+                            ; \uXXXX. Without this the backslash was dropped
+                            ; and the four hex digits were read as text, so a
+                            ; `\u00b7` written by an agent reached the screen
+                            ; as the literal `u00b7` — which is exactly what it
+                            ; looked like, and reads as a broken font rather
+                            ; than a broken parser.
+                            if (e == 117) {
+                                out = (out + (this.readEscape()))
+                            } {
+                                out = (out + (substring src (at - 1) at))
+                            }
+                        }
+                    }
+                }
+            } {
+                out = (out + (substring src (at - 1) at))
+            }
+        }
+        ok = false
+        return out
+    }
+
+
+    ; One `\uXXXX`, already past the `u`, as the character it names. A high
+    ; surrogate takes the `\uXXXX` after it as its pair, because that is how
+    ; JSON writes anything above U+FFFF — every emoji, among other things — and
+    ; half a pair is not a character.
+    fn readEscape:string () {
+        def cp:int (this.hex4())
+        if (cp < 0) {
+            return "u"
+        }
+        if (EVGCodepoint.isHighSurrogate(cp)) {
+            def save:int at
+            if ((at + 1) < (strlen src)) {
+                if ((charAt src at) == 92) {
+                    if ((charAt src (at + 1)) == 117) {
+                        at = (at + 2)
+                        def lo:int (this.hex4())
+                        if (EVGCodepoint.isLowSurrogate(lo)) {
+                            cp = (65536 + ((((cp - 55296) * 1024)) + (lo - 56320)))
+                        } {
+                            at = save
+                        }
+                    }
+                }
+            }
+        }
+        return (EVGCodepoint.toStr(cp))
+    }
+
+    ; Four hex digits, or -1 when they are not there. `at` only moves when all
+    ; four were read, so a malformed escape is left exactly as written.
+    fn hex4:int () {
+        if ((at + 4) > (strlen src)) {
+            return (0 - 1)
+        }
+        def out:int 0
+        def i:int 0
+        while (i < 4) {
+            def d:int (EVGJsonCursor.hexDigit((charAt src (at + i))))
+            if (d < 0) {
+                return (0 - 1)
+            }
+            out = ((out * 16) + d)
+            i = (i + 1)
+        }
+        at = (at + 4)
+        return out
+    }
+
+    sfn hexDigit:int (c:int) {
+        if ((c >= 48) && (c <= 57)) {
+            return (c - 48)
+        }
+        if ((c >= 97) && (c <= 102)) {
+            return ((c - 97) + 10)
+        }
+        if ((c >= 65) && (c <= 70)) {
+            return ((c - 65) + 10)
+        }
+        return (0 - 1)
+    }
+
+    ; Numbers appear in an ops file (`index`), never in a document, so this is
+    ; small on purpose: an optional minus and digits.
+    ; `true` or `false`; anything else is stepped over and answers false.
+    fn readBool:boolean () {
+        this.skipWs()
+        if ((this.peek()) == 116) {
+            def i:int 0
+            while (i < 4) {
+                def taken:int (this.take())
+                i = (i + 1)
+            }
+            return true
+        }
+        this.skipValue()
+        return false
+    }
+
+    fn readNumber:int () {
+        this.skipWs()
+        def neg:boolean false
+        if ((this.peek()) == 45) {
+            neg = true
+            at = (at + 1)
+        }
+        def v:int 0
+        def digits:int 0
+        while (at < (strlen src)) {
+            def c:int (this.peek())
+            if ((c >= 48) && (c <= 57)) {
+                v = ((v * 10) + (c - 48))
+                digits = (digits + 1)
+                at = (at + 1)
+            } {
+                if (digits == 0) {
+                    ok = false
+                }
+                if neg {
+                    return (0 - v)
+                }
+                return v
+            }
+        }
+        if (digits == 0) {
+            ok = false
+        }
+        if neg {
+            return (0 - v)
+        }
+        return v
+    }
+
+    ; Enough to step over a value this format does not use — a number, a
+    ; boolean, null, or a nested object or array.
+    fn skipValue:void () {
+        this.skipWs()
+        def c:int (this.peek())
+        if (c == 34) {
+            def ignored:string (this.readString())
+            return
+        }
+        if ((c == 123) || (c == 91)) {
+            def depth:int 0
+            while (at < (strlen src)) {
+                def d:int (this.take())
+                if ((d == 123) || (d == 91)) {
+                    depth = (depth + 1)
+                }
+                if ((d == 125) || (d == 93)) {
+                    depth = (depth - 1)
+                    if (depth == 0) {
+                        return
+                    }
+                }
+                if (d == 34) {
+                    at = (at - 1)
+                    def inner:string (this.readString())
+                }
+            }
+            ok = false
+            return
+        }
+        while (at < (strlen src)) {
+            def e:int (this.peek())
+            if ((((e == 44) || (e == 125)) || (e == 93)) || (e == 32)) {
+                return
+            }
+            at = (at + 1)
+        }
+    }
+
+    fn readNode@(optional):EVGElement () {
+        this.skipWs()
+        if ((this.take()) != 123) {
+            ok = false
+            def bad@(optional):EVGElement
+            return bad
+        }
+        ; The tag decides which element to make, and it is not guaranteed to
+        ; come first, so the node is read into locals and built at the end.
+        def tag:string "div"
+        def id:string ""
+        def key:string ""
+        def text:string ""
+        ; What the node IS, read back the way it was written.
+        def role:string ""
+        def label:string ""
+        def hidden:boolean false
+        def checked:int 0
+        def propNames:[string]
+        def propValues:[string]
+        def kids:[EVGElement]
+
+        while (ok) {
+            this.skipWs()
+            def ch:int (this.peek())
+            if (ch == 125) {
+                def closing:int (this.take())
+                def made@(optional):EVGElement (EVGPatch.create(tag))
+                if (null? made) {
+                    ok = false
+                    def none@(optional):EVGElement
+                    return none
+                }
+                def el:EVGElement (unwrap made)
+                el.id = id
+                el.key = key
+                el.textContent = text
+                el.role = role
+                el.a11yLabel = label
+                el.a11yHidden = hidden
+                el.a11yChecked = checked
+                def i:int 0
+                while (i < (array_length propNames)) {
+                    def pn:string (itemAt propNames i)
+                    def pv:string (itemAt propValues i)
+                    el.setAttribute(pn pv)
+                    el.markInline(pn)
+                    i = (i + 1)
+                }
+                def k:int 0
+                while (k < (array_length kids)) {
+                    el.addChild((itemAt kids k))
+                    k = (k + 1)
+                }
+                def out@(optional):EVGElement el
+                return out
+            }
+            if (ch == 44) {
+                def comma:int (this.take())
+            } {
+                if (ch == 0) {
+                    ok = false
+                } {
+                    def field:string (this.readString())
+                    this.skipWs()
+                    def colon:int (this.take())
+                    if (field == "tag") {
+                        tag = (this.readString())
+                    } {
+                        if (field == "id") {
+                            id = (this.readString())
+                        } {
+                            if (field == "key") {
+                                key = (this.readString())
+                            } {
+                                if (field == "text") {
+                                    text = (this.readString())
+                                } {
+                                  if (field == "role") {
+                                    role = (this.readString())
+                                  } {
+                                  if (field == "label") {
+                                    label = (this.readString())
+                                  } {
+                                  if (field == "hidden") {
+                                    hidden = (this.readBool())
+                                  } {
+                                  if (field == "checked") {
+                                    checked = (this.readNumber())
+                                  } {
+                                    if (field == "props") {
+                                        this.readProps(propNames propValues)
+                                    } {
+                                        if (field == "children") {
+                                            this.readChildren(kids)
+                                        } {
+                                            this.skipValue()
+                                        }
+                                    }
+                                  }
+                                  }
+                                  }
+                                  }
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+        }
+        def failed@(optional):EVGElement
+        return failed
+    }
+
+    fn readProps:void (names:[string] values:[string]) {
+        this.skipWs()
+        if ((this.take()) != 123) {
+            ok = false
+            return
+        }
+        while (ok) {
+            this.skipWs()
+            def ch:int (this.peek())
+            if (ch == 125) {
+                def closing:int (this.take())
+                return
+            }
+            if (ch == 44) {
+                def comma:int (this.take())
+            } {
+                if (ch == 0) {
+                    ok = false
+                    return
+                }
+                def name:string (this.readString())
+                this.skipWs()
+                def colon:int (this.take())
+                def value:string (this.readString())
+                push names name
+                push values value
+            }
+        }
+    }
+
+    fn readChildren:void (kids:[EVGElement]) {
+        this.skipWs()
+        if ((this.take()) != 91) {
+            ok = false
+            return
+        }
+        while (ok) {
+            this.skipWs()
+            def ch:int (this.peek())
+            if (ch == 93) {
+                def closing:int (this.take())
+                return
+            }
+            if (ch == 44) {
+                def comma:int (this.take())
+            } {
+                if (ch == 0) {
+                    ok = false
+                    return
+                }
+                def kid@(optional):EVGElement (this.readNode())
+                if (null? kid) {
+                    ok = false
+                    return
+                }
+                push kids (unwrap kid)
+            }
+        }
+    }
+}