eu.cdevreeze.yaidom

PathAwareElemApi

trait PathAwareElemApi[E <: PathAwareElemApi[E]] extends ElemApi[E]

This is the Path-aware part of the yaidom uniform query API. It is a sub-trait of trait eu.cdevreeze.yaidom.ElemApi. 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 eu.cdevreeze.yaidom.PathAwareElemLike. That trait only knows about elements (and not about other nodes), and only knows the following about elements:

Using this minimal knowledge alone, that trait not only offers the methods of its parent trait, but also:

In other words, the PathAwareElemApi trait is quite a rich query API, considering the minimal knowledge it needs to have about elements.

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

PathAwareElemApi examples

To illustrate the use of this API, consider the following example XML:

<book:Bookstore xmlns:book="http://bookstore/book" xmlns:auth="http://bookstore/author">
  <book:Book ISBN="978-0321356680" Price="35" Edition="2">
    <book:Title>Effective Java (2nd Edition)</book:Title>
    <book:Authors>
      <auth:Author>
        <auth:First_Name>Joshua</auth:First_Name>
        <auth:Last_Name>Bloch</auth:Last_Name>
      </auth:Author>
    </book:Authors>
  </book:Book>
  <book:Book ISBN="978-0981531649" Price="35" Edition="2">
    <book:Title>Programming in Scala: A Comprehensive Step-by-Step Guide, 2nd Edition</book:Title>
    <book:Authors>
      <auth:Author>
        <auth:First_Name>Martin</auth:First_Name>
        <auth:Last_Name>Odersky</auth:Last_Name>
      </auth:Author>
      <auth:Author>
        <auth:First_Name>Lex</auth:First_Name>
        <auth:Last_Name>Spoon</auth:Last_Name>
      </auth:Author>
      <auth:Author>
        <auth:First_Name>Bill</auth:First_Name>
        <auth:Last_Name>Venners</auth:Last_Name>
      </auth:Author>
    </book:Authors>
  </book:Book>
</book:Bookstore>

Suppose this XML has been parsed into eu.cdevreeze.yaidom.Elem instance bookstoreElem. Then we can perform the following query, using only the ElemApi query API:

val bookstoreNamespace = "http://bookstore/book"
val authorNamespace = "http://bookstore/author"
require(bookstoreElem.resolvedName == EName(bookstoreNamespace, "Bookstore"))

val scalaBookElems =
  for {
    bookElem <- bookstoreElem \\ EName(bookstoreNamespace, "Book")
    if (bookElem \ EName(bookstoreNamespace, "Title")).map(_.text).headOption.getOrElse("").contains("Scala")
  } yield bookElem

This is a top-down approach for finding Scala books. A bottom-up approach, using the PathAwareElemApi query API, could be coded as follows:

val scalaBookElems =
for {
  titlePath <- bookstoreElem filterElemPaths (e => e.resolvedName == EName(bookstoreNamespace, "Title"))
  if bookstoreElem.getElemOrSelfByPath(titlePath).text.contains("Scala")
  bookPath <- titlePath.findAncestorPath(_.endsWithName(EName(bookstoreNamespace, "Book")))
} yield bookstoreElem.getElemOrSelfByPath(bookPath)

A few remarks are in order:

In spite of these remarks, the methods specific to the PathAwareElemApi trait are a nice tool in the yaidom querying toolbox.

PathAwareElemApi more formally

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

The PathAwareElemApi trait can be understood more formally, as shown below.

The most fundamental methods of this trait are findAllChildElemsWithPathEntries and findChildElemByPathEntry. The semantics of the other methods can be defined directly or indirectly in terms of method findAllChildElemsWithPathEntries.

The following must hold (for indexed.Elem, which has structural equality defined):

elem.findAllChildElemsWithPathEntries.map(_._1) == elem.findAllChildElems

elem.findAllChildElemsWithPathEntries forall { case (che, pe) => elem.findChildElemByPathEntry(pe).get == che }

The basic operations definable in terms of method findAllChildElemsWithPathEntries are filterChildElemPaths, filterElemOrSelfPaths and findTopmostElemOrSelfPaths, analogous to trait ParentElemApi. Their semantics must be as if they had been defined as follows:

def filterChildElemPaths(p: E => Boolean): immutable.IndexedSeq[Path] =
  this.findAllChildElemsWithPathEntries collect { case (che, pe) if p(che) => Path(Vector(pe)) }

def filterElemOrSelfPaths(p: E => Boolean): immutable.IndexedSeq[Path] =
  (if (p(this)) Vector(Path.Root) else Vector()) ++ {
    this.findAllChildElemsWithPathEntries flatMap { case (che, pe) =>
      che.filterElemOrSelfPaths(p).map(_.prepend(pe))
    }
  }

def findTopmostElemOrSelfPaths(p: E => Boolean): immutable.IndexedSeq[Path] =
  if (p(this)) Vector(Path.Root)
  else {
    this.findAllChildElemsWithPathEntries flatMap { case (che, pe) =>
      che.findTopmostElemOrSelfPaths(p).map(_.prepend(pe))
    }
  }

Moreover, we could have defined:

def filterElemPaths(p: E => Boolean): immutable.IndexedSeq[Path] =
  this.findAllChildElemsWithPathEntries flatMap { case (che, pe) =>
    che.filterElemOrSelfPaths(p).map(_.prepend(pe))
  }

def findTopmostElemPaths(p: E => Boolean): immutable.IndexedSeq[Path] =
  this.findAllChildElemsWithPathEntries flatMap { case (che, pe) =>
    che.findTopmostElemOrSelfPaths(p).map(_.prepend(pe))
  }

and:

def findAllElemOrSelfPaths: immutable.IndexedSeq[Path] = filterElemOrSelfPaths(e => true)

def findAllElemPaths: immutable.IndexedSeq[Path] = filterElemPaths(e => true)

Then, analogously to ParentElemApi, the following properties hold:

elem.filterElemPaths(p) == elem.findAllElemPaths.filter(path => p(elem.findElemOrSelfByPath(path).get))

elem.filterElemOrSelfPaths(p) == elem.findAllElemOrSelfPaths.filter(path => p(elem.findElemOrSelfByPath(path).get))

etc.

Knowing that for resolved.Elem instance elem, we have:

(elem.findAllChildElemsWithPathEntries map (_._1)) == elem.findAllChildElems

it follows that:

(elem.filterChildElemPaths(p) map (path => elem.findElemOrSelfByPath(path).get)) == elem.filterChildElems(p)

(elem.filterElemOrSelfPaths(p) map (path => elem.findElemOrSelfByPath(path).get)) == elem.filterElemsOrSelf(p)

(elem.filterElemPaths(p) map (path => elem.findElemOrSelfByPath(path).get)) == elem.filterElems(p)

etc., where findElemOrSelfByPath is defined recursively, using method findChildElemByPathEntry.

No proofs are provided. Note that the similarities with trait ParentElemLike are striking.

E

The captured element subtype

Self Type
E
Linear Supertypes
ElemApi[E], ParentElemApi[E], AnyRef, Any
Known Subclasses
Ordering
  1. Alphabetic
  2. By inheritance
Inherited
  1. PathAwareElemApi
  2. ElemApi
  3. ParentElemApi
  4. AnyRef
  5. Any
  1. Hide All
  2. Show all
Learn more about member selection
Visibility
  1. Public
  2. All

