Scripting

Scripting¶

In Display MICRESS it is possible to automate every user action with scripting. This means that every action the user does with the mouse or keyboard is reproducible with a script without human interaction. The user is able to write a script within Display MICRESS or in any text editor. Additionally, it is possible to automatically generate scripts from the user’s actions within the program; this process is called recording. Scripts can be executed from the internal script editor via hotkeys or at the startup of Display MICRESS.

Writing scripts¶

As script files are plain text files they can be written in any text editor. However, it is recommended to use the internal editor within Display MICRESS to benefit from syntax highlighting and command references. The editor, called scripting console, can be invoked via Show scripting console in the scripting menu.

The editor consists of three sections. The lower left section is the editor area where the user is able to write text. The area above the editor area, called information area, is used to display information about the current command. Every command is defined in a single line and consists of a main command, a sub command and command arguments. While the user enters his commands, the information area will display what the user has to enter to get a valid command. In practice this means that as soon as the command and sub command have been entered, a list of expected arguments will be shown. Some arguments are optional, they will be written in normal text style, whereas required arguments will be written in bold. The yellow background shows in which command argument the text cursor is currently located. To the right side of the editor area the choice area is located. In this area all possible keyword which the user can currently write are displayed. These keywords can be inserted into the text by double clicking them or by pressing the tab key during editing in the editor area. If multiple keywords are available while pressing the tab key, only the leading characters which are equal in all possible keywords will be inserted. All valid keywords are written in lower cases. If a keyword begins with an upper case character, this indicates that the user has to replace this keyword by its meaning. An example would be 'Integer' where the user has to enter an integer number.

Commands are separated by newlines and command arguments are separated by spaces. If an argument needs to contain spaces it can be enclosed by quotation marks. If the first character in a line is '#', the line is considered to be a comment and is thus ignored during execution.

For easier reading of the command lines they are highlighted according to their syntax. Valid commands will be written in blue, valid arguments in green and invalid text will be written in black. If a command line is invalid its background color will be red, valid commands will have a white background color.

As soon as a command line is valid, it can be executed. There are four ways of execution:

• Execute current line, meaning the line where the text curser is located
• Execute all lines from top to bottom
• Execute all lines from the top to the current line, including the current line
• Execute all lines from the current line to the bottom, including the current line

The executions can be inherited via the Run script menu or via hotkeys (see Run script menu entry).

During execution, the background color in the line number area (left to the editor area) will indicate a line’s execution status. Gray lines are pending, blue lines are currently executing, green lines have been executed successfully and red lines have executed with errors. If a line executed with errors the execution of all other lines will be stopped. Lines will be executed one after another and it is guaranteed that the previous command’s result is available to the next command. For example a newly opened file can be safely referenced to in the next command line.

The scripting menu includes several slots to hold scripts and execute it, especially a startup script slot which will be executed at each DP_MICRESS startup. These slots and the containing scripts can be modified by Edit custom scripts. Do not save these dedicated scripts with another file name because otherwise the connection to the execution slots will be lost (see also section Default scripts, etc.).

Recording scripts¶

It can be very helpful to not write every single command of a longer command chain, but just let the scripting console record what the user does. To enable this feature recording has to be started via the “Record script” menu in the scripting console. Once recording was started the scripting console will be appended with command lines as soon as the user performs an action within Display MICRESS. Generated scripts should always be read and corrected prior to using them, because some generated command lines can be needless. For example if three EDX points are placed with the mouse, three commands will be generated where only the last one would be needed. Some of the actions are not plotted, for example the line scan export as a table.

After recording the script, be sure to stop recording via the Record script menu. Running a script during recording can potentially produce infinite loops because the executed commands will be added to the script again.

Default scripts, startup script and command line use¶

One way of executing a script is to load it in the scripting console and execute it. For scripts which are used very often there is a more convenient method: Custom scripts. There are ten custom scripts which can be executed via the Display MICRESS scripting menu or by a simple hotkey combination. To edit these scripts use Edit custom scripts in the scripting menu and select one of the custom scripts. This essentially opens a scripting console with an opened file which can be edited and saved. Please don’t use the “Save as” feature, because this would save the custom script as a new and unrelated script. The custom scripts will automatically be saved in the user’s home directory and are thus personalized for every user. The first line of the script file contains a comment where the user can enter a name for the script; this name will appear in the scripting menu.

