Converter from A
(which can be anything) to eu.cdevreeze.yaidom.Document.
Converter from A
(which can be anything) to eu.cdevreeze.yaidom.Elem.
Namespace declarations (and undeclarations), typically at the level of one element.
Builder of a yaidom Document.
Document
.
Minimal API for Documents, having a type parameter for the element type.
Converter from eu.cdevreeze.yaidom.Document to A
(which can be anything, such as a DOM Document
).
Expanded name.
Immutable, thread-safe element node.
This is the best known part of the yaidom uniform query API.
Builder for elements.
Converter from eu.cdevreeze.yaidom.Elem to A
(which can be anything, such as a DOM Element
).
API and implementation trait for elements as containers of elements, each having a name and possible attributes.
An entity reference.
API and implementation trait for elements that can be asked for the ancestor elements, if any.
Trait defining the contract for elements as text containers.
Immutable XML Node.
DSL to build Elem
s (or Document
s) without having to pass parent Scope
s around.
This is the foundation of the yaidom uniform query API.
API and implementation trait for elements as containers of elements, as element nodes in a node tree.
Unique identification of a descendant (or self) Elem
given a root Elem
.
This is the Path-aware part of the yaidom uniform query API.
API and implementation trait for elements as containers of elements, each having a name and possible attributes, as well as having awareness of paths.
Builder for Path
instances.
Qualified name.
Scope mapping prefixes to namespace URIs, as well as holding an optional default namespace.
This is the element transformation part of the yaidom query and update API.
API and implementation trait for transformable elements.
This is the functional update part of the yaidom uniform query API.
API and implementation trait for functionally updatable elements.
(Since version 0.7.1) Use Path instead
(Since version 0.7.1) Use PathBuilder instead
This companion object offers some convenience factory methods for "element predicates", that can be used in yaidom queries.
This singleton object contains a DSL to easily create deeply nested Elems.
Generator for parsers of "tree representation" expressions.
Support for conversions from/to yaidom.
This package contains element representations that contain the "context" of the element, including the URI of the containing document.
Wrapper around class org.w3c.dom.Element
, adapting it to the eu.cdevreeze.yaidom.ElemLike API.
This package contains element representations that contain the "context" of the element.
Support for parsing XML into yaidom Document
s and Elem
s.
Support for "printing" yaidom Document
s and Elem
s.
This package contains element representations that can be compared for (some notion of "value") equality, unlike normal yaidom nodes.
Wrapper around class scala.xml.Elem
, adapting it to the eu.cdevreeze.yaidom.ElemLike API.
(Since version 0.7.1) Use Path instead
(Since version 0.7.1) Use PathBuilder instead
Yaidom is yet another Scala immutable DOM-like XML API. The other well-known Scala immutable DOM-like APIs are the standard scala.xml API and Anti-XML. The latter API is considered by many to be an improvement over the former, but both APIs:
Yaidom takes a different approach, avoiding XPath-like query support, and offering good namespace and decent (functional) update support. Yaidom is also characterized by mathematical precision and clarity. Still, the API remains practical and pragmatic. In particular, the API user has much configuration control over parsing and serialization, because yaidom exposes the underlying JAXP parsers and serializers, which can be configured by the library user.
Yaidom chooses its battles. For example, given that DTDs do not know about namespaces, yaidom offers good namespace support, but ignores DTDs entirely. Of course the underlying XML parser may still validate XML against a DTD, if so desired. As another example, yaidom tries to leave the handling of the gory details of XML processing (such as whitespace handling) as much as possible to JAXP (and JAXP parser/serializer configuration). As yet another example, yaidom knows nothing about (XML Schema) types of elements and attributes.
Yaidom, and in particular this package, contains the following layers:
It makes sense to read this documentation, because it helps in getting up-to-speed with yaidom.
Basic concepts
In real world XML, elements (and sometimes attributes) tend to have names within a certain namespace. There are 2 kinds of names at play here:
book:Title
, and unprefixed names, such asEdition
{http://bookstore/book}Title
(in James Clark notation), and not having a namespace, such asEdition
They are represented by immutable classes eu.cdevreeze.yaidom.QName and eu.cdevreeze.yaidom.EName, respectively.
Qualified names occur in XML, whereas expanded names do not. Yet qualified names have no meaning on their own. They need to be resolved to expanded names, via the in-scope namespaces. Note that the term "qualified name" is often used for what yaidom (and the Namespaces specification) calls "expanded name", and that most XML APIs do not distinguish between the 2 kinds of names. Yaidom has to clearly make this distinction, in order to model namespaces correctly.
To resolve qualified names to expanded names, yaidom distinguishes between:
They are represented by immutable classes eu.cdevreeze.yaidom.Declarations and eu.cdevreeze.yaidom.Scope, respectively.
Namespace declarations occur in XML, whereas in-scope namespaces do not. The latter are the accumulated effect of the namespace declarations of the element itself, if any, and those in ancestor elements.
Note: in the code examples below, we assume the following import:
import eu.cdevreeze.yaidom._
To see the resolution of qualified names in action, consider the following sample XML:
Consider the last element with qualified name
QName("book:Book")
. To resolve this qualified name as expanded name, we need to know the namespaces in scope at that element. To compute the in-scope namespaces, we need to accumulate the namespace declarations of the lastbook:Book
element and of its ancestor element(s), starting with the root element.The start Scope is "parent scope"
Scope.Empty
. Then, in the root element we find namespace declarations:This leads to the following namespaces in scope at the root element:
which is equal to:
We find no other namespace declarations in the last
book:Book
element or its ancestor(s), so the computed scope is also the scope of the lastbook:Book
element.Then
QName("book:Book")
is resolved as follows:which is equal to:
This namespace support in yaidom has mathematical rigor. The immutable classes
QName
,EName
,Declarations
andScope
have precise definitions, reflected in their implementations, and they obey some interesting properties. For example, if we correctly define Scope operationrelativize
(along withresolve
), we get:This may not sound like much, but by getting the basics right, yaidom succeeds in offering first-class support for XML namespaces, without the magic and namespace-related bugs often found in other XML libraries.
There are 2 other basic concepts in this package, representing paths to elements:
They are represented by immutable classes eu.cdevreeze.yaidom.PathBuilder and eu.cdevreeze.yaidom.Path, respectively.
Path builders are like canonical XPath expressions, yet they do not contain the root element itself, and indexing starts with 0 instead of 1.
For example, the last name of the first author of the last book element has path:
This path could be written as path builder as follows:
Using the Scope mentioned earlier, the latter path builder resolves to the path given before that, by invoking method
PathBuilder.build(scope)
. In order for this to work, the Scope must be invertible. That is, there must be a one-to-one correspondence between prefixes ("" for the default namespace) and namespace URIs, because otherwise the index numbers may differ. Also note that the prefixesbook
andauth
in the path builder are arbitrary, and need not match with the prefixes used in the XML tree itself.Uniform query API traits
Yaidom provides a relatively small query API, to query an individual element for collections of child elements, descendant elements or descendant-or-self elements. The resulting collections are immutable Scala collections, that can further be manipulated using the Scala Collections API.
This query API is uniform, in that different element implementations share (most of) the same query API. It is also element-centric (unlike standard Scala XML and Anti-XML).
For example, consider the XML example given earlier, as a Scala XML literal named
bookstore
. We can wrap this Scala XML Elem into a yaidom wrapper of type eu.cdevreeze.yaidom.scalaxml.ScalaXmlElem, namedbookstoreElem
. Then we can query for all books, that is, all descendant-or-self elements with resolved (or expanded) nameEName("{http://bookstore/book}Book")
, as follows:The result would be an immutable IndexedSeq of
ScalaXmlElem
instances, holding 2 book elements.We could instead have written:
bookstoreElem.filterElemsOrSelf(EName("{http://bookstore/book}Book"))
with the same result.
Instead of searching for appropriate descendant-or-self elements, we could have searched for descendant elements only, without altering the result in this case:
or:
bookstoreElem.filterElems(EName("{http://bookstore/book}Book"))
We could even have searched for appropriate child elements only, without altering the result in this case:
or:
bookstoreElem.filterChildElems(EName("{http://bookstore/book}Book"))
or, knowing that all child elements are books:
We could find all authors of the Scala book as follows:
or:
We could even use operator notation, as follows:
or:
where
\\
stands forfilterElemsOrSelf
.Now suppose the same XML is stored in a (org.w3c.dom) DOM tree, wrapped in a eu.cdevreeze.yaidom.dom.DomElem
bookstoreElem
. Then the same queries would use exactly the same code as above! The result would be a collection ofDomElem
instances instead ofScalaXmlElem
instances, however. There are many more element implementations in yaidom, and they share (most of) the same query API. Therefore this query API is called a uniform query API.The last example, using operator notation, looks a bit more "XPath-like". It is more verbose than queries in Scala XML, however, partly because in yaidom these operators cannot be chained. Yet this is with good reason. Yaidom does not blur the distinction between elements and element collections, and therefore does not offer any XPath experience. The small price paid in verbosity is made up for by precision. The yaidom query API traits have very precise definitions of their operations, as can be seen in the corresponding documentation.
The uniform query API traits turn minimal APIs into richer APIs, where each richer API is defined very precisely in terms of the minimal API. The top-level query API trait is eu.cdevreeze.yaidom.ParentElemLike. It needs to be given a method implementation to query for child elements (not child nodes in general, but just child elements!), and it offers methods to query for some or all child elements, descendant elements, and descendant-or-self elements. That is, the minimal API consists of abstract method
findAllChildElems
, and it offers methods such asfilterChildElems
,filterElems
andfilterElemsOrSelf
. This trait has no knowledge about elements at all, other than the fact that elements can have child elements.Sub-trait eu.cdevreeze.yaidom.ElemLike adds minimal knowledge about elements themselves, viz. that elements have a "resolved" (or expanded) name, and "resolved" attributes (mapping attribute expanded names to attribute values). That is, it needs to be given implementations of abstract methods
resolvedName
andresolvedAttributes
, and then offers methods to query for attributes or child/descendant/descendant-or-self elements with a given expanded name. The trait is trivially defined in terms of its super-trait.It is important to note that yaidom does not consider namespace declarations to be attributes themselves. Otherwise, there would have been circular dependencies between both concepts, because attributes with namespaces require in-scope namespaces and therefore namespace declarations for resolving the names of these attributes.
Note that traits eu.cdevreeze.yaidom.ElemLike and eu.cdevreeze.yaidom.ParentElemLike only know about elements, not about other kinds of nodes. Of course the actual element implementations mixing in this query API know about other node types, but that knowledge is outside the uniform query API. Note that the example queries above only use the minimal element knowledge that traits
ElemLike
andParentElemLike
have about elements. Therefore the query code can be used unchanged for different element implementations.The
ElemLike
trait has sub-trait eu.cdevreeze.yaidom.PathAwareElemLike. It adds knowledge about paths. Paths can be queried (in the same way that elements can be queried in traitParentElemLike
), and elements can be found given a path.For example, to query for the Scala book authors, the following alternative code can be used (if the used element implementation mixes in trait
PathAwareElemLike
, which is not the case for the Scala XML and DOM wrappers above):The
PathAwareElemLike
trait has sub-trait eu.cdevreeze.yaidom.UpdatableElemLike. This trait offers functional updates at given paths. Whereas the super-traits know only about elements, this trait knows that elements have some node super-type.Instead of functional updates at given paths, elements can also be "transformed" functionally without specifying any paths. This is offered by trait eu.cdevreeze.yaidom.TransformableElemLike, which unlike the traits above has no super-traits. The Scala XML and DOM wrappers above do not mix in this trait.
Some element implementations
The uniform query API traits, especially
ParentElemLike
and its sub-traitElemLike
are mixed in by many element implementations. In this package there are 2 immutable element implementations, eu.cdevreeze.yaidom.ElemBuilder and eu.cdevreeze.yaidom.Elem.Class eu.cdevreeze.yaidom.Elem is the default element implementation of yaidom. It extends class eu.cdevreeze.yaidom.Node. The latter also has sub-classes for text nodes, comments, entity references and processing instructions. Class eu.cdevreeze.yaidom.Document contains a document
Elem
, but is not aNode
sub-class itself.The eu.cdevreeze.yaidom.Elem class has the following characteristics:
HasParent
Scope
, but noDeclarations
parse
andprint
offerDocumentParser
andDocumentPrinter
classes for parsing/serializing these defaultElem
(andDocument
) instancesCreating such
Elem
trees by hand is a bit cumbersome, partly because scopes have to be passed to eachElem
in the tree. The latter is not needed if we use class eu.cdevreeze.yaidom.ElemBuilder to create element trees by hand. When the tree has been fully created asElemBuilder
, invoke methodElemBuilder.build(parentScope)
to turn it into anElem
.Like their super-classes
Node
andNodeBuilder
, classesElem
andElemBuilder
have very much in common. Both are immutable, easy to compose (ElemBuilder
instances even more so), equality is reference equality, etc. The most important differences are as follows:Scope
, anElemBuilder
contains aDeclarations
ElemBuilder
easier to compose than anElem
, because no Scope needs to be passed around throughout the treeElemBuilder
uses a minimal query API, mixing in only traitsParentElemLike
andTransformableElemLike
ElemBuilder
neither keeps nor knows about Scopes, so does not know about resolved element/attribute namesThe Effective Java book element in the XML example above could have been written as
ElemBuilder
(without the inter-element whitespace) as follows:This
ElemBuilder
(say,eb
) lacks namespace declarations for prefixesbook
andauth
. So, the following returnsfalse
:while the following returns
true
:Indeed,
returns the element tree as
Elem
.Note that the distinction between
ElemBuilder
andElem
"solves" the mismatch that immutable ("functional") element trees are constructed in a bottom-up manner, while namespace scoping works in a top-down manner. (See also Anti-XML issue 78, in https://github.com/djspiewak/anti-xml/issues/78).There are many more element implementations in yaidom, most of them in sub-packages of this package. Yaidom is extensible in that new element implementations can be invented, for example elements that are better "roundtrippable" (at the expense of "composability"), or yaidom wrappers around other DOM-like APIs (such as XOM or JDOM2). The current element implementations in yaidom are:
Elem
by hand. See above.ElemLike
query API, but knows its ancestry, despite being immutable! This element implementation is handy for querying XML schemas, for example, because in schemas the ancestry of queried elements typically matters.indexed.Elem
, but also stores the document URI.ElemLike
query API.ElemLike
andHasParent
query APIs.This illustrates that especially trait
ElemLike
is a uniform query API in yaidom.Packages and dependencies
Yaidom has the following packages, and layering between packages:
convert
package depends on the yaidom root package.Indeed, all yaidom package dependencies are uni-directional.