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 Summary

  Modifier and Type
  Method
  Description
  `static GhidraClass`
  `convertNamespaceToClass(Namespace namespace)`
  Convert a namespace to a class by copying all namespace children into a newly created class and then removing the old namespace
  `static Namespace`
  `createNamespaceHierarchy(String namespacePath, Namespace rootNamespace, Program program, Address address, SourceType source)`
  Takes a namespace path string and creates a namespace hierarchy to match that string.
  `static Namespace`
  `createNamespaceHierarchy(String namespacePath, Namespace rootNamespace, Program program, SourceType source)`
  Takes a namespace path string and creates a namespace hierarchy to match that string.
  `static Namespace`
  `getFirstNonFunctionNamespace(Namespace parent, String namespaceName, Program program)`
  Returns the first namespace with the given name and that is NOT a function that is within the parent namespace.
  `static Namespace`
  `getFunctionNamespaceAt(Program program, SymbolPath symbolPath, Address address)`
  Returns the existing Function at the given address if its `SymbolPath` matches the given path
  `static Namespace`
  `getFunctionNamespaceContaining(Program program, SymbolPath symbolPath, Address address)`
  Returns the existing Function containing the given address if its `SymbolPath` matches the given path
  `static Library`
  `getLibrary(Namespace namespace)`
  Get the library associated with the specified namespace
  `static List<Namespace>`
  `getMatchingNamespaces(String childName, List<Namespace> parents, Program program)`
  Returns a list all namespaces that have the given name in any of the given namespaces
  `static List<Namespace>`
  `getNamespaceByPath(Program program, Namespace parent, String pathString)`
  Returns a list of namespaces that match the given path.
  `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.
  `static String`
  `getNamespacePathWithoutLibrary(Namespace namespace)`
  Get the normal namespace path excluding any library name.
  `static String`
  `getNamespaceQualifiedName(Namespace namespace, String symbolName, boolean excludeLibraryName)`
  Get namespace qualified symbol name
  `static List<Namespace>`
  `getNamespacesByName(Program program, Namespace parent, String namespaceName)`
  Returns a list of all namespaces with the given name in the parent namespace
  `static Namespace`
  `getNonFunctionNamespace(Program program, SymbolPath symbolPath)`
  Finds the namespace for the given symbol path that is not a function
  `static List<Symbol>`
  `getSymbols(SymbolPath symbolPath, Program program)`
  Returns a list of Symbol that match the given symbolPath within the global namespace.
  `static List<Symbol>`
  `getSymbols(SymbolPath symbolPath, Program program, boolean searchWithinAllLibraries)`
  Returns a list of Symbol that match the given symbolPath.
  `static List<Symbol>`
  `getSymbols(String symbolPath, Program program)`
  Returns a list of all symbols that match the given path within the global namespace.
  `static List<Symbol>`
  `getSymbols(String symbolPath, Program program, boolean searchWithinAllLibraries)`
  Returns a list of all symbols that match the given path.

  ### Methods inherited from class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## 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:
      - assumptions

  - ### 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:
      - assumptions

  - ### 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