ranger-compiler 3.5.0 → 3.5.2

package/dist/lib/evg/EVGTextEngine.rgr

@@ -0,0 +1,536 @@
+; SPDX-License-Identifier: MIT
+
+; EVGTextEngine.rgr - The one text measurement + line breaking implementation
+;
+; PLAN_CSS_LAYOUT_AND_FONTS.md §8. Layout, PDF paint and raster paint must agree
+; on where text breaks and how wide it is, or a page that looks right in preview
+; prints wrong. Before this module there were four separate wrap implementations:
+;
+;   EVGLayout.estimateLineCount   word-by-word, space width guessed as
+;                                 fontSize * 0.3, family hardcoded "Helvetica"
+;   EVGPDFRenderer.wrapText       whole-candidate-line measurement, real family
+;   EVGTextMeasurer.wrapText      character-by-character accumulation
+;   FontManager.measureText       strlen * fontSize * 0.5 when no face loaded
+;
+; They break lines in different places, so layout computed one line count and
+; paint drew another. This module keeps the PDF algorithm — measuring the whole
+; candidate line so the real space advance is included rather than approximated
+; — and everything else calls into it.
+;
+; The engine does not itself know about fonts: it delegates to an
+; EVGTextMeasurer. What it adds is (a) one algorithm, (b) the actual font family
+; threaded through instead of a hardcoded one, and (c) honesty about whether the
+; measurer can back the families a document asks for.
+
+Import "EVGGrapheme.rgr"
+Import "EVGTextMeasurer.rgr"
+; So that every compiled module a host can attach to has the host measurer
+; and the default registry, without the program importing them itself.
+Import "EVGHostTextMeasurer.rgr"
+
+; One laid-out line. ascent/descent are carried from day one so baseline
+; alignment (§4.1 rule 4) can be added without re-measuring.
+class EVGTextLine {
+    def text:string ""
+    def width:double 0.0
+    def ascent:double 0.0
+    def descent:double 0.0
+    ; True on the first line of every paragraph after the first — the line
+    ; that a `paragraph-spacing` gap goes ABOVE. A wrapped continuation is
+    ; not one: the gap belongs to the break the author typed, not to the
+    ; ones the box made.
+    def startsParagraph:boolean false
+
+    Constructor () {
+        text = ""
+        width = 0.0
+        ascent = 0.0
+        descent = 0.0
+    }
+}
+
+; One cached wrap. A map cannot hold a list directly, so the lines live in a
+; store beside the index and this is what the store holds.
+class EVGWrapEntry {
+    def lines:[EVGTextLine]
+
+    Constructor () {
+    }
+}
+
+class EVGTextEngine {
+    def measurer:EVGTextMeasurer
+    ; When strict, a family the measurer cannot back is a hard error rather
+    ; than a silent fall back to guessed widths. Print pipelines should set it.
+    def strict:boolean false
+    ; Families already reported, so one missing face does not produce one
+    ; warning per text node.
+    def reported:[string]
+    def warnings:[string]
+    ; Set once a strict violation has been seen, so callers can fail the run.
+    def hadFatal:boolean false
+
+    ; --- THE WRAP CACHE -------------------------------------------------------
+    ;
+    ; A SCROLL LAYS THE WHOLE TREE OUT AGAIN. The offset moved, so every box is
+    ; measured and every paragraph is broken into lines again — and not one
+    ; character of the text changed. In a profile of `gallery/realtrainer`
+    ; scrolling a real training diary, `breakLines` was over half of the frame
+    ; and every wrap in it produced the answer it had produced on the frame
+    ; before.
+    ;
+    ; A wrap is a pure function of five things: the text, the family, the size,
+    ; the width it is wrapped into, and what the measurer would say. The first
+    ; four are the arguments; the fifth is `measurer.measureKey()`, which is
+    ; how a measurer that loads a face or is switched to bold mid-run says that
+    ; its answers have changed — see `EVGTextMeasurer.measureKey`.
+    ;
+    ; It is a CACHE and not a memo table: it is dropped whole when it grows
+    ; past a bound, because a document that is edited produces a new key for
+    ; every keystroke and nothing would ever evict them. Dropping everything is
+    ; the cheapest eviction there is and the next frame refills what it uses.
+    ;
+    ; What comes back is SHARED. Two callers asking for the same wrap get the
+    ; same `EVGTextLine` objects, so the lines are to be read and not written
+    ; to; every caller in the tree derives a count, a width or the strings and
+    ; leaves them alone.
+    def wrapIndex:[string:int]
+    def wrapStore:[EVGWrapEntry]
+    ; The same for whole-string metrics, which `EVGLayout` asks for once per
+    ; text node per frame and `InputCtl` asks for once per character of the
+    ; string in front of the caret.
+    def runIndex:[string:int]
+    def runStore:[EVGTextMetrics]
+
+    ; The last key's PREFIX, and the fields it was built from.
+    ;
+    ; Everything in a cache key except the text is the same from one call to
+    ; the next almost every time — a paragraph is measured word by word in one
+    ; face at one size — and building it was costing more than the lookup it
+    ; is for: two doubles turned into strings and six joins, per word. Five
+    ; comparisons and one join instead.
+    def keyPrefix:string ""
+    def keyKind:string ""
+    def keyFamily:string ""
+    def keySize:double -1.0
+    def keyMax:double -1.0
+    def keyMeasure:string ""
+
+    ; Starts on the heuristic measurer so the engine is always usable; callers
+    ; that care about print correctness install a real one via setMeasurer and
+    ; turn on strict mode.
+    Constructor () {
+        def m:EVGTextMeasurer (EVGDefaultMeasurer.measurer())
+        measurer = m
+        strict = false
+        hadFatal = false
+    }
+
+    ; A different measurer measures differently, so nothing measured by the
+    ; old one may survive it.
+    fn setMeasurer:void (m:EVGTextMeasurer) {
+        measurer = m
+        this.clearCache()
+    }
+
+    ; Drop everything measured so far. Called when the measurer is replaced,
+    ; and when the cache has grown past the bound below; a caller that knows
+    ; its measurer has changed underneath it in a way `measureKey` does not
+    ; report may also call it.
+    fn clearCache:void () {
+        def wi:[string:int]
+        wrapIndex = wi
+        def ws:[EVGWrapEntry]
+        wrapStore = ws
+        def ri:[string:int]
+        runIndex = ri
+        def rs:[EVGTextMetrics]
+        runStore = rs
+    }
+
+    ; The slack a line is allowed over the width it is being broken into: a
+    ; millionth of a pixel, which is a hundred million times the error a
+    ; shrink-wrap round trip introduces and a millionth of the smallest thing
+    ; anyone can see.
+    sfn fitEpsilon:double () {
+        return 0.000001
+    }
+
+    ; How many wraps and how many metrics are kept before the lot is dropped.
+    ; A page of text is a few hundred distinct strings; this is room for a
+    ; document's worth of them at several widths without ever growing without
+    ; bound.
+    sfn cacheLimit:int () {
+        return 4096
+    }
+
+    ; Everything about a measurement that is not the text: the size, the width
+    ; it is wrapped into, what the measurer would say, and the family. The TEXT
+    ; GOES LAST because it is the one field that can contain the separator.
+    fn cacheKey:string (kind:string fontFamily:string fontSize:double maxWidth:double text:string) {
+        ; `measureKey` is asked every time on purpose: it is what a face
+        ; loaded after something was measured changes, and a prefix that
+        ; remembered it would hand back keys the new face has made stale.
+        def mk:string (measurer.measureKey())
+        def same:boolean true
+        if (kind != keyKind) { same = false }
+        if (fontFamily != keyFamily) { same = false }
+        if (fontSize != keySize) { same = false }
+        if (maxWidth != keyMax) { same = false }
+        if (mk != keyMeasure) { same = false }
+        if (! same) {
+            keyKind = kind
+            keyFamily = fontFamily
+            keySize = fontSize
+            keyMax = maxWidth
+            keyMeasure = mk
+            keyPrefix = (kind + "\n" + (to_string fontSize) + "\n" + (to_string maxWidth)
+                + "\n" + mk + "\n" + fontFamily + "\n")
+        }
+        return (keyPrefix + text)
+    }
+
+    fn setStrict:void (s:boolean) {
+        strict = s
+    }
+
+    fn warningCount:int () {
+        return (array_length warnings)
+    }
+
+    fn warningAt:string (i:int) {
+        return (itemAt warnings i)
+    }
+
+    ; -----------------------------------------------------------------------
+    ; Font honesty
+    ; -----------------------------------------------------------------------
+
+    ; Record (once per family) that this family cannot be measured from a real
+    ; face. In strict mode this also marks the run as failed.
+    fn noteFamily:void (fontFamily:string) {
+        def i:int 0
+        while (i < (array_length reported)) {
+            if ((itemAt reported i) == fontFamily) {
+                return
+            }
+            i = (i + 1)
+        }
+        push reported fontFamily
+
+        if ((measurer.isFontAccurate()) == false) {
+            push warnings ("No font metrics available for \"" + fontFamily
+                + "\" - measuring with heuristic widths. Print layout will not match paint.")
+            if strict {
+                hadFatal = true
+            }
+            return
+        }
+        if ((measurer.hasFace(fontFamily)) == false) {
+            push warnings ("Font face not loaded: \"" + fontFamily
+                + "\" - falling back to another face. Widths will not match paint.")
+            if strict {
+                hadFatal = true
+            }
+        }
+    }
+
+    fn checkFamily:void (fontFamily:string) {
+        if ((measurer.isFontAccurate()) == false) {
+            this.noteFamily(fontFamily)
+            return
+        }
+        if ((measurer.hasFace(fontFamily)) == false) {
+            this.noteFamily(fontFamily)
+        }
+    }
+
+    ; -----------------------------------------------------------------------
+    ; §8 contract
+    ; -----------------------------------------------------------------------
+
+    fn measureRunSpaced:EVGTextMetrics (text:string fontFamily:string fontSize:double spacing:double) {
+        def m:EVGTextMetrics (this.measureRun(text fontFamily fontSize))
+        if (spacing == 0.0) {
+            return m
+        }
+        def wider (new EVGTextMetrics())
+        wider.width = (m.width + (EVGTextEngine.trackingWidth(text spacing)))
+        wider.height = m.height
+        wider.ascent = m.ascent
+        wider.descent = m.descent
+        wider.lineHeight = m.lineHeight
+        return wider
+    }
+
+    fn measureRun:EVGTextMetrics (text:string fontFamily:string fontSize:double) {
+        ; Before the cache, and not inside it: the font warnings are counted
+        ; per family and reported once, and a second frame must not be quieter
+        ; than the first because the first one filled a cache.
+        this.checkFamily(fontFamily)
+        def key:string (this.cacheKey("m" fontFamily fontSize 0.0 text))
+        def hit@(optional):int (get runIndex key)
+        if (null? hit) {
+            def m:EVGTextMetrics (measurer.measureText(text fontFamily fontSize))
+            if ((array_length runStore) >= (EVGTextEngine.cacheLimit())) {
+                this.clearCache()
+            }
+            push runStore m
+            set runIndex key ((array_length runStore) - 1)
+            return m
+        }
+        return (itemAt runStore (unwrap hit))
+    }
+
+    fn lineHeightFor:double (fontFamily:string fontSize:double) {
+        return (measurer.getLineHeight(fontFamily fontSize))
+    }
+
+    ; Greedy word wrap. Honours explicit newlines, and measures each CANDIDATE
+    ; LINE whole rather than summing word widths plus a guessed space — that is
+    ; what makes the result identical to what the paint side draws.
+    ;
+    ; maxWidth <= 0 means "do not wrap": each newline-separated paragraph
+    ; becomes exactly one line.
+    fn breakLines:[EVGTextLine] (text:string fontFamily:string fontSize:double maxWidth:double) {
+        return (this.breakLinesSpaced(text fontFamily fontSize maxWidth 0.0))
+    }
+
+    ; The same wrap with `letter-spacing` in it. Zero is the call above and
+    ; the same cache entry, so a caller that has no tracking pays nothing
+    ; and cannot be moved by this.
+    fn breakLinesSpaced:[EVGTextLine] (text:string fontFamily:string fontSize:double maxWidth:double spacing:double) {
+        this.checkFamily(fontFamily)
+        def key:string (this.cacheKey("w" fontFamily fontSize maxWidth text))
+        if (spacing != 0.0) {
+            key = ((key + "|ls") + (to_string spacing))
+        }
+        def hit@(optional):int (get wrapIndex key)
+        if (null? hit) {
+            def fresh:[EVGTextLine] (this.wrapUncached(text fontFamily fontSize maxWidth spacing))
+            if ((array_length wrapStore) >= (EVGTextEngine.cacheLimit())) {
+                this.clearCache()
+            }
+            def entry (new EVGWrapEntry())
+            entry.lines = fresh
+            push wrapStore entry
+            set wrapIndex key ((array_length wrapStore) - 1)
+            return fresh
+        }
+        def kept:EVGWrapEntry (itemAt wrapStore (unwrap hit))
+        return kept.lines
+    }
+
+    ; The wrap itself, with no cache in front of it.
+    fn wrapUncached:[EVGTextLine] (text:string fontFamily:string fontSize:double maxWidth:double spacing:double) {
+        def out:[EVGTextLine]
+
+        def paragraphs:[string] (strsplit text "\n")
+        def p:int 0
+        while (p < (array_length paragraphs)) {
+            def para:string (itemAt paragraphs p)
+            def firstOfPara:int (array_length out)
+            if (maxWidth <= 0.0) {
+                push out (this.measuredLineSpaced(para fontFamily fontSize spacing))
+            } {
+                def words:[string] (strsplit para " ")
+                ; How many TOKENS are on the line, not how many characters.
+                ; `strsplit " / " " "` is ["", "/", ""], and an empty token is a
+                ; token: it is the space that was there. Asking `strlen
+                ; currentLine == 0` cannot tell "nothing on this line yet" from
+                ; "one empty token on this line", so it took the `testLine =
+                ; word` branch a second time and dropped the space in front —
+                ; the breadcrumb separator went in as " / " and came out "/ ",
+                ; drawn hard against the crumb before it with the gap on the
+                ; wrong side. The no-wrap path (maxWidth <= 0) pushed the
+                ; paragraph verbatim and kept its spaces, so the same string
+                ; drew two different ways depending on whether it had a width.
+                def currentLine:string ""
+                def tokensOnLine:int 0
+                def w:int 0
+                while (w < (array_length words)) {
+                    def word:string (itemAt words w)
+                    def testLine:string ""
+                    if (tokensOnLine == 0) {
+                        testLine = word
+                    } {
+                        testLine = currentLine + " " + word
+                    }
+                    def testWidth:double ((measurer.measureTextWidth(testLine fontFamily fontSize)) + (EVGTextEngine.trackingWidth(testLine spacing)))
+                    ; A HAIR OF TOLERANCE, and it is not a fudge — it is what
+                    ; stops a box from breaking its own content.
+                    ;
+                    ; A text element with no stated width shrink-wraps: the
+                    ; layout measures the run, adds the padding and the border,
+                    ; and that sum is the box. The breaker then works with the
+                    ; box MINUS the same padding and border, and
+                    ; `(w + chrome) - chrome` is not always `w` in binary
+                    ; floating point. For some strings it lands a few parts in
+                    ; a quadrillion low, and the line that was measured to fit
+                    ; exactly is then one part in a quadrillion too wide and
+                    ; goes onto a second line. `lib/evg/web/responsive`
+                    ; had six labels in a column, five on one line and
+                    ; `Display list` on two, for exactly this reason — see
+                    ; ISSUES.md #7.
+                    ;
+                    ; A micron of a pixel cannot change any wrap a person
+                    ; asked for; it can only undo a round trip that should
+                    ; have been the identity.
+                    if (((testWidth - maxWidth) > (EVGTextEngine.fitEpsilon())) && (tokensOnLine > 0)) {
+                        push out (this.measuredLineSpaced(currentLine fontFamily fontSize spacing))
+                        currentLine = word
+                        tokensOnLine = 1
+                    } {
+                        currentLine = testLine
+                        tokensOnLine = (tokensOnLine + 1)
+                    }
+                    w = (w + 1)
+                }
+                ; An empty paragraph is still a line — blank lines take vertical
+                ; space, and dropping them would shorten the block.
+                push out (this.measuredLineSpaced(currentLine fontFamily fontSize spacing))
+            }
+            if (p > 0) {
+                if (firstOfPara < (array_length out)) {
+                    def opener:EVGTextLine (itemAt out firstOfPara)
+                    opener.startsParagraph = true
+                }
+            }
+            p = (p + 1)
+        }
+
+        if ((array_length out) == 0) {
+            push out (this.measuredLineSpaced("" fontFamily fontSize spacing))
+        }
+        return out
+    }
+
+    ; One measured line, RETURNED rather than pushed into a list the caller
+    ; passed in.
+    ;
+    ; It used to take the list. That works on JavaScript, where an array
+    ; parameter is the caller's array, and does nothing on Go, where it is a
+    ; slice and the append lands on a copy — so `breakLines` returned NO lines
+    ; on Go at any width, and every display list built from an element tree
+    ; drew no text there at all. Nothing warns in between: the JavaScript
+    ; suites pass and the Go ones draw an empty page.
+    ;
+    ; Found from `gallery/markdown`, whose own layout had hit the same trap
+    ; a week earlier and left a note about it.
+    fn measuredLine:EVGTextLine (text:string fontFamily:string fontSize:double) {
+        return (this.measuredLineSpaced(text fontFamily fontSize 0.0))
+    }
+
+    fn measuredLineSpaced:EVGTextLine (text:string fontFamily:string fontSize:double spacing:double) {
+        def m:EVGTextMetrics (measurer.measureText(text fontFamily fontSize))
+        def line (new EVGTextLine())
+        line.text = text
+        line.width = (m.width + (EVGTextEngine.trackingWidth(text spacing)))
+        line.ascent = m.ascent
+        line.descent = m.descent
+        return line
+    }
+
+    ; What `letter-spacing` adds to a run: the extra advance AFTER every
+    ; character, the last one included, which is what CSS says and what a
+    ; canvas with `letterSpacing` set measures back. Counting the gaps
+    ; BETWEEN characters instead would make every measurement here one
+    ; space narrower than the ink the painter lays down, and a box sized
+    ; from it would clip its own last letter.
+    ;
+    ; Counted in graphemes, so an emoji or a combining accent is one
+    ; character and not the two or four units it is stored in.
+    sfn trackingWidth:double (text:string spacing:double) {
+        if (spacing == 0.0) {
+            return 0.0
+        }
+        return ((to_double (EVGGrapheme.clusterCount(text))) * spacing)
+    }
+
+    ; Number of lines `text` occupies at `maxWidth` — the wrap and the height
+    ; calculation therefore cannot disagree, because it is the same wrap.
+    fn lineCount:int (text:string fontFamily:string fontSize:double maxWidth:double) {
+        return (this.lineCountSpaced(text fontFamily fontSize maxWidth 0.0))
+    }
+
+    fn lineCountSpaced:int (text:string fontFamily:string fontSize:double maxWidth:double spacing:double) {
+        def lines:[EVGTextLine] (this.breakLinesSpaced(text fontFamily fontSize maxWidth spacing))
+        return (array_length lines)
+    }
+
+    ; Widest line, for shrink-wrapping a text node to its content.
+    fn maxLineWidth:double (text:string fontFamily:string fontSize:double) {
+        return (this.maxLineWidthSpaced(text fontFamily fontSize 0.0))
+    }
+
+    fn maxLineWidthSpaced:double (text:string fontFamily:string fontSize:double spacing:double) {
+        def lines:[EVGTextLine] (this.breakLinesSpaced(text fontFamily fontSize 0.0 spacing))
+        def maxW:double 0.0
+        def i:int 0
+        while (i < (array_length lines)) {
+            def ln:EVGTextLine (itemAt lines i)
+            if (ln.width > maxW) {
+                maxW = ln.width
+            }
+            i = (i + 1)
+        }
+        return maxW
+    }
+
+    ; The narrowest this text can be made without breaking a word — CSS's
+    ; min-content. Breaking at every opportunity puts one word per line, so the
+    ; widest of those lines is the answer.
+    fn minLineWidth:double (text:string fontFamily:string fontSize:double) {
+        return (this.minLineWidthSpaced(text fontFamily fontSize 0.0))
+    }
+
+    fn minLineWidthSpaced:double (text:string fontFamily:string fontSize:double spacing:double) {
+        def lines:[EVGTextLine] (this.breakLinesSpaced(text fontFamily fontSize 0.001 spacing))
+        def maxW:double 0.0
+        def i:int 0
+        while (i < (array_length lines)) {
+            def ln:EVGTextLine (itemAt lines i)
+            if (ln.width > maxW) {
+                maxW = ln.width
+            }
+            i = (i + 1)
+        }
+        return maxW
+    }
+
+    ; How much taller a block is for the gaps between its paragraphs: one
+    ; `paragraph-spacing` per break the author typed, and none for the
+    ; breaks the box made by wrapping.
+    fn paragraphLeading:double (text:string fontFamily:string fontSize:double maxWidth:double spacing:double paragraphSpacing:double) {
+        if (paragraphSpacing == 0.0) {
+            return 0.0
+        }
+        def lines:[EVGTextLine] (this.breakLinesSpaced(text fontFamily fontSize maxWidth spacing))
+        def breaks:int 0
+        def i:int 0
+        while (i < (array_length lines)) {
+            if ((itemAt lines i).startsParagraph) {
+                breaks = (breaks + 1)
+            }
+            i = (i + 1)
+        }
+        return ((to_double breaks) * paragraphSpacing)
+    }
+
+    ; Convenience for callers that only want the strings (PDF paint).
+    fn breakToStrings:[string] (text:string fontFamily:string fontSize:double maxWidth:double) {
+        return (this.breakToStringsSpaced(text fontFamily fontSize maxWidth 0.0))
+    }
+
+    fn breakToStringsSpaced:[string] (text:string fontFamily:string fontSize:double maxWidth:double spacing:double) {
+        def out:[string]
+        def lines:[EVGTextLine] (this.breakLinesSpaced(text fontFamily fontSize maxWidth spacing))
+        def i:int 0
+        while (i < (array_length lines)) {
+            def ln:EVGTextLine (itemAt lines i)
+            push out ln.text
+            i = (i + 1)
+        }
+        return out
+    }
+}