eu.cdevreeze.yaidom

PathAwareElemLike

trait PathAwareElemLike[E <: PathAwareElemLike[E]] extends ElemLike[E] with PathAwareElemApi[E]

API and implementation trait for elements as containers of elements, each having a name and possible attributes, as well as an "element path" from the root element. This trait extends trait ElemLike, adding knowledge about "element paths" of elements with respect to a root element.

Most users of the yaidom API do not use this trait directly, so may skip the documentation of this trait.

This trait to a large extent mirrors the ParentElemLike trait, with queries returning "element paths" instead of "elements". As mentioned above, this trait knows more about elements than its supertraits, because it knows about "element paths". Still, it knows only about element nodes, so other node types than elements are not known to this API.

Based on its supertraits ElemLike and ParentElemLike, this trait offers a rich ElemPath query API. Two additional abstract methods other than those required by the supertraits need to be implemented, viz. findWithElemPathEntry and allChildElemsWithPathEntries.

This trait is extended by trait UpdatableElemLike, and therefore mixed in by Elem and Elem.

Example usage:

val bookstoreElm = doc.documentElement
require(bookstoreElm.localName == "Bookstore")

val bookAuthorElms =
  for {
    authorPath <- bookstoreElm findTopmostElemPaths { _.localName == "Author" }
    if authorPath.containsName(EName("Book"))
  } yield bookstoreElm.getWithElemPath(authorPath)

The above example shows how we can use the results of queries for ElemPaths, if we are interested in the ancestors of the elements at those paths. Of course, using only the ElemLike API, this example could have been written simply as:

val bookstoreElm = doc.documentElement
require(bookstoreElm.localName == "Bookstore")

val bookAuthorElms =
  for {
    bookElm <- bookstoreElm \\ EName("Book")
    authorElm <- bookElm \\! "Author"
  } yield authorElm

Indeed, the query methods of the ParentElemLike API (or ElemLike API) should often be preferred to those of this PathAwareElemLike API. After all, ElemPaths are relative to one specific root element, they are "volatile" (in that "functional updates" may render them useless), and they are rather slow indexes. Moreover, the ParentElemLike query methods tend to be faster than those of this trait.

On the other hand, it is often the combination of ParentElemLike API query methods and PathAwareElemLike API query methods that offer interesting querying possibilities. After all, sometimes it is handy to formulate a query in such a way that ancestors are retrieved in at least one of the intermediate steps.

Another use for ElemPath queries is functional updates. See UpdatableElemLike for the "update" methods. Some updated methods take an ElemPath, and another updated method is implemented using an ElemPath query offered by this API.

Note that this API does not offer any query methods using a predicate on ElemPaths instead of on elements. Such queries can always be rewritten to queries in which the Scala Collections API filter method is used for filtering on ElemPaths.

PathAwareElemLike more formally

Analogously to the ParentElemLike API, there are 3 core element path retrieval methods:

For example, instead of:

val titlePaths = elm filterElemOrSelfPaths { e => e.resolvedName == EName("Title") }

we could write (more verbosely):

val titlePaths = elm.findAllElemOrSelfPaths filter { path => elm.getWithElemPath(path).resolvedName == EName("Title") }

The second statement is far less efficient, due to repeated calls to method getWithElemPath. In this case, we could instead have written:

val titlePaths = elm.findAllElemOrSelfPaths filter { path => path.endsWithName(EName("Title")) }

Assuming correct implementations of the abstract methods, and using "resolved" (!) Elem instances (which have structural equality defined), this trait obeys some obvious properties, expressed using equality:

(elm.findAllElemOrSelfPaths map (path => elm.getWithElemPath(path))) == elm.findAllElemsOrSelf
(elm.findAllElemPaths map (path => elm.getWithElemPath(path))) == elm.findAllElems
(elm.allChildElemPaths map (path => elm.getWithElemPath(path))) == elm.allChildElems

