ranger-compiler 3.5.1 → 3.5.2

package/dist/lib/evg/EVGUnit.rgr

@@ -0,0 +1,554 @@
+; SPDX-License-Identifier: MIT
+
+; EVGUnit.rgr - Unit parsing and resolution for EVG layout
+; Supports: px, %, em, rem, hp (height percent), vw / vh, fill, and the
+; absolute print units pt / pc / in / mm / cm, which are folded into px at
+; parse time.
+;
+; `vw` and `vh` are the VIEWPORT, which is a different thing from the parent —
+; and the reason they are worth having at all: `height: 100%` needs a chain of
+; ancestors that all have a definite height, so a page that wants to be as tall
+; as the screen has to be handed that number by its host. `100vh` asks the
+; layout, which already knows: `EVGLayout.pageWidth` / `pageHeight`.
+;
+; ON PAPER that is the PAGE AREA — the sheet less its margins — which is what
+; CSS says viewport-percentage lengths mean in paged media, and what the print
+; renderers already give the layout as its page size (`EVGPDFRenderer` and
+; `EVGHTMLRenderer` both set `layout.pageWidth` to the section width less two
+; margins before laying a page out). So `100vh` is the text column on A4 and
+; the window on a screen, with nothing to configure in either.
+;
+; A unit cannot reach the layout on its own, so whoever resolves it calls
+; `setContext` first, the same way `rem` gets the root font size. With no
+; viewport handed over — an element resolved outside a layout — a viewport
+; length comes out ZERO rather than falling back to the parent's size: one of
+; those is a visible mistake and the other is `100vh` quietly meaning two
+; different things depending on where the element sits.
+;
+; Not supported, deliberately: vmin / vmax (nothing has asked, and they are two
+; more lines the day something does), ch/ex (they need font metrics the unit
+; layer has no access to), and calc().
+; An unrecognised suffix leaves the unit UNSET — i.e. auto, the way a browser
+; drops a declaration it cannot parse. It must not fall through to the bare
+; number path, because to_double("10ch") is 10 and the length would silently
+; become 10px.
+
+; Unit type constants
+; 0 = PIXELS (default)
+; 1 = PERCENT (% of parent width)
+; 2 = EM (relative to font size)
+; 3 = HEIGHT_PERCENT (% of parent height)
+; 4 = FILL (expand to fill available space)
+; 5 = REM (relative to the ROOT font size)
+; 6 = FIT_CONTENT (as wide as the children turn out to be)
+; 7 = VIEWPORT_WIDTH (vw, % of the layout's page width)
+; 8 = VIEWPORT_HEIGHT (vh, % of the layout's page height)
+
+; The one unset unit every element shares.
+;
+; An element has 39 unit-valued fields and a fresh box 14 more, and nearly all
+; of them are "nothing was said". Allocating a separate object to say nothing
+; 53 times per element was, measured, most of the element's memory (6.7 kB of
+; which 4.4 kB was sub-objects) and most of its construction time. So there is
+; ONE unset unit, and `EVGUnit.unset()` hands it out.
+;
+; That is only sound if nobody writes into it, and the unit has exactly two
+; in-place mutators: `setContext` and the `resolve` family. Both now do
+; nothing for an unset unit — an unset unit resolves to 0 whatever its
+; context is, so there was never anything to write. A caller that wants to
+; SET a unit assigns a new one to the field (`el.width = EVGUnit.px(..)`);
+; it must not flip `isSet` on the object it found there, because that object
+; may be this one.
+class EVGUnitDefaults @singleton(true) {
+    def unset:EVGUnit (new EVGUnit())
+}
+
+class EVGUnit {
+    def value:double 0.0
+    def unitType:int 0
+    def isSet:boolean false
+    def pixels:double 0.0
+    ; What `rem` resolves against. A unit has no way to reach the root of the
+    ; tree, so whoever resolves it (EVGElement/EVGBox.resolveUnits) sets this
+    ; first. Ignored by every other unit type.
+    def rootFontSize:double 14.0
+    ; And what `vw` / `vh` resolve against: the layout's page size, which on
+    ; paper is the page area rather than the sheet. Zero means nobody said, and
+    ; a viewport length then comes out zero — see the note at the top.
+    def viewportW:double 0.0
+    def viewportH:double 0.0
+    
+    Constructor () {
+        value = 0.0
+        unitType = 0
+        isSet = false
+        pixels = 0.0
+    }
+
+    ; Everything a relative length needs beyond its parent's size: the root
+    ; font size for `rem`, the viewport for `vw` and `vh`. One call rather than
+    ; three assignments at every site, because the three travel together and a
+    ; site that set two of them would be a bug nothing announces.
+    fn setContext:void (rfs:double vw:double vh:double) {
+        ; An unset unit resolves to 0 in any context, and it may be the
+        ; shared one: nothing to record.
+        if (isSet == false) {
+            return
+        }
+        rootFontSize = rfs
+        viewportW = vw
+        viewportH = vh
+    }
+
+    ; The part before a suffix, and whether it is a NUMBER — digits, one dot,
+    ; a sign. `to_double` stops at the first character it cannot use, so a
+    ; suffix test on its own is not enough to know a length was written the way
+    ; the parser thinks it was: "10vmin" ends in "in", inches are one of the
+    ; absolute units, and it parsed as 10 inches — 960 pixels — for a unit this
+    ; layer deliberately does not support. Every branch below asks this first.
+    sfn isNumeric:boolean (str:string) {
+        def n:int (strlen str)
+        if (n == 0) {
+            return false
+        }
+        def i:int 0
+        def digits:int 0
+        while (i < n) {
+            def c:int (charAt str i)
+            def isDigit:boolean ((c >= 48) && (c <= 57))
+            if isDigit {
+                digits = (digits + 1)
+            } {
+                ; A sign only at the front, a dot anywhere, nothing else.
+                if (c == 46) {
+                } {
+                    if ((c == 43) || (c == 45)) {
+                        if (i > 0) {
+                            return false
+                        }
+                    } {
+                        return false
+                    }
+                }
+            }
+            i = (i + 1)
+        }
+        return (digits > 0)
+    }
+
+    sfn isAlpha:boolean (c:int) {
+        if ((c >= 65) && (c <= 90)) {
+            return true
+        }
+        return ((c >= 97) && (c <= 122))
+    }
+
+    ; CSS defines the absolute units against the reference pixel: 1in = 96px.
+    sfn pxPerUnit:double (suffix:string) {
+        if (suffix == "pt") {
+            return (96.0 / 72.0)
+        }
+        if (suffix == "pc") {
+            return 16.0
+        }
+        if (suffix == "in") {
+            return 96.0
+        }
+        if (suffix == "mm") {
+            return (96.0 / 25.4)
+        }
+        if (suffix == "cm") {
+            return (96.0 / 2.54)
+        }
+        return 0.0
+    }
+    
+    sfn create:EVGUnit (val:double uType:int) {
+        def unit (new EVGUnit())
+        unit.value = val
+        unit.unitType = uType
+        unit.isSet = true
+        return unit
+    }
+    
+    sfn px:EVGUnit (val:double) {
+        def unit:EVGUnit (EVGUnit.create(val 0))
+        ; A pixel length is already in pixels. parse("14px") fills this in
+        ; eagerly and callers read .pixels without resolving first, so px()
+        ; has to as well.
+        unit.pixels = val
+        return unit
+    }
+    
+    sfn percent:EVGUnit (val:double) {
+        return (EVGUnit.create(val 1))
+    }
+    
+    sfn em:EVGUnit (val:double) {
+        return (EVGUnit.create(val 2))
+    }
+    
+    sfn rem:EVGUnit (val:double) {
+        return (EVGUnit.create(val 5))
+    }
+    
+    sfn heightPercent:EVGUnit (val:double) {
+        return (EVGUnit.create(val 3))
+    }
+    
+    sfn fill:EVGUnit () {
+        return (EVGUnit.create(100.0 4))
+    }
+    
+    ; The shared unset unit. Read-only by convention — see EVGUnitDefaults.
+    sfn unset:EVGUnit () {
+        return ((EVGUnitDefaults.__singleton()).unset)
+    }
+    
+    sfn parse:EVGUnit (str:string) {
+        ; Parse unit string like "100px", "50%", "2em", "30hp", "fill", "auto"
+        def unit (new EVGUnit())
+        def trimmed:string (trim str)
+        def len:int (strlen trimmed)
+        
+        if (len == 0) {
+            return unit
+        }
+        
+        ; Check for "fill"
+        if (trimmed == "fill") {
+            unit.value = 100.0
+            unit.unitType = 4
+            unit.isSet = true
+            return unit
+        }
+        
+        ; Check for "auto" - return unset unit (auto sizing)
+        if (trimmed == "auto") {
+            return unit
+        }
+
+        ; fit-content: the box is as wide as what it holds. Not the same as
+        ; leaving the width off, which in EVG means "as wide as the parent" —
+        ; that difference is why a row of containers stacked vertically instead
+        ; of sitting side by side, every one of them filling the row.
+        if (trimmed == "fit-content") {
+            unit.value = 0.0
+            unit.unitType = 6
+            unit.isSet = false
+            return unit
+        }
+        
+        ; Check for percentage
+        def lastChar:int (charAt trimmed (len - 1))
+        if (lastChar == 37) {  ; '%'
+            def numStr:string (substring trimmed 0 (len - 1))
+            if (EVGUnit.isNumeric(numStr) == false) {
+                return unit
+            }
+            def numVal@(optional):double (to_double numStr)
+            if numVal {
+                unit.value = (unwrap numVal)
+                unit.unitType = 1
+                unit.isSet = true
+            }
+            return unit
+        }
+        
+        ; "rem" has to be tested before "em", or a 3-character suffix gets
+        ; chopped to "2r" — which to_double happily reads as 2, so "2rem"
+        ; silently became "2em".
+        if (len >= 3) {
+            def suffix3:string (substring trimmed (len - 3) len)
+            if (suffix3 == "rem") {
+                def numStr3:string (substring trimmed 0 (len - 3))
+                if (EVGUnit.isNumeric(numStr3) == false) {
+                    return unit
+                }
+                def numVal3@(optional):double (to_double numStr3)
+                if numVal3 {
+                    unit.value = (unwrap numVal3)
+                    unit.unitType = 5
+                    unit.isSet = true
+                }
+                return unit
+            }
+        }
+        
+        ; Check for "em"
+        if (len >= 2) {
+            def suffix:string (substring trimmed (len - 2) len)
+            ; Absolute print units. These have a fixed pixel value, so they are
+            ; folded to px here and never need resolving again.
+            def perUnit:double (EVGUnit.pxPerUnit(suffix))
+            if (perUnit > 0.0) {
+                def numStrA:string (substring trimmed 0 (len - 2))
+                if (EVGUnit.isNumeric(numStrA) == false) {
+                    return unit
+                }
+                def numValA@(optional):double (to_double numStrA)
+                if numValA {
+                    unit.value = ((unwrap numValA) * perUnit)
+                    unit.pixels = unit.value
+                    unit.unitType = 0
+                    unit.isSet = true
+                }
+                return unit
+            }
+            if (suffix == "em") {
+                def numStr:string (substring trimmed 0 (len - 2))
+                if (EVGUnit.isNumeric(numStr) == false) {
+                    return unit
+                }
+                def numVal@(optional):double (to_double numStr)
+                if numVal {
+                    unit.value = (unwrap numVal)
+                    unit.unitType = 2
+                    unit.isSet = true
+                }
+                return unit
+            }
+            if (suffix == "px") {
+                def numStr:string (substring trimmed 0 (len - 2))
+                if (EVGUnit.isNumeric(numStr) == false) {
+                    return unit
+                }
+                def numVal@(optional):double (to_double numStr)
+                if numVal {
+                    unit.value = (unwrap numVal)
+                    unit.pixels = unit.value  ; For pixels, set pixels immediately
+                    unit.unitType = 0
+                    unit.isSet = true
+                }
+                return unit
+            }
+            if (suffix == "hp") {
+                def numStr:string (substring trimmed 0 (len - 2))
+                if (EVGUnit.isNumeric(numStr) == false) {
+                    return unit
+                }
+                def numVal@(optional):double (to_double numStr)
+                if numVal {
+                    unit.value = (unwrap numVal)
+                    unit.unitType = 3
+                    unit.isSet = true
+                }
+                return unit
+            }
+            ; The viewport, which is the layout's page size — and on paper the
+            ; page AREA, because that is the page size the print renderers set.
+            if (suffix == "vw") {
+                def numStrVW:string (substring trimmed 0 (len - 2))
+                if (EVGUnit.isNumeric(numStrVW) == false) {
+                    return unit
+                }
+                def numValVW@(optional):double (to_double numStrVW)
+                if numValVW {
+                    unit.value = (unwrap numValVW)
+                    unit.unitType = 7
+                    unit.isSet = true
+                }
+                return unit
+            }
+            if (suffix == "vh") {
+                def numStrVH:string (substring trimmed 0 (len - 2))
+                if (EVGUnit.isNumeric(numStrVH) == false) {
+                    return unit
+                }
+                def numValVH@(optional):double (to_double numStrVH)
+                if numValVH {
+                    unit.value = (unwrap numValVH)
+                    unit.unitType = 8
+                    unit.isSet = true
+                }
+                return unit
+            }
+        }
+        
+        ; Default: treat as pixels — but only for something that really is a
+        ; bare number. to_double stops at the first character it cannot use, so
+        ; without this guard every unit the parser does not know ("10vw",
+        ; "4ch") would quietly turn into that many pixels.
+        if ((EVGUnit.isAlpha(lastChar)) || (lastChar == 41)) {
+            return unit
+        }
+        def numVal@(optional):double (to_double trimmed)
+        if numVal {
+            unit.value = (unwrap numVal)
+            unit.pixels = unit.value  ; For pixels, set pixels immediately
+            unit.unitType = 0
+            unit.isSet = true
+        }
+        return unit
+    }
+    
+    fn resolve:void (parentSize:double fontSize:double) {
+        ; Resolve unit to actual pixel value
+        if (isSet == false) {
+            ; Only a unit that WAS set and was then unset in place can have a
+            ; stale pixel value; the shared unset unit never does, and is not
+            ; written to.
+            if (pixels != 0.0) {
+                pixels = 0.0
+            }
+            return
+        }
+        
+        ; PIXELS
+        if (unitType == 0) {
+            pixels = value
+            return
+        }
+        
+        ; PERCENT
+        if (unitType == 1) {
+            pixels = ((parentSize * value) / 100.0)
+            return
+        }
+        
+        ; EM
+        if (unitType == 2) {
+            pixels = (fontSize * value)
+            return
+        }
+        
+        ; REM - against the root font size, not this element's
+        if (unitType == 5) {
+            pixels = (rootFontSize * value)
+            return
+        }
+        
+        ; HEIGHT_PERCENT (resolved separately with height)
+        if (unitType == 3) {
+            pixels = ((parentSize * value) / 100.0)
+            return
+        }
+        
+        ; VIEWPORT_WIDTH / VIEWPORT_HEIGHT. The parent is not consulted: that
+        ; is the whole point of the unit, and it is what makes `100vh` on a
+        ; nested box mean the screen rather than whatever box it happens to be
+        ; sitting in.
+        if (unitType == 7) {
+            pixels = ((viewportW * value) / 100.0)
+            return
+        }
+        if (unitType == 8) {
+            pixels = ((viewportH * value) / 100.0)
+            return
+        }
+
+        ; FILL - resolved by layout engine
+        if (unitType == 4) {
+            pixels = parentSize
+            return
+        }
+        
+        pixels = value
+    }
+    
+    fn resolveForHeight:void (parentWidth:double parentHeight:double fontSize:double) {
+        ; Resolve unit for HEIGHT property - percent uses parentHeight
+        if (isSet == false) {
+            if (pixels != 0.0) {
+                pixels = 0.0
+            }
+            return
+        }
+        
+        if (unitType == 3) {
+            ; HEIGHT_PERCENT uses parent height
+            pixels = ((parentHeight * value) / 100.0)
+            return
+        }
+        
+        ; For percentage on height property, use parentHeight
+        if (unitType == 1) {
+            pixels = ((parentHeight * value) / 100.0)
+            return
+        }
+        
+        ; For other types (px, em), use normal resolve
+        this.resolve(parentWidth fontSize)
+    }
+    
+    fn resolveWithHeight:void (parentWidth:double parentHeight:double fontSize:double) {
+        ; Resolve unit using width as primary (for width property)
+        if (isSet == false) {
+            if (pixels != 0.0) {
+                pixels = 0.0
+            }
+            return
+        }
+        
+        if (unitType == 3) {
+            ; HEIGHT_PERCENT uses parent height
+            pixels = ((parentHeight * value) / 100.0)
+            return
+        }
+        
+        ; For other types, use width
+        this.resolve(parentWidth fontSize)
+    }
+    
+    fn isPixels:boolean () {
+        return (unitType == 0)
+    }
+    
+    fn isPercent:boolean () {
+        return (unitType == 1)
+    }
+    
+    fn isEm:boolean () {
+        return (unitType == 2)
+    }
+    
+    fn isRem:boolean () {
+        return (unitType == 5)
+    }
+    
+    fn isHeightPercent:boolean () {
+        return (unitType == 3)
+    }
+    
+    fn isFill:boolean () {
+        return (unitType == 4)
+    }
+
+    fn isViewport:boolean () {
+        if (unitType == 7) {
+            return true
+        }
+        return (unitType == 8)
+    }
+    
+    fn toString:string () {
+        if (isSet == false) {
+            return "unset"
+        }
+        if (unitType == 0) {
+            return ((to_string value) + "px")
+        }
+        if (unitType == 1) {
+            return ((to_string value) + "%")
+        }
+        if (unitType == 2) {
+            return ((to_string value) + "em")
+        }
+        if (unitType == 3) {
+            return ((to_string value) + "hp")
+        }
+        if (unitType == 4) {
+            return "fill"
+        }
+        if (unitType == 5) {
+            return ((to_string value) + "rem")
+        }
+        if (unitType == 7) {
+            return ((to_string value) + "vw")
+        }
+        if (unitType == 8) {
+            return ((to_string value) + "vh")
+        }
+        return (to_string value)
+    }
+}