Class SymbolUtilities

java.lang.Object
ghidra.program.model.symbol.SymbolUtilities

public class SymbolUtilities extends Object
Class with static methods to deal with symbol strings.
  • Field Details

  • Constructor Details

    • SymbolUtilities

      public SymbolUtilities()
  • Method Details

    • getOrdinalValue

      public static int getOrdinalValue(String symbolName)
    • containsInvalidChars

      public static boolean containsInvalidChars(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 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(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 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 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(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(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(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(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 String replaceInvalidChars(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 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 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 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, 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 String getAddressString(Address addr)
    • getDefaultParamName

      public static String getDefaultParamName(int ordinal)
    • isDefaultParameterName

      public static boolean isDefaultParameterName(String name)
    • getDefaultLocalName

      public static String getDefaultLocalName(Program program, int stackOffset, int firstUseOffset)
    • getDefaultLocalName

      public static String getDefaultLocalName(Program program, VariableStorage storage, int firstUseOffset)
    • isDefaultLocalName

      public static boolean isDefaultLocalName(Program program, String name, VariableStorage storage)
    • isPossibleDefaultLocalOrParamName

      public static boolean isPossibleDefaultLocalOrParamName(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(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(String name)
    • getAddressAppendedName

      public static String getAddressAppendedName(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 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 String getCleanSymbolName(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 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, String symbolName, Consumer<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, String symbolName, Consumer<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, 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 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