(elm.filterElemOrSelfPaths(p) map (path => elm.getWithElemPath(path))) == elm.filterElemsOrSelf(p)
(elm.filterElemPaths(p) map (path => elm.getWithElemPath(path))) == elm.filterElems(p)

(elm.findTopmostElemOrSelfPaths(p) map (path => elm.getWithElemPath(path))) == elm.findTopmostElemsOrSelf(p)
(elm.findTopmostElemPaths(p) map (path => elm.getWithElemPath(path))) == elm.findTopmostElems(p)

etc.

We offer no proofs of these properties.

Implementation notes

Like trait ParentElemLike, some query methods use recursion in their implementations, but no tail recursion. See ParentElemLike for a motivation.

E

The captured element subtype

Self Type
E
Linear Supertypes
PathAwareElemApi[E], ElemLike[E], ElemApi[E], ParentElemLike[E], ParentElemApi[E], AnyRef, Any
Known Subclasses
Elem, Elem, UpdatableElemLike
Ordering
  1. Alphabetic
  2. By inheritance
Inherited
  1. Hide All
  2. Show all
  1. PathAwareElemLike
  2. PathAwareElemApi
  3. ElemLike
  4. ElemApi
  5. ParentElemLike
  6. ParentElemApi
  7. AnyRef
  8. Any
Visibility
  1. Public
  2. All

Abstract Value Members

  1. abstract def allChildElems: IndexedSeq[E]

    Returns all child elements, in the correct order.

    Returns all child elements, in the correct order. The faster this method is, the faster the other ParentElemLike methods will be.

    Note that this method is named "allChildElems" instead of "findAllChildElems". The latter name would be more consistent with the rest of this API, but the chosen name illustrates that allChildElems is seen more as "data" than as a "computation".

    Definition Classes
    ParentElemLike → ParentElemApi

  2. abstract def allChildElemsWithPathEntries: IndexedSeq[(E, Entry)]

    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: (allChildElemsWithPathEntries map (_._1)) == allChildElems

    Definition Classes
    PathAwareElemLike → PathAwareElemApi

  3. abstract def findWithElemPathEntry(entry: Entry): Option[E]

    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.

    Definition Classes
    PathAwareElemLike → PathAwareElemApi

  4. abstract def resolvedAttributes: Iterable[(EName, String)]

    The attributes as a mapping from ENames (instead of QNames) to values.

    The attributes as a mapping from ENames (instead of QNames) to values.

    The implementation must ensure that resolvedAttributes.toMap.size == resolvedAttributes.size.

    Definition Classes
    ElemLike → ElemApi

  5. abstract def resolvedName: EName

    Resolved name of the element, as EName

    Resolved name of the element, as EName

    Definition Classes
    ElemLike → ElemApi

