NodeBuilder

DSL to build Elems (or Documents) without having to pass parent Scopes around. For example:

import NodeBuilder._

elem(
 qname = QName("dbclass:Magazine"),
 attributes = Vector(QName("Month") -> "February", QName("Year") -> "2009"),
 namespaces = Declarations.from("dbclass" -> "http://www.db-class.org"),
 children = Vector(
   elem(
     qname = QName("dbclass:Title"),
     children = Vector(text("Newsweek"))))).build()

The latter expression could also be written as follows:

elem(
 qname = QName("dbclass:Magazine"),
 attributes = Vector(QName("Month") -> "February", QName("Year") -> "2009"),
 namespaces = Declarations.from("dbclass" -> "http://www.db-class.org"),
 children = Vector(
   textElem(QName("dbclass:Title"), "Newsweek"))).build()

There is an impedance mismatch between XML's scoping rules (which are top-down, from root to leaves) and "functional trees" (which are built bottom-up, from leaves to root). In the context of the Anti-XML library, Daniel Spiewak explained this impedance mismatch in https://github.com/djspiewak/anti-xml/issues/78. In yaidom, however, this impedance mismatch is far less severe. Yaidom distinguishes between eu.cdevreeze.yaidom.simple.Node and eu.cdevreeze.yaidom.simple.NodeBuilder, and eu.cdevreeze.yaidom.simple.Elem and eu.cdevreeze.yaidom.simple.ElemBuilder in particular. Elems have (fixed, resolved) Scopes, but ElemBuilders do not. Using NodeBuilders, Scope determination is postponed. Only ElemBuilders can have unbound prefixes, but only Elems have (resolved) scopes. Instead of a eu.cdevreeze.yaidom.core.Scope, an ElemBuilder has a eu.cdevreeze.yaidom.core.Declarations.

Another reason that the above-mentioned impedance mismatch is less of a problem in practice is that typically the XML trees (as NodeBuilders or directly as Nodes) are built in a top-down manner. The eu.cdevreeze.yaidom.simple.ConverterToDocuments in package convert recursively build Elems in a top-down manner, possibly creating an Elem instance (for each element) twice (first without children, and finally as a copy with children added).

When using NodeBuilders to create a Document, this Document typically contains no "ignorable whitespace". This may cause the Document not to be pretty-printed when using a (default) eu.cdevreeze.yaidom.print.DocumentPrinter to convert the Document to an XML string. See also the classes in package eu.cdevreeze.yaidom.print.