Interpolation Resolution

[ianjosephwilson]

Along the same lines of the attribute resolution I was trying to document how the interpolations are resolved. This is what I have so far. This reduces some of the API surface area in certain situations but allows us to start thinking about what is actually permitted in each case. Whereas before it seemed that we tried to do everything in every case and it was really hard to reason about IMO.

Adding Text/Elements

Interpolation in element (has parent tag) or bare (no parent tag)

• Normal Text
  • Example: t'''<div>{t"Hello and {'good day to you'}"} World</div>'''
  • Escaping normal text can be done by the individual character so each interpolation can be processed independently.
  • Kinds:
    • str -- processed with an escape function that is Markup aware
    • None -- ignored (essentially the same as "")
    • Template -- processed recursively, should inherit normal text context
    • Iterable -- processed recursively, must consist of values of these same "kinds"
    • Everything else will be processed with an escape function that coerces it to an instance of str.
      • Note that instances of HasHTMLDunder will be detected by the escaping function and pass through unescaped.
• Raw Text(script/style) / Escapable Raw Text(title/textarea) / Comment
  • Example: t'<title>{"Hello"} World</title>'
  • Alternative: t'<script>var x = {15};</script>'
  • Alternative: t'<!-- Example {3} -->'
  • All texts are joined together before escaping.
    • Escaping method depends on parent tag.
    • In singleton / exact match case an object with __html__ is allowed to bypass escaping.
  • Kinds:
    • str -- processed in "".join() (escaped as sum of parts, method depends on parent)
    • HasHTMLDunder -- allowed for exact matches otherwise an exception is raised
    • None -- ignored (essentially the same as "")
    • Template -- an exception is raised
    • Iterable -- an exception is raised
    • Everything else will be processed in "".join() after str() is applied
• Dynamic Text (No parent tag is known until processing time)
  • Example: ex_t = t'Hello {"World"}'
  • If interpolated into a tag that isn't raw text or escapable raw text then assume normal text
    • Example: t'<div>{ex_t}</div>'
  • Note that raw text / escapable text tags cannot actually interpolate templates
    • Example: t'<script>{ex_t}</script>' raises exception
  • If interpolated without an effective parent tag then raise an exception
    • Example: t'The greeting is {ex_t}' raises exception

Invoking Components

Interpolation as tag, can be in an "startend" / self-closing tag or in a pair of "start"/"end" tags.

• Start or statend tag
  • Example: t'<{value}>...'
  • Alternative form: t'<{value} />'
  • Kinds:
    • Callable[..., Template] - executed as component function, Template should adhere to "Normal Text" rules.
    • Callable[..., Callable[[], Template]] -- created with first call, then result is called to create Template, Template should adhere to "Normal Text" rules.
      • The first Callable can optionally accept a children kw arg that will be filled by whatever Template content was between its tags.
        • If no content exists then an "empty" Template will be provided, ie. t"".
        • If no children kw arg is defined and there are no **kwargs defined then no children will be passed to the callable even if the children do exist in the original Template.
      • Note that a component cannot exist inside elements that hold "raw text" or "escapable raw text" because Elements cannot exist there.
    • Everything else would be an exception.
• End tag
  • Example: t'...</{value}>'
  • Kinds:
    • Callable -- must be identical to start tag's value
      • identity should be checked at parse time
      • most likely checked at process time as well although it kind of doesn't matter
    • Everything else would be an exception.

Defining Attributes (For Elements or Components)

Interpolation as attribute name, value or part of value.

We mostly ironed this out already and it seems to be working okay waiting on more real-world usage.

• As entire value
  • Referred to as an "interpolated" attribute
  • Example: t'<div title={value}></div>'
  • Kinds:
    • object -- merged into pool of attributes unless special handling applies, see below
• As part of value
  • Referred to as a "templated" attribute
  • Example: t'<div title="Mr. {value}"></div>'
  • Kinds:
    • Every value will be coerced with str() before applying "".join() and finally escaping.
    • Final attribute will be merged into pool of attributes unless special handling applies, see below
• As entire name: spread attribute
  • Referred to as a "spread" attribute
  • Example: t'<div {value}></div>'
  • Kinds:
    • dict[str, object] -- key/value pairs from .items() are merged into pool of attributes unless special handling applies, see below
    • None -- ignored, no attributes are merged
• Merging attributes into pool of attributes
  • Attributes without special handling are written into a general pool from left to right. Later, rightmost, values writing over earlier, leftmost, values.
  • Special "accumulating" attributes are removed from this merge process until the last step and then are each added back into the general pool as a single attribute.
  • Special "expanding" attributes are written into the general pool from left to right after key expansion and any value modifications are performed.
• Processing attributes for HTML versus Components
  • The pool of attributes are passed on to components as kw arguments with values as-is at the end of the merging process.
  • The pool of attributes are serialized to HTML attributes at the end of the merging process using the following rules:
    • None | False -- attribute will be omitted
    • True -- attribute will be a bare attribute
    • str() -- escaped value will be used for attribute's value
• Special accumulating attributes:
  • Accumulated from left to right
  • class
    • Accumulation only occurs if there is more than one literal class attribute AND/OR class is used in any kind of attribute interpolation.
    • Stored internally approximately like this classes: dict[str, bool]
    • Process via class_value = " ".join(f"{key}" for key, value in classes.items() if value) or None
  • style
    • Accumulation only occurs if there is more than one literal style attribute AND/OR style is used in any kind of attribute interpolation.
    • Stored internally approximately like this styles: dict[str, str|None]
    • Process via style_value = "; ".join([f"{pn}: {pv}" for pn, pv in styles.items() if pv is not None]) or None
• Special expanding attributes:
  • Expand each occurrence from left to right into larger pool of attributes
  • aria
    • Kinds:
      • dict[str, str|bool|None|object]
        • str -- as-is
        • bool -- transformed to "true" for True and "false" for False
        • None -- as-is
        • All other kinds will be coerced with str()
      • None -- ignored, no attributes expanded into pool
  • data
    • Kinds:
      • dict[str, str|bool|None]
        • str | bool | None -- as-is
        • All other kinds will be coerced with str()
      • None -- ignored, no attributes expanded into pool