Concrete Value Members

  1. final def !=(arg0: AnyRef): Boolean

    Definition Classes
    AnyRef

  2. final def !=(arg0: Any): Boolean

    Definition Classes
    Any

  3. final def ##(): Int

    Definition Classes
    AnyRef → Any

  4. final def ==(arg0: AnyRef): Boolean

    Definition Classes
    AnyRef

  5. final def ==(arg0: Any): Boolean

    Definition Classes
    Any

  6. final def \(localName: String): IndexedSeq[E]

    Shorthand for filterChildElems { _.localName == localName }.

    Shorthand for filterChildElems { _.localName == localName }.

    Definition Classes
    ElemLike → ElemApi

  7. final def \(expandedName: EName): IndexedSeq[E]

    Shorthand for filterChildElems(expandedName).

    Shorthand for filterChildElems(expandedName).

    Definition Classes
    ElemLike → ElemApi

  8. final def \(p: (E) ⇒ Boolean): IndexedSeq[E]

    Shorthand for filterChildElems(p).

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

    Definition Classes
    ParentElemLike → ParentElemApi

  9. final def \@(localName: String): Option[String]

    Shorthand for findAttribute(localName)

    Shorthand for findAttribute(localName)

    Definition Classes
    ElemLike → ElemApi

  10. final def \@(expandedName: EName): Option[String]

    Shorthand for attributeOption(expandedName)

    Shorthand for attributeOption(expandedName)

    Definition Classes
    ElemLike → ElemApi

  11. final def \\(localName: String): IndexedSeq[E]

    Shorthand for filterElemsOrSelf { _.localName == localName }.

    Shorthand for filterElemsOrSelf { _.localName == localName }.

    Definition Classes
    ElemLike → ElemApi

  12. final def \\(expandedName: EName): IndexedSeq[E]

    Shorthand for filterElemsOrSelf(expandedName).

    Shorthand for filterElemsOrSelf(expandedName).

    Definition Classes
    ElemLike → ElemApi

  13. final def \\(p: (E) ⇒ Boolean): IndexedSeq[E]

    Shorthand for filterElemsOrSelf(p).

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

    Definition Classes
    ParentElemLike → ParentElemApi

  14. final def \\!(localName: String): IndexedSeq[E]

    Shorthand for findTopmostElemsOrSelf { _.localName == localName }.

    Shorthand for findTopmostElemsOrSelf { _.localName == localName }.

    Definition Classes
    ElemLike → ElemApi

  15. final def \\!(expandedName: EName): IndexedSeq[E]

    Shorthand for findTopmostElemsOrSelf(expandedName).

    Shorthand for findTopmostElemsOrSelf(expandedName).

    Definition Classes
    ElemLike → ElemApi

  16. final def \\!(p: (E) ⇒ Boolean): IndexedSeq[E]

    Shorthand for findTopmostElemsOrSelf(p).

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

    Definition Classes
    ParentElemLike → ParentElemApi

  17. final def allChildElemPathEntries: IndexedSeq[Entry]

    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 allChildElemsWithPathEntries map { _._2 }.

    Definition Classes
    PathAwareElemLike → PathAwareElemApi

  18. final def allChildElemPaths: IndexedSeq[ElemPath]

    Returns allChildElemsWithPathEntries map { case (e, pe) => ElemPath.from(pe) }

    Returns allChildElemsWithPathEntries map { case (e, pe) => ElemPath.from(pe) }

    Definition Classes
    PathAwareElemLike → PathAwareElemApi

  19. final def asInstanceOf[T0]: T0

    Definition Classes
    Any

  20. final def attribute(expandedName: EName): String

    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

    Definition Classes
    ElemLike → ElemApi

  21. final def attributeOption(expandedName: EName): Option[String]

    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

    Definition Classes
    ElemLike → ElemApi

  22. def clone(): AnyRef

    Attributes
    protected[lang]
    Definition Classes
    AnyRef
    Annotations
    @throws()

  23. final def collectFromChildElems[B](pf: PartialFunction[E, B]): IndexedSeq[B]

    Returns allChildElems collect pf

    Returns allChildElems collect pf

    Definition Classes
    ParentElemLike → ParentElemApi

  24. final def collectFromElems[B](pf: PartialFunction[E, B]): IndexedSeq[B]

    Returns (the equivalent of) findAllElems collect pf

    Returns (the equivalent of) findAllElems collect pf

    Definition Classes
    ParentElemLike → ParentElemApi

  25. final def collectFromElemsOrSelf[B](pf: PartialFunction[E, B]): IndexedSeq[B]

    Returns (the equivalent of) findAllElemsOrSelf collect pf

    Returns (the equivalent of) findAllElemsOrSelf collect pf

    Definition Classes
    ParentElemLike → ParentElemApi

  26. final def eq(arg0: AnyRef): Boolean

    Definition Classes
    AnyRef

  27. def equals(arg0: Any): Boolean

    Definition Classes
    AnyRef → Any

  28. final def filterChildElemPaths(p: (E) ⇒ Boolean): IndexedSeq[ElemPath]

    Returns the paths of child elements obeying the given predicate

    Returns the paths of child elements obeying the given predicate

    Definition Classes
    PathAwareElemLike → PathAwareElemApi

  29. final def filterChildElems(expandedName: EName): IndexedSeq[E]

    Returns the child elements with the given expanded name

    Returns the child elements with the given expanded name

    Definition Classes
    ElemLike → ElemApi

  30. final def filterChildElems(p: (E) ⇒ Boolean): IndexedSeq[E]

    Returns the child elements obeying the given predicate

    Returns the child elements obeying the given predicate

    Definition Classes
    ParentElemLike → ParentElemApi

  31. final def filterElemOrSelfPaths(p: (E) ⇒ Boolean): IndexedSeq[ElemPath]

    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.

    Definition Classes
    PathAwareElemLike → PathAwareElemApi

  32. final def filterElemPaths(p: (E) ⇒ Boolean): IndexedSeq[ElemPath]

    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

    Definition Classes
    PathAwareElemLike → PathAwareElemApi

  33. final def filterElems(expandedName: EName): IndexedSeq[E]

    Returns the descendant elements with the given expanded name

    Returns the descendant elements with the given expanded name

    Definition Classes
    ElemLike → ElemApi

  34. final def filterElems(p: (E) ⇒ Boolean): IndexedSeq[E]

    Returns the descendant elements obeying the given predicate, that is, findAllElems filter p

    Returns the descendant elements obeying the given predicate, that is, findAllElems filter p

    Definition Classes
    ParentElemLike → ParentElemApi

  35. final def filterElemsOrSelf(expandedName: EName): IndexedSeq[E]

    Returns the descendant-or-self elements that have the given expanded name

    Returns the descendant-or-self elements that have the given expanded name

    Definition Classes
    ElemLike → ElemApi

  36. final def filterElemsOrSelf(p: (E) ⇒ Boolean): IndexedSeq[E]

    Returns the descendant-or-self elements that obey the given predicate.

    Returns the descendant-or-self elements that obey the given predicate. That is, the result is equivalent to findAllElemsOrSelf filter p.

    Definition Classes
    ParentElemLike → ParentElemApi

  37. def finalize(): Unit

    Attributes
    protected[lang]
    Definition Classes
    AnyRef
    Annotations
    @throws()

  38. final def findAllElemOrSelfPaths: IndexedSeq[ElemPath]

    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)

    Definition Classes
    PathAwareElemLike → PathAwareElemApi

  39. final def findAllElemPaths: IndexedSeq[ElemPath]

    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)

    Definition Classes
    PathAwareElemLike → PathAwareElemApi

  40. final def findAllElems: IndexedSeq[E]

    Returns all descendant elements (not including this element).

    Returns all descendant elements (not including this element). Equivalent to findAllElemsOrSelf.drop(1)

    Definition Classes
    ParentElemLike → ParentElemApi

  41. final def findAllElemsOrSelf: IndexedSeq[E]

    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)

    Definition Classes
    ParentElemLike → ParentElemApi

  42. final def findAttribute(localName: String): Option[String]

    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.

    Definition Classes
    ElemLike → ElemApi

  43. final def findChildElem(expandedName: EName): Option[E]

    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

    Definition Classes
    ElemLike → ElemApi

  44. final def findChildElem(p: (E) ⇒ Boolean): Option[E]

    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

    Definition Classes
    ParentElemLike → ParentElemApi

  45. final def findChildElemPath(p: (E) ⇒ Boolean): Option[ElemPath]

    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

    Definition Classes
    PathAwareElemLike → PathAwareElemApi

  46. final def findElem(expandedName: EName): Option[E]

    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

    Definition Classes
    ElemLike → ElemApi

  47. final def findElem(p: (E) ⇒ Boolean): Option[E]

    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

    Definition Classes
    ParentElemLike → ParentElemApi

  48. final def findElemOrSelf(expandedName: EName): Option[E]

    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

    Definition Classes
    ElemLike → ElemApi

  49. final def findElemOrSelf(p: (E) ⇒ Boolean): Option[E]

    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

    Definition Classes
    ParentElemLike → ParentElemApi

  50. final def findElemOrSelfPath(p: (E) ⇒ Boolean): Option[ElemPath]

    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

    Definition Classes
    PathAwareElemLike → PathAwareElemApi

  51. final def findElemPath(p: (E) ⇒ Boolean): Option[ElemPath]

    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

    Definition Classes
    PathAwareElemLike → PathAwareElemApi

  52. final def findTopmostElemOrSelfPaths(p: (E) ⇒ Boolean): IndexedSeq[ElemPath]

    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.

    Definition Classes
    PathAwareElemLike → PathAwareElemApi

  53. final def findTopmostElemPaths(p: (E) ⇒ Boolean): IndexedSeq[ElemPath]

    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

    Definition Classes
    PathAwareElemLike → PathAwareElemApi

  54. final def findTopmostElems(expandedName: EName): IndexedSeq[E]

    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

    Definition Classes
    ElemLike → ElemApi

  55. final def findTopmostElems(p: (E) ⇒ Boolean): IndexedSeq[E]

    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

    Definition Classes
    ParentElemLike → ParentElemApi

  56. final def findTopmostElemsOrSelf(expandedName: EName): IndexedSeq[E]

    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

    Definition Classes
    ElemLike → ElemApi

  57. final def findTopmostElemsOrSelf(p: (E) ⇒ Boolean): IndexedSeq[E]

    Returns the descendant-or-self elements that obey the given predicate, such that no ancestor obeys the predicate.

    Returns the descendant-or-self elements that obey the given predicate, such that no ancestor obeys the predicate.

    Definition Classes
    ParentElemLike → ParentElemApi

  58. final def findWithElemPath(path: ElemPath): Option[E]

    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. This method must be very efficient, which depends on the efficiency of method findWithElemPathEntry.

    Definition Classes
    PathAwareElemLike → PathAwareElemApi

  59. final def getChildElem(expandedName: EName): E

    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

    Definition Classes
    ElemLike → ElemApi

  60. final def getChildElem(p: (E) ⇒ Boolean): E

    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

    Definition Classes
    ParentElemLike → ParentElemApi

  61. final def getChildElemPath(p: (E) ⇒ Boolean): ElemPath

    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

    Definition Classes
    PathAwareElemLike → PathAwareElemApi

  62. final def getClass(): java.lang.Class[_]

    Definition Classes
    AnyRef → Any

  63. final def getIndex[K](f: (E) ⇒ K): Map[K, IndexedSeq[E]]

    Computes an index on the given function taking an element, that is, returns findAllElemsOrSelf groupBy f.

    Computes an index on the given function taking an element, that is, returns findAllElemsOrSelf groupBy f.

    Definition Classes
    ParentElemLike → ParentElemApi

  64. final def getWithElemPath(path: ElemPath): E

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

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

    Definition Classes
    PathAwareElemLike → PathAwareElemApi

  65. def hashCode(): Int

    Definition Classes
    AnyRef → Any

  66. final def isInstanceOf[T0]: Boolean

    Definition Classes
    Any

  67. final def localName: String

    The local name (or local part).

    The local name (or local part). Convenience method.

    Definition Classes
    ElemLike → ElemApi

  68. final def ne(arg0: AnyRef): Boolean

    Definition Classes
    AnyRef

  69. final def notify(): Unit

    Definition Classes
    AnyRef

  70. final def notifyAll(): Unit

    Definition Classes
    AnyRef

  71. final def synchronized[T0](arg0: ⇒ T0): T0

    Definition Classes
    AnyRef

  72. def toString(): String

    Definition Classes
    AnyRef → Any

  73. final def wait(): Unit

    Definition Classes
    AnyRef
    Annotations
    @throws()

  74. final def wait(arg0: Long, arg1: Int): Unit

    Definition Classes
    AnyRef
    Annotations
    @throws()

  75. final def wait(arg0: Long): Unit

    Definition Classes
    AnyRef
    Annotations
    @throws()

Inherited from PathAwareElemApi[E]

Inherited from ElemLike[E]

Inherited from ElemApi[E]

Inherited from ParentElemLike[E]

Inherited from ParentElemApi[E]

Inherited from AnyRef

Inherited from Any