Elem

Shorthand for filterChildElems(p). Use this shorthand only if the predicate is a short expression.

Shorthand for attributeOption(expandedName).

Shorthand for filterElemsOrSelf(p). Use this shorthand only if the predicate is a short expression.

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 QName value of the attribute with the given expanded name, and throws an exception otherwise

Returns the QName value of the attribute with the given expanded name, if any, wrapped in an Option. If the attribute exists, but its value is not a QName, an exception is thrown.

Returns the resolved QName value (as EName) of the attribute with the given expanded name, and throws an exception otherwise

Returns the resolved QName value (as EName) of the attribute with the given expanded name, if any, wrapped in an Option. None is returned if the attribute does not exist. If the QName value cannot be resolved given the scope of the element, an exception is thrown.

Returns the value of the attribute with the given expanded name, if any, wrapped in an Option.

The attributes of the element as mapping from QNames to values

Finds the child node index of the given path entry, or -1 if not found. More precisely, returns:

collectChildNodeIndexes(Set(pathEntry)).getOrElse(pathEntry, -1)

Returns the child nodes of this element, in the correct order

Filters the child elements with the given path entries, and returns a Map from the path entries of those filtered elements to the child node indexes. The result Map has no entries for path entries that cannot be resolved. This method should be fast, especially if the passed path entry set is small.

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 descendant elements obeying the given predicate. This method could be defined as:

this.findAllChildElems flatMap (_.filterElemsOrSelf(p))

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 element children

Returns all child elements paired with their path entries.

This method is final, so more efficient implementations for sub-types are not supported. This implementation is only efficient if finding all child elements as well as computing their resolved names is efficient. That is not the case for DOM wrappers or Scala XML Elem wrappers (due to their expensive Scope computations). On the other hand, those wrapper element implementations are convenient, but not intended for heavy use in production. Hence, this method should typically be fast enough.

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). 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. 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 obeying the given predicate, if any, wrapped in an Option. This method could be defined as filterChildElems(p).headOption.

Finds the child element with the given Path.Entry (where this element is the root), if any, wrapped in an Option.

This method is final, so more efficient implementations for sub-types are not supported. This implementation is only efficient if finding all child elements as well as computing their resolved names is efficient. That is not the case for DOM wrappers or Scala XML Elem wrappers (due to their expensive Scope computations). On the other hand, those wrapper element implementations are convenient, but not intended for heavy use in production. Hence, this method should typically be fast enough.

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 obeying the given predicate, if any, wrapped in an Option. This method could be defined as filterElemsOrSelf(p).headOption.

Finds the element with the given Path (where this element is the root), if any, wrapped in an Option.

That is, returns:

findReverseAncestryOrSelfByPath(path).map(_.last)

Note that for each non-empty Path, we have:

findElemOrSelfByPath(path) == findChildElemByPathEntry(path.firstEntry) flatMap (e => e.findElemOrSelfByPath(path.withoutFirstEntry))

Finds the reversed ancestry-or-self of the element with the given Path (where this element is the root), wrapped in an Option. None is returned if no element can be found at the given Path.

Hence, the resulting element collection, if any, starts with this element and ends with the element at the given Path, relative to this element.

This method comes in handy for (efficiently) computing base URIs, where the (reverse) ancestry-or-self is needed as input.

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

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 equivalent of) findChildElemByPathEntry(entry).get

Returns (the equivalent of) findElemOrSelfByPath(path).get

Returns (the equivalent of) findReverseAncestryOrSelfByPath(path).get

The local name, that is, the local part of the EName

Functionally removes the given attribute, if present.

More precisely, returns withAttributes(self.attributes filterNot (_._1 == attributeName)).

Returns a copy in which the child at the given position (0-based) has been removed. Throws an exception if index >= children.size.

Returns XmlStringUtils.normalizeString(text).

Returns an "equivalent" Elem in which the implicit namespace declarations throughout the tree do not contain any prefixed namespace undeclarations, given the passed parent Scope.

This method could be defined by recursion as follows:

def notUndeclaringPrefixes(parentScope: Scope): Elem = {
val newScope = parentScope.withoutDefaultNamespace ++ this.scope
this.copy(scope = newScope) transformChildElems { e => e.notUndeclaringPrefixes(newScope) }
}

It can be proven by structural induction that for each parentScope the XML remains the "same":

resolved.Elem(this.notUndeclaringPrefixes(parentScope)) == resolved.Elem(this)

Moreover, there are no prefixed namespace undeclarations:

NodeBuilder.fromElem(this.notUndeclaringPrefixes(parentScope))(Scope.Empty).findAllElemsOrSelf.
map(_.namespaces.withoutDefaultNamespace.retainingUndeclarations).toSet ==
  Set(Declarations.Empty)