Abstract Value Members

  1. abstract def \(expandedName: EName): IndexedSeq[E]

    Shorthand for filterChildElems(expandedName).

    Shorthand for filterChildElems(expandedName).

    Definition Classes
    ElemApi
  2. abstract 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
    ParentElemApi
  3. abstract def \@(expandedName: EName): Option[String]

    Shorthand for attributeOption(expandedName)

    Shorthand for attributeOption(expandedName)

    Definition Classes
    ElemApi
  4. abstract def \\(expandedName: EName): IndexedSeq[E]

    Shorthand for filterElemsOrSelf(expandedName).

    Shorthand for filterElemsOrSelf(expandedName).

    Definition Classes
    ElemApi
  5. abstract 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
    ParentElemApi
  6. abstract def \\!(expandedName: EName): IndexedSeq[E]

    Shorthand for findTopmostElemsOrSelf(expandedName).

    Shorthand for findTopmostElemsOrSelf(expandedName).

    Definition Classes
    ElemApi
  7. abstract 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
    ParentElemApi
  8. abstract 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
    ElemApi
  9. abstract 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
    ElemApi
  10. abstract def filterChildElemPaths(p: (E) ⇒ Boolean): IndexedSeq[Path]

    Returns the paths of child elements obeying the given predicate

  11. abstract 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
    ElemApi
  12. abstract def filterChildElems(p: (E) ⇒ Boolean): IndexedSeq[E]

    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)
    Definition Classes
    ParentElemApi
  13. abstract def filterElemOrSelfPaths(p: (E) ⇒ Boolean): IndexedSeq[Path]

    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.

  14. abstract def filterElemPaths(p: (E) ⇒ Boolean): IndexedSeq[Path]

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

  15. abstract 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
    ElemApi
  16. abstract def filterElems(p: (E) ⇒ Boolean): IndexedSeq[E]

    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))
    Definition Classes
    ParentElemApi
  17. abstract 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
    ElemApi
  18. abstract def filterElemsOrSelf(p: (E) ⇒ Boolean): IndexedSeq[E]

    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.

    Definition Classes
    ParentElemApi
  19. abstract def findAllChildElemPathEntries: IndexedSeq[Entry]

    Returns the Path entries of all child elements, in the correct order.

    Returns the Path entries of all child elements, in the correct order. Equivalent to findAllChildElemsWithPathEntries map { _._2 }.

  20. abstract def findAllChildElemPaths: IndexedSeq[Path]

    Returns findAllChildElemsWithPathEntries map { case (e, pe) => Path.from(pe) }

  21. abstract def findAllChildElems: IndexedSeq[E]

    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.

    Definition Classes
    ParentElemApi
  22. abstract def findAllChildElemsWithPathEntries: IndexedSeq[(E, Entry)]

    Returns all child elements with their Path entries, in the correct order.

    Returns all child elements with their Path entries, in the correct order. This method should be very efficient.

    The implementation must be such that the following holds: (findAllChildElemsWithPathEntries map (_._1)) == findAllChildElems

  23. abstract def findAllElemOrSelfPaths: IndexedSeq[Path]

    Returns the path of this element followed by the paths of all descendant elements (that is, the descendant-or-self elements)

  24. abstract def findAllElemPaths: IndexedSeq[Path]

    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)

  25. abstract def findAllElems: IndexedSeq[E]

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

    Definition Classes
    ParentElemApi
  26. abstract 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). This method could be defined as filterElemsOrSelf { e => true }.

    Definition Classes
    ParentElemApi
  27. abstract def findAttributeByLocalName(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
    ElemApi
  28. abstract 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
    ElemApi
  29. abstract 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. This method could be defined as filterChildElems(p).headOption.

    Definition Classes
    ParentElemApi
  30. abstract def findChildElemByPathEntry(entry: Entry): Option[E]

    Returns the equivalent of findElemOrSelfByPath(Path(immutable.IndexedSeq(entry))), but it should be very efficient.

    Returns the equivalent of findElemOrSelfByPath(Path(immutable.IndexedSeq(entry))), but it should be very efficient.

    Indeed, it is function findElemOrSelfByPath that is defined in terms of this function, findChildElemByPathEntry, and not the other way around.

  31. abstract def findChildElemPath(p: (E) ⇒ Boolean): Option[Path]

    Returns the path of the first found child element obeying the given predicate, if any, wrapped in an Option

  32. abstract 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
    ElemApi
  33. abstract 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. This method could be defined as filterElems(p).headOption.

    Definition Classes
    ParentElemApi
  34. abstract 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
    ElemApi
  35. abstract 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. This method could be defined as filterElemsOrSelf(p).headOption.

    Definition Classes
    ParentElemApi
  36. abstract def findElemOrSelfByPath(path: Path): Option[E]

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

  37. abstract def findElemOrSelfPath(p: (E) ⇒ Boolean): Option[Path]

    Returns the path of the first found (topmost) descendant-or-self element obeying the given predicate, if any, wrapped in an Option

  38. abstract def findElemPath(p: (E) ⇒ Boolean): Option[Path]

    Returns the path of the first found (topmost) descendant element obeying the given predicate, if any, wrapped in an Option

  39. abstract def findTopmostElemOrSelfPaths(p: (E) ⇒ Boolean): IndexedSeq[Path]

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

  40. abstract def findTopmostElemPaths(p: (E) ⇒ Boolean): IndexedSeq[Path]

    Returns the paths of the descendant elements obeying the given predicate that have no ancestor obeying the predicate

  41. abstract 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
    ElemApi
  42. abstract 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. This method could be defined as:

    this.findAllChildElems flatMap (_.findTopmostElemsOrSelf(p))
    Definition Classes
    ParentElemApi
  43. abstract 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
    ElemApi
  44. abstract def findTopmostElemsOrSelf(p: (E) ⇒ Boolean): IndexedSeq[E]

    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)))
    Definition Classes
    ParentElemApi
  45. abstract 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
    ElemApi
  46. abstract 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. This method could be defined as findChildElem(p).get.

    Definition Classes
    ParentElemApi
  47. abstract def getChildElemByPathEntry(entry: Entry): E

    Returns (the equivalent of) findChildElemByPathEntry(entry).get

  48. abstract def getChildElemPath(p: (E) ⇒ Boolean): Path

    Returns the path of the single child element obeying the given predicate, and throws an exception otherwise

  49. abstract def getElemOrSelfByPath(path: Path): E

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

  50. abstract def localName: String

    The local name (or local part).

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

    Definition Classes
    ElemApi
  51. 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.

    Namespace declarations are not considered attributes in yaidom, so are not included in the result.

    Definition Classes
    ElemApi
  52. abstract def resolvedName: EName

    Resolved name of the element, as EName

    Resolved name of the element, as EName

    Definition Classes
    ElemApi
  53. abstract def findWithElemPath(path: Path): Option[E]

    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.

    Annotations
    @deprecated
    Deprecated

    (Since version 0.7.1) Use findElemOrSelfByPath instead

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

    Returns the equivalent of findElemOrSelfByPath(Path(immutable.IndexedSeq(entry))), but it should be very efficient.

    Returns the equivalent of findElemOrSelfByPath(Path(immutable.IndexedSeq(entry))), but it should be very efficient.

    Indeed, it is function findElemOrSelfByPath that is defined in terms of this function, findChildElemByPathEntry, and not the other way around.

    Annotations
    @deprecated
    Deprecated

    (Since version 0.7.1) Use findChildElemByPathEntry instead

  55. abstract def getWithElemPath(path: Path): E

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

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

    Annotations
    @deprecated
    Deprecated

    (Since version 0.7.1) Use getElemOrSelfByPath instead

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 asInstanceOf[T0]: T0

    Definition Classes
    Any
  7. def clone(): AnyRef

    Attributes
    protected[java.lang]
    Definition Classes
    AnyRef
    Annotations
    @throws()
  8. final def eq(arg0: AnyRef): Boolean

    Definition Classes
    AnyRef
  9. def equals(arg0: Any): Boolean

    Definition Classes
    AnyRef → Any
  10. def finalize(): Unit

    Attributes
    protected[java.lang]
    Definition Classes
    AnyRef
    Annotations
    @throws()
  11. final def getClass(): Class[_]

    Definition Classes
    AnyRef → Any
  12. def hashCode(): Int

    Definition Classes
    AnyRef → Any
  13. final def isInstanceOf[T0]: Boolean

    Definition Classes
    Any
  14. final def ne(arg0: AnyRef): Boolean

    Definition Classes
    AnyRef
  15. final def notify(): Unit

    Definition Classes
    AnyRef
  16. final def notifyAll(): Unit

    Definition Classes
    AnyRef
  17. final def synchronized[T0](arg0: ⇒ T0): T0

    Definition Classes
    AnyRef
  18. def toString(): String

    Definition Classes
    AnyRef → Any
  19. final def wait(): Unit

    Definition Classes
    AnyRef
    Annotations
    @throws()
  20. final def wait(arg0: Long, arg1: Int): Unit

    Definition Classes
    AnyRef
    Annotations
    @throws()
  21. final def wait(arg0: Long): Unit

    Definition Classes
    AnyRef
    Annotations
    @throws()

Inherited from ElemApi[E]

Inherited from ParentElemApi[E]

Inherited from AnyRef

Inherited from Any

Ungrouped