Package ghidra.program.model.symbol
Class SymbolUtilities
java.lang.Object
ghidra.program.model.symbol.SymbolUtilities
Class with static methods to deal with symbol strings.
-
Field Summary
Modifier and TypeFieldDescriptionstatic final int
static final int
static final int
static final char[]
Invalid characters for a symbol name.static final int
static final int
static final String
The standard prefix for denoting the ordinal values of a symbol.static final int
static final int
-
Constructor Summary
-
Method Summary
Modifier and TypeMethodDescriptionstatic boolean
Check for invalid characters (space, colon, asterisk, plus, bracket) in labels.static Symbol
createPreferredLabelOrFunctionSymbol
(Program program, Address address, Namespace namespace, String name, SourceType source) Create label symbol giving preference to non-global symbols.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.static String
getAddressString
(Address addr) static String
getCleanSymbolName
(Symbol symbol) Gets the base symbol name regardless of whether or not the address has been appended.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.static String
Generates a default external name for an external functionstatic String
getDefaultExternalName
(Address addr, DataType dt) Generates a default external name for a given external data/code location.static String
Generates a default function name for a given address.static String
getDefaultLocalName
(Program program, int stackOffset, int firstUseOffset) static String
getDefaultLocalName
(Program program, VariableStorage storage, int firstUseOffset) static String
getDefaultParamName
(int ordinal) 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.static String
getDynamicName
(Program program, Address addr) Create a name for a dynamic symbol.static String
getDynamicOffcutName
(Address addr) Create a dynamic label name for an offcut reference.static Symbol
getExpectedLabelOrFunctionSymbol
(Program program, String symbolName, Consumer<String> errorConsumer) Returns the unique global label or function symbol with the given name.static Symbol
getLabelOrFunctionSymbol
(Program program, String symbolName, Consumer<String> errorConsumer) Returns the unique global label or function symbol with the given name.static int
getOrdinalValue
(String symbolName) static Comparator
<Symbol> Returns a comparator for symbols.static String
getSymbolTypeDisplayName
(Symbol symbol) Returns display text suitable for describing in the GUI theSymbolType
of the given symbolstatic Symbol
getUniqueSymbol
(Program program, String name) Returns the global symbol with the given name if and only if it is the only global symbol with that name.static Symbol
getUniqueSymbol
(Program program, String name, Namespace namespace) Returns the symbol in the given namespace with the given name if and only if it is the only symbol in that namespace with that name.static boolean
isDefaultLocalName
(Program program, String name, VariableStorage storage) static boolean
static boolean
isDefaultParameterName
(String name) static boolean
isDynamicSymbolPattern
(String name, boolean caseSensitive) Tests if the given name is a possible dynamic symbol name.static boolean
isInvalidChar
(char c) Returns true if the specified char is not valid for use in a symbol namestatic boolean
Checks if the given name could be a default external location namestatic boolean
Returns true if the given name is a possible default parameter name or local variable namestatic 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.static boolean
isReservedExternalDefaultName
(String name, AddressFactory addrFactory) Returns true if the specified name is reserved as a default external name.static Address
parseDynamicName
(AddressFactory factory, String name) Parse a dynamic name and return its address or null if unable to parse.static String
replaceInvalidChars
(String str, boolean replaceWithUnderscore) Removes from the given string any invalid characters or replaces them with underscores.static boolean
Returns true if the given name starts with a possible default symbol prefix.static void
validateName
(String name) Validate the given symbol name: cannot be null, cannot be an empty string, cannot contain blank characters, cannot be a reserved name.
-
Field Details
-
MAX_SYMBOL_NAME_LENGTH
public static final int MAX_SYMBOL_NAME_LENGTH- See Also:
-
UNK_LEVEL
public static final int UNK_LEVEL- See Also:
-
DAT_LEVEL
public static final int DAT_LEVEL- See Also:
-
LAB_LEVEL
public static final int LAB_LEVEL- See Also:
-
SUB_LEVEL
public static final int SUB_LEVEL- See Also:
-
EXT_LEVEL
public static final int EXT_LEVEL- See Also:
-
FUN_LEVEL
public static final int FUN_LEVEL- See Also:
-
ORDINAL_PREFIX
The standard prefix for denoting the ordinal values of a symbol.- See Also:
-
INVALIDCHARS
public static final char[] INVALIDCHARSInvalid characters for a symbol name.
-
-
Constructor Details
-
SymbolUtilities
public SymbolUtilities()
-
-
Method Details
-
getOrdinalValue
-
containsInvalidChars
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
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
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
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
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
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 - seeisDynamicSymbolPattern(String, boolean)
for more liberal check -
validateName
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
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
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 testcaseSensitive
- 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
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
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
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
Create a name for a dynamic symbol.- Parameters:
program
- the current programaddr
- the address of the symbol for which to generate a name- Returns:
- a name for the symbol at the given address
-
parseDynamicName
Parse a dynamic name and return its address or null if unable to parse.- Parameters:
factory
- address factoryname
- 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
-
getDefaultParamName
-
isDefaultParameterName
-
getDefaultLocalName
-
getDefaultLocalName
public static String getDefaultLocalName(Program program, VariableStorage storage, int firstUseOffset) -
isDefaultLocalName
-
isPossibleDefaultLocalOrParamName
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
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
-
getAddressAppendedName
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 symboladdress
- the address to be appended- Returns:
- the name with the address appended.
-
getCleanSymbolName
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
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 thegetAddressString(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
Returns display text suitable for describing in the GUI theSymbolType
of the given symbol- Parameters:
symbol
- The symbol from which to get the SymbolType- Returns:
- a display string for the SymbolType
-
getUniqueSymbol
Returns the global symbol with the given name if and only if it is the only global symbol with that name.- Parameters:
program
- the program to search.name
- the name of the global symbol to find.- Returns:
- the global symbol with the given name if and only if it is the only one.
-
getUniqueSymbol
Returns the symbol in the given namespace with the given name if and only if it is the only symbol in that namespace with that name.- Parameters:
program
- the program to search.name
- the name of the symbol to find.namespace
- the parent namespace; may be null- Returns:
- the symbol with the given name if and only if it is the only one in that namespace
-
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 createdaddress
- memory address where symbol should be creatednamespace
- symbol namespace or null for globalname
- symbol namesource
- 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
Returns a comparator for symbols. The comparison is based upon the name. This call replaces the formercompareTo
method on Symbol. This comparator returned here is case-insensitive.- Returns:
- the comparator
-