Package ghidra.app.util

Class NamespaceUtils

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

    Example string format:

    Assumptions for creating namespaces from a path string:
    • All elements of a namespace path should be namespace symbols and not other symbol types.
    • If the method takes an address, 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.
    • 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 Detail

      • getNamespacePathWithoutLibrary

        public static java.lang.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 java.lang.String getNamespaceQualifiedName​(Namespace namespace,
                                                         java.lang.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

      • splitNamespacePath

        @Deprecated
public static java.util.List<java.lang.String> splitNamespacePath​(java.lang.String path)
        Deprecated.
        use SymbolPath instead
        Provide a standard method for splitting a symbol path into its various namespace and symbol name elements. While the current implementation uses a very simplistic approach, this may be improved upon in the future to handle various grouping concepts.
        Parameters:
        path - symbol namespace path (path will be trimmed before parse)
        Returns:
        order list of namespace names

      • 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

      • getNamespaces

        public static java.util.List<Namespace> getNamespaces​(java.lang.String namespacePath,
                                                      Namespace rootNamespace,
                                                      Program program)
        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:
        namespacePath - the path to the desired namespace.
        rootNamespace - the namespace to use as the root for relative paths. If null, the global namespace will be used.
        program - the program to search.
        Returns:
        a list of namespaces that match the given path.

      • getMatchingNamespaces

        public static java.util.List<Namespace> getMatchingNamespaces​(java.lang.String childName,
                                                              java.util.List<Namespace> parents,
                                                              Program program)
        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.

      • getSymbols

        public static java.util.List<Symbol> getSymbols​(java.lang.String symbolPath,
                                                Program program)
        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
        Returns:
        the list of symbols that match the given

      • getSymbols

        public static java.util.List<Symbol> getSymbols​(SymbolPath symbolPath,
                                                Program program)
        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.
        Returns:
        a list of Symbol that match the given symbolPath.

      • getNamespaces

        public static java.util.List<Namespace> getNamespaces​(Namespace parent,
                                                      java.lang.String namespaceName,
                                                      Program program)
        Returns a list of all namespaces with the given name in the parent namespace.
        Parameters:
        parent - the parent namespace from which to find all namespaces with the given name.
        namespaceName - the name of the namespaces to retrieve.
        program - the program to search.
        Returns:
        a list of all namespaces that match the given name in the given parent namespace.

      • getFirstNonFunctionNamespace

        public static Namespace getFirstNonFunctionNamespace​(Namespace parent,
                                                     java.lang.String namespaceName,
                                                     Program program)
        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.

      • createNamespaceHierarchy

        public static Namespace createNamespaceHierarchy​(java.lang.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​(java.lang.String namespacePath,
                                                 Namespace rootNamespace,
                                                 Program program,
                                                 Address address,
                                                 SourceType source)
                                          throws InvalidInputException
        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.

        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.
        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.
        See Also:
        assumptions

      • getNamespace

        public static Namespace getNamespace​(Program program,
                                     SymbolPath symbolPath,
                                     Address address)
        Finds the namespace for the given symbolPath. Since this method takes an address, the symbolPath can contain a function name provided the address lives in the body of that function.
        Parameters:
        program - the program from which to get the namespace.
        symbolPath - the path of namespace names including the name of the desired namespace.
        address - the address used to determine if any function namespaces can be used to resolve the path. For a function to be used, it must contain this address in it's body.
        Returns:
        the namespace represented by the given path, or null if no such namespace exists.

      • 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