final class Path extends AnyRef
Unique identification of a descendant (or self) Elem
given a root Elem
. It represents a unique path to an element, given
a root element, independent of other types of nodes, as if the XML tree only consists of elements.
In other words, a Path
is a sequence of instructions, each of them stating how to get to a specific child element.
Each such instruction is a Path.Entry
. So Paths do not contain the root element, and we can talk about Paths
in isolation, without referring to any specific DOM-like tree.
For example, consider the following 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>
Then the last name of the first author of the Scala book (viz. Odersky) has the following path:
Path.from( EName("{http://bookstore/book}Book") -> 1, EName("{http://bookstore/book}Authors") -> 0, EName("{http://bookstore/author}Author") -> 0, EName("{http://bookstore/author}Last_Name") -> 0 )
or:
PathBuilder.from( QName("book:Book") -> 1, QName("book:Authors") -> 0, QName("auth:Author") -> 0, QName("auth:Last_Name") -> 0).build(Scope.from("book" -> "http://bookstore/book", "auth" -> "http://bookstore/author"))
Path
instances are useful when navigating (see eu.cdevreeze.yaidom.queryapi.IsNavigable), and in "functional updates"
(see eu.cdevreeze.yaidom.queryapi.UpdatableElemLike).
An eu.cdevreeze.yaidom.core.Path corresponds to one and only one canonical path of the element (modulo prefix names),
which is the corresponding (canonical) XPath expression. See http://ns.inria.org/active-tags/glossary/glossary.html#canonical-path.
There is one catch, though. The Path
does not know the root element name, so that is not a part of the corresponding
canonical XPath expression. See the documentation of method toResolvedCanonicalXPath
.
The Path
contains an IndexedSeq
of path entries for a specific child element, grandchild element etc.,
but the (root) element itself is referred to by an empty list of path entries.
As an alternative to class Path
, each element in a tree could be uniquely identified by "path entries" that only contained
a child index instead of an element name plus element child index (of element children with the given name). Yet that would
be far less easy to use. Hence Path.Entry
instances each contain an element name plus index.
- Self Type
- Path
- Alphabetic
- By Inheritance
- Path
- AnyRef
- Any
- Hide All
- Show All
- Public
- Protected
Value Members
- final def !=(arg0: Any): Boolean
- Definition Classes
- AnyRef → Any
- final def ##(): Int
- Definition Classes
- AnyRef → Any
- def ++(other: Path): Path
Appends a given relative
Path
to thisPath
.Appends a given relative
Path
to thisPath
. Alias forappend(other)
. - final def ==(arg0: Any): Boolean
- Definition Classes
- AnyRef → Any
- def ancestorOrSelfPaths: IndexedSeq[Path]
Returns the ancestor-or-self paths, starting with this path, then the parent (if any), and ending with the root path
- def ancestorPaths: IndexedSeq[Path]
Returns the ancestor paths, starting with the parent path (if any), and ending with the root path
- def append(other: Path): Path
Appends a given relative
Path
to thisPath
- def append(entry: Entry): Path
Appends a given
Entry
to thisPath
- final def asInstanceOf[T0]: T0
- Definition Classes
- Any
- def clone(): AnyRef
- Attributes
- protected[lang]
- Definition Classes
- AnyRef
- Annotations
- @throws(classOf[java.lang.CloneNotSupportedException]) @native()
- def containsName(ename: EName): Boolean
Convenience method returning true if at least one entry has the given element name
- def elementNameOption: Option[EName]
Returns the element name (as EName) of the last path entry, if any, wrapped in an Option
- def endsWithName(ename: EName): Boolean
Convenience method returning true if the last entry (if any) has the given element name
- val entries: IndexedSeq[Entry]
- final def eq(arg0: AnyRef): Boolean
- Definition Classes
- AnyRef
- def equals(obj: Any): Boolean
- Definition Classes
- Path → AnyRef → Any
- def finalize(): Unit
- Attributes
- protected[lang]
- Definition Classes
- AnyRef
- Annotations
- @throws(classOf[java.lang.Throwable])
- def findAncestorOrSelfPath(p: (Path) => Boolean): Option[Path]
Returns
ancestorOrSelfPaths find { path => p(path) }
- def findAncestorPath(p: (Path) => Boolean): Option[Path]
Returns
ancestorPaths find { path => p(path) }
- def firstEntry: Entry
Returns the first entry, if any, and throws an exception otherwise
- def firstEntryOption: Option[Entry]
Returns the first entry, if any, wrapped in an
Option
- final def getClass(): Class[_ <: AnyRef]
- Definition Classes
- AnyRef → Any
- Annotations
- @native()
- def hashCode(): Int
- Definition Classes
- Path → AnyRef → Any
- def isEmpty: Boolean
Returns true if this is the empty
Path
, so if it has no entries - final def isInstanceOf[T0]: Boolean
- Definition Classes
- Any
- def lastEntry: Entry
Returns the last entry, if any, and throws an exception otherwise
- def lastEntryOption: Option[Entry]
Returns the last entry, if any, wrapped in an
Option
- final def ne(arg0: AnyRef): Boolean
- Definition Classes
- AnyRef
- def nonEmpty: Boolean
Returns true if this is not the empty
Path
, so if it has at least one entry - final def notify(): Unit
- Definition Classes
- AnyRef
- Annotations
- @native()
- final def notifyAll(): Unit
- Definition Classes
- AnyRef
- Annotations
- @native()
- def parentPath: Path
Like
parentPathOption
, but unwrapping the result (or throwing an exception otherwise) - def parentPathOption: Option[Path]
Gets the parent path (if any, because the empty path has no parent) wrapped in an
Option
.Gets the parent path (if any, because the empty path has no parent) wrapped in an
Option
.This method shows much of the reason why class
Path
exists. If we know an element'sPath
, and therefore its parentPath
(using this method), then we can obtain the parent element by following the parent path from the root of the tree. - def prepend(other: Path): Path
Prepends a given
Path
to thisPath
- def prepend(entry: Entry): Path
Prepends a given
Entry
to thisPath
- def skippingPath(otherPath: Path): Path
Returns the Path resulting from skipping ("consuming") the entries of the parameter Path.
Returns the Path resulting from skipping ("consuming") the entries of the parameter Path. If this Path does not start with the parameter Path, an exception is thrown.
- def startsWithName(ename: EName): Boolean
Convenience method returning true if the first entry (if any) has the given element name
- final def synchronized[T0](arg0: => T0): T0
- Definition Classes
- AnyRef
- def toResolvedCanonicalXPath: String
Returns the corresponding "resolved" canonical XPath, but modified for the root element (which is unknown in the
Path
).Returns the corresponding "resolved" canonical XPath, but modified for the root element (which is unknown in the
Path
). The modification is that the root element is written as a slash followed by an asterisk. Unlike real XPath, QNames are resolved as ENames, and shown in James Clark notation for ENames.See http://ns.inria.org/active-tags/glossary/glossary.html#canonical-path for (real) canonical XPath.
The "resolved" XPath-like expressions returned by this method need no context to convey their semantics, unlike real XPath expressions (canonical or otherwise). This is an important advantage of these expressions, in spite of their relative verbosity. A good use case is error reporting about parts of XML documents. For example, Saxon-EE uses a similar notation for error reporting (in XML format) in its schema validator.
Preferably used method
AbsolutePath.toCanonicalXPath
instead, because the notion of canonical XPath applies more to absolute paths than to navigation paths, and also because that method returns real XPath expressions, be it without QNames but using URI-qualified EQ-names in their place. - def toString(): String
- Definition Classes
- Path → AnyRef → Any
- final def wait(): Unit
- Definition Classes
- AnyRef
- Annotations
- @throws(classOf[java.lang.InterruptedException])
- final def wait(arg0: Long, arg1: Int): Unit
- Definition Classes
- AnyRef
- Annotations
- @throws(classOf[java.lang.InterruptedException])
- final def wait(arg0: Long): Unit
- Definition Classes
- AnyRef
- Annotations
- @throws(classOf[java.lang.InterruptedException]) @native()
- def withoutFirstEntry: Path
Like
withoutFirstEntryOption
, but unwrapping the result (or throwing an exception otherwise) - def withoutFirstEntryOption: Option[Path]
Returns the
Path
with the first path entry (if any) removed, wrapped in anOption
.