Package ghidra.app.script

Class GhidraScript

java.lang.Object
ghidra.program.flatapi.FlatProgramAPI
ghidra.app.script.GhidraScript
Direct Known Subclasses:
HeadlessScript, JythonScript
public abstract class GhidraScript extends FlatProgramAPI

Ghidra Script Development.

In order to write a script:
  1. Ghidra script must be written in Java.
  2. Your script class must extend ghidra.app.script.GhidraScript.
  3. You must implement the run() method. This is where you insert your script-specific code.
  4. You should create a description comment at the top of the file. Each description line should start with "//".


When you create a new script using the script manager, you will automatically receive a source code stub (as shown below). 
  // TODO write a description for this script

        public class NewScript extends GhidraScript {

                public void run() throws Exception {
                        // TODO Add User Code Here
                }
        }

Ghidra Script State

All scripts, when run, will be handed the current state in the form of class instance variable. These variables are:

  1. currentProgram: the active program
  2. currentAddress: the address of the current cursor location in the tool
  3. currentLocation: the program location of the current cursor location in the tool, or null if no program location exists
  4. currentSelection: the current selection in the tool, or null if no selection exists
  5. currentHighlight: the current highlight in the tool, or null if no highlight exists

Hello World Example

This example, when run, will simply print "Hello World" into the Ghidra console. 
        public class HelloWorldScript extends GhidraScript {
                public void run() throws Exception {
                        println("Hello World!");
                }
        }