Note that XML 1.0 does not allow prefix undeclarations, and this method helps avoid them, while preserving the "same" XML. So, when manipulating an Elem tree, calling notUndeclaringPrefixes(Scope.Empty) on the document element results in an equivalent Elem that has no prefixed namespace undeclarations anywhere in the tree.

Functionally adds or updates the given attribute.

More precisely, if an attribute with the same name exists at position idx (0-based), withAttributes(attributes.updated(idx, (attributeName -> attributeValue))) is returned. Otherwise, withAttributes(attributes :+ (attributeName -> attributeValue)) is returned.

Functionally adds or updates the given attribute, if a value is given. That is, returns if (attributeValueOption.isEmpty) self else plusAttribute(attributeName, attributeValueOption.get).

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). If index == children.size, adds the element at the end. If index > children.size, throws an exception.

Afterwards, the resulting element indeed has the given child at position index (0-based).

Returns a copy in which the given child, if any, has been inserted at the end. That is, returns plusChild(childOption.get) if the given optional child element is non-empty.

Returns a copy in which the given child, if any, has been inserted at the given position (0-based). That is, returns plusChild(index, childOption.get) if the given optional child element is non-empty.

Returns a copy in which the given children have been inserted at the end

"Prettifies" this Elem. That is, first calls method removeAllInterElementWhitespace, and then transforms the result by inserting text nodes with newlines and whitespace for indentation.

The QName of the element

The attributes as an ordered mapping from ENames (instead of QNames) to values, obtained by resolving attribute QNames against the attribute scope

The Elem name as EName, obtained by resolving the element QName against the Scope

The Scope stored with the element

Returns the concatenation of the texts of text children, including whitespace and CData. Non-text children are ignored. If there are no text children, the empty string is returned.

Returns QName(text.trim)

Returns the equivalent of scope.resolveQNameOption(textAsQName).get

Returns the tree representation string corresponding to this element, that is, toTreeRepr.

Possibly expensive, especially for large XML trees! Note that the toString method is often called implicitly, for example in logging statements. So, if the toString method is not used carefully, OutOfMemoryErrors may occur.

Same as toTreeRepr(emptyScope)

Returns the tree representation String, conforming to the tree representation DSL that creates NodeBuilders. That is, it does not correspond to the tree representation DSL of Nodes, but of NodeBuilders!

There are a couple of advantages of this method compared to some "toXmlString" method which returns the XML string:

• The parsed XML tree is made explicit, which makes debugging far easier, especially since method toString invokes this method
• The output of method toTreeRepr clearly corresponds to a NodeBuilder, and can indeed be parsed into one
• That toTreeRepr output is even valid Scala code
• When parsing the string into a NodeBuilder, the following is out of scope: character escaping (for XML), entity resolving, "ignorable" whitespace handling, etc.

Returns the same element, except that child elements have been replaced by applying the given function. Non-element child nodes occur in the result element unaltered.

That is, returns the equivalent of:

val newChildren =
  children map {
    case e: E => f(e)
    case n: N => n
  }
withChildren(newChildren)

Returns the same element, except that child elements have been replaced by applying the given function. Non-element child nodes occur in the result element unaltered.

That is, returns the equivalent of:

val newChildren =
  children flatMap {
    case e: E => f(e)
    case n: N => Vector(n)
  }
withChildren(newChildren)

Transforms the element by applying the given function to all its descendant elements, in a bottom-up manner.

That is, returns the equivalent of:

transformChildElems (e => e.transformElemsOrSelf(f))

Transforms the element by applying the given function to all its descendant-or-self elements, in a bottom-up manner.

That is, returns the equivalent of:

f(transformChildElems (e => e.transformElemsOrSelf(f)))

In other words, returns the equivalent of:

f(transformElems(f))

Transforms each descendant element to a node sequence by applying the given function to all its descendant-or-self elements, in a bottom-up manner.

That is, returns the equivalent of:

f(transformChildElemsToNodeSeq(e => e.transformElemsOrSelfToNodeSeq(f)))

In other words, returns the equivalent of:

f(transformElemsToNodeSeq(f))

Transforms each descendant element to a node sequence by applying the given function to all its descendant elements, in a bottom-up manner. The function is not applied to this element itself.

That is, returns the equivalent of:

transformChildElemsToNodeSeq(e => e.transformElemsOrSelfToNodeSeq(f))

It is equivalent to the following expression:

transformElemsOrSelf { e => e.transformChildElemsToNodeSeq(che => f(che)) }

Returns text.trim.

Returns updateChildElem(pathEntry) { e => newElem }

