Script commands

The format of a script command is

(command argument ...)

The command is either a name of a script command or a function name. The list of script commands is given below. The functions may be defined in applications (in script modules, in loaded Lisp code, or in dynamically linked libraries (DLL)).

Evaluation order

The following evaluation order is used for most script commands and all script functions.

First, the arguments are evaluated as script expressions, from left to right.

Then, the function (or the command) is applied to the evaluated arguments.

For some commands, the evaluation order is different. All such cases are indicated in the command descriptions below.

Evaluation environment (the base and the variables)

The IDA objects are referred in scripts relative to some base object. The base is specified by the caller, but may be reassigned in the script.

The arguments passed to a script are treated as local variables. The local variables may also be defined in the script. The scripts have also access to the caller’s local variables (if called from a script). When exiting from the script, all local variables are discarded.

The scripts may also define global variables. A global variable defined in a nested script is equivalent to a local variable in the top-level (outermost) script. The global variables are discarded when exiting from the top-level script.

List of script commands:

Working with environment

(:set (varname value) ... )

Defines local variables and assigns values to these variables. The values are evaluated.

The varname may also be a list of variables. In this case, the value should be evaluated to a list and the names are associated with the corresponding values in the value list.
If none of varname is a list, the inner parentheses may be omitted.

(:defaults (varname value) ... )

Defines local variables and assigns values to them, if the variables are not yet defined. If the variables are already defined, their values are unchanged. The values are evaluated. All parameters are the same as for :set command.

(:gset varname value)

Defines a global variable and assigns the values to this variable. The value is evaluated. The global variables survive the return from nested scripts (function exec-script), but not the return from topmost script (functions execute-script, run-script).

(:root reference)

Changes the base, i.e., the start point of the references. The argument is evaluated.

Working with data objects

(:build name sform)

Builds a new data object from the source form sform. The result is assigned to the (new) local variable name.

The name is not evaluated. The argument sform is interpreted as a source form

(:update object sforms ...)

Adds, modifies, and removes components of the object. Every source form sform corresponds to one changed component. Only the argument object is evaluated as script expression; the result of the evaluation should be a valid object. Other arguments are interpreted as source forms

(:attr object attr value [attr value ...])

Modifies the attributes of the object. All arguments are evaluated.

(:run object)

Runs (simulates) the object. The argument is evaluated.

(:show object [view-type [subobj]])

Opens the object with the given or default view type. The arguments are evaluated.

The view type may be (after evaluating) either a symbol denoting view type (e.g., form, schema, outline), or a string denoting pathname of the form document, or NIL for default view.
If subobj is specified, tries to highlight it on the open view.

(:show "url")

Opens the given location in the default Web browser. The url should start with http://, https://, or ftp://.

(:close object)

Closes all views of the object. The argument is evaluated.

(:connections connection-form ...)

Makes the given connections (uses the function invoke-local-connection). The format of connection-form is (from-ref to-ref [:at points [attributes...]]), where from-ref and to-ref are references to interfaces or variables (without starting @). The start point of the to-ref is the base's parent.

The attributes (including points) are evaluated.

Control commands

(:cond clause ...)

The clauses are lists (not evaluated). The first members of each clause are evaluated in turn until some of them returns non-nil value. Then the remaining members of this clause are executed as script commands. Other clauses are ignored.

(:case expr (selector code) ...)

The first argument is evaluated. The result is compared in turn with selectors until a match is found. The code in the selected clause is executed as a script. Other clauses are ignored.

An expression matches a selector if either (1) they are identical, (2) the selector is a list and the expression is identical to a member of this list, or (3) the selector is the symbol otherwise.

The selectors are not evaluated.

([:call] function [argument ...])

Applies the function to the arguments. All arguments (including the function name) are evaluated before the call. The command name :call may be omitted, if the function name does not coincide with some command name. In this case, the function name is not evaluated.

(:exec script [var value ...])

Executes the script with the current base and given arguments.

The called script treats the arguments as local variables.

The parameter script and the values are evaluated; variable names are not evaluated.

• script code (a list of script commands)
• a symbol, denoting a script method associated with the base object.
• a name (string) of a file containing script code

The value of script may be (after evaluation)

(:include code)

The argument code is evaluated to a name of the fragment to be included in the script. The fragment itself is fetched from the script module of the base object.

The elements of the inserted fragment are executed as they are in the current script.

(:for (varname value-list [options]) body)

In the loop for every value from the value-list, temporary bind the local variable varname to this value and execute the body (that is a sequence of script commands). The argument values-list is evaluated and should return a list.

The argument varname may be a single name or a list of names. If it is a list, the values of value-list should also be lists and the variables are bound to the corresponding (by order) elements of values.

The options are written as a sequence name value ... (the option names are not evaluated):

(:continue [value])

Starts the next round of the innermost :for loop. In the last round, breaks the loop returning the given value. The argument is evaluated.

(:break [value])

Exits from the innermost :for loop returning the given value. The argument is evaluated.

(:return [value])

Exits from the script and returns the given value. The argument is evaluated.

(:batch [log] command ...)

Executes the commands in batch mode. No arguments are evaluated. The option log may be used to redirect the diagnostic messages from the log window to a file. Supported variants: > "filename" (to overwrite the log file if it exists), >> "filename" (to append new messages to the existing log file), and > NIL (to not print the messages)

User interface

(:menu item1 ...)

Displays the menu consisting of named items. Returns the result of the selected item.
The arguments and the evaluation are described in Script code for menus.

Error handling

(:assert expr level hint message [arg1 ...])

Evaluates the expression. If it returns NIL, evaluates the remaining arguments and generates a message, see script function inform.

(:on-error ([type ...]) code ...)

The code to be evaluated if an exception of given type is signaled while the rest of the script is executed, see :signal command. The command (:on-error () ...) with empty list of types intercept all types of signals. The code may contain :restart commands that instruct how to continue execution of the script. If no restart command is executed, this script and all nested scripts are aborted (but the :clean code is executed in any way).

(:restart restart)

Allowed only inside :on-error command. Instructs how to continue execution of the script after error handling. The alternatives are:

(:signal type hint message [arg1 ...])

Fires (signals) an error of given type. The signal is intercepted by the most recent active error handler that accepts errors of given types. If there is no appropriate active error handlers, IDA prints the message, sets the error flag, and aborts all active scripts.

The arguments hint and arg1 … are used when printing the error message, see script function inform.

(:clean code ...)

The code that should be evaluated even if the script is aborted or exited. The value returned by the cleaner is ignored, so the script returns the value of the previous command.

The cleaner code that is inside of :cond, :case, :for, :try is evaluated only if the execution of the corresponding clause was started.

(:try code ...)

Executes the code as a nested script, with own error handling.

Expressions

(* arg ...)
(/ arg ...)

Evaluates as script expression. If the result is not an integer, it is rounded to 4 significant digits.

(or arg ...)
(and arg ...)
(if cond ...)

Evaluates as script expression. Only the required arguments are evaluated.