Elem
Shorthand for filterChildElems(p).
Shorthand for attributeOption(expandedName).
Shorthand for attributeOption(expandedName).
Shorthand for filterElemsOrSelf(p).
Shorthand for findTopmostElemsOrSelf(p).
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 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, and throws an exception otherwise
Returns the QName value of the attribute with the given expanded name, if any, wrapped in an Option.
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, 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.
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.
Returns the value of the attribute with the given expanded name, if any, wrapped in an Option.
The attribute Scope, which is the same Scope but without the default namespace (which is not used for attributes)
The attributes of the element as mapping from QNames to values
The attributes of the element as mapping from QNames to values
Returns the child node index of the child element at the given path entry, if any, and -1 otherwise.
Returns the child node index of the child element at the given path entry, if any, and -1 otherwise. The faster this method is, the better.
Returns the child nodes of this element, in the correct order
Returns the child nodes of this element, in the correct order
Returns the comment children
Creates a copy, altered with the explicitly passed parameters (for qname, attributes, scope and children).
Returns the child elements obeying the given predicate.
Returns the descendant elements obeying the given predicate.
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 element children
Returns all child elements with Path entries, in the correct order.
Returns all child elements with Path entries, in the correct order.
This method is also needed for fast recursive construction of docaware/indexed Elems.
Returns all descendant elements (not including this element).
Returns this element followed by all descendant elements (that is, the descendant-or-self elements).
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 obeying the given predicate, if any, wrapped in an Option.
Finds the child element with the given Path.Entry (where this element is the root), if any, wrapped in an Option.
Finds the child element with the given Path.Entry (where this element is the root), 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-or-self element obeying the given predicate, if any, wrapped in an Option.
Finds the element with the given Path (where this element is the root), if any, wrapped in an Option.
Finds the element with the given Path (where this element is the root), if any, wrapped in an Option.
This method must be very efficient, which depends on the efficiency of method findChildElemByPathEntry.
Returns the descendant elements obeying the given predicate that have no ancestor obeying the predicate.
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)))
Returns the single child element obeying the given predicate, and throws an exception otherwise.
Returns (the equivalent of) findChildElemByPathEntry(entry).get
Returns (the equivalent of) findChildElemByPathEntry(entry).get
Returns (the equivalent of) findElemOrSelfByPath(path).get
Returns (the equivalent of) findElemOrSelfByPath(path).get
The local name, that is, the local part of the EName
The local name, that is, the local part of the EName
Functionally removes the given attribute, if present.
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
Returns a copy in which the child at the given position (0-based) has been removed
Returns XmlStringUtils.normalizeString(text).
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.
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.
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.
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 end
Returns a copy in which the given child has been inserted at the given position (0-based)
Returns a copy in which the given child has been inserted at the given position (0-based)
Returns a copy in which the given child, if any, has been inserted at the end
Returns a copy in which the given child, if any, has been inserted at the end
Returns a copy in which the given child, if any, has been inserted at the given position (0-based)
Returns a copy in which the given child, if any, has been inserted at the given position (0-based)
"Prettifies" this Elem.
"Prettifies" this Elem. That is, first calls method removeAllInterElementWhitespace, and then transforms the result
by inserting text nodes with newlines and whitespace for indentation.
Returns the processing instruction children
The QName of the element
The QName of the element
Returns a copy where inter-element whitespace has been removed, throughout the node tree
The attributes as an ordered mapping from ENames (instead of QNames) to values, obtained by resolving attribute QNames against the attribute scope
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 Elem name as EName, obtained by resolving the element QName against the Scope
The Scope stored with the element
The Scope stored with the element
Returns the concatenation of the texts of text children, including whitespace and CData.
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 QName(text.trim)
Returns the equivalent of scope.resolveQNameOption(textAsQName).get
Returns the equivalent of scope.resolveQNameOption(textAsQName).get
Returns the text children
Returns the tree representation string corresponding to this element, that is, toTreeRepr.
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)
Same as toTreeRepr(emptyScope)
Returns the tree representation String, conforming to the tree representation DSL that creates NodeBuilders.
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:
toTreeRepr clearly corresponds to a NodeBuilder, and can indeed be parsed into onetoTreeRepr output is even valid Scala codeNodeBuilder, 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.
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.
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.
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.
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.
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.
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 text.trim.
Returns updated(path) { e => newElem }
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 eu.cdevreeze.yaidom.core.Path (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 eu.cdevreeze.yaidom.core.Path (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 == Path.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 eu.cdevreeze.yaidom.core.Path.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 eu.cdevreeze.yaidom.core.Path.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 = pathEntries.toSeq.map(entry => (entry -> childNodeIndex(entry))).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[Path])(f: (E, Path) => 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(Path.Root)) f(resultWithoutSelf, Path.Root) else resultWithoutSelf }
For simple elements, it is also equivalent to:
val pathsReversed = indexed.Elem(this).findAllElemsOrSelf.map(_.path).filter(p => paths.contains(p)).reverse pathsReversed.foldLeft(self) { case (acc, path) => acc.updated(path) { e => f(e, path) } }
Returns updatedWithNodeSeq(path) { e => newNodes }
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 eu.cdevreeze.yaidom.core.Path (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 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:
// First define function g as follows: def g(e: Elem): Elem = { if (path == Path.Root) e else { e.withPatchedChildren( e.childNodeIndex(path.lastEntry), f(e.findChildElemByPathEntry(path.lastEntry).get), 1) } } // Then the function updatedWithNodeSeq(path)(f) could be defined as: updated(path.parentPathOption.getOrElse(Path.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 = pathEntries.toSeq.map(entry => (entry -> childNodeIndex(entry))).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)) } }
Creates a copy, but with the attributes passed as parameter newAttributes
Creates a copy, but with (only) the children passed as parameter newChildren
Creates a copy, but with (only) the children passed as parameter newChildren
Shorthand for withChildren(children.patch(from, newChildren, replace))
Shorthand for withChildren(children.patch(from, newChildren, replace))
Shorthand for withChildren(children.updated(index, newChild))
Shorthand for withChildren(children.updated(index, newChild))
Immutable, thread-safe element node. It is the default element implementation in yaidom. As the default element implementation among several alternative element implementations, it strikes a balance between loss-less roundtripping and composability.
The parsers and serializers in packages eu.cdevreeze.yaidom.parse and eu.cdevreeze.yaidom.print return and take these default elements (or the corresponding
Documentinstances), respectively.As for its query API, class eu.cdevreeze.yaidom.simple.Elem is among the most powerful element implementations offered by yaidom. These elements offer all of the eu.cdevreeze.yaidom.queryapi.ElemApi, eu.cdevreeze.yaidom.queryapi.UpdatableElemApi and eu.cdevreeze.yaidom.queryapi.TransformableElemApi query APIs, and more.
See the documentation of the mixed-in query API traits for more details on the uniform query API offered by this class.
The following example illustrates the use of the yaidom uniform query API in combination with some Elem-specific methods. In this XML scripting example the namespace prefix "xsd" is replaced by prefix "xs", including those in QName-valued attributes. The trivial XML file of this example is the following XML Schema:
The edit action can be performed on this
schemaElemas follows, starting with some checks:Note that besides the uniform query API, this example uses some
Elem-specific methods, such asattributeAsQName,copyandplusAttributeOption.Class
Elemis immutable, and (should be) thread-safe. Hence, Elems do not know about their parent element, if any.An Elem has the following state:
Note that namespace declarations are not considered to be attributes in
Elem, just like in the rest of yaidom. Elem construction is unsuccessful if the element name and/or some attribute names cannot be resolved using theScopeof the element (ignoring the default namespace, if any, for attributes). As can be seen from the above-mentioned state, namespaces are first-class citizens.Elems can (relatively easily) be constructed manually in a bottom-up manner. Yet care must be taken to give the element and its descendants the correct
Scope. Otherwise it is easy to introduce (prefixed) namespace undeclarations, which are not allowed in XML 1.0. The underlying issue is that functional Elem trees are created in a bottom-up manner, whereas namespace scoping works in a top-down manner. This is not a big issue in practice, since manual Elem creation is rather rare, and it is always possible to call methodnotUndeclaringPrefixesafterwards. An alternative method to create element trees by hand uses class eu.cdevreeze.yaidom.simple.ElemBuilder. A manually createdElemBuildercan be converted to anElemby calling methodbuild.Round-tripping (parsing and serializing) is not entirely loss-less, but (in spite of the good composability and rather small state) not much is lost. Comments, processing instructions and entity references are retained. Attribute order is retained, although according to the XML Infoset this order is irrelevant. Namespace declaration order is not necessarily retained, however. Superfluous namespace declarations are also lost. (That is because namespace declarations are not explicitly stored in Elems, but are implicit, viz.
parentElem.scope.relativize(this.scope)). The short versus long form of an empty element is also not remembered.Equality has not been defined for class
Elem(that is, it is reference equality). There is no clear sensible notion of equality for XML trees at the abstraction level ofElem. For example, think about prefixes, "ignorable whitespace", DTDs and XSDs, etc.