Package ghidra.app.util

Class NamespaceUtils

java.lang.Object
ghidra.app.util.NamespaceUtils
public class NamespaceUtils extends Object
A class to hold utility methods for working with namespaces.

Example string format:

  • global::child1::child2
  • child1
Assumptions for creating namespaces from a path string:
  • All elements of a namespace path should be namespace symbols and not other symbol types.
  • Absolute paths can optionally start with the global namespace.
  • You can provide a relative path that will start at the given parent namespace (or global if there is no parent provided).
  • You can provide a path that has as its first entry the name of the given parent. In this case, the first entry will not be created, but rather the provided parent will be used.
  • If you provide a path and a parent, but the first element of the path is the global namespace, then the global namespace will be used as the parent namespace and not the one that was provided.
  • You cannot embed the global namespace in a path, but it can be at the root.

  • Method Details

    • getNamespacePathWithoutLibrary

      public static String getNamespacePathWithoutLibrary(Namespace namespace)
      Get the normal namespace path excluding any library name. Global namespace will be returned as empty string, while other namespace paths will be returned with trailing :: suffix.
      Parameters:
      namespace - namespace
      Returns:
      namespace path excluding any library name

    • getNamespaceQualifiedName

      public static String getNamespaceQualifiedName(Namespace namespace, String symbolName, boolean excludeLibraryName)
      Get namespace qualified symbol name
      Parameters:
      namespace - namespace object
      symbolName - name of symbol
      excludeLibraryName - if true any library name will be excluded from path returned, otherwise it will be included
      Returns:
      namespace qualified symbol name

    • getLibrary

      public static Library getLibrary(Namespace namespace)
      Get the library associated with the specified namespace
      Parameters:
      namespace - namespace
      Returns:
      associated library or null if not associated with a library

    • getNamespacesByName

      public static List<Namespace> getNamespacesByName(Program program, Namespace parent, String namespaceName) throws IllegalArgumentException
      Returns a list of all namespaces with the given name in the parent namespace
      Parameters:
      program - the program to search
      parent - the parent namespace from which to find all namespaces with the given name; if null, the global namespace will be used
      namespaceName - the name of the namespaces to retrieve
      Returns:
      a list of all namespaces that match the given name in the given parent namespace. An empty list is returned if none found.
      Throws:
      IllegalArgumentException - if specified parent Namespace is not valid for specified program.

    • getNamespaceByPath

      public static List<Namespace> getNamespaceByPath(Program program, Namespace parent, String pathString) throws IllegalArgumentException
      Returns a list of namespaces that match the given path. The path can be relative to the given root namespace or absolute if the path begins with the global namespace name.

      Note: this path must only contain Namespace names and no other symbol types.

      Parameters:
      program - the program to search
      parent - the namespace to use as the root for relative paths. If null, the global namespace will be used
      pathString - the path to the desired namespace
      Returns:
      a list of namespaces that match the given path. An empty list is returned if none found.
      Throws:
      IllegalArgumentException - if specified parent Namespace is not valid for specified program.

    • getMatchingNamespaces

      public static List<Namespace> getMatchingNamespaces(String childName, List<Namespace> parents, Program program) throws IllegalArgumentException
      Returns a list all namespaces that have the given name in any of the given namespaces
      Parameters:
      childName - the name of the namespaces to retrieve
      parents - a list of all namespaces to search for child namespaces with the given name
      program - the program to search
      Returns:
      a list all namespaces that have the given name in any of the given namespaces. Empty list if none found.
      Throws:
      IllegalArgumentException - if one or more invalid parent namespaces were specified

    • getSymbols

      public static List<Symbol> getSymbols(String symbolPath, Program program)
      Returns a list of all symbols that match the given path within the global namespace. The path consists of a series of namespaces names separated by "::" followed by a label or function name.
      Parameters:
      symbolPath - the names of namespaces and symbol separated by "::".
      program - the program to search
      Returns:
      the list of symbols that match the given symbolPath. An empty list is returned if none found.

    • getSymbols

      public static List<Symbol> getSymbols(String symbolPath, Program program, boolean searchWithinAllLibraries)
      Returns a list of all symbols that match the given path. The path consists of a series of namespaces names separated by "::" followed by a label or function name.
      Parameters:
      symbolPath - the names of namespaces and symbol separated by "::".
      program - the program to search
      searchWithinAllLibraries - if true all libraries will be searched provided first element of symbolPath is not a library name, else search symbolPath within global namespace only.
      Returns:
      the list of symbols that match the given symbolPath. An empty list is returned if none found.

    • getSymbols

      public static List<Symbol> getSymbols(SymbolPath symbolPath, Program program)
      Returns a list of Symbol that match the given symbolPath within the global namespace.
      Parameters:
      symbolPath - the symbol path that specifies a series of namespace and symbol names.
      program - the program to search for symbols with the given path.
      Returns:
      a list of Symbol that match the given symbolPath. An empty list is returned if none found.

    • getSymbols

      public static List<Symbol> getSymbols(SymbolPath symbolPath, Program program, boolean searchWithinAllLibraries)
      Returns a list of Symbol that match the given symbolPath.
      Parameters:
      symbolPath - the symbol path that specifies a series of namespace and symbol names.
      program - the program to search for symbols with the given path.
      searchWithinAllLibraries - if true all libraries will be searched provided first element of symbolPath is not a library name, else search symbolPath within global namespace only.
      Returns:
      a list of Symbol that match the given symbolPath. An empty list is returned if none found.

    • getFirstNonFunctionNamespace

      public static Namespace getFirstNonFunctionNamespace(Namespace parent, String namespaceName, Program program) throws IllegalArgumentException
      Returns the first namespace with the given name and that is NOT a function that is within the parent namespace. (ie. the first namespace that is not tied to a program address)
      Parameters:
      parent - the parent namespace to search
      namespaceName - the name of the namespace to find
      program - the program to search.
      Returns:
      the first namespace that matches, or null if no match.
      Throws:
      IllegalArgumentException - if specified parent Namespace is not valid for specified program.

    • createNamespaceHierarchy

      public static Namespace createNamespaceHierarchy(String namespacePath, Namespace rootNamespace, Program program, SourceType source) throws InvalidInputException
      Takes a namespace path string and creates a namespace hierarchy to match that string. This method ignores function namespaces so the path should not contain any function names. If you want traverse down through functions, then use the version that also takes an address that is used to distinguish between multiple functions with the same name.

      The root namespace can be a function.

      Parameters:
      namespacePath - The namespace name or path string to be parsed. This value should not include a trailing symbol name, only namespace names.
      rootNamespace - The parent namespace under which the desired namespace or path resides. If this value is null, then the global namespace will be used. This namespace can be a function name;
      program - The current program in which the desired namespace resides.
      source - the source type of the namespace
      Returns:
      The namespace that matches the given path. This can be either an existing namespace or a newly created one.
      Throws:
      InvalidInputException - If a given namespace name is in an invalid format and this method attempts to create that namespace, or if the namespace string contains the global namespace name in a position other than the root.
      See Also:

    • createNamespaceHierarchy

      public static Namespace createNamespaceHierarchy(String namespacePath, Namespace rootNamespace, Program program, Address address, SourceType source) throws InvalidInputException, IllegalArgumentException
      Takes a namespace path string and creates a namespace hierarchy to match that string. This method allows function namespaces in the path and uses the given address to resolve functions with duplicate names. When resolving down the namespace path, a function that matches a name will only be used if the given address is contained in the body of that function.

      The root namespace can be a function.

      If an address is passed, then the path can contain a function name provided the address is in the body of the function; otherwise the names must all be namespaces other than functions.

      Parameters:
      namespacePath - The namespace name or path string to be parsed This value should not include a trailing symbol name, only namespace names
      rootNamespace - The parent namespace under which the desired namespace or path resides. If this value is null, then the global namespace will be used.
      program - The current program in which the desired namespace resides
      address - the address used to resolve possible functions with duplicate names; may be null
      source - the source of the namespace
      Returns:
      The namespace that matches the given path. This can be either an existing namespace or a newly created one.
      Throws:
      InvalidInputException - If a given namespace name is in an invalid format and this method attempts to create that namespace, or if the namespace string contains the global namespace name in a position other than the root.
      IllegalArgumentException - if specified rootNamespace is not valid for specified program.
      See Also:

    • getFunctionNamespaceAt

      public static Namespace getFunctionNamespaceAt(Program program, SymbolPath symbolPath, Address address)
      Returns the existing Function at the given address if its SymbolPath matches the given path
      Parameters:
      program - the program
      symbolPath - the path of namespace
      address - the address
      Returns:
      the namespace represented by the given path, or null if no such namespace exists

    • getFunctionNamespaceContaining

      public static Namespace getFunctionNamespaceContaining(Program program, SymbolPath symbolPath, Address address)
      Returns the existing Function containing the given address if its SymbolPath matches the given path
      Parameters:
      program - the program
      symbolPath - the path of namespace
      address - the address
      Returns:
      the namespace represented by the given path, or null if no such namespace exists

    • getNonFunctionNamespace

      public static Namespace getNonFunctionNamespace(Program program, SymbolPath symbolPath)
      Finds the namespace for the given symbol path that is not a function
      Parameters:
      program - the program from which to get the namespace
      symbolPath - the path of namespace names including the name of the desired namespace
      Returns:
      the namespace represented by the given path, or null if no such namespace exists or the namespace is a function

    • convertNamespaceToClass

      public static GhidraClass convertNamespaceToClass(Namespace namespace) throws InvalidInputException
      Convert a namespace to a class by copying all namespace children into a newly created class and then removing the old namespace
      Parameters:
      namespace - namespace to be converted
      Returns:
      new class namespace
      Throws:
      InvalidInputException - if namespace was contained within a function and can not be converted to a class

    • getNamespaceParts

      public static List<Namespace> getNamespaceParts(Namespace namespace)
      Returns a list of namespaces, where each element is a component of the original specified namespace, excluding the global root namespace.

      Namespace "ns1::ns2::ns3" returns [ "ns1", "ns1::ns2", "ns1::ns2::ns3" ]

      Parameters:
      namespace - namespace to process
      Returns:
      list of namespaces