ElemApi

This is the foundation of the yaidom uniform query API. Many DOM-like element implementations in yaidom mix in this trait (indirectly, because some implementing sub-trait is mixed in), thus sharing this query API.

This trait typically does not show up in application code using yaidom, yet its (uniform) API does. Hence, it makes sense to read the documentation of this trait, knowing that the API is offered by multiple element implementations.

This trait is purely abstract. The most common implementation of this trait is eu.cdevreeze.yaidom.queryapi.ElemLike. That trait only knows about elements (and not about other nodes), and only knows that elements can have child elements (again not knowing about other child nodes). Using this minimal knowledge alone, it offers methods to query for descendant elements, descendant-or-self methods, or sub-collections thereof. It is this minimal knowledge that makes this API uniform.

This query API leverages the Scala Collections API. Query results can be manipulated using the Collections API, and the query API implementation (in ElemLike) uses the Collections API internally.

ElemApi examples

To illustrate usage of this API, consider the following example. Let's say we want to determine if some XML has its namespace declarations (if any) only at the root element level. We show the query code for several yaidom DOM-like element implementations.

Note that it depends on the DOM-like element implementation how to query for namespace declarations, but the code to query for descendant or descendant-or-self elements remains the same. The method to retrieve all descendant elements is called findAllElems, and the method to retrieve all descendant-or-self elements is called findAllElemsOrSelf. The corresponding "filtering" methods are called filterElems and filterElemsOrSelf, respectively. Knowing this, it is easy to guess the other API method names.

Let's start with a yaidom DOM wrapper, named rootElem, of type DomElem, and query for the "offending" descendant elements:

rootElem filterElems (elem => !convert.DomConversions.extractNamespaceDeclarations(elem.wrappedNode.getAttributes).isEmpty)

This returns all offending elements, that is, all descendant elements of the root element (excluding the root element itself) that have at least one namespace declaration.

Now let's use an eu.cdevreeze.yaidom.simple.ElemBuilder, again named rootElem:

rootElem filterElems (elem => !elem.namespaces.isEmpty)

The query is the same as the preceding one, except for the retrieval of namespace declarations of an element. (It should be noted that class ElemBuilder already has a method allDeclarationsAreAtTopLevel.)

Finally, let's use a rootElem of type eu.cdevreeze.yaidom.indexed.Elem, which is immutable, but knows its ancestry:

rootElem filterElems (elem => !elem.namespaces.isEmpty)

This is exactly the same code as for ElemBuilder, because namespace declarations happen to be retrieved in the same way.

If we want to query for all elements with namespace declarations, including the root element itself, we could write:

rootElem filterElemsOrSelf (elem => !elem.namespaces.isEmpty)

In summary, the extremely simple ElemApi query API is indeed a uniform query API, offered by many different yaidom DOM-like element implementations.

ElemApi more formally

In order to get started using the API, this more formal section can safely be skipped. On the other hand, this section may provide a deeper understanding of the API.

The ElemApi trait can be understood in a precise mathematical sense, as shown below.

The most fundamental method of this trait is findAllChildElems. The semantics of the other methods can be defined directly or indirectly in terms of this method.

The basic operations definable in terms of that method are \ (alias for filterChildElems), \\ (alias for filterElemsOrSelf) and \\! (alias for findTopmostElemsOrSelf). Their semantics must be as if they had been defined as follows:

def filterChildElems(p: ThisElem => Boolean): immutable.IndexedSeq[ThisElem] =
  this.findAllChildElems.filter(p)

def filterElemsOrSelf(p: ThisElem => Boolean): immutable.IndexedSeq[ThisElem] =
  Vector(this).filter(p) ++ (this.findAllChildElems flatMap (_.filterElemsOrSelf(p)))

def findTopmostElemsOrSelf(p: ThisElem => Boolean): immutable.IndexedSeq[ThisElem] =
  if (p(this)) Vector(this)
  else (this.findAllChildElems flatMap (_.findTopmostElemsOrSelf(p)))

Moreover, we could have defined:

def filterElems(p: ThisElem => Boolean): immutable.IndexedSeq[ThisElem] =
  this.findAllChildElems flatMap (_.filterElemsOrSelf(p))

def findTopmostElems(p: ThisElem => Boolean): immutable.IndexedSeq[ThisElem] =
  this.findAllChildElems flatMap (_.findTopmostElemsOrSelf(p))

and:

def findAllElemsOrSelf: immutable.IndexedSeq[ThisElem] = filterElemsOrSelf(e => true)

def findAllElems: immutable.IndexedSeq[ThisElem] = filterElems(e => true)

The following properties must hold (in the absence of side-effects), and can indeed be proven (given the documented "definitions" of these operations):

// Filtering

elem.filterElems(p) == elem.findAllElems.filter(p)

elem.filterElemsOrSelf(p) == elem.findAllElemsOrSelf.filter(p)

// Finding topmost

elem.findTopmostElems(p) == {
  elem.filterElems(p) filter { e =>
    val hasNoMatchingAncestor = elem.filterElems(p) forall { _.findElem(_ == e).isEmpty }
    hasNoMatchingAncestor
  }
}

elem.findTopmostElemsOrSelf(p) == {
  elem.filterElemsOrSelf(p) filter { e =>
    val hasNoMatchingAncestor = elem.filterElemsOrSelf(p) forall { _.findElem(_ == e).isEmpty }
    hasNoMatchingAncestor
  }
}

(elem.findTopmostElems(p) flatMap (_.filterElemsOrSelf(p))) == (elem.filterElems(p))

(elem.findTopmostElemsOrSelf(p) flatMap (_.filterElemsOrSelf(p))) == (elem.filterElemsOrSelf(p))