Shorthand for filterChildElems(expandedName)
.
Shorthand for filterChildElems(expandedName)
.
Shorthand for filterChildElems(p)
.
Shorthand for filterChildElems(p)
. Use this shorthand only if the predicate is a short expression.
Shorthand for attributeOption(expandedName)
Shorthand for attributeOption(expandedName)
Shorthand for filterElemsOrSelf(expandedName)
.
Shorthand for filterElemsOrSelf(expandedName)
.
Shorthand for filterElemsOrSelf(p)
.
Shorthand for filterElemsOrSelf(p)
. Use this shorthand only if the predicate is a short expression.
Shorthand for findTopmostElemsOrSelf(expandedName)
.
Shorthand for findTopmostElemsOrSelf(expandedName)
.
Shorthand for findTopmostElemsOrSelf(p)
.
Shorthand for findTopmostElemsOrSelf(p)
. Use this shorthand only if the predicate is a short expression.
Returns the value of the attribute with the given expanded name, and throws an exception otherwise.
Returns the value of the attribute with the given expanded name, and throws an exception otherwise.
Returns the value of the attribute with the given expanded name, if any, wrapped in an Option
.
Returns the value of the attribute with the given expanded name, if any, wrapped in an Option
.
Shorthand for childNodeIndexesByPathEntries.getOrElse(childPathEntry, -1)
.
Shorthand for childNodeIndexesByPathEntries.getOrElse(childPathEntry, -1)
.
The faster this method is, the better.
Returns a Map from path entries (with respect to this element as parent element) to child node indexes.
Returns a Map from path entries (with respect to this element as parent element) to child node indexes. The faster this method is, the better.
Returns the child nodes of this element, in the correct order
Returns the paths of child elements obeying the given predicate
Returns the paths of child elements obeying the given predicate
Returns the child elements with the given expanded name
Returns the child elements with the given expanded name
Returns the child elements obeying the given predicate.
Returns the child elements obeying the given predicate. This method could be defined as:
def filterChildElems(p: E => Boolean): immutable.IndexedSeq[E] = this.findAllChildElems.filter(p)
Returns the paths of descendant-or-self elements that obey the given predicate.
Returns the paths of descendant-or-self elements that obey the given predicate.
That is, the result is equivalent to the paths of findAllElemsOrSelf filter p
.
Returns the paths of descendant elements obeying the given predicate, that is, the paths of findAllElems filter p
Returns the paths of descendant elements obeying the given predicate, that is, the paths of findAllElems filter p
Returns the descendant elements with the given expanded name
Returns the descendant elements with the given expanded name
Returns the descendant elements obeying the given predicate.
Returns the descendant elements obeying the given predicate. This method could be defined as:
this.findAllChildElems flatMap (_.filterElemsOrSelf(p))
Returns the descendant-or-self elements that have the given expanded name
Returns the descendant-or-self elements that have the given expanded name
Returns the descendant-or-self elements obeying the given predicate.
Returns the descendant-or-self elements obeying the given predicate. This method could be defined as:
def filterElemsOrSelf(p: E => Boolean): immutable.IndexedSeq[E] = Vector(this).filter(p) ++ (this.findAllChildElems flatMap (_.filterElemsOrSelf(p)))
It can be proven that the result is equivalent to findAllElemsOrSelf filter p
.
Returns the ElemPath
entries of all child elements, in the correct order.
Returns the ElemPath
entries of all child elements, in the correct order.
Equivalent to findAllChildElemsWithPathEntries map { _._2 }
.
Returns findAllChildElemsWithPathEntries map { case (e, pe) => ElemPath.from(pe) }
Returns findAllChildElemsWithPathEntries map { case (e, pe) => ElemPath.from(pe) }
Core method that returns all child elements, in the correct order.
Core method that returns all child elements, in the correct order. Other operations can be defined in terms of this one.
Returns all child elements with their ElemPath
entries, in the correct order.
Returns all child elements with their ElemPath
entries, in the correct order. This method should be very efficient.
The implementation must be such that the following holds: (findAllChildElemsWithPathEntries map (_._1)) == findAllChildElems
Returns the path of this element followed by the paths of all descendant elements (that is, the descendant-or-self elements)
Returns the path of this element followed by the paths of all descendant elements (that is, the descendant-or-self elements)
Returns the paths of all descendant elements (not including this element).
Returns the paths of all descendant elements (not including this element). Equivalent to findAllElemOrSelfPaths.drop(1)
Returns all descendant elements (not including this element).
Returns all descendant elements (not including this element). This method could be defined as filterElems { e => true }
.
Equivalent to findAllElemsOrSelf.drop(1)
.
Returns this element followed by all descendant elements (that is, the descendant-or-self elements).
Returns this element followed by all descendant elements (that is, the descendant-or-self elements).
This method could be defined as filterElemsOrSelf { e => true }
.
Returns the first found attribute value of an attribute with the given local name, if any, wrapped in an Option
.
Returns the first found attribute value of an attribute with the given local name, if any, wrapped in an Option
.
Because of differing namespaces, it is possible that more than one such attribute exists, although this is not often the case.
Returns the first found child element with the given expanded name, if any, wrapped in an Option
Returns the first found child element with the given expanded name, if any, wrapped in an Option
Returns the first found child element obeying the given predicate, if any, wrapped in an Option
.
Returns the first found child element obeying the given predicate, if any, wrapped in an Option
.
This method could be defined as filterChildElems(p).headOption
.
Returns the path of the first found child element obeying the given predicate, if any, wrapped in an Option
Returns the path of the first found child element obeying the given predicate, if any, wrapped in an Option
Returns the first found (topmost) descendant element with the given expanded name, if any, wrapped in an Option
Returns the first found (topmost) descendant element with the given expanded name, if any, wrapped in an Option
Returns the first found (topmost) descendant element obeying the given predicate, if any, wrapped in an Option
.
Returns the first found (topmost) descendant element obeying the given predicate, if any, wrapped in an Option
.
This method could be defined as filterElems(p).headOption
.
Returns the first found (topmost) descendant-or-self element with the given expanded name, if any, wrapped in an Option
Returns the first found (topmost) descendant-or-self element with the given expanded name, if any, wrapped in an Option
Returns the first found (topmost) descendant-or-self element obeying the given predicate, if any, wrapped in an Option
.
Returns the first found (topmost) descendant-or-self element obeying the given predicate, if any, wrapped in an Option
.
This method could be defined as filterElemsOrSelf(p).headOption
.
Returns the path of the first found (topmost) descendant-or-self element obeying the given predicate, if any, wrapped in an Option
Returns the path of the first found (topmost) descendant-or-self element obeying the given predicate, if any, wrapped in an Option
Returns the path of the first found (topmost) descendant element obeying the given predicate, if any, wrapped in an Option
Returns the path of the first found (topmost) descendant element obeying the given predicate, if any, wrapped in an Option
Returns the paths of the descendant-or-self elements that obey the given predicate, such that no ancestor obeys the predicate.
Returns the paths of the descendant-or-self elements that obey the given predicate, such that no ancestor obeys the predicate.
Returns the paths of the descendant elements obeying the given predicate that have no ancestor obeying the predicate
Returns the paths of the descendant elements obeying the given predicate that have no ancestor obeying the predicate
Returns the descendant elements with the given expanded name that have no ancestor with the same name
Returns the descendant elements with the given expanded name that have no ancestor with the same name
Returns the descendant elements obeying the given predicate that have no ancestor obeying the predicate.
Returns the descendant elements obeying the given predicate that have no ancestor obeying the predicate. This method could be defined as:
this.findAllChildElems flatMap (_.findTopmostElemsOrSelf(p))
Returns the descendant-or-self elements with the given expanded name that have no ancestor with the same name
Returns the descendant-or-self elements with the given expanded name that have no ancestor with the same name
Returns the descendant-or-self elements obeying the given predicate, such that no ancestor obeys the predicate.
Returns the descendant-or-self elements obeying the given predicate, such that no ancestor obeys the predicate. This method could be defined as:
def findTopmostElemsOrSelf(p: E => Boolean): immutable.IndexedSeq[E] = if (p(this)) Vector(this) else (this.findAllChildElems flatMap (_.findTopmostElemsOrSelf(p)))
Finds the element with the given ElemPath
(where this element is the root), if any, wrapped in an Option
.
Finds the element with the given ElemPath
(where this element is the root), if any, wrapped in an Option
.
Returns the equivalent of findWithElemPath(ElemPath(immutable.IndexedSeq(entry)))
, but it should be very efficient.
Returns the equivalent of findWithElemPath(ElemPath(immutable.IndexedSeq(entry)))
, but it should be very efficient.
Indeed, it is function findWithElemPath
that is defined in terms of this function, findWithElemPathEntry
, and not
the other way around.
Returns the single child element with the given expanded name, and throws an exception otherwise
Returns the single child element with the given expanded name, and throws an exception otherwise
Returns the single child element obeying the given predicate, and throws an exception otherwise.
Returns the single child element obeying the given predicate, and throws an exception otherwise.
This method could be defined as findChildElem(p).get
.
Returns the path of the single child element obeying the given predicate, and throws an exception otherwise
Returns the path of the single child element obeying the given predicate, and throws an exception otherwise
Returns (the equivalent of) findWithElemPath(path).get
Returns (the equivalent of) findWithElemPath(path).get
The local name (or local part).
The local name (or local part). Convenience method.
Returns a copy in which the child at the given position (0-based) has been removed
Returns a copy in which the given child has been inserted at the end
Returns a copy in which the given child has been inserted at the given position (0-based)
The attributes as a mapping from EName
s (instead of QName
s) to values.
The attributes as a mapping from EName
s (instead of QName
s) to values.
The implementation must ensure that resolvedAttributes.toMap.size == resolvedAttributes.size
.
Namespace declarations are not considered attributes in yaidom, so are not included in the result.
Resolved name of the element, as EName
Resolved name of the element, as EName
Returns updated(path) { e => newElem }
Method that "functionally updates" the tree with this element as root element, by applying the passed function to the element that has the given ElemPath (compared to this element as root).
Method that "functionally updates" the tree with this element as root element, by applying the passed function to the element that has the given ElemPath (compared to this element as root).
The method throws an exception if no element is found with the given path.
It can be defined (recursively) as follows:
if (path == ElemPath.Root) f(self) else updated(path.firstEntry) { e => e.updated(path.withoutFirstEntry)(f) }
Core method that "functionally updates" the tree with this element as root element, by applying the passed function to the element that has the given Entry (compared to this element as root).
Core method that "functionally updates" the tree with this element as root element, by applying the passed function to the element that has the given Entry (compared to this element as root).
The method throws an exception if no element is found with the given path entry.
It can be defined as follows:
val idx = self.childNodeIndex(pathEntry)
self.withUpdatedChildren(idx, f(children(idx).asInstanceOf[E]))
Method that "functionally updates" the tree with this element as root element, by applying the passed function to all child elements with the given path entries (compared to this element as root).
Method that "functionally updates" the tree with this element as root element, by applying the passed function to all child elements with the given path entries (compared to this element as root).
It can be defined as follows (ignoring exceptions):
val newChildren = childNodeIndexesByPathEntries.filterKeys(pathEntries).toSeq.sortBy(_._2).reverse.foldLeft(children) { case (acc, (pathEntry, idx)) => acc.updated(idx, f(acc(idx).asInstanceOf[E], pathEntry)) } withChildren(newChildren)
Method that "functionally updates" the tree with this element as root element, by applying the passed function to all descendant-or-self elements with the given paths (compared to this element as root).
Method that "functionally updates" the tree with this element as root element, by applying the passed function to all descendant-or-self elements with the given paths (compared to this element as root).
It can be defined (recursively) as follows (ignoring exceptions):
def updatedAtPaths(paths: Set[ElemPath])(f: (E, ElemPath) => E): E = { val pathsByPathEntries = paths.filter(path => !path.isRoot).groupBy(path => path.firstEntry) val resultWithoutSelf = self.updatedAtPathEntries(pathsByPathEntries.keySet) { (che, pathEntry) => val newChe = che.updatedAtPaths(paths.map(_.withoutFirstEntry)) { (elem, relativePath) => f(elem, relativePath.prepend(pathEntry)) } newChe } if (paths.contains(ElemPath.Root)) f(resultWithoutSelf, ElemPath.Root) else resultWithoutSelf }
It is also equivalent to:
val pathsReversed = findAllElemOrSelfPaths.filter(p => paths.contains(p)).reverse pathsReversed.foldLeft(self) { case (acc, path) => acc.updated(path) { e => f(e, path) } }
Returns updatedWithNodeSeq(path) { e => newNodes }
"Functionally updates" the tree with this element as root element, by applying the passed function to the element that has the given ElemPath (compared to this element as root).
"Functionally updates" the tree with this element as root element, by applying the passed function to the element that has the given ElemPath (compared to this element as root). If the given path is the root path, this element itself is returned unchanged.
This function could be defined as follows:
// First define function g as follows: def g(e: Elem): Elem = { if (path == ElemPath.Root) e else { e.withPatchedChildren( e.childNodeIndex(path.lastEntry), f(e.findWithElemPathEntry(path.lastEntry).get), 1) } } // Then the function updatedWithNodeSeq(path)(f) could be defined as: updated(path.parentPathOption.getOrElse(ElemPath.Root))(g)
After all, this is just a functional update that replaces the parent element, if it exists.
The method throws an exception if no element is found with the given path.
Method that "functionally updates" the tree with this element as root element, by applying the passed function to all child elements with the given path entries (compared to this element as root).
Method that "functionally updates" the tree with this element as root element, by applying the passed function to all child elements with the given path entries (compared to this element as root).
It can be defined as follows (ignoring exceptions):
val indexesByPathEntries = childNodeIndexesByPathEntries.filterKeys(pathEntries).toSeq.sortBy(_._2).reverse val newChildGroups = indexesByPathEntries.foldLeft(self.children.map(n => immutable.IndexedSeq(n))) { case (acc, (pathEntry, idx)) => acc.updated(idx, f(acc(idx).head.asInstanceOf[E], pathEntry)) } withChildren(newChildGroups.flatten)
Method that "functionally updates" the tree with this element as root element, by applying the passed function to all descendant elements with the given paths (compared to this element as root), but ignoring the root path.
Method that "functionally updates" the tree with this element as root element, by applying the passed function to all descendant elements with the given paths (compared to this element as root), but ignoring the root path.
It can be defined as follows (ignoring exceptions):
val pathsByParentPaths = paths.filter(path => !path.isRoot).groupBy(path => path.parentPath) self.updatedAtPaths(pathsByParentPaths.keySet) { (elem, path) => val childPathEntries = pathsByParentPaths(path).map(_.lastEntry) elem.updatedWithNodeSeqAtPathEntries(childPathEntries) { (che, pathEntry) => f(che, path.append(pathEntry)) } }
Returns an element with the same name, attributes and scope as this element, but with the given child nodes
Shorthand for withChildren(children.patch(from, newChildren, replace))
Shorthand for withChildren(children.updated(index, newChild))
This is the functional update part of the yaidom uniform query API. It is a sub-trait of trait PathAwareElemApi. Only a few 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 UpdatableElemLike. The trait has all the knowledge of its super-trait, but in addition to that knows the following:
Obviously methods
,children
andwithChildren
must be consistent with methods such aschildNodeIndexesByPathEntries
andfindAllChildElems
.findAllChildElemsWithPathEntries
Using this minimal knowledge alone, trait
not only offers the methods of its parent trait, but also:UpdatableElemLike
In other words, the
trait is quite a rich query API, considering the minimal knowledge it needs to have about elements.UpdatableElemApi
For the conceptual difference with "transformable" elements, see trait TransformableElemApi.
This query API leverages the Scala Collections API. Query results can be manipulated using the Collections API, and the query API implementation (in
) uses the Collections API internally.UpdatableElemLike
UpdatableElemApi examples
To illustrate the use of this API, consider the following example XML:
Suppose this XML has been parsed into Elem variable named
. Then we can add a book as follows, where we "forget" the 2nd author for the moment:bookstoreElem
Note that the namespace declarations for prefixes
andbook
had to be repeated in the Scala XML literal for the added book, because otherwise theauth
method would throw an exception (sinceconvertToElem
instances cannot be created unless all element and attribute QNames can be resolved as ENames).Elem
The resulting bookstore seems ok, but if we print
, the result does not look pretty. This can be fixed if the last assignment is replaced by:convertElem(bookstoreElem)
bookstoreElem = bookstoreElem.plusChild(fpBookElem).prettify(2)
knowing that an indentation of 2 spaces has been used throughout the original XML. Method
is expensive, so it is best not to invoke it within a tight loop. As an alternative, formatting can be left to theprettify
, of course.DocumentPrinter
The assignment above is the same as the following one:
bookstoreElem = bookstoreElem.withChildren(bookstoreElem.children :+ fpBookElem).prettify(2)
There are several methods to functionally update the children of an element. For example, method
is overloaded, and the other variant can insert a child at a given 0-based position. Other "children update" methods areplusChild
,minusChild
andwithPatchedChildren
.withUpdatedChildren
Let's now turn to functional update methods that take
instances or collections thereof. In the example above the second author of the added book is missing. Let's fix that:ElemPath
Clearly the resulting bookstore element is nicely formatted, but there was another possible issue that was taken into account. See the line of code transforming the "raw result". That line was added in order to prevent namespace undeclarations, which for XML version 1.0 are not allowed (with the exception of the default namespace). After all, the XML for the second author was created with only the
namespace declared. Without the above-mentioned line of code, a namespace undeclaration for prefixauth
would have occurred in the resulting XML, thus leading to an invalid XML 1.0 element tree.book
To illustrate functional update methods taking collections of element paths, let's remove the added book from the book store. Here is one (somewhat inefficient) way to do that:
There are very many ways to write this functional update, using different functional update methods in trait
, or even only using transformation methods in traitUpdatableElemApi
(thus not using element paths).TransformableElemApi
The example code above is enough to get started using the
methods, but it makes sense to study the entire API, and practice with it. Always keep in mind that functional updates typically mess up formatting and/or namespace (un)declarations, unless these aspects are taken into account.UpdatableElemApi
The node supertype of the element subtype
The captured element subtype