Functionally updates the tree with this element as root element, by applying the passed function to the element that has the given eu.cdevreeze.yaidom.core.Path.Entry (compared to this element as root).

It can be defined as follows:

updateChildElems(Set(pathEntry)) { case (che, pe) => f(che) }

Returns updateChildElemWithNodeSeq(pathEntry) { e => newNodes }

Functionally updates the tree with this element as root element, by applying the passed function to the element that has the given eu.cdevreeze.yaidom.core.Path.Entry (compared to this element as root).

It can be defined as follows:

updateChildElemsWithNodeSeq(Set(pathEntry)) { case (che, pe) => f(che) }

Invokes updateChildElems, passing the path entries for which the passed function is defined. It is equivalent to:

val editsByPathEntries: Map[Path.Entry, E] =
  findAllChildElemsWithPathEntries.flatMap({ case (che, pe) => f(che, pe).map(newE => (pe, newE)) }).toMap

updateChildElems(editsByPathEntries.keySet) { case (che, pe) => editsByPathEntries.getOrElse(pe, che) }

Updates the child elements with the given path entries, applying the passed update function.

That is, returns the equivalent of:

updateChildElemsWithNodeSeq(pathEntries) { case (che, pe) => Vector(f(che, pe)) }

If the set of path entries is small, this method is rather efficient.

Invokes updateChildElemsWithNodeSeq, passing the path entries for which the passed function is defined. It is equivalent to:

val editsByPathEntries: Map[Path.Entry, immutable.IndexedSeq[N]] =
  findAllChildElemsWithPathEntries.flatMap({ case (che, pe) => f(che, pe).map(newNodes => (pe, newNodes)) }).toMap

updateChildElemsWithNodeSeq(editsByPathEntries.keySet) { case (che, pe) =>
  editsByPathEntries.getOrElse(pe, immutable.IndexedSeq(che))
}

Updates the child elements with the given path entries, applying the passed update function. This is the core method of the update API, and the other methods have implementations that directly or indirectly depend on this method.

That is, returns:

if (pathEntries.isEmpty) self
else {
  val indexesByPathEntries: Seq[(Path.Entry, Int)] =
    collectChildNodeIndexes(pathEntries).toSeq.sortBy(_._2)

  // Updating in reverse order of indexes, in order not to invalidate the path entries
  val newChildren = indexesByPathEntries.reverse.foldLeft(self.children) {
    case (accChildNodes, (pathEntry, idx)) =>
      val che = accChildNodes(idx).asInstanceOf[E]
      accChildNodes.patch(idx, f(che, pathEntry), 1)
  }
  self.withChildren(newChildren)
}

If the set of path entries is small, this method is rather efficient.

Returns updateElemOrSelf(path) { e => newElem }

Functionally updates the tree with this element as root element, by applying the passed function to the element that has the given eu.cdevreeze.yaidom.core.Path (compared to this element as root).

It can be defined as follows:

updateElemsOrSelf(Set(path)) { case (e, path) => f(e) }

