Skip to content

3.10.0

Choose a tag to compare

@plutext plutext released this 27 Oct 20:57
· 9 commits to master since this release

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):

  • text is the node's text as parsed, untrimmed.
  • node is the text or CDATA node itself. Its parentNode is the containing element, and in Node it carries lineNumber and columnNumber.
  • classInfo is 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