dymokomi/luce-browser-engine
Source of release 0.6.1
0.6.1 / docs / regions / r31.md
# Region r31: CSS rule, selector, media, descriptor and syntax parsing — what other regions need to know
Region r31 ports `CSS/Parser/RuleParsing.cpp`, `SelectorParsing.cpp`, `MediaParsing.cpp`,
`DescriptorParsing.cpp`, `Syntax.cpp/.h` and `SyntaxParsing.cpp/.h`. The stub fragment
`stubs/stub_r31_css_rule_parsing.lucb` is gone; every one of its functions is ported, except the
header declaration of `parse_syntax_component` that the skeleton emitted a second time with an
unmapped parameter (`css_parse_syntax_component_opaque`, dropped with its namemap row; the
definition is `css_parse_syntax_component_token_stream`).
## Fragments
| Fragment | Donor |
| --- | --- |
| `css/parser/descriptor_parsing_1` | `DescriptorParsing.cpp` 82-388: the value-type lambda of `parse_descriptor_value` and its nested lambdas |
| `css/parser/descriptor_parsing_2` | `DescriptorParsing.cpp` 1-81, 389-448: `parse_descriptor_value`, `convert_to_descriptor` |
| `css/parser/media_parsing_1` | `MediaParsing.cpp` 1-424: media query lists, `<media-query>`, `<media-condition>`, `<media-feature>` (its lambdas: `<mf-name>`, `<mf-boolean>`, `<mf-plain>`, `<mf-comparison>`, `<mf-range>`) |
| `css/parser/media_parsing_2` | 426-663: `<media-type>`, `is_media_feature_value_token`, `<mf-value>`, `convert_to_media_rule` |
| `css/parser/rule_parsing_1` | `RuleParsing.cpp` 1-356: `DescriptorList`, `convert_to_rule`, style rules, `@import`, `<layer-name>` |
| `css/parser/rule_parsing_2` | 358-708: `@layer`, `@keyframes`, `@namespace`, `@supports` |
| `css/parser/rule_parsing_3` | 710-1061: `@property`, `@container`, `@counter-style`, `@font-face` |
| `css/parser/rule_parsing_4` | 1063-1384: family name lists, `@font-feature-values`, `<css-type>`, `parse_function_prelude` |
| `css/parser/rule_parsing_5` | 1386-1528: `@function`, `@page`, margin rules, `convert_to_descriptors` |
| `css/parser/selector_parsing_1` | `SelectorParsing.cpp` 1-388: entry points, `<selector-list>`, `<complex-selector>`, `<compound-selector>`, combinators, `<wq-name>` |
| `css/parser/selector_parsing_2` | 390-870: attribute selectors, pseudo-classes |
| `css/parser/selector_parsing_3` | 872-1185: pseudo-elements, `<simple-selector>` |
| `css/parser/selector_parsing_4` | 1187-1566: the An+B microsyntax, `<page-selector-list>` |
| `css/parser/syntax` | `Syntax.cpp` and `Syntax.h`'s inline members |
| `css/parser/syntax_parsing` | `SyntaxParsing.cpp` |
| `css/parser/tests_css_rule_parsing_cases`, `tests_css_rule_parsing` | tests (Ladybird has none for these files) |
Lambdas are private functions named after their enclosing function, with a capture struct where
they capture; `for_each_as_*` callbacks are `ak.Function1`s over them.
## What other regions must know
### Types filled by hand
- **r38 (selectors)**: `types_selector` now has `CssSelectorSimpleSelector { type_, value }`, its
value variant `CssSelectorSimpleSelectorValue` (cases named after the member types, the
generator's rule), `CssSelectorSimpleSelectorAnPlusBPattern { step_size, offset }`,
`...PseudoClassSelector` (+ `...PseudoClassSelectorIdent`), `...Name` with
`css_selector_simple_selector_name_create(n)` (Selector.h's `Name(FlyString)`: the lowercase
name), `...QualifiedName` (+ `NamespaceType`), `...Attribute` (+ `MatchType`, `CaseType`),
`...Invalid`, and `CssSelectorCompoundSelector { combinator, simple_selectors }`. r13's
`dump_selector` / `dump_qualified_name` (Dump.cpp), which trap waiting for these types, can now
be completed.
- **r37**: `CssContainerRuleCondition { container_name, container_query }`; added an opaque
`CssKeyframeRule` (types_css_keyframes_rule) and stubs `css_keyframe_rule_create`,
`css_keyframes_rule_create` (CSSKeyframe(s)Rule are outside the phase-1 files). The parser
treats both as CSSRules by cast (`(CssRule*)`), so their ports must embed `CssRule` first.
- `CssParserFunctionPrelude { name, parameters, return_type }` (types_parser).
### Templates over the nested-declarations rule type
`convert_to_rule`, `convert_to_container_rule`, `_layer_rule`, `_media_rule` and `_supports_rule`
stay generics `[TNestedDeclarationsRule]`; call them with `CssNestedDeclarations` or
`CssFunctionDeclarations`. `NestedDeclarationsRule::create(...)` is
`css_parser_create_nested_declarations_rule[T]`, which tells the two types apart by size (a
module assert checks they differ), as r30b's per-T token steps do. `convert_to_descriptors[T]`
is instantiated for `CssFunctionDescriptors` only (it asserts so).
### Signatures
- `css_alternatives_syntax_node_children_2 -> const (CssSyntaxNode*)[]` (was `const
CssSyntaxNode*[]`, a span of pointers to const nodes that a Vector of pointers does not give).
- `css_parser_parse_a_media_query_list`, `_parse_a_selector_list`, `_parse_a_page_selector_list`
have the `[T: css_syntax.TokenStreamToken[T]]` constraint (HANDOFF §5 item 4).
- Error codes: r30b's `css_parser_parse_error_syntax_error` / `..._includes_ignored_vendor_prefix`.
### Where phase-1 paths stop (other regions' stubs)
- Every selector that parses reaches r38's `Selector::create`; pseudo-elements reach r38's
`PseudoElementSelector` constructors, legacy single-colon ones `is_legacy_single_colon_pseudo_element`;
`@page` selectors reach `PageSelector`'s constructor and `page_pseudo_class_from_string` (r38).
- Media queries reach r42's `MediaQuery::create`, `MediaFeature::*`, `MediaFeatureValue` and
`media_type_from_string`; `<mf-value>`s reach r32's value parsers.
- Rule conversion: at-rules after `@layer` in `convert_to_rule`'s order trap in r37's
`is_margin_rule_name` (and r30b's top-level validity check traps there for every at-rule);
every converted rule reaches r37's `CSS*Rule::create`; `@container`/`@counter-style` preludes
r32's `parse_custom_ident` / `parse_counter_style_name`; `@import` r32's `parse_url_function`.
- Descriptors trap at once in r36's `DescriptorNameAndID::id()`/`from_name`; `DescriptorList::append`
in r37's `is_shorthand`.
- `TypeSyntaxNode::create` (every `<type>` in a `<syntax>`) traps in r36's `value_type_from_string`.
- r36: `css_infinite_range`, `css_non_negative_range` and `css_infinite_integer_range`
(`types_numeric_range`) are zero-valued `var`s; their C++ initializers were not translated.
## Deviations and notes
- `create_invalid_selector` clones its by-value vector before trimming it (DESIGN §3.3 rule 2).
- `parse_media_feature_value`'s first block and `parse_mf_range`'s rewinding scan are functions
of their own (their transactions end where the C++ scopes end).
- The `dbgln` of `parse_as_syntax` prints the component's address as `0x<hex>` (AK pads to 16
digits); it is a debug log only.
- An empty blacklist (`{}`) is an empty span local: `[]` has no Base spelling (§5.4).
## Tests
- `tests_css_rule_parsing_cases` (273 cases) and `tests_css_rule_parsing`: the cases run through
the port and a local oracle (`luce-browser-tools/oracles/luce-browser-engine/css_rule_parsing`:
`oracle.cpp` links the reference build's LibWeb objects like r30b's, `cases.txt`,
`gen_luce_cases.py` writes the table, `build.sh`), compared byte for byte with the
ErrorReporter's errors: `<syntax>` (dump and serialization, custom-ident limited), compound
selectors with type, universal, class, id, attribute (every match and case type, every error),
pseudo-class (idents, An+B, `:lang`, `:dir`, `:heading`, errors) and pseudo-element errors,
An+B patterns, combinators, `<wq-name>` with and without wildcards, complex-selector and
`@page` errors, `<media-type>` failures, `<layer-name>`, the error paths of every rule
converter reachable without stubs, and `@function` preludes. The cases are chosen to stop
before other regions' stubs (`cases.txt` says which); the oracle runs every path, so cases can
be added as those regions land.
- Focused tests: `is_media_feature_value_token`, `<mf-name>`, `<mf-comparison>`, comparison
matching, the `not`/`only` modifiers, syntax nodes made directly (`<type>` nodes, multipliers,
alternatives, casts) and joining component values.
## Compiler issues
None. Language limits worked with: no empty array literal; a char literal adapts to `u8`, not
`u32` (`(u32)'x'` for delims).