There is an eleventh custom scripted called Startup script. The startup script behaves like any other custom script with the addition that it will be run automatically after every startup of Display MICRESS. If the user passed filenames to Display MICRESS at startup, it is guaranteed that the files will be loaded before the startup script is executed.

The last two ways of running a script file are command line arguments. When starting Display MICRESS the user can add the keyword --script, followed by the filename of a script file. This will result in the script being loaded and run after all data files have been loaded and after the startup script was executed. The --script keyword cannot be followed by multiple script files but it is possible to use the keyword multiple times. If this is done the scripts will be executed in the order in which they were specified. The second command line argument for script execution is --console. This argument behaves like --script, with the exception that the graphical user interface will be created but will stay minimized and thus in the background. It is recommended to end scripts with the quit command if they are invoked with --console, as this will create a behavior where Display MICRESS starts up, executes a script and then closes itself without any user interference.

** Usage from the command line

Usage of Diplay MICRESS 
  DP_MICRESS [FILE ...] [OPTION ...] 
Options:
  --help or -h                Show this help
  --vector FILE1 FILE2 FILE3  Open and display the files, in a fourth window show file 1 with file 2 as x vector and file 3 as y vector
  --script FILE               After loading all files, load and execute script file
  --console FILE              Like --script, but keeps main window minimized during script execution

Script language definition¶

Most of the scripting commands consist of a main command, a sub command and some arguments. All performable actions can be grouped in multiple groups which are defined by the main command, meaning that actions which are related will share a main command. This grouping was adapted for the following sub chapters. There exist two commands, which don’t need any sub command or argument.

Some arguments are optional. All optional arguments can be replaced by the '*' sign, which means that the default value of the argument will be used. If a command ends with optional arguments the trailing '*' signs can be omitted.

Some arguments expect a list of integer numbers. This list must contain comma separated numbers without spaces. Dashes can be used to express series of numbers. An example list is '1,2,3-5' meaning 1, 2, 3, 4 and 5.

Window commands¶

All following sub commands need to be prefixed with the window command and apply on all active windows of the current group, if not specified differently. Some sub commands require window IDs. These can be specified directly by referencing the number shown at the beginning of the header of a window. Another way is to use negative IDs to reference the newest windows. For example -1 would be the newest window, -2 the second newest window, and so on. A window is newer than another if its ID is larger. The same holds for group IDs.

Group commands¶

Time step commands¶

All following sub commands need to be prefixed with the “timestep” command. All commands are applied on all active windows of the current group.

3^rd dimension commands¶

All following sub commands need to be prefixed with the 3d command. All commands are applied on all active windows of the current group.

Repetition and mirroring commands¶

All following sub commands need to be prefixed with the “repeat” command. All commands are applied on all active windows of the current group.

Content Commands¶

All following sub commands need to be prefixed with the “content” command. Most commands are applied on all active windows of the current group if the window ID is optional and ignored.

Color scale commands¶

All following sub commands need to be prefixed with the colorscale command. Most commands are applied on all active windows of the current group. The window and dataset ID arguments follow the same rules as described in Writing scripts.

Length scale commands¶

All following sub commands need to be prefixed with the lengthscale command. All commands are applied on all active windows of the current group.

Information box commands¶

All following sub commands need to be prefixed with the infobox command. All commands are applied on all active windows of the current group.

Vector commands¶

All following sub commands need to be prefixed with the vector command. Most commands are applied on all active windows of the current group.

Isoline commands¶

All following sub commands need to be prefixed with the isoline command. Most commands are applied on all active windows of the current group.

EDX commands¶

All following sub commands need to be prefixed with the “edx” command. Most commands are applied on all active windows of the current group.

Anchor commands¶

All following sub commands need to be prefixed with the “anchor” command.