All scripts, when run, will be handed the current state and are automatically run in a separate thread.
See Also:

  • Field Details

  • Constructor Details

    • GhidraScript

      public GhidraScript()

  • Method Details

    • run

      protected abstract void run() throws Exception
      The run method is where the script specific code is placed.
      Throws:
      Exception - if any exception occurs.

    • set

      public final void set(GhidraState state, TaskMonitor monitor, PrintWriter writer)
      Set the context for this script.
      Parameters:
      state - state object
      monitor - the monitor to use during run
      writer - the target of script "print" statements

    • setReusePreviousChoices

      public void setReusePreviousChoices(boolean reuse)
      Sets whether the user's previously selected values should be used when showing the various ask methods. This is true by default, meaning that previous choices will be shown instead of any provided default value.
      Parameters:
      reuse - true to reuse values; false to not reuse previous values

    • getReusePreviousChoices

      public boolean getReusePreviousChoices()
      Returns whether scripts will reuse previously selected values when showing the various ask methods.
      Returns:
      true to reuse values; false to not reuse previous values

    • execute

      public final void execute(GhidraState runState, TaskMonitor runMonitor, PrintWriter runWriter) throws Exception
      Execute/run script and doCleanup(boolean) afterwards.
      Parameters:
      runState - state object
      runMonitor - the monitor to use during run
      runWriter - the target of script "print" statements
      Throws:
      Exception - if the script excepts

    • loadPropertiesFile

      protected void loadPropertiesFile() throws IOException
      Throws:
      IOException

    • cleanup

      public void cleanup(boolean success)
      A callback for scripts to perform any needed cleanup after the script is finished
      Parameters:
      success - true if the script was successful

    • setPotentialPropertiesFileLocations

      public void setPotentialPropertiesFileLocations(List<ResourceFile> locations)
      Set potential locations of .properties files for scripts (including subscripts). This should be used when the .properties file is not located in the same directory as the script, and the user has supplied one or more potential locations for the .properties file(s).
      Parameters:
      locations - directories that contain .properties files

    • setPropertiesFileLocation

      public void setPropertiesFileLocation(String dirLocation, String basename) throws IOException
      Explicitly set the .properties file location and basename for this script (used if a ResourceFile representing the GhidraScript is not available -- i.e., if running GhidraScript from a .class file or instantiating the actual GhidraScript object directly).
      Parameters:
      dirLocation - String representation of the path to the .properties file
      basename - base name of the file
      Throws:
      IOException - if there is an exception loading the new properties file

    • setPropertiesFile

      public void setPropertiesFile(File propertiesFile) throws IOException
      Explicitly set the .properties file (used if a ResourceFile representing the GhidraScript is not available -- i.e., if running GhidraScript from a .class file or instantiating the actual GhidraScript object directly).
      Parameters:
      propertiesFile - the actual .properties file for this GhidraScript
      Throws:
      IOException - if there is an exception reading the properties

    • getProjectRootFolder

      public DomainFolder getProjectRootFolder()
      Description copied from class: FlatProgramAPI
      This method looks up the current project and returns the root domain folder.
      Overrides:
      getProjectRootFolder in class FlatProgramAPI
      Returns:
      the root domain folder of the current project

    • promptToKeepChangesOnException

      protected boolean promptToKeepChangesOnException()

    • analyzeAll

      public void analyzeAll(Program program)
      Description copied from class: FlatProgramAPI
      Starts auto-analysis on the specified program and performs complete analysis of the entire program. This is usually only necessary if full analysis was never performed. This method will block until analysis completes.
      Overrides:
      analyzeAll in class FlatProgramAPI
      Parameters:
      program - the program to analyze

    • analyzeChanges

      public void analyzeChanges(Program program)
      Description copied from class: FlatProgramAPI
      Starts auto-analysis if not started and waits for pending analysis to complete. Only pending analysis on program changes is performed, including changes resulting from any analysis activity. This method will block until analysis completes. NOTE: The auto-analysis manager will only detect program changes once it has been instantiated for a program (i.e, AutoAnalysisManager.getAnalysisManager(program) ). This is automatically done for the initial currentProgram, however, if a script is opening/instantiating its own programs it may be necessary to do this prior to making changes to the program.
      Overrides:
      analyzeChanges in class FlatProgramAPI
      Parameters:
      program - the program to analyze

    • updateStateFromVariables

      protected final void updateStateFromVariables()

    • loadVariablesFromState

      protected final void loadVariablesFromState()

    • getState

      public final GhidraState getState()
      Returns the state object for this script after first synchronizing its state with its corresponding convenience variables.
      Returns:
      the state object

    • setCurrentLocation

      public final void setCurrentLocation(Address address)
      Set the script currentAddress, currentLocation, and update state object.
      Parameters:
      address - the new address

    • setSourceFile

      public final void setSourceFile(ResourceFile sourceFile)
      Set associated source file
      Parameters:
      sourceFile - the source file

    • getScriptAnalysisMode

      public GhidraScript.AnalysisMode getScriptAnalysisMode()
      Determines the behavior of Auto-Analysis while this script is executed and the manner in which this script is executed. If a script overrides this method and returns DISABLED or SUSPENDED, this script will execute as an AnalysisWorker. Note that this will only work reliably when the script is working with the currentProgram only and is not opening and changing other programs. If multiple programs will be modified and auto-analysis should be disabled/suspended, the AutoAnalysisManager.scheduleWorker method should be used with the appropriate AutoAnalysisManager instance.
      Returns:
      the analysis mode associated with this script.
      See Also:
      • AutoAnalysisManager.getAnalysisManager(Program)
      • AutoAnalysisManager.scheduleWorker(AnalysisWorker, Object, boolean, TaskMonitor)
      • AutoAnalysisManager.setIgnoreChanges(boolean)

    • setServerCredentials

      public final boolean setServerCredentials(String username, String password)
      Establishes fixed login credentials for Ghidra Server access.

      NOTE: Only used for Headless environment, other GUI environments should continue to prompt user for login credentials as needed.

      Parameters:
      username - login name or null if not applicable or to use default name
      password - login password
      Returns:
      true if active project is either private or shared project is connected to its server repository. False is returned if not active project or an active shared project failed to connect.

    • setAnonymousServerCredentials

      public final boolean setAnonymousServerCredentials()
      Enable use of anonymous read-only user connection to Ghidra Server in place of fixed username/password credentials.

      NOTE: Only used for Headless environment, other GUI environments should continue to prompt user for login credentials as needed.

      Returns:
      true if active project is either private or shared project is connected to its server repository. False is returned if not active project or an active shared project failed to connect.

    • getCategory

      public String getCategory()
      Returns the category for this script.
      Returns:
      the category for this script

    • getUserName

      public String getUserName()
      Returns the username of the user running the script.
      Returns:
      the username of the user running the script

    • toString

      public final String toString()
      Overrides:
      toString in class Object

    • getScriptName

      public final String getScriptName()
      Returns name of script
      Returns:
      name of script

    • getSourceFile

      public final ResourceFile getSourceFile()
      Returns the script source file.
      Returns:
      the script source file

    • getScriptArgs

      public String[] getScriptArgs()
      Returns the script-specific arguments
      Returns:
      The script-specific arguments. Could be an empty array, but won't be null.

    • setScriptArgs

      public void setScriptArgs(String[] scriptArgs)
      Sets script-specific arguments
      Parameters:
      scriptArgs - The script-specific arguments to use. For no scripts, use null or an empty array.

    • getGhidraVersion

      public String getGhidraVersion()
      Returns the version of the Ghidra being run.
      Returns:
      the version of the Ghidra being run

    • isRunningHeadless

      public final boolean isRunningHeadless()
      Returns whether this script is running in a headless (Non GUI) environment.

      This method should not be using GUI type script calls like showAddress()

      Returns:
      true if the script is running without a GUI.

    • runScript

      public final void runScript(String scriptName) throws Exception
      Runs a script by name (allows current state to be changed by script).

      It attempts to locate the script in the directories defined in GhidraScriptUtil.getScriptDirectories().

      The script being run uses the same GhidraState (e.g., script variables) as this calling script. Also, any changes to the state by the script being run will be reflected in this calling script's state.

      Parameters:
      scriptName - the name of the script to run
      Throws:
      IllegalArgumentException - if the script does not exist
      Exception - if any exceptions occur while running the script
      See Also:

    • runScript

      public final void runScript(String scriptName, String[] scriptArguments) throws Exception
      Runs a script by name with the provided arguments (allows current state to be changed by script).

      It attempts to locate the script in the directories defined in GhidraScriptUtil.getScriptDirectories().

      The script being run uses the same GhidraState (e.g., script variables) as this calling script. Also, any changes to the state by the script being run will be reflected in this calling script's state.

      Parameters:
      scriptName - the name of the script to run
      scriptArguments - the arguments to pass to the script
      Throws:
      IllegalArgumentException - if the script does not exist
      Exception - if any exceptions occur while running the script
      See Also:

    • runScriptPreserveMyState

      public final GhidraState runScriptPreserveMyState(String scriptName) throws Exception
      Runs a script by name (does not allow current state to change).

      It attempts to locate the script in the directories defined in GhidraScriptUtil.getScriptDirectories().

      The script being run uses the same GhidraState (e.g., script variables) as this calling script. However, any changes to the state by the script being run will NOT be reflected in this calling script's state.

      Parameters:
      scriptName - the name of the script to run
      Returns:
      a GhidraState object containing the final state of the run script.
      Throws:
      IllegalArgumentException - if the script does not exist
      Exception - if any exceptions occur while running the script
      See Also:

    • runScript

      public void runScript(String scriptName, GhidraState scriptState) throws Exception
      Runs a script by name using the given state.

      It attempts to locate the script in the directories defined in GhidraScriptUtil.getScriptDirectories().

      The script being run uses the given GhidraState (e.g., script variables) Any changes to the state by the script being run will be reflected in the given state object. If the given object is the current state, the this scripts state may be changed by the called script.

      Parameters:
      scriptName - the name of the script to run
      scriptState - the Ghidra state
      Throws:
      IllegalArgumentException - if the script does not exist
      Exception - if any exceptions occur while running the script
      See Also:

    • runScript

      public void runScript(String scriptName, String[] scriptArguments, GhidraState scriptState) throws Exception
      Runs a script by name with the given arguments using the given state.

      It attempts to locate the script in the directories defined in GhidraScriptUtil.getScriptDirectories().

      The script being run uses the given GhidraState (e.g., script variables) Any changes to the state by the script being run will be reflected in the given state object. If the given object is the current state, the this scripts state may be changed by the called script.

      Parameters:
      scriptName - the name of the script to run
      scriptArguments - the arguments to pass to the script
      scriptState - the Ghidra state
      Throws:
      IllegalArgumentException - if the script does not exist
      Exception - if any exceptions occur while running the script
      See Also:

    • runCommand

      public final boolean runCommand(Command<Program> cmd)
      Runs the specified command using the current program.
      Parameters:
      cmd - the command to run
      Returns:
      true if the command successfully ran

    • runCommand

      public final boolean runCommand(BackgroundCommand<Program> cmd)
      Runs the specified background command using the current program. The command will be given the script task monitor.
      Parameters:
      cmd - the background command to run
      Returns:
      true if the background command successfully ran

    • getDefaultLanguage

      public final Language getDefaultLanguage(Processor processor) throws LanguageNotFoundException
      Returns the default language provider for the specified processor name.
      Parameters:
      processor - the processor
      Returns:
      the default language provider for the specified processor name
      Throws:
      LanguageNotFoundException - if no language provider exists for the processor
      See Also:

    • getLanguage

      public final Language getLanguage(LanguageID languageID) throws LanguageNotFoundException
      Returns the language provider for the specified language name.
      Parameters:
      languageID - the language name
      Returns:
      the language provider for the specified language name
      Throws:
      LanguageNotFoundException - if no language provider exists
      See Also:

    • getDemangled

      public String getDemangled(String mangled)
      Returns a demangled version of the mangled string.
      Parameters:
      mangled - the mangled string to demangled
      Returns:
      a demangled version of the mangled string

    • println

      public void println()
      Prints a newline.
      See Also:

    • println

      public void println(String message)
      Prints the message to the console followed by a line feed.
      Parameters:
      message - the message to print
      See Also:

    • printf

      public void printf(String message, Object... args)
      A convenience method to print a formatted String using Java's printf feature, which is similar to that of the C programming language. For a full description on Java's printf usage, see Formatter.

      For examples, see the included FormatExampleScript.

      Note: This method will not:

      • print out the name of the script, as does println(String)
      • print a newline
      If you would like the name of the script to precede you message, then you must add that yourself. The println(String) does this via the following code: 
           String messageWithSource = getScriptName() + "> " + message;
      Parameters:
      message - the message to format
      args - formatter arguments (see above)
      See Also:

    • print

      public void print(String message)
      Prints the message to the console - no line feed

      Note: This method will not print out the name of the script, as does println(String)

      If you would like the name of the script to precede you message, then you must add that yourself. The println(String) does this via the following code: 

           String messageWithSource = getScriptName() + "> " + message;
      Parameters:
      message - the message to print
      See Also:

    • printerr

      public void printerr(String message)
      Prints the error message to the console followed by a line feed.
      Parameters:
      message - the error message to print

    • getAnalysisOptionDescription

      public String getAnalysisOptionDescription(Program program, String analysisOption)
      Returns the description of an analysis option name, as provided by the analyzer. This method returns an empty string if no description is available.
      Parameters:
      program - the program to get the analysis option description from
      analysisOption - the analysis option to get the description for
      Returns:
      the analysis description, or empty String if none has been provided

    • getAnalysisOptionDescriptions

      public Map<String,String> getAnalysisOptionDescriptions(Program program, List<String> analysisOptions)
      Returns descriptions mapping to the given list of analysis option names. This method returns an empty string for an analysis option if no description is available.
      Parameters:
      program - the program to get the analysis option description from
      analysisOptions - the lists of analysis options to get the description for
      Returns:
      mapping between each analysis options and its description (description is empty string if none has been provided).

    • resetAllAnalysisOptions

      public void resetAllAnalysisOptions(Program program)
      Reset all analysis options to their default values.
      Parameters:
      program - the program for which all analysis options should be reset

    • resetAnalysisOption

      public void resetAnalysisOption(Program program, String analysisOption)
      Reset one analysis option to its default value.
      Parameters:
      program - the program for which the specified analysis options should be reset
      analysisOption - the specified analysis option to reset (invalid options will be ignored)

    • resetAnalysisOptions

      public void resetAnalysisOptions(Program program, List<String> analysisOptions)
      Resets a specified list of analysis options to their default values.
      Parameters:
      program - the program for which the specific analysis options should be reset
      analysisOptions - the specified analysis options to reset (invalid options will be ignored)

    • isAnalysisOptionDefaultValue

      public boolean isAnalysisOptionDefaultValue(Program program, String analysisOption, String analysisValue)
      Returns a boolean value representing whether the specified value for the specified analysis option is actually the default value for that option.
      Parameters:
      program - the program for which we want to verify the analysis option value
      analysisOption - the analysis option whose value we want to verify
      analysisValue - the analysis value to be compared to the option's default value
      Returns:
      whether the given value for the given option is default or not

    • getAnalysisOptionDefaultValue

      public String getAnalysisOptionDefaultValue(Program program, String analysisOption)
      Returns the default value for the given analysis option. Returns empty string if invalid option.
      Parameters:
      program - the program for which we want to retrieve the default value for the given analysis option
      analysisOption - the analysis option for which we want to retrieve the default value
      Returns:
      String representation of default value (returns empty string if analysis option is invalid).

    • getAnalysisOptionDefaultValues

      public Map<String,String> getAnalysisOptionDefaultValues(Program program, List<String> analysisOptions)
      Returns a mapping of the given analysis options to their default values in String form. An individual option is mapped to the empty String if the option is invalid.
      Parameters:
      program - the program for which to retrieve default values for the given analysis options
      analysisOptions - the analysis options for which to retrieve default values
      Returns:
      mapping from analysis options to their default values. An individual option will be mapped to an empty String if the option is invalid.

    • getCurrentAnalysisOptionsAndValues

      public Map<String,String> getCurrentAnalysisOptionsAndValues(Program program)
      Gets the given program's ANALYSIS_PROPERTIES and returns a HashMap of the program's analysis options to current values (values represented as strings).

      The string "(default)" is appended to the value if it represents the default value for the option it is assigned to.

      Parameters:
      program - the program to get analysis options from
      Returns:
      mapping of analysis options to current settings (represented as strings)

    • setAnalysisOptions

      public void setAnalysisOptions(Program program, Map<String,String> analysisSettings)
      Allows user to set analysis options by passing a mapping of analysis option to desired value. This method does the work of converting the option value to its actual object type (if needed).
      Parameters:
      program - the program for which analysis options should be set
      analysisSettings - a mapping from analysis options to desired new settings

    • setAnalysisOption

      public void setAnalysisOption(Program program, String optionName, String optionValue)
      Allows user to set one analysis option by passing in the analysis option to be changed and the new value of that option. This method does the work of converting the option value to its actual object type (if needed).
      Parameters:
      program - the program for which analysis options should be set
      optionName - the name of the option to be set
      optionValue - the new value of the option

    • setCurrentSelection

      public void setCurrentSelection(AddressSetView addressSet)
      Sets the selection state to the given address set.

      The actual behavior of the method depends on your environment, which can be GUI or headless:

      1. In the GUI environment this method will set the currentSelection variable to the given value, update the GhidraState's selection variable, and will set the Tool's selection to the given value.
      2. In the headless environment this method will set the currentSelection variable to the given value and update the GhidraState's selection variable.

      Parameters:
      addressSet - the set of addresses to include in the selection. If this value is null, the current selection will be cleared and the variables set to null.

    • createSelection

      public void createSelection(AddressSetView set)
      Calling this method is equivalent to calling setCurrentSelection(AddressSetView).
      Parameters:
      set - the addresses

    • removeSelection

      public void removeSelection()
      Clears the current selection. Calling this method is equivalent to calling setCurrentSelection(AddressSetView) with a null or empty AddressSet.

    • setCurrentHighlight

      public void setCurrentHighlight(AddressSetView addressSet)
      Sets the highlight state to the given address set.

      The actual behavior of the method depends on your environment, which can be GUI or headless:

      1. In the GUI environment this method will set the currentHighlight variable to the given value, update the GhidraState's highlight variable, and will set the Tool's highlight to the given value.
      2. In the headless environment this method will set the currentHighlight variable to the given value and update the GhidraState's highlight variable.

      Parameters:
      addressSet - the set of addresses to include in the highlight. If this value is null, the current highlight will be cleared and the variables set to null.

    • createHighlight

      public void createHighlight(AddressSetView set)
      Sets this script's highlight state (both the local variable currentHighlight and the GhidraState's currentHighlight) to the given address set. Also sets the tool's highlight if the tool exists. (Same as calling setCurrentHightlight(set);
      Parameters:
      set - the set of addresses to include in the highlight. May be null.

    • removeHighlight

      public void removeHighlight()
      Clears the current highlight. Sets this script's highlight state (both the local variable currentHighlight and the ghidraState's currentHighlight) to null. Also clears the tool's highlight if the tool exists.

    • setBackgroundColor

      public void setBackgroundColor(Address address, Color color) throws ImproperUseException
      Sets the background of the Listing at the given address to the given color. See the Listing help page in Ghidra help for more information.

      This method is unavailable in headless mode.

      Note: you can use the ColorizingService directly to access more color changing functionality. See the source code of this method to learn how to access services from a script.

      Parameters:
      address - The address at which to set the color
      color - The color to set
      Throws:
      ImproperUseException - if this method is run in headless mode
      See Also:

    • setBackgroundColor

      public void setBackgroundColor(AddressSetView addresses, Color color) throws ImproperUseException
      Sets the background of the Listing at the given addresses to the given color. See the Listing help page in Ghidra help for more information.

      This method is unavailable in headless mode.

      Note: you can use the ColorizingService directly to access more color changing functionality. See the source code of this method to learn how to access services from a script.

      Parameters:
      addresses - The addresses at which to set the color
      color - The color to set
      Throws:
      ImproperUseException - if this method is run in headless mode
      See Also:

    • clearBackgroundColor

      public void clearBackgroundColor(Address address) throws ImproperUseException
      Clears the background of the Listing at the given address to the given color. See the Listing help page in Ghidra help for more information.

      This method is unavailable in headless mode.

      Note: you can use the ColorizingService directly to access more color changing functionality. See the source code of this method to learn how to access services from a script.

      Parameters:
      address - The address at which to clear the color
      Throws:
      ImproperUseException - if this method is run in headless mode
      See Also:

    • clearBackgroundColor

      public void clearBackgroundColor(AddressSetView addresses) throws ImproperUseException
      Clears the background of the Listing at the given addresses to the given color. See the Listing help page in Ghidra help for more information.

      This method is unavailable in headless mode.

      Note: you can use the ColorizingService directly to access more color changing functionality. See the source code of this method to learn how to access services from a script.

      Parameters:
      addresses - The address at which to clear the color
      Throws:
      ImproperUseException - if this method is run in headless mode
      See Also:

    • createTableChooserDialog

      public TableChooserDialog createTableChooserDialog(String title, TableChooserExecutor executor) throws ImproperUseException
      Creates a TableChooserDialog that allows the script to display a list of addresses (and associated column data) in a table and also provides the capability to execute an action from a selection in the table.

      This method is unavailable in headless mode.

      Parameters:
      title - the title of the dialog
      executor - the TableChooserExecuter to be used to apply operations on table entries.
      Returns:
      a new TableChooserDialog.
      Throws:
      ImproperUseException - if this method is run in headless mode

    • createTableChooserDialog

      public TableChooserDialog createTableChooserDialog(String title, TableChooserExecutor executor, boolean isModal) throws ImproperUseException
      Creates a TableChooserDialog that allows the script to display a list of addresses (and associated column data) in a table and also provides the capability to execute an action from a selection in the table.

      This method is unavailable in headless mode.

      Parameters:
      title - of the dialog
      executor - the TableChooserExecuter to be used to apply operations on table entries.
      isModal - indicates whether the dialog should be modal or not
      Returns:
      a new TableChooserDialog.
      Throws:
      ImproperUseException - if this method is run in headless mode; if this script is run directly via Java or another script where the state does not include a tool.

    • getCodeUnitFormat

      public CodeUnitFormat getCodeUnitFormat()
      Returns the code unit format established for the code browser listing or a default format if no tool (e.g., headless).

      This format object may be used to format any code unit (instruction/data) using the same option settings.

      Returns:
      code unit format when in GUI mode, default format in headless

    • popup

      public void popup(String message)
      Displays a popup dialog with the specified message. The dialog title will be the name of this script.

      In headless mode, the message is displayed in the log output.

      Parameters:
      message - the message to display in the dialog

    • parseFile

      public File parseFile(String s)
      Parses a file from a string.
      Parameters:
      s - The string to parse.
      Returns:
      The file that was parsed from the string.
      Throws:
      IllegalArgumentException - if the parsed value is not a valid file.

    • askFile

      public File askFile(String title, String approveButtonText) throws CancelledException
      Returns a File object, using the String parameters for guidance. The actual behavior of the method depends on your environment, which can be GUI or headless.

      Regardless of environment -- if script arguments have been set, this method will use the next argument in the array and advance the array index so the next call to an ask method will get the next argument. If there are no script arguments and a .properties file sharing the same base name as the Ghidra Script exists (i.e., Script1.properties for Script1.java), then this method will then look there for the String value to return. The method will look in the .properties file by searching for a property name that is a space-separated concatenation of the input String parameters (title + " " + approveButtonText). If that property name exists and its value represents a valid absolute path of a valid File, then the .properties value will be used in the following way:

      1. In the GUI environment, this method displays a file chooser dialog that allows the user to select a file. If the file chooser dialog has been run before in the same session, the File selection will be pre-populated with the last-selected file. If not, the File selection will be pre-populated with the .properties value (if it exists).
      2. In the headless environment, this method returns a File object representing the .properties String value (if it exists), or throws an Exception if there is an invalid or missing .properties value.
      Parameters:
      title - the title of the dialog (in GUI mode) or the first part of the variable name (in headless mode or when using using .properties file)
      approveButtonText - the approve button text (in GUI mode - typically, this would be "Open" or "Save") or the second part of the variable name (in headless mode or when using .properties file)
      Returns:
      the selected file or null if no tool was available
      Throws:
      CancelledException - if the user hit the 'cancel' button in GUI mode
      IllegalArgumentException - if in headless mode, there was a missing or invalid file name specified in the .properties file

    • parseDirectory

      public File parseDirectory(String val)
      Parses a directory from a string.
      Parameters:
      val - The string to parse.
      Returns:
      The directory that was parsed from the string.
      Throws:
      IllegalArgumentException - if the parsed value is not a valid directory.

    • askDirectory

      public File askDirectory(String title, String approveButtonText) throws CancelledException
      Returns a directory File object, using the String parameters for guidance. The actual behavior of the method depends on your environment, which can be GUI or headless.

      Regardless of environment -- if script arguments have been set, this method will use the next argument in the array and advance the array index so the next call to an ask method will get the next argument. If there are no script arguments and a .properties file sharing the same base name as the Ghidra Script exists (i.e., Script1.properties for Script1.java), then this method will then look there for the String value to return. The method will look in the .properties file by searching for a property name that is a space-separated concatenation of the input String parameters (title + " " + approveButtonText). If that property name exists and its value represents a valid absolute path of a valid directory File, then the .properties value will be used in the following way:

      1. In the GUI environment, this method displays a file chooser dialog that allows the user to select a directory. If the file chooser dialog has been run before in the same session, the directory selection will be pre-populated with the last-selected directory. If not, the directory selection will be pre-populated with the .properties value (if it exists).
      2. In the headless environment, this method returns a directory File representing the .properties value (if it exists), or throws an Exception if there is an invalid or missing .properties value.
      Parameters:
      title - the title of the dialog (in GUI mode) or the first part of the variable name (in headless mode or when using .properties file)
      approveButtonText - the approve button text (in GUI mode - typically, this would be "Open" or "Save") or the second part of the variable name (in headless mode or when using .properties file)
      Returns:
      the selected directory or null if no tool was available
      Throws:
      CancelledException - if the user hit the 'cancel' button in GUI mode
      IllegalArgumentException - if in headless mode, there was a missing or invalid directory name specified in the .properties file

    • parseLanguageCompileSpecPair

      public LanguageCompilerSpecPair parseLanguageCompileSpecPair(String val)
      Parses a LanguageCompilerSpecPair from a string.
      Parameters:
      val - The string to parse.
      Returns:
      The directory that was parsed from the LanguageCompilerSpecPair.
      Throws:
      IllegalArgumentException - if the parsed value is not a valid LanguageCompilerSpecPair.

    • askLanguage

      public LanguageCompilerSpecPair askLanguage(String title, String approveButtonText) throws CancelledException
      Returns a LanguageCompilerSpecPair, using the String parameters for guidance. The actual behavior of the method depends on your environment, which can be GUI or headless.

      Regardless of environment -- if script arguments have been set, this method will use the next argument in the array and advance the array index so the next call to an ask method will get the next argument. If there are no script arguments and a .properties file sharing the same base name as the Ghidra Script exists (i.e., Script1.properties for Script1.java), then this method will then look there for the String value to return. The method will look in the .properties file by searching for a property name that is a space-separated concatenation of the input String parameters (title + " " + message). If that property name exists and its value represents a valid LanguageCompilerSpecPair value, then the .properties value will be used in the following way:

      1. In the GUI environment, this method displays a language table dialog and returns the selected language. If the same popup has been run before in the same session, the last-used language will be pre-selected. If not, the language specified in the .properties file will be pre-selected (if it exists).
      2. In the headless environment, this method returns a LanguageCompilerSpecPair representing the .properties value (if it exists), or throws an Exception if there is an invalid or missing .properties value.
      Parameters:
      title - the title of the dialog (in GUI mode) or the first part of the variable name (in headless mode or when using .properties file)
      approveButtonText - the approve button text (in GUI mode - typically, this would be "Open" or "Save") or the second part of the variable name (in headless mode or when using .properties file)
      Returns:
      the selected LanguageCompilerSpecPair
      Throws:
      CancelledException - if the user hit the 'cancel' button
      IllegalArgumentException - if in headless mode, there was a missing or invalid language specified in the .properties file

    • parseProjectFolder

      public DomainFolder parseProjectFolder(String val)
      Parses a ProjectFolder from a string.
      Parameters:
      val - The string to parse.
      Returns:
      The ProjectFolder that was parsed from the string.
      Throws:
      IllegalArgumentException - if the parsed value is not a valid ProjectFolder.

    • askProjectFolder

      public DomainFolder askProjectFolder(String title) throws CancelledException
      Returns a DomainFolder object, using the supplied title string for guidance. The actual behavior of the method depends on your environment, which can be GUI or headless.

      Regardless of environment -- if script arguments have been set, this method will use the next argument in the array and advance the array index so the next call to an ask method will get the next argument. If there are no script arguments and a .properties file sharing the same base name as the Ghidra Script exists (i.e., Script1.properties for Script1.java), then this method will then look there for the String value to return. The method will look in the .properties file by searching for a property name that is the title String parameter. If that property name exists and its value represents a valid project folder, then the .properties value will be used in the following way:

      1. In the GUI environment, this method displays a file chooser dialog that allows the user to select a project folder. The selected folder will be returned.
      2. In the headless environment, if a .properties file sharing the same base name as the Ghidra Script exists (i.e., Script1.properties for Script1.java), then this method looks there for the name of the project folder to return. The method will look in the .properties file by searching for a property name equal to the 'title' parameter. If that property name exists and its value represents a valid DomainFolder in the project, then that value is returned. Otherwise, an Exception is thrown if there is an invalid or missing .properties value.
      Parameters:
      title - the title of the dialog (GUI) or the variable name (headless or when using .properties file)
      Returns:
      the selected project folder or null if there was an invalid .properties value
      Throws:
      CancelledException - if the user hit the 'cancel' button in GUI mode
      IllegalArgumentException - if in headless mode, there was a missing or invalid project folder specified in the .properties file

    • parseInt

      public int parseInt(String val)
      Parses an integer from a string.
      Parameters:
      val - The string to parse.
      Returns:
      The integer that was parsed from the string.
      Throws:
      IllegalArgumentException - if the parsed value is not a valid integer.

    • askValues

      public GhidraValuesMap askValues(String title, String optionalMessage, GhidraValuesMap values) throws CancelledException
      Prompts for multiple values at the same time. To use this method, you must first create a GhidraValuesMap and define the values that will be supplied by this method. In the GUI environment, this will result in a single dialog with an entry for each value defined in the values map. This method returns a GhidraValuesMap with the values supplied by the user in GUI mode or command line arguments in headless mode. If the user cancels the dialog, a cancelled exception will be thrown, and unless it is explicity caught by the script, will terminate the script. Also, if the values map has a ValuesMapValidator, the values will be validated when the user presses the "OK" button and will only exit the dialog if the validate check passes. Otherwise, the validator should have reported an error message in the dialog and the dialog will remain visible.

      Regardless of environment -- if script arguments have been set, this method will use the next arguments in the array and advance the array index until all values in the values map have been satisfied and so the next call to an ask method will get the next argument after those consumed by this call.

      Parameters:
      title - the title of the dialog if in GUI mode
      optionalMessage - an optional message that is displayed in the dialog, just above the list of name/value pairs
      values - the GhidraValuesMap containing the values to include in the dialog.
      Returns:
      the GhidraValuesMap with values set from user input in the dialog (This is the same instance that was passed in, so you don't need to use this)
      Throws:
      CancelledException - if the user hit the 'cancel' button in GUI mode

    • askInt

      public int askInt(String title, String message) throws CancelledException
      Returns an int, using the String parameters for guidance. The actual behavior of the method depends on your environment, which can be GUI or headless.

      Regardless of environment -- if script arguments have been set, this method will use the next argument in the array and advance the array index so the next call to an ask method will get the next argument. If there are no script arguments and a .properties file sharing the same base name as the Ghidra Script exists (i.e., Script1.properties for Script1.java), then this method will then look there for the String value to return. The method will look in the .properties file by searching for a property name that is a space-separated concatenation of the input String parameters (title + " " + message). If that property name exists and its value represents a valid int value, then the .properties value will be used in the following way:

      1. In the GUI environment, this method displays a popup dialog that prompts the user for an int value. If the same popup has been run before in the same session, the int input field will be pre-populated with the last-used int. If not, the int input field will be pre-populated with the .properties value (if it exists).
      2. In the headless environment, this method returns an int value representing the .properties value (if it exists), or throws an Exception if there is an invalid or missing .properties value.
      Parameters:
      title - the title of the dialog (in GUI mode) or the first part of the variable name (in headless mode or when using .properties file)
      message - the message to display next to the input field (in GUI mode) or the second part of the variable name (in headless mode or when using .properties file)
      Returns:
      the user-specified int value
      Throws:
      CancelledException - if the user hit the 'cancel' button in GUI mode
      IllegalArgumentException - if in headless mode, there was a missing or invalid int specified in the .properties file

    • parseLong

      public long parseLong(String val)
      Parses a long from a string.
      Parameters:
      val - The string to parse.
      Returns:
      The long that was parsed from the string.
      Throws:
      IllegalArgumentException - if the parsed value is not a valid long.

    • askLong

      public long askLong(String title, String message) throws CancelledException
      Returns a long, using the String parameters for guidance. The actual behavior of the method depends on your environment, which can be GUI or headless.

      Regardless of environment -- if script arguments have been set, this method will use the next argument in the array and advance the array index so the next call to an ask method will get the next argument. If there are no script arguments and a .properties file sharing the same base name as the Ghidra Script exists (i.e., Script1.properties for Script1.java), then this method will then look there for the String value to return. The method will look in the .properties file by searching for a property name that is a space-separated concatenation of the input String parameters (title + " " + message). If that property name exists and its value represents a valid long value, then the .properties value will be used in the following way:

      1. In the GUI environment, this method displays a popup dialog that prompts the user for a long value. If the same popup has been run before in the same session, the long input field will be pre-populated with the last-used long. If not, the long input field will be pre-populated with the .properties value (if it exists).
      2. In the headless environment, this method returns a long value representing the .properties value (if it exists), or throws an Exception if there is an invalid or missing .properties value.
      Parameters:
      title - the title of the dialog (in GUI mode) or the first part of the variable name (in headless mode or when using .properties file)
      message - the message to display next to the input field (in GUI mode) or the second part of the variable name (in headless mode or when using .properties file)
      Returns:
      the user-specified long value
      Throws:
      CancelledException - if the user hit the 'cancel' button in GUI mode
      IllegalArgumentException - if in headless mode, there was a missing or invalid long specified in the .properties file

    • parseAddress

      public Address parseAddress(String val)
      Parses an address from a string.
      Parameters:
      val - The string to parse.
      Returns:
      The address that was parsed from the string.
      Throws:
      IllegalArgumentException - if there was a problem parsing an address from the string.

    • askAddress

      public Address askAddress(String title, String message) throws CancelledException
      Returns an Address, using the String parameters for guidance. The actual behavior of the method depends on your environment, which can be GUI or headless.

      Regardless of environment -- if script arguments have been set, this method will use the next argument in the array and advance the array index so the next call to an ask method will get the next argument. If there are no script arguments and a .properties file sharing the same base name as the Ghidra Script exists (i.e., Script1.properties for Script1.java), then this method will then look there for the String value to return. The method will look in the .properties file by searching for a property name that is a space-separated concatenation of the input String parameters (title + " " + message). If that property name exists and its value represents a valid Address value, then the .properties value will be used in the following way:

      1. In the GUI environment, this method displays a popup dialog that prompts the user for an address value. If the same popup has been run before in the same session, the address input field will be pre-populated with the last-used address. If not, the address input field will be pre-populated with the .properties value (if it exists).
      2. In the headless environment, this method returns an Address representing the .properties value (if it exists), or throws an Exception if there is an invalid or missing .properties value.
      Parameters:
      title - the title of the dialog (in GUI mode) or the first part of the variable name (in headless mode or when using .properties file)
      message - the message to display next to the input field (in GUI mode) or the second part of the variable name (in headless mode or when using .properties file)
      Returns:
      the user-specified Address value
      Throws:
      CancelledException - if the user hit the 'cancel' button in GUI mode
      IllegalArgumentException - if in headless mode, there was a missing or invalid Address specified in the .properties file

    • askAddress

      public Address askAddress(String title, String message, String defaultValue) throws CancelledException
      Returns an Address, using the String parameters for guidance. The actual behavior of the method depends on your environment, which can be GUI or headless.

      Regardless of environment -- if script arguments have been set, this method will use the next argument in the array and advance the array index so the next call to an ask method will get the next argument. If there are no script arguments and a .properties file sharing the same base name as the Ghidra Script exists (i.e., Script1.properties for Script1.java), then this method will then look there for the String value to return. The method will look in the .properties file by searching for a property name that is a space-separated concatenation of the input String parameters (title + " " + message). If that property name exists and its value represents a valid Address value, then the .properties value will be used in the following way:

      1. In the GUI environment, this method displays a popup dialog that prompts the user for an address value. If the same popup has been run before in the same session, the address input field will be pre-populated with the last-used address. If not, the address input field will be pre-populated with the .properties value (if it exists).
      2. In the headless environment, this method returns an Address representing the .properties value (if it exists), or throws an Exception if there is an invalid or missing .properties value.
      Parameters:
      title - the title of the dialog (in GUI mode) or the first part of the variable name (in headless mode or when using .properties file)
      message - the message to display next to the input field (in GUI mode) or the second part of the variable name (in headless mode or when using .properties file)
      defaultValue - the optional default address as a String - if null is passed or an invalid address is given no default will be shown in dialog
      Returns:
      the user-specified Address value
      Throws:
      CancelledException - if the user hit the 'cancel' button in GUI mode
      IllegalArgumentException - if in headless mode, there was a missing or invalid Address specified in the .properties file

    • parseBytes

      public byte[] parseBytes(String val)
      Parses bytes from a string.
      Parameters:
      val - The string to parse.
      Returns:
      The bytes that were parsed from the string.
      Throws:
      IllegalArgumentException - if there was a problem parsing bytes from the string.

    • askBytes

      public byte[] askBytes(String title, String message) throws CancelledException
      Returns a byte array, using the String parameters for guidance. The actual behavior of the method depends on your environment, which can be GUI or headless.

      Regardless of environment -- if script arguments have been set, this method will use the next argument in the array and advance the array index so the next call to an ask method will get the next argument. If there are no script arguments and a .properties file sharing the same base name as the Ghidra Script exists (i.e., Script1.properties for Script1.java), then this method will then look there for the String value to return. The method will look in the .properties file by searching for a property name that is a space-separated concatenation of the input String parameters (title + " " + message). If that property name exists and its value represents valid bytes, then the .properties value will be used in the following way:

      1. In the GUI environment, this method displays a popup dialog that prompts the user for a byte pattern. If the same popup has been run before in the same session, the byte pattern input field will be pre-populated with the last-used bytes string. If not, the byte pattern input field will be pre-populated with the .properties value (if it exists).
      2. In the headless environment, this method returns a byte array representing the .properties byte pattern value (if it exists), or throws an Exception if there is an invalid or missing .properties value.
      Parameters:
      title - the title of the dialog (in GUI mode) or the first part of the variable name (in headless mode or when using .properties file)
      message - the message to display next to the input field (in GUI mode) or the second part of the variable name (in headless mode or when using .properties file)
      Returns:
      the user-specified byte array
      Throws:
      CancelledException - if the user hit the 'cancel' button in GUI mode
      IllegalArgumentException - if in headless mode, there was a missing or invalid bytes string specified in the .properties file

    • askProgram

      public Program askProgram(String title) throws VersionException, IOException, CancelledException
      Returns a Program, using the title parameter for guidance. The actual behavior of the method depends on your environment, which can be GUI or headless. If in headless mode, the program will not be upgraded (see askProgram(String, boolean) if you want more control). In GUI mode, the user will be prompted to upgrade.
      Regardless of environment -- if script arguments have been set, this method will use the next argument in the array and advance the array index so the next call to an ask method will get the next argument. If there are no script arguments and a .properties file sharing the same base name as the Ghidra Script exists (i.e., Script1.properties for Script1.java), then this method will then look there for the String value to return. The method will look in the .properties file by searching for a property name that is the title String parameter. If that property name exists and its value represents a valid program, then the .properties value will be used in the following way:
      1. In the GUI environment, this method displays a popup dialog that prompts the user to select a program.
      2. In the headless environment, if a .properties file sharing the same base name as the Ghidra Script exists (i.e., Script1.properties for Script1.java), then this method looks there for the name of the program to return. The method will look in the .properties file by searching for a property name equal to the 'title' parameter. If that property name exists and its value represents a valid Program in the project, then that value is returned. Otherwise, an Exception is thrown if there is an invalid or missing .properties value.
      Parameters:
      title - the title of the pop-up dialog (in GUI mode) or the variable name (in headless mode)
      Returns:
      the user-selected Program with this script as the consumer if a program was selected. Null is returned if a program is not selected. NOTE: It is very important that the program instance returned by this method ALWAYS be properly released when no longer needed. The script which invoked this method must be specified as the consumer upon release (i.e., program.release(this) - failure to properly release the program may result in improper project disposal. If the program was opened by the tool, the tool will be a second consumer responsible for its own release.
      Throws:
      VersionException - if the Program is out-of-date from the version of Ghidra and an upgrade was not been performed. In non-headless mode, the user will have already been notified via a popup dialog.
      IOException - if there is an error accessing the Program's DomainObject
      CancelledException - if the program open operation is cancelled
      IllegalArgumentException - if in headless mode, there was a missing or invalid program specified in the .properties file

    • askProgram

      public Program askProgram(String title, boolean upgradeIfNeeded) throws VersionException, IOException, CancelledException
      Returns a Program, using the title parameter for guidance with the option to upgrade if needed. The actual behavior of the method depends on your environment, which can be GUI or headless. You can control whether or not the program is allowed to upgrade via the upgradeIfNeeded parameter.
      Regardless of environment -- if script arguments have been set, this method will use the next argument in the array and advance the array index so the next call to an ask method will get the next argument. If there are no script arguments and a .properties file sharing the same base name as the Ghidra Script exists (i.e., Script1.properties for Script1.java), then this method will then look there for the String value to return. The method will look in the .properties file by searching for a property name that is the title String parameter. If that property name exists and its value represents a valid program, then the .properties value will be used in the following way:
      1. In the GUI environment, this method displays a popup dialog that prompts the user to select a program.
      2. In the headless environment, if a .properties file sharing the same base name as the Ghidra Script exists (i.e., Script1.properties for Script1.java), then this method looks there for the name of the program to return. The method will look in the .properties file by searching for a property name equal to the 'title' parameter. If that property name exists and its value represents a valid Program in the project, then that value is returned. Otherwise, an Exception is thrown if there is an invalid or missing .properties value.
      Parameters:
      title - the title of the pop-up dialog (in GUI mode) or the variable name (in headless mode)
      upgradeIfNeeded - if true, program will be upgraded if needed and possible. If false, the program will only be upgraded after first prompting the user. In headless mode, it will attempt to upgrade only if the parameter is true.
      Returns:
      the user-selected Program with this script as the consumer if a program was selected. Null is returned if a program is not selected. NOTE: It is very important that the program instance returned by this method ALWAYS be properly released when no longer needed. The script which invoked this method must be specified as the consumer upon release (i.e., program.release(this) - failure to properly release the program may result in improper project disposal. If the program was opened by the tool, the tool will be a second consumer responsible for its own release.
      Throws:
      VersionException - if the Program is out-of-date from the version of GHIDRA and an upgrade was not been performed. In non-headless mode, the user will have already been notified via a popup dialog.
      IOException - if there is an error accessing the Program's DomainObject
      CancelledException - if the program open operation is cancelled
      IllegalArgumentException - if in headless mode, there was a missing or invalid program specified in the .properties file

    • parseDomainFile

      public DomainFile parseDomainFile(String val)
      Parses a DomainFile from a string.
      Parameters:
      val - The string to parse.
      Returns:
      The DomainFile that was parsed from the string.
      Throws:
      IllegalArgumentException - if the parsed value is not a valid DomainFile.

    • askDomainFile

      public DomainFile askDomainFile(String title) throws CancelledException
      Returns a DomainFile, using the title parameter for guidance. The actual behavior of the method depends on your environment, which can be GUI or headless.

      Regardless of environment -- if script arguments have been set, this method will use the next argument in the array and advance the array index so the next call to an ask method will get the next argument. If there are no script arguments and a .properties file sharing the same base name as the Ghidra Script exists (i.e., Script1.properties for Script1.java), then this method will then look there for the String value to return. The method will look in the .properties file by searching for a property name that is the title String parameter. If that property name exists and its value represents a valid domain file, then the .properties value will be used in the following way:

      1. In the GUI environment, this method displays a popup dialog listing all domain files in the current project, allowing the user to select one.
      2. In the headless environment, if a .properties file sharing the same base name as the Ghidra Script exists (i.e., Script1.properties for Script1.java), then this method looks there for the name of the DomainFile to return. The method will look in the .properties file by searching for a property name equal to the 'title' parameter. If that property name exists and its value represents a valid DomainFile in the project, then that value is returned. Otherwise, an Exception is thrown if there is an invalid or missing .properties value.
      Parameters:
      title - the title of the pop-up dialog (in GUI mode) or the variable name (in headless mode or when using .properties file)
      Returns:
      the user-selected domain file
      Throws:
      CancelledException - if the operation is cancelled
      IllegalArgumentException - if in headless mode, there was a missing or invalid domain file specified in the .properties file

    • parseDouble

      public double parseDouble(String val)
      Parses a double from a string.
      Parameters:
      val - The string to parse.
      Returns:
      The double that was parsed from the string.
      Throws:
      IllegalArgumentException - if the parsed value is not a valid double.

    • askDouble

      public double askDouble(String title, String message) throws CancelledException
      Returns a double, using the String parameters for guidance. The actual behavior of the method depends on your environment, which can be GUI or headless.

      Regardless of environment -- if script arguments have been set, this method will use the next argument in the array and advance the array index so the next call to an ask method will get the next argument. If there are no script arguments and a .properties file sharing the same base name as the Ghidra Script exists (i.e., Script1.properties for Script1.java), then this method will then look there for the String value to return. The method will look in the .properties file by searching for a property name that is a space-separated concatenation of the input String parameters (title + " " + message). If that property name exists and its value represents a valid double value, then the .properties value will be used in the following way:

      1. In the GUI environment, this method displays a popup dialog that prompts the user for a double value. If the same popup has been run before in the same session, the double input field will be pre-populated with the last-used double. If not, the double input field will be pre-populated with the .properties value (if it exists).
      2. In the headless environment, this method returns a double value representing the .properties value (if it exists), or throws an Exception if there is an invalid or missing .properties value.

      Note that in both headless and GUI modes, you may specify "PI" or "E" and get the corresponding floating point value to 15 decimal places.

      Parameters:
      title - the title of the dialog (in GUI mode) or the first part of the variable name (in headless mode or when using .properties file)
      message - the message to display next to the input field (in GUI mode) or the second part of the variable name (in headless mode or when using .properties file)
      Returns:
      the user-specified double value
      Throws:
      CancelledException - if the user hit the 'cancel' button in GUI mode
      IllegalArgumentException - if in headless mode, there was a missing or invalid double specified in the .properties file

    • askString

      public String askString(String title, String message) throws CancelledException
      Returns a String, using the String input parameters for guidance. The actual behavior of the method depends on your environment, which can be GUI or headless.

      Regardless of environment -- if script arguments have been set, this method will use the next argument in the array and advance the array index so the next call to an ask method will get the next argument. If there are no script arguments and a .properties file sharing the same base name as the Ghidra Script exists (i.e., Script1.properties for Script1.java), then this method will then look there for the String value to return. The method will look in the .properties file by searching for a property name that is a space-separated concatenation of the input String parameters (title + " " + message). If that property name exists and its value represents a valid String value, then the .properties value will be used in the following way:

      1. In the GUI environment, this method displays a popup dialog that prompts the user for a String value. If the same popup has been run before in the same session, the String input field will be pre-populated with the last-used String. If not, the String input field will be pre-populated with the .properties value (if it exists).
      2. In the headless environment, this method returns a String value representing the .properties value (if it exists), or throws an Exception if there is an invalid or missing .properties value.
      Parameters:
      title - the title of the dialog (in GUI mode) or the first part of the variable name (in headless mode or when using .properties file)
      message - the message to display next to the input field (in GUI mode) or the second part of the variable name (in headless mode or when using .properties file)
      Returns:
      the user-specified String value
      Throws:
      CancelledException - if the user hit the 'cancel' button in GUI mode
      IndexOutOfBoundsException - if in headless mode and arguments are being used, but not enough arguments were passed in to accommodate the request.
      IllegalArgumentException - if in headless mode, there was an invalid String specified in the arguments, or an invalid or missing String specified in the .properties file

    • askString

      public String askString(String title, String message, String defaultValue) throws CancelledException
      Returns a String, using the String input parameters for guidance. The actual behavior of the method depends on your environment, which can be GUI or headless.

      Regardless of environment -- if script arguments have been set, this method will use the next argument in the array and advance the array index so the next call to an ask method will get the next argument. If there are no script arguments and a .properties file sharing the same base name as the Ghidra Script exists (i.e., Script1.properties for Script1.java), then this method will then look there for the String value to return. The method will look in the .properties file by searching for a property name that is a space-separated concatenation of the input String parameters (title + " " + message). If that property name exists and its value represents a valid String value, then the .properties value will be used in the following way:

      1. In the GUI environment, this method displays a popup dialog that prompts the user for a String value. The pre-populated value for the String input field will be the last-used String (if the dialog has been run before). If that does not exist, the pre-populated value is the .properties value. If that does not exist or is invalid, then the 'defaultValue' parameter is used (as long as it is not null or the empty String).
      2. In the headless environment, this method returns a String value representing the .properties value (if it exists). Otherwise, if the 'defaultValue' parameter is not null or an empty String, it is returned. In all other cases, an exception is thrown.
      Parameters:
      title - the title of the dialog (in GUI mode) or the first part of the variable name (in headless mode or when using .properties file)
      message - the message to display next to the input field (in GUI mode) or the second part of the variable name (in headless mode or when using .properties file)
      defaultValue - the optional default value
      Returns:
      the user-specified String value
      Throws:
      CancelledException - if the user hit the 'cancel' button in GUI mode
      IllegalArgumentException - if in headless mode, there was a missing or invalid String specified in the .properties file

    • askPassword

      public Password askPassword(String title, String prompt) throws CancelledException
      Returns a Password, using the String input parameters for guidance. This method can only be used in headed mode.

      In the GUI environment, this method displays a password popup dialog that prompts the user for a password. There is no pre-population of the input. If the user cancels the dialog, it is immediately disposed, and any input to that dialog is cleared from memory. If the user completes the dialog, then the password is returned in a wrapped buffer. The buffer can be cleared by calling Password.close(); however, it is meant to be used in a try-with-resources block. The pattern does not guarantee protection of the password, but it will help you avoid some typical pitfalls: 

       String user = askString("Login", "Username:");
 Project project;
 try (Password password = askPassword("Login", "Password:")) {
        project = doLoginAndOpenProject(user, password.getPasswordChars());
 }
      The buffer will be zero-filled upon leaving the try-with-resources block. If, in the sample, the doLoginAndOpenProject method or any part of its implementation needs to retain the password, it must make a copy. It is then the implementation's responsibility to protect its copy.
      Parameters:
      title - the title of the dialog
      prompt - the prompt to the left of the input field, or null to display "Password:"
      Returns:
      the password
      Throws:
      CancelledException - if the user cancels
      ImproperUseException - if in headless mode

    • parseChoice

      public <T> T parseChoice(String val, List<T> validChoices)
      Parses a choice from a string.
      Parameters:
      val - The string to parse.
      validChoices - An array of valid choices.
      Returns:
      The choice
      Throws:
      IllegalArgumentException - if the parsed string was not a valid choice.

    • askChoice

      public <T> T askChoice(String title, String message, List<T> choices, T defaultValue) throws CancelledException
      Returns an object that represents one of the choices in the given list. The actual behavior of the method depends on your environment, which can be GUI or headless.

      Regardless of environment -- if script arguments have been set, this method will use the next argument in the array and advance the array index so the next call to an ask method will get the next argument. If there are no script arguments and a .properties file sharing the same base name as the Ghidra Script exists (i.e., Script1.properties for Script1.java), then this method will then look there for the String value to return. The method will look in the .properties file by searching for a property name that is a space-separated concatenation of the input String parameters (title + " " + message). If that property name exists and its value represents a valid choice, then the .properties value will be used in the following way:

      1. In the GUI environment, this method displays a popup dialog that prompts the user to choose from the given list of objects. The pre-chosen choice will be the last user-chosen value (if the dialog has been run before). If that does not exist, the pre-chosen value is the .properties value. If that does not exist or is invalid, then the 'defaultValue' parameter is used (as long as it is not null).
      2. In the headless environment, this method returns an object representing the .properties value (if it exists and is a valid choice), or throws an Exception if there is an invalid or missing .properties value.
      Parameters:
      title - the title of the dialog (in GUI mode) or the first part of the variable name (in headless mode or when using .properties file)
      message - the message to display next to the input field (in GUI mode) or the second part of the variable name (in headless mode or when using .properties file)
      choices - set of choices (toString() value of each object will be displayed in the dialog)
      defaultValue - the default value to display in the input field; may be null, but must be a valid choice if non-null.
      Returns:
      the user-selected value
      Throws:
      CancelledException - if the user hit the 'cancel' button
      IllegalArgumentException - if in headless mode, there was a missing or invalid choice specified in the .properties file

    • parseChoices

      public <T> List<T> parseChoices(String s, List<T> validChoices)
      Parses choices from a string. The string must be surrounded by quotes, with a ';' as the separator.
      Parameters:
      s - The string to parse.
      validChoices - An array of valid choices.
      Returns:
      The choices, if they found in the array of choices.
      Throws:
      IllegalArgumentException - if the parsed string did not contain any valid choices.

    • parseChoices

      public <T> List<T> parseChoices(String val, List<T> validChoices, List<String> stringRepresentationOfValidChoices)
      Parses choices from a string.
      Parameters:
      val - The string to parse.
      validChoices - A list of valid choices.
      stringRepresentationOfValidChoices - An corresponding array of valid choice string representations.
      Returns:
      The choices
      Throws:
      IllegalArgumentException - if the parsed string did not contain any valid choices.

    • askChoices

      public <T> List<T> askChoices(String title, String message, List<T> choices) throws CancelledException
      Returns an array of Objects representing one or more choices from the given list. The actual behavior of the method depends on your environment, which can be GUI or headless.

      Regardless of environment -- if script arguments have been set, this method will use the next argument in the array and advance the array index so the next call to an ask method will get the next argument. If there are no script arguments and a .properties file sharing the same base name as the Ghidra Script exists (i.e., Script1.properties for Script1.java), then this method will then look there for the String value to return. The method will look in the .properties file by searching for a property name that is a space-separated concatenation of the input String parameters (title + " " + message). If that property name exists and its value represents valid choices, then the .properties value will be used in the following way:

      1. In the GUI environment, this method displays a pop-up dialog that presents the user with checkbox choices (to allow a more flexible option where the user can pick some, all, or none).
      2. In the headless environment, if a .properties file sharing the same base name as the Ghidra Script exists (i.e., Script1.properties for Script1.java), then this method looks there for the choices to return. The method will look in the .properties file by searching for a property name equal to a space-separated concatenation of the String parameters (title + " " + message). If that property name exists and represents a list (one or more) of valid choice(s) in the form "choice1;choice2;choice3;..." (<-- note the quotes surrounding the choices), then an Object array of those choices is returned. Otherwise, an Exception is thrown if there is an invalid or missing .properties value.
      Parameters:
      title - the title of the dialog (in GUI mode) or the first part of the variable name (in headless mode or when using .properties file)
      message - the message to display with the choices (in GUI mode) or the second part of the variable name (in headless mode or when using .properties file)
      choices - set of choices (toString() value of each object will be displayed in the dialog)
      Returns:
      the user-selected value(s); an empty list if no selection was made
      Throws:
      CancelledException - if the user hits the 'cancel' button
      IllegalArgumentException - if in headless mode, there was a missing or invalid set of choices specified in the .properties file

    • askChoices

      public <T> List<T> askChoices(String title, String message, List<T> choices, List<String> choiceLabels) throws CancelledException
      Returns an array of Objects representing one or more choices from the given list. The user specifies the choices as Objects, also passing along a corresponding array of String representations for each choice (used as the checkbox label). The actual behavior of the method depends on your environment, which can be GUI or headless.

      Regardless of environment -- if script arguments have been set, this method will use the next argument in the array and advance the array index so the next call to an ask method will get the next argument. If there are no script arguments and a .properties file sharing the same base name as the Ghidra Script exists (i.e., Script1.properties for Script1.java), then this method will then look there for the String value to return. The method will look in the .properties file by searching for a property name that is a space-separated concatenation of the input String parameters (title + " " + message). If that property name exists and its value represents valid choices, then the .properties value will be used in the following way:

      1. In the GUI environment, this method displays a pop-up dialog that presents the user with checkbox choices (to allow a more flexible option where the user can pick some, all, or none).
      2. In the headless environment, if a .properties file sharing the same base name as the Ghidra Script exists (i.e., Script1.properties for Script1.java), then this method looks there for the choices to return. The method will look in the .properties file by searching for a property name equal to a space-separated concatenation of the String parameters (title + " " + message). If that property name exists and represents a list (one or more) of valid choice(s) in the form "choice1;choice2;choice3;..." (<-- note the quotes surrounding the choices), then an Object array of those choices is returned. Otherwise, an Exception is thrown if there is an invalid or missing .properties value. NOTE: the choice names for this method must match those in the stringRepresentationOfChoices array.
      Parameters:
      title - the title of the dialog (in GUI mode) or the first part of the variable name (in headless mode or when using .properties file)
      message - the message to display with the choices (in GUI mode) or the second part of the variable name (in headless mode or when using .properties file)
      choices - set of choices
      choiceLabels - the String representation for each choice, used for checkbox labels
      Returns:
      the user-selected value(s); null if no selection was made
      Throws:
      CancelledException - if the user hits the 'cancel' button
      IllegalArgumentException - if choices is empty; if in headless mode, there was a missing or invalid set of choices specified in the .properties file

    • parseBoolean

      public Boolean parseBoolean(String val)
      Parses a boolean from a string.
      Parameters:
      val - The string to parse.
      Returns:
      The boolean that was parsed from the string.
      Throws:
      IllegalArgumentException - if the parsed value is not a valid boolean.

    • askYesNo

      public boolean askYesNo(String title, String question)
      Returns a boolean value, using the String parameters for guidance. The actual behavior of the method depends on your environment, which can be GUI or headless.

      Regardless of environment -- if script arguments have been set, this method will use the next argument in the array and advance the array index so the next call to an ask method will get the next argument. If there are no script arguments and a .properties file sharing the same base name as the Ghidra Script exists (i.e., Script1.properties for Script1.java), then this method will then look there for the String value to return. The method will look in the .properties file by searching for a property name that is a space-separated concatenation of the input String parameters (title + " " + question). If that property name exists and its value represents a valid boolean value, then the .properties value will be used in the following way:

      1. In the GUI environment, this method displays a popup dialog that prompts the user with a yes/no dialog with the specified title and question. Returns true if the user selects "yes" to the question or false if the user selects "no".
      2. In the headless environment, if a .properties file sharing the same base name as the Ghidra Script exists (i.e., Script1.properties for Script1.java), then this method looks there for the boolean value to return. The method will look in the .properties file by searching for a property name that is a space-separated concatenation of the String parameters (title + " " + question). If that property name exists and its value represents a valid boolean value (either 'true' or 'false', case insensitive), then that value is returned. Otherwise, an Exception is thrown if there is an invalid or missing .properties value.
      Parameters:
      title - the title of the dialog (in GUI mode) or the first part of the variable name (in headless mode)
      question - the question to display to the user (in GUI mode) or the second part of the variable name (in headless mode)
      Returns:
      true if the user selects "yes" to the question (in GUI mode) or "true" (in headless mode)
      Throws:
      IllegalArgumentException - if in headless mode, there was a missing or invalid boolean specified in the .properties file

    • toHexString

      public String toHexString(byte b, boolean zeropad, boolean header)
      Returns a hex string representation of the byte.
      Parameters:
      b - the integer
      zeropad - true if the value should be zero padded
      header - true if "0x" should be prepended
      Returns:
      the hex formatted string

    • toHexString

      public String toHexString(short s, boolean zeropad, boolean header)
      Returns a hex string representation of the short.
      Parameters:
      s - the short
      zeropad - true if the value should be zero padded
      header - true if "0x" should be prepended
      Returns:
      the hex formatted string

    • toHexString

      public String toHexString(int i, boolean zeropad, boolean header)
      Returns a hex string representation of the integer.
      Parameters:
      i - the integer
      zeropad - true if the value should be zero padded
      header - true if "0x" should be prepended
      Returns:
      the hex formatted string

    • toHexString

      public String toHexString(long l, boolean zeropad, boolean header)
      Returns a hex string representation of the long.
      Parameters:
      l - the long
      zeropad - true if the value should be zero padded
      header - true if "0x" should be prepended
      Returns:
      the hex formatted string

    • goTo

      public boolean goTo(Address address)
      Sends a 'goto' event that navigates the listing to the specified address.
      Parameters:
      address - the address to 'goto'
      Returns:
      true if the address is valid

    • goTo

      public boolean goTo(Symbol symbol)
      Sends a 'goto' event that navigates the listing to the specified symbol.
      Parameters:
      symbol - the symbol to 'goto'
      Returns:
      true if the symbol is valid

    • goTo

      public boolean goTo(Function function)
      Sends a 'goto' event that navigates the listing to the specified function.
      Parameters:
      function - the function to 'goto'
      Returns:
      true if the function is valid

    • importFile

      public Program importFile(File file) throws Exception
      Attempts to import the specified file. It attempts to detect the format and automatically import the file. If the format is unable to be determined, then null is returned. For more control over the import process, AutoImporter may be directly called.

      NOTE: The returned Program is not automatically saved into the current project.

      NOTE: It is the responsibility of the script that calls this method to release the returned Program with DomainObject.release(Object consumer) when it is no longer needed, where consumer is this.

      Parameters:
      file - the file to import
      Returns:
      the newly imported program, or null
      Throws:
      Exception - if any exceptions occur while importing

    • importFileAsBinary

      public Program importFileAsBinary(File file, Language language, CompilerSpec compilerSpec) throws Exception
      Imports the specified file as raw binary. For more control over the import process, AutoImporter may be directly called.

      NOTE: It is the responsibility of the script that calls this method to release the returned Program with DomainObject.release(Object consumer) when it is no longer needed, where consumer is this.

      Parameters:
      file - the file to import
      language - the language of the new program
      compilerSpec - the compilerSpec to use for the import.
      Returns:
      the newly created program, or null
      Throws:
      Exception - if any exceptions occur when importing

    • openProgram

      public void openProgram(Program program)
      Opens the specified program in the current tool.
      Parameters:
      program - the program to open

    • closeProgram

      public void closeProgram(Program program)
      Closes the specified program in the current tool.
      Parameters:
      program - the program to close

    • createProgram

      public Program createProgram(String programName, LanguageID languageID, CompilerSpecID compilerSpecID) throws Exception
      Creates a new program with specified name and language name. The actual language object is located using the language name provided.

      Please note: the program is not automatically saved into the program.

      Parameters:
      programName - the program name
      languageID - the language ID
      compilerSpecID - the compiler Spec ID
      Returns:
      the new unsaved program
      Throws:
      Exception - the language name is invalid or an I/O error occurs

    • createProgram

      public Program createProgram(String programName, LanguageID languageID) throws Exception
      Creates a new program with specified name and language name. The actual language object is located using the language name provided.

      Please note: the program is not automatically saved into the program.

      Parameters:
      programName - the program name
      languageID - the language name
      Returns:
      the new unsaved program
      Throws:
      Exception - the language name is invalid or an I/O error occurs

    • createProgram

      public Program createProgram(String programName, Language language, CompilerSpec compilerSpec) throws Exception
      Creates a new program with specified name and language. It uses the default compilerSpec for the given language.

      Please note: the program is not automatically saved into the project.

      Parameters:
      programName - the program name
      language - the language
      compilerSpec - the compilerSpec to use.
      Returns:
      the new unsaved program
      Throws:
      Exception - the language name is invalid or an I/O error occurs

    • setToolStatusMessage

      public void setToolStatusMessage(String msg, boolean beep) throws ImproperUseException
      Display a message in tools status bar.

      This method is unavailable in headless mode.

      Parameters:
      msg - the text to display.
      beep - if true, causes the tool to beep.
      Throws:
      ImproperUseException - if this method is run in headless mode

    • show

      public void show(Address[] addresses) throws ImproperUseException
      Displays the address array in a table component. The table contains an address column, a label column, and a preview column.

      This method is unavailable in headless mode.

      Parameters:
      addresses - the address array to display
      Throws:
      ImproperUseException - if this method is run in headless mode

    • show

      public void show(String title, AddressSetView addresses) throws ImproperUseException
      Displays the given AddressSet in a table, in a dialog.

      This method is unavailable in headless mode.

      Parameters:
      title - The title of the table
      addresses - The addresses to display
      Throws:
      ImproperUseException - if this method is run in headless mode

    • getPlateCommentAsRendered

      public String getPlateCommentAsRendered(Address address)
      Returns the PLATE comment at the specified address, as rendered. Comments support annotations, which are displayed differently than the raw text. If you want the raw text, then you must call FlatProgramAPI.getPlateComment(Address). This method returns the text as seen in the display.
      Parameters:
      address - the address to get the comment
      Returns:
      the PLATE comment at the specified address or null if one does not exist
      See Also:

    • getPreCommentAsRendered

      public String getPreCommentAsRendered(Address address)
      Returns the PRE comment at the specified address. If you want the raw text, then you must call FlatProgramAPI.getPreComment(Address). This method returns the text as seen in the display.
      Parameters:
      address - the address to get the comment
      Returns:
      the PRE comment at the specified address or null if one does not exist
      See Also:

    • getPostCommentAsRendered

      public String getPostCommentAsRendered(Address address)
      Returns the POST comment at the specified address. If you want the raw text, then you must call FlatProgramAPI.getPostComment(Address). This method returns the text as seen in the display.
      Parameters:
      address - the address to get the comment
      Returns:
      the POST comment at the specified address or null if one does not exist
      See Also:

    • getEOLCommentAsRendered

      public String getEOLCommentAsRendered(Address address)
      Returns the EOL comment at the specified address. If you want the raw text, then you must call FlatProgramAPI.getEOLComment(Address). This method returns the text as seen in the display.
      Parameters:
      address - the address to get the comment
      Returns:
      the EOL comment at the specified address or null if one does not exist
      See Also:

    • getRepeatableCommentAsRendered

      public String getRepeatableCommentAsRendered(Address address)
      Returns the repeatable comment at the specified address. If you want the raw text, then you must call FlatProgramAPI.getRepeatableComment(Address). This method returns the text as seen in the display.
      Parameters:
      address - the address to get the comment
      Returns:
      the repeatable comment at the specified address or null if one does not exist
      See Also: