Repository navigation
3.10.0
Character data that unmarshalling drops can now be reported. This is a per-call unmarshaller option beside onUnexpectedElement and onUnexpectedAttribute, unset by default:
context.createUnmarshaller({
onUnexpectedText: function (text, node, classInfo) { /* ... */ }
})What it does. <w:r>MISPLACED<w:t>x</w:t></w:r> unmarshals as a run holding w:t alone, and until now no callback fired for the lost string. onUnexpectedText is called once for each text or CDATA node that is dropped and that holds a character other than XML whitespace (space, tab, CR, LF):
textis the node's text as parsed, untrimmed.nodeis the text or CDATA node itself. ItsparentNodeis the containing element, and in Node it carrieslineNumberandcolumnNumber.classInfois the containing element's class info.
Text is dropped, and now reported, in three places:
- the element content of a class with no mixed property (a run, a paragraph, the body);
- any text inside an element whose class has no content (
<w:b>x</w:b>); - in any class, text the runtime treats as space although XML does not. For example, a lone U+00A0 or U+3000 in a run was dropped as if it were blank.
Whitespace-only text is never reported. Neither is text inside an element that onUnexpectedElement reports. A comment splits a text into two calls.
Calls come in document order with onUnexpectedElement's, before the containing element's onElement. The text stays dropped, and the return value is ignored. A callback that throws stops the unmarshal, located as #text (line N): .... The typings add UnmarshalCallbacks.onUnexpectedText?.
Why. @docx4j/generated-objects-ts reports misplaced children (its CR-017). A string read inside a run was the one misplaced form that vanished with no trace anywhere: Word 365's repair and JAXB drop it too. With this release, objects can report it, and core-ts can warn on load.
Cost. Unset, unmarshalling is within noise of 3.9.0. Set, it is about 2% slower on a pretty-printed document, the whitespace test on each indentation node. Across objects' fidelity corpus (359 checks), the option reported nothing. With it unset, every re-marshalled part was byte-identical to 3.9.0's.
What a consumer must do. Nothing. The runtime's jsonix-factory.js in this release is byte-identical to commit c259464, which objects tested.
Change request: docs/change-requests/jsonix-CR-013-report-dropped-character-data.md