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:

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

      • 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 java.util.List<Namespace> getNamespacesByName​(Program program,
                                                            Namespace parent,
                                                            java.lang.String namespaceName)
        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.

      • getNamespaceByPath

        public static java.util.List<Namespace> getNamespaceByPath​(Program program,
                                                           Namespace parent,
                                                           java.lang.String pathString)
        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

      • 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.

      • 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.

        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.
        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 java.util.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