Returns updateElemWithNodeSeq(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 eu.cdevreeze.yaidom.core.Path (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:

updateElemsWithNodeSeq(Set(path)) { case (e, path) => f(e) }

Updates the descendant elements with the given paths, applying the passed update function.

That is, returns:

val pathsByFirstEntry: Map[Path.Entry, Set[Path]] = paths.filterNot(_.isRoot).groupBy(_.firstEntry)

updateChildElems(pathsByFirstEntry.keySet) {
  case (che, pathEntry) =>
    che.updateElemsOrSelf(pathsByFirstEntry(pathEntry).map(_.withoutFirstEntry)) {
      case (elm, path) =>
        f(elm, path.prepend(pathEntry))
    }
}

If the set of paths is small, this method is rather efficient.

Updates the descendant-or-self elements with the given paths, applying the passed update function.

That is, returns:

val pathsByFirstEntry: Map[Path.Entry, Set[Path]] = paths.filterNot(_.isRoot).groupBy(_.firstEntry)

val descendantUpdateResult =
  updateChildElems(pathsByFirstEntry.keySet) {
    case (che, pathEntry) =>
      // Recursive (but non-tail-recursive) call
      che.updateElemsOrSelf(pathsByFirstEntry(pathEntry).map(_.withoutFirstEntry)) {
        case (elm, path) =>
          f(elm, path.prepend(pathEntry))
      }
  }

if (paths.contains(Path.Root)) f(descendantUpdateResult, Path.Root) else descendantUpdateResult

In other words, returns:

val descendantUpdateResult = updateElems(paths)(f)
if (paths.contains(Path.Root)) f(descendantUpdateResult, Path.Root) else descendantUpdateResult

If the set of paths is small, this method is rather efficient.

Updates the descendant-or-self elements with the given paths, applying the passed update function.

That is, returns:

val pathsByFirstEntry: Map[Path.Entry, Set[Path]] = paths.filterNot(_.isRoot).groupBy(_.firstEntry)

val descendantUpdateResult =
  updateChildElemsWithNodeSeq(pathsByFirstEntry.keySet) {
    case (che, pathEntry) =>
      // Recursive (but non-tail-recursive) call
      che.updateElemsOrSelfWithNodeSeq(pathsByFirstEntry(pathEntry).map(_.withoutFirstEntry)) {
        case (elm, path) =>
          f(elm, path.prepend(pathEntry))
      }
  }

if (paths.contains(Path.Root)) f(descendantUpdateResult, Path.Root) else Vector(descendantUpdateResult)

In other words, returns:

val descendantUpdateResult = updateElemsWithNodeSeq(paths)(f)
if (paths.contains(Path.Root)) f(descendantUpdateResult, Path.Root) else Vector(descendantUpdateResult)

If the set of paths is small, this method is rather efficient.

Updates the descendant elements with the given paths, applying the passed update function.

That is, returns:

val pathsByFirstEntry: Map[Path.Entry, Set[Path]] = paths.filterNot(_.isRoot).groupBy(_.firstEntry)

updateChildElemsWithNodeSeq(pathsByFirstEntry.keySet) {
  case (che, pathEntry) =>
    che.updateElemsOrSelfWithNodeSeq(pathsByFirstEntry(pathEntry).map(_.withoutFirstEntry)) {
      case (elm, path) =>
        f(elm, path.prepend(pathEntry))
    }
}

If the set of paths is small, this method is rather efficient.

Invokes updateElems, passing the topmost non-empty paths for which the passed function is defined. It is equivalent to:

val mutableEditsByPaths = mutable.Map[Path, E]()

val foundElems =
  ElemWithPath(self) findTopmostElems { elm =>
    val optResult = f(elm.elem, elm.path)
    if (optResult.isDefined) {
      mutableEditsByPaths += (elm.path -> optResult.get)
    }
    optResult.isDefined
  }

val editsByPaths = mutableEditsByPaths.toMap

updateElems(editsByPaths.keySet) {
  case (elm, path) => editsByPaths.getOrElse(path, elm)
}

Invokes updateElemsOrSelf, passing the topmost paths for which the passed function is defined. It is equivalent to:

val mutableEditsByPaths = mutable.Map[Path, E]()

val foundElems =
  ElemWithPath(self) findTopmostElemsOrSelf { elm =>
    val optResult = f(elm.elem, elm.path)
    if (optResult.isDefined) {
      mutableEditsByPaths += (elm.path -> optResult.get)
    }
    optResult.isDefined
  }

val editsByPaths = mutableEditsByPaths.toMap

updateElemsOrSelf(editsByPaths.keySet) {
  case (elm, path) => editsByPaths.getOrElse(path, elm)
}

Invokes updateElemsOrSelfWithNodeSeq, passing the topmost paths for which the passed function is defined. It is equivalent to:

val mutableEditsByPaths = mutable.Map[Path, immutable.IndexedSeq[N]]()

val foundElems =
  ElemWithPath(self) findTopmostElemsOrSelf { elm =>
    val optResult = f(elm.elem, elm.path)
    if (optResult.isDefined) {
      mutableEditsByPaths += (elm.path -> optResult.get)
    }
    optResult.isDefined
  }

val editsByPaths = mutableEditsByPaths.toMap

updateElemsOrSelfWithNodeSeq(editsByPaths.keySet) {
  case (elm, path) => editsByPaths.getOrElse(path, immutable.IndexedSeq(elm))
}

Invokes updateElemsWithNodeSeq, passing the topmost non-empty paths for which the passed function is defined. It is equivalent to:

val mutableEditsByPaths = mutable.Map[Path, immutable.IndexedSeq[N]]()

val foundElems =
  ElemWithPath(self) findTopmostElems { elm =>
    val optResult = f(elm.elem, elm.path)
    if (optResult.isDefined) {
      mutableEditsByPaths += (elm.path -> optResult.get)
    }
    optResult.isDefined
  }

val editsByPaths = mutableEditsByPaths.toMap

updateElemsWithNodeSeq(editsByPaths.keySet) {
  case (elm, path) => editsByPaths.getOrElse(path, immutable.IndexedSeq(elm))
}

Shorthand for withChildren(newChildSeqs.flatten)

Creates a copy, but with (only) the children passed as parameter newChildren

Shorthand for withChildren(children.patch(from, newChildren, replace))

Shorthand for withChildren(children.updated(index, newChild))