Package ghidra.trace.model.target.path

Class KeyPath

java.lang.Object
ghidra.trace.model.target.path.KeyPath
All Implemented Interfaces:
Comparable<KeyPath>, Iterable<String>
public final class KeyPath extends Object implements Comparable<KeyPath>, Iterable<String>
An immutable path of keys leading from one object (usually the root) object to another

Often, the source is the root. These are often taken as a parameter when searching for values. In essence, they simply wrap a list of string keys, but it provides convenience methods, sensible comparison, and better typing.

  • Field Details

    • ROOT

      public static final KeyPath ROOT

  • Method Details

    • makeIndex

      public static String makeIndex(long i)
      Encode the given index in decimal, without brackets
      Parameters:
      i - the numeric index
      Returns:
      the encoded index

    • isIndex

      public static boolean isIndex(String key)
      Check if the given key is a bracketed index
      Parameters:
      key - the key to check
      Returns:
      true if it is an index

    • isName

      public static boolean isName(String key)
      Check if the given key is an attribute name, i.e., not an index
      Parameters:
      key - the key to check
      Returns:
      true if it is an attribute name

    • parseIndex

      public static String parseIndex(String key)
      Parse an index value from a key

      Where key is the form [index], this merely returns index.

      Parameters:
      key - the key
      Returns:
      the index
      Throws:
      IllegalArgumentException - if key is not of the required form

    • parseIfIndex

      public static String parseIfIndex(String key)
      If an index, parse it, otherwise just return the key
      Parameters:
      key - the key
      Returns:
      the index or key

    • makeKey

      public static String makeKey(String index)
      Encode the given index as a key

      When indexing elements, no brackets are needed. The brackets become necessary when used as a key, e.g., when specifying an index within a path, or as keys in a map of all children.

      Parameters:
      index - the index
      Returns:
      the key, specifying an element.

    • of

      public static KeyPath of(List<String> keyList)
      Create a path from the given list of keys
      Parameters:
      keyList - the list of keys from source to destination
      Returns:
      the path

    • of

      public static KeyPath of(Stream<String> keyStream)

    • of

      public static KeyPath of(String... keys)
      Create a path from the given keys
      Parameters:
      keys - the keys from source to destination
      Returns:
      the path

    • parse

      public static KeyPath parse(String path)
      Parse a path from the given string
      Parameters:
      path - the dot-separated keys from source to destination
      Returns:
      the path

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • compareTo

      public int compareTo(KeyPath that)
      Specified by:
      compareTo in interface Comparable<KeyPath>

    • equals

      public boolean equals(Object obj)
      Overrides:
      equals in class Object

    • size

      public int size()

    • iterator

      public Iterator<String> iterator()
      Specified by:
      iterator in interface Iterable<String>

    • key

      public String key(int i)

    • toList

      public List<String> toList()
      Get the (immutable) list of keys from source to destination
      Returns:
      the key list

    • containsWildcard

      public boolean containsWildcard()

    • countWildcards

      public int countWildcards()

    • isRoot

      public boolean isRoot()
      Assuming the source is the root, check if this path refers to that root
      Returns:
      true if the path is empty, false otherwise

    • key

      public KeyPath key(String name)
      Create a new path by appending the given key

      For example, if this path is "Processes[2]" and name takes the value "Threads", the result will be "Processes[2].Threads".

      Parameters:
      name - the new final key
      Returns:
      the resulting path

    • key

      public String key()
      Get the final key of this path
      Returns:
      the final key

    • index

      public KeyPath index(long index)
      Create a new path by appending the given element index

      For example, if this path is "Processes" and index takes the value 2, the result will be "Processes[2]".

      Parameters:
      index - the new final index
      Returns:
      the resulting path

    • index

      public KeyPath index(String index)
      Create a new path by appending the given element index

      This does the same as key(String) but uses brackets instead. For example, if this path is "Processes[2].Threads[0].Registers" and index takes the value "RAX", the result will be "Processes[2].Threads[0].Registers[RAX]".

      Parameters:
      index - the new final index
      Returns:
      the resulting path

    • index

      public String index()
      Get the final index of this path
      Returns:
      the final index
      Throws:
      IllegalArgumentException - if the final key is not an index, i.e., in brackets

    • toString

      public String toString()

      Gives the dot-joined path

      Overrides:
      toString in class Object

    • parent

      public KeyPath parent()
      Create a new path by removing the final key
      Returns:
      the resulting path, or null if this path is empty

    • parent

      public KeyPath parent(int n)
      Create a new path by removing the final n keys
      Parameters:
      n - the number of keys to remove
      Returns:
      the resulting path, or null if fewer than 0 keys would remain

    • extend

      public KeyPath extend(KeyPath sub)
      Create a new path by appending the given list of keys

      For example, if this path is "Processes[2]" and sub takes the value "Threads[0]", the result will be "Processes[2].Threads[0]".

      Parameters:
      sub - the path to append
      Returns:
      the resulting path

    • extend

      public KeyPath extend(String... subKeys)
      Create a new path by appending the given keys
      Parameters:
      subKeys - the keys to append
      Returns:
      the resulting path
      See Also:

    • streamMatchingAncestry

      public Stream<KeyPath> streamMatchingAncestry(PathFilter filter)
      Stream, starting with the longer paths, paths that match the given predicates
      Parameters:
      filter - the predicates to filter the ancestor paths
      Returns:
      the stream of matching paths, longest to shortest

    • isAncestor

      public boolean isAncestor(KeyPath successor)
      Check if this path is an ancestor of the given path

      Equivalently, check if the given path is a successor of this path. A path is considered an ancestor of itself. To check for a strict ancestor, use this.isAncestor(that) && !this.equals(that).

      Parameters:
      successor - the supposed successor to this path
      Returns:
      true if the given path is in fact a successor

    • relativize

      public KeyPath relativize(KeyPath successor)
      Assuming this is an ancestor of the given successor, compute the relative path from here to there
      Parameters:
      successor - the successor
      Returns:
      the relative path