Package ghidra.app.script

Class GhidraScript

  • Direct Known Subclasses:
    HeadlessScript, PythonScript
    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:
    GhidraState, Program

    • Constructor Detail

      • GhidraScript

        public GhidraScript()

    • Method Detail

      • run

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

      • execute

        public final void execute​(GhidraState runState,
                          TaskMonitor runMonitor,
                          java.io.PrintWriter runWriter)
                   throws java.lang.Exception
        Throws:
        java.lang.Exception

      • loadPropertiesFile

        protected void loadPropertiesFile()
                           throws java.io.IOException
        Throws:
        java.io.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​(java.util.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​(java.lang.String dirLocation,
                                      java.lang.String basename)
                               throws java.io.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:
        java.io.IOException - if there is an exception loading the new properties file

      • setPropertiesFile

        public void setPropertiesFile​(java.io.File propertiesFile)
                       throws java.io.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:
        java.io.IOException - if there is an exception reading the properties

      • getProjectRootFolder

        protected 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)

      • 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​(java.lang.String username,
                                          java.lang.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 java.lang.String getCategory()
        Returns the category for this script.
        Returns:
        the category for this script

      • getUserName

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

      • toString

        public final java.lang.String toString()
        Overrides:
        toString in class java.lang.Object

      • getScriptName

        public final java.lang.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 java.lang.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​(java.lang.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 java.lang.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​(java.lang.String scriptName)
                     throws java.lang.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:
        java.lang.IllegalArgumentException - if the script does not exist
        java.lang.Exception - if any exceptions occur while running the script
        See Also:
        runScriptPreserveMyState(String), runScript(String, GhidraState)

      • runScript

        public final void runScript​(java.lang.String scriptName,
                            java.lang.String[] scriptArguments)
                     throws java.lang.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:
        java.lang.IllegalArgumentException - if the script does not exist
        java.lang.Exception - if any exceptions occur while running the script
        See Also:
        runScriptPreserveMyState(String), runScript(String, GhidraState)

      • runScriptPreserveMyState

        public final GhidraState runScriptPreserveMyState​(java.lang.String scriptName)
                                           throws java.lang.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:
        java.lang.IllegalArgumentException - if the script does not exist
        java.lang.Exception - if any exceptions occur while running the script
        See Also:
        runScript(String), runScript(String, GhidraState)

      • runScript

        public void runScript​(java.lang.String scriptName,
                      GhidraState scriptState)
               throws java.lang.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:
        java.lang.IllegalArgumentException - if the script does not exist
        java.lang.Exception - if any exceptions occur while running the script
        See Also:
        runScriptPreserveMyState(String), runScript(String)

      • runScript

        public void runScript​(java.lang.String scriptName,
                      java.lang.String[] scriptArguments,
                      GhidraState scriptState)
               throws java.lang.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:
        java.lang.IllegalArgumentException - if the script does not exist
        java.lang.Exception - if any exceptions occur while running the script
        See Also:
        runScriptPreserveMyState(String), runScript(String)

      • runCommand

        public final boolean runCommand​(Command 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 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:
        Language

      • getDemangled

        public java.lang.String getDemangled​(java.lang.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​(java.lang.String message)
        Prints the message to the console followed by a line feed.
        Parameters:
        message - the message to print
        See Also:
        printf(String, Object...)

      • printf

        public void printf​(java.lang.String message,
                   java.lang.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:
        String.format(String, Object...), Formatter, print(String), println(String)

      • print

        public void print​(java.lang.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:
        printf(String, Object...)

      • printerr

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

      • getAnalysisOptionDescription

        public java.lang.String getAnalysisOptionDescription​(Program program,
                                                     java.lang.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 java.util.Map<java.lang.String,​java.lang.String> getAnalysisOptionDescriptions​(Program program,
                                                                                            java.util.List<java.lang.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,
                                java.lang.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,
                                 java.util.List<java.lang.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,
                                            java.lang.String analysisOption,
                                            java.lang.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 java.lang.String getAnalysisOptionDefaultValue​(Program program,
                                                      java.lang.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 java.util.Map<java.lang.String,​java.lang.String> getAnalysisOptionDefaultValues​(Program program,
                                                                                             java.util.List<java.lang.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 java.util.Map<java.lang.String,​java.lang.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,
                               java.util.Map<java.lang.String,​java.lang.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,
                              java.lang.String optionName,
                              java.lang.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.

      • 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,
                               java.awt.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(AddressSetView, Color), clearBackgroundColor(Address), ColorizingService

      • setBackgroundColor

        public void setBackgroundColor​(AddressSetView addresses,
                               java.awt.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:
        setBackgroundColor(Address, Color), clearBackgroundColor(AddressSetView), ColorizingService

      • 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:
        setBackgroundColor(AddressSetView, Color), clearBackgroundColor(AddressSetView), ColorizingService

      • 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:
        setBackgroundColor(AddressSetView, Color), clearBackgroundColor(AddressSetView), ColorizingService

      • createTableChooserDialog

        public TableChooserDialog createTableChooserDialog​(java.lang.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​(java.lang.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​(java.lang.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 java.io.File parseFile​(java.lang.String s)
        Parses a file from a string.
        Parameters:
        s - The string to parse.
        Returns:
        The file that was parsed from the string.
        Throws:
        java.lang.IllegalArgumentException - if the parsed value is not a valid file.

      • askFile

        public java.io.File askFile​(java.lang.String title,
                            java.lang.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
        java.lang.IllegalArgumentException - if in headless mode, there was a missing or invalid file name specified in the .properties file

      • parseDirectory

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

      • askDirectory

        public java.io.File askDirectory​(java.lang.String title,
                                 java.lang.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
        java.lang.IllegalArgumentException - if in headless mode, there was a missing or invalid directory name specified in the .properties file

      • parseLanguageCompileSpecPair

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

      • askLanguage

        public LanguageCompilerSpecPair askLanguage​(java.lang.String title,
                                            java.lang.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
        java.lang.IllegalArgumentException - if in headless mode, there was a missing or invalid language specified in the .properties file

      • parseProjectFolder

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

      • askProjectFolder

        public DomainFolder askProjectFolder​(java.lang.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
        java.lang.IllegalArgumentException - if in headless mode, there was a missing or invalid project folder specified in the .properties file

      • parseInt

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

      • askInt

        public int askInt​(java.lang.String title,
                  java.lang.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
        java.lang.IllegalArgumentException - if in headless mode, there was a missing or invalid int specified in the .properties file

      • parseLong

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

      • askLong

        public long askLong​(java.lang.String title,
                    java.lang.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
        java.lang.IllegalArgumentException - if in headless mode, there was a missing or invalid long specified in the .properties file

      • parseAddress

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

      • askAddress

        public Address askAddress​(java.lang.String title,
                          java.lang.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
        java.lang.IllegalArgumentException - if in headless mode, there was a missing or invalid Address specified in the .properties file

      • parseBytes

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

      • askBytes

        public byte[] askBytes​(java.lang.String title,
                       java.lang.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
        java.lang.IllegalArgumentException - if in headless mode, there was a missing or invalid bytes string specified in the .properties file

      • askProgram

        public Program askProgram​(java.lang.String title)
                   throws VersionException,
                          java.io.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.
        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-specified Program
        Throws:
        VersionException - if the Program is out-of-date from the version of GHIDRA
        java.io.IOException - if there is an error accessing the Program's DomainObject
        CancelledException - if the operation is cancelled
        java.lang.IllegalArgumentException - if in headless mode, there was a missing or invalid program specified in the .properties file

      • parseDomainFile

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

      • askDomainFile

        public DomainFile askDomainFile​(java.lang.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:
        java.lang.IllegalArgumentException - if in headless mode, there was a missing or invalid domain file specified in the .properties file
        CancelledException - if the operation is cancelled

      • parseDouble

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

      • askDouble

        public double askDouble​(java.lang.String title,
                        java.lang.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
        java.lang.IllegalArgumentException - if in headless mode, there was a missing or invalid double specified in the .properties file

      • askString

        public java.lang.String askString​(java.lang.String title,
                                  java.lang.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
        java.lang.IndexOutOfBoundsException - if in headless mode and arguments are being used, but not enough arguments were passed in to accommodate the request.
        java.lang.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 java.lang.String askString​(java.lang.String title,
                                  java.lang.String message,
                                  java.lang.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
        java.lang.IllegalArgumentException - if in headless mode, there was a missing or invalid String specified in the .properties file

      • parseChoice

        public <T> T parseChoice​(java.lang.String val,
                         java.util.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:
        java.lang.IllegalArgumentException - if the parsed string was not a valid choice.

      • askChoice

        public <T> T askChoice​(java.lang.String title,
                       java.lang.String message,
                       java.util.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
        java.lang.IllegalArgumentException - if in headless mode, there was a missing or invalid choice specified in the .properties file

      • parseChoices

        public <T> java.util.List<T> parseChoices​(java.lang.String s,
                                          java.util.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:
        java.lang.IllegalArgumentException - if the parsed string did not contain any valid choices.

      • parseChoices

        public <T> java.util.List<T> parseChoices​(java.lang.String val,
                                          java.util.List<T> validChoices,
                                          java.util.List<java.lang.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:
        java.lang.IllegalArgumentException - if the parsed string did not contain any valid choices.

      • askChoices

        public <T> java.util.List<T> askChoices​(java.lang.String title,
                                        java.lang.String message,
                                        java.util.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
        java.lang.IllegalArgumentException - if in headless mode, there was a missing or invalid set of choices specified in the .properties file

      • askChoices

        public <T> java.util.List<T> askChoices​(java.lang.String title,
                                        java.lang.String message,
                                        java.util.List<T> choices,
                                        java.util.List<java.lang.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
        java.lang.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 java.lang.Boolean parseBoolean​(java.lang.String val)
        Parses a boolean from a string.
        Parameters:
        val - The string to parse.
        Returns:
        The boolean that was parsed from the string.
        Throws:
        java.lang.IllegalArgumentException - if the parsed value is not a valid boolean.

      • askYesNo

        public boolean askYesNo​(java.lang.String title,
                        java.lang.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:
        java.lang.IllegalArgumentException - if in headless mode, there was a missing or invalid boolean specified in the .properties file

      • toHexString

        public java.lang.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 java.lang.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 java.lang.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 java.lang.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​(java.io.File file)
                   throws java.lang.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.
        Parameters:
        file - the file to import
        Returns:
        the newly imported program, or null
        Throws:
        java.lang.Exception - if any exceptions occur while importing

      • importFileAsBinary

        public Program importFileAsBinary​(java.io.File file,
                                  Language language,
                                  CompilerSpec compilerSpec)
                           throws java.lang.Exception
        Imports the specified file as raw binary.
        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:
        java.lang.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​(java.lang.String programName,
                             LanguageID languageID,
                             CompilerSpecID compilerSpecID)
                      throws java.lang.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:
        java.lang.Exception - the language name is invalid or an I/O error occurs

      • createProgram

        public Program createProgram​(java.lang.String programName,
                             LanguageID languageID)
                      throws java.lang.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:
        java.lang.Exception - the language name is invalid or an I/O error occurs

      • createProgram

        public Program createProgram​(java.lang.String programName,
                             Language language,
                             CompilerSpec compilerSpec)
                      throws java.lang.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:
        java.lang.Exception - the language name is invalid or an I/O error occurs

      • setToolStatusMessage

        public void setToolStatusMessage​(java.lang.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​(java.lang.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 java.lang.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:
        FlatProgramAPI.getPlateComment(Address)

      • getPreCommentAsRendered

        public java.lang.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:
        FlatProgramAPI.getPreComment(Address)

      • getPostCommentAsRendered

        public java.lang.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:
        FlatProgramAPI.getPostComment(Address)

      • getEOLCommentAsRendered

        public java.lang.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:
        FlatProgramAPI.getEOLComment(Address)