Package ghidra.program.model.symbol

Class SymbolUtilities

  • public class SymbolUtilities
extends java.lang.Object
    Class with static methods to deal with symbol strings.

    • Constructor Detail

      • SymbolUtilities

        public SymbolUtilities()

    • Method Detail

      • getOrdinalValue

        public static int getOrdinalValue​(java.lang.String symbolName)

      • containsInvalidChars

        public static boolean containsInvalidChars​(java.lang.String str)
        Check for invalid characters (space, colon, asterisk, plus, bracket) in labels.
        Parameters:
        str - the string to be checked for invalid characters.
        Returns:
        boolean true if no invalid chars

      • getDefaultFunctionName

        public static java.lang.String getDefaultFunctionName​(Address addr)
        Generates a default function name for a given address.
        Parameters:
        addr - the entry point of the function.
        Returns:
        the default generated name for the function.

      • isReservedExternalDefaultName

        public static boolean isReservedExternalDefaultName​(java.lang.String name,
                                                    AddressFactory addrFactory)
        Returns true if the specified name is reserved as a default external name.
        Parameters:
        name -
        addrFactory -
        Returns:
        true if the specified name is reserved as a default external name.

      • getDefaultExternalFunctionName

        public static java.lang.String getDefaultExternalFunctionName​(Address addr)
        Generates a default external name for an external function
        Parameters:
        addr - the memory address referred to by the external.
        Returns:
        the default generated name for the external.

      • getDefaultExternalName

        public static java.lang.String getDefaultExternalName​(Address addr,
                                                      DataType dt)
        Generates a default external name for a given external data/code location.
        Parameters:
        addr - the memory address referred to by the external.
        dt - data type associated with the specified external memory address
        Returns:
        the default generated name for the external.

      • isReservedDynamicLabelName

        public static boolean isReservedDynamicLabelName​(java.lang.String name,
                                                 AddressFactory addrFactory)
        Returns true if the given name could match a default dynamic label (EXT, LAB, SUB, FUN, DAT) at some address. WARNING! Does not handle dynamic labels which use data-type prefixes - see isDynamicSymbolPattern(String, boolean) for more liberal check

      • validateName

        public static void validateName​(java.lang.String name)
                         throws InvalidInputException
        Validate the given symbol name: cannot be null, cannot be an empty string, cannot contain blank characters, cannot be a reserved name.
        Parameters:
        name - symbol name to be validated
        Throws:
        InvalidInputException - invalid or reserved name has been specified

      • startsWithDefaultDynamicPrefix

        public static boolean startsWithDefaultDynamicPrefix​(java.lang.String name)
        Returns true if the given name starts with a possible default symbol prefix.
        Parameters:
        name - the name string to test.
        Returns:
        true if name starts with a know dynamic prefix

      • isDynamicSymbolPattern

        public static boolean isDynamicSymbolPattern​(java.lang.String name,
                                             boolean caseSensitive)
        Tests if the given name is a possible dynamic symbol name. WARNING! This method should be used carefully since it will return true for any name which starts with a known dynamic label prefix or ends with an '_' followed by a valid hex value.
        Parameters:
        name - the name to test
        caseSensitive - true if case matters.
        Returns:
        true if name is a possible dynamic symbol name, else false

      • isInvalidChar

        public static boolean isInvalidChar​(char c)
        Returns true if the specified char is not valid for use in a symbol name
        Parameters:
        c - the character to be tested as a valid symbol character.
        Returns:
        return true if c is an invalid char within a symbol name, else false

      • replaceInvalidChars

        public static java.lang.String replaceInvalidChars​(java.lang.String str,
                                                   boolean replaceWithUnderscore)
        Removes from the given string any invalid characters or replaces them with underscores. For example: given "a:b*c", the return value would be "a_b_c"
        Parameters:
        str - the string to have invalid chars converted to underscores or removed.
        replaceWithUnderscore - - true means replace the invalid chars with underscore. if false, then just drop the invalid chars
        Returns:
        modified string

      • getDynamicOffcutName

        public static java.lang.String getDynamicOffcutName​(Address addr)
        Create a dynamic label name for an offcut reference.
        Parameters:
        addr - the address at which to create an offcut reference name.
        Returns:
        dynamic offcut label name

      • getDynamicName

        public static java.lang.String getDynamicName​(int referenceLevel,
                                              Address addr)
        Create a name for a dynamic symbol with a 3-letter prefix based upon reference level and an address. Acceptable referenceLevel's are: UNK_LEVEL, DAT_LEVEL, LAB_LEVEL, SUB_LEVEL, EXT_LEVEL, FUN_LEVEL.
        Parameters:
        referenceLevel - the type of reference for which to create a dynamic name.
        addr - the address at which to create a dynamic name.
        Returns:
        dynamic symbol name

      • getDynamicName

        public static java.lang.String getDynamicName​(Program program,
                                              Address addr)
        Create a name for a dynamic symbol.
        Parameters:
        program - the current program
        addr - the address of the symbol for which to generate a name
        Returns:
        a name for the symbol at the given address

      • parseDynamicName

        public static Address parseDynamicName​(AddressFactory factory,
                                       java.lang.String name)
        Parse a dynamic name and return its address or null if unable to parse.
        Parameters:
        factory - address factory
        name - the dynamic label name to parse into an address.
        Returns:
        address corresponding to symbol name if it satisfies possible dynamic naming or null if unable to parse address fro name

      • getAddressString

        public static java.lang.String getAddressString​(Address addr)

      • getDefaultParamName

        public static java.lang.String getDefaultParamName​(int ordinal)

      • isDefaultParameterName

        public static boolean isDefaultParameterName​(java.lang.String name)

      • getDefaultLocalName

        public static java.lang.String getDefaultLocalName​(Program program,
                                                   int stackOffset,
                                                   int firstUseOffset)

      • getDefaultLocalName

        public static java.lang.String getDefaultLocalName​(Program program,
                                                   VariableStorage storage,
                                                   int firstUseOffset)

      • isDefaultLocalName

        public static boolean isDefaultLocalName​(Program program,
                                         java.lang.String name,
                                         VariableStorage storage)

      • isPossibleDefaultLocalOrParamName

        public static boolean isPossibleDefaultLocalOrParamName​(java.lang.String name)
        Returns true if the given name is a possible default parameter name or local variable name
        Parameters:
        name - the name to check to see if it is a possible default local or parameter name
        Returns:
        true if the given name is a possible default parameter name or local variable name

      • isPossibleDefaultExternalName

        public static boolean isPossibleDefaultExternalName​(java.lang.String name)
        Checks if the given name could be a default external location name
        Parameters:
        name - the name to check
        Returns:
        true if the given name is a possible default external location name

      • isDefaultLocalStackName

        public static boolean isDefaultLocalStackName​(java.lang.String name)

      • getAddressAppendedName

        public static java.lang.String getAddressAppendedName​(java.lang.String name,
                                                      Address address)
        Creates the standard symbol name for symbols that have the addresses appended to the name following an "@" character in order to make it unique.
        Parameters:
        name - the "true" name of the symbol
        address - the address to be appended
        Returns:
        the name with the address appended.

      • getCleanSymbolName

        public static java.lang.String getCleanSymbolName​(Symbol symbol)
        Gets the base symbol name regardless of whether or not the address has been appended.
        Parameters:
        symbol - the symbol to get the clean name for.
        Returns:
        the base symbol name where the "@<address>" has been stripped away if it exists.

      • getCleanSymbolName

        public static java.lang.String getCleanSymbolName​(java.lang.String symbolName,
                                                  Address address)
        Gets the base symbol name regardless of whether or not the address has been appended using either the standard "@" separator, or the less preferred "_" separator. The address string extension must match that which is produced by the getAddressString(Address) method for it to be recognized.
        Parameters:
        symbolName - a symbol name to get the clean name for.
        address - the symbol's address
        Returns:
        the base symbol name where the "@<address>" has been stripped away if it exists.

      • getSymbolTypeDisplayName

        public static java.lang.String getSymbolTypeDisplayName​(Symbol symbol)
        Returns display text suitable for describing in the GUI the SymbolType of the given symbol
        Parameters:
        symbol - The symbol from which to get the SymbolType
        Returns:
        a display string for the SymbolType

      • getExpectedLabelOrFunctionSymbol

        public static Symbol getExpectedLabelOrFunctionSymbol​(Program program,
                                                      java.lang.String symbolName,
                                                      java.util.function.Consumer<java.lang.String> errorConsumer)
        Returns the unique global label or function symbol with the given name. Also, logs if there is not exactly one symbol with that name.
        Parameters:
        program - the program to search.
        symbolName - the name of the global label or function symbol to search.
        errorConsumer - the object to use for reporting errors via it's accept() method.
        Returns:
        symbol if a unique label/function symbol with name is found or null

      • getLabelOrFunctionSymbol

        public static Symbol getLabelOrFunctionSymbol​(Program program,
                                              java.lang.String symbolName,
                                              java.util.function.Consumer<java.lang.String> errorConsumer)
        Returns the unique global label or function symbol with the given name. Also, logs if there is more than one symbol with that name.
        Parameters:
        program - the program to search.
        symbolName - the name of the global label or function symbol to search.
        errorConsumer - the object to use for reporting errors via it's accept() method.
        Returns:
        symbol if a unique label/function symbol with name is found or null

      • createPreferredLabelOrFunctionSymbol

        public static Symbol createPreferredLabelOrFunctionSymbol​(Program program,
                                                          Address address,
                                                          Namespace namespace,
                                                          java.lang.String name,
                                                          SourceType source)
                                                   throws InvalidInputException
        Create label symbol giving preference to non-global symbols. An existing function symbol may be returned. If attempting to create a global symbol and the name already exists at the address no symbol will be created and null will be returned. If attempting to create a non-global symbol, which does not exist, and a global symbol does exist with same name its namespace will be changed.
        Parameters:
        program - program within which the symbol should be created
        address - memory address where symbol should be created
        namespace - symbol namespace or null for global
        name - symbol name
        source - symbol source type
        Returns:
        new or existing label or function symbol or null if creating a global symbol whose name already exists at address
        Throws:
        InvalidInputException - if invalid symbol name provided

      • getSymbolNameComparator

        public static java.util.Comparator<Symbol> getSymbolNameComparator()
        Returns a comparator for symbols. The comparison is based upon the name. This call replaces the former compareTo method on Symbol. This comparator returned here is case-insensitive.
        Returns:
        the comparator