Chapter 7. Analyze Commands

Table of Contents

Types
Label
Command

GoGui allows the Go program to define analyze commands. An analyze command corresponds to a GTP command and describes its parameters and response type in a way that they can be invoked from the user interface and the response be displayed graphically on the board.

Analyze commands can be run from the analyze dialog. In this dialog, you can also select if the command should automatically run after each change on the board, and if the board should be cleared from results of previous commands before displaying the new result.

It is recommended that the Go program implements the extension command gogui-analyze_commands, which allows GoGui to query what analyze commands are supported when a new program is attached. Otherwise a default configuration is used, which knows some standard GTP and GNU Go extension commands. It is also possible to provide a configuration file by using the -analyze-commands command line option when invoking GoGui.

An example configuration is the default configuration file src/net/sf/gogui/gui/analyze-commands in the GoGui package. The format consists of one line per command:


type/label/command

Types

The command type determines in what format the response is expected to be and how it is interpreted and displayed. It can be one of the following:

bwboard
The response of the command is a board of strings. Strings "b" or "black" will be displayed as black territory, "w" or "white" as white territory, all other strings are not displayed.
cboard
The response of the command is a board of strings with color names. They will be displayed as background colors for the fields. Valid color names are black, blue, cyan, green, gray, magenta, pink, red, white, and yellow or #rrggbb. Unknown names or the special string "" are ignored.
dboard
The response of the command is a board of floating point numbers that represent influence data. They will be displayed as black (positive) and white (negative) squares on the board. The maximum size of a square is such that the corner would touch the edge of a stone on that field; the edge length of the square is proportional to the floating point number. The numbers are expected to be between -1 and 1.
eplist
Editable point list command. The command is used to set a list of points. It needs the following syntax: the current point list is set, if the argument is a point list (or empty); the current point list is returned, if the argument is show. GoGui always queries the current point list first, selects the points on the board and allows the user to edit them, then it sends the command with the selected points as the argument.
gfx
General graphical display command. The response contains one graphics command per line. Graphics commands are: BLACK, CIRCLE, COLOR, INFLUENCE, LABEL, MARK, SQUARE, TEXT, TRIANGLE, VAR, WHITE. TEXT is followed by a text displayed on the status bar; LABEL arguments are point text pairs; INFLUENCE arguments are point double pairs; COLOR arguments are a color (like in cboard) and a point list; VAR arguments are moves (b|w point|PASS); all other commands take a point list. If more than one TEXT commands exist, the text will not be displayed in the status bar, but the lines will be merged to a multi-line text and displayed in a window. See the gogui-dummy-gfx command in gogui-dummy(1) for an example.
hstring
The response is a multi-line text. It will be displayed in a window using syntax highlighting. Lines beginning with a word followed by a colon are displayed in bold, points and moves in blue, the strings "black" and "white" in purple, numbers in green, and words that are completely uppercase in red.
hpstring
Combines pstring and hstring.
none
The response is not displayed.
param

The response to the command is a list of program parameters. A dialog will be shown to edit the parameters. Each line of the response must contain a key and value. It must be possible to change a value using the same command, with the key and new value as arguments. No whitespaces are allowed in the keys, but underscores will be replaced by spaces in the labels of the dialog and lowercase keys will be capitalized. Optionally, a line can have a type identifier for the value before the key. Currently, the following types are supported:

[string]
The value is displayed by an editable text field.
[bool]
The value is a boolean parameter (using "1" for true and "0" for false) and displayed by a checkbox.
[list/item1/item2/...]
The value is selected from a list of valid items and displayed by a combobox. No whitespaces are allowed in the items, but underscores will be replaced by spaces in the labels of the combobox and lowercase items will be capitalized.

If no type or an unknown type is given, "string" is assumed by default.

plist
The response of the command is a list of points. All points will be marked on the board.
pspairs
The response of the command is a list of point string pairs. The strings are displayed as labels on the points.
pstring
The response of the command is a text, which also contains points. Valid points contained in the text will be marked on the board. If the text has only a single line, it will be displayed in the status line. If it has multiple lines, a window will pop up. If text in the window is selected, only the valid points contained in the selected text are marked on the board.
sboard
The response of the command is a board of strings. The strings will be displayed as labels for the points on the board. Strings containing whitespaces have to be put in quotation marks. The special string "" is used for no string on a point.
string
The response of the command is a text. If the text has only a single line, it will be displayed in the status line. If it has multiple lines, a window will pop up.
var
The response of the command is a variation of moves containing points or passes. The moves do not include the player color and are expected to be of alternating color. Text not containing points is ignored. They will be displayed as numbered semi-transparent stones on the board. The current color to move is assumed to move first. Additionally the response is displayed as a string.
varb
Like var, but Black is assumed to move first.
varc
Like var, but the wildcard color in the command is assumed to move first (see below).
varp
Like var, but the command needs a point argument; the color at that point is assumed to move first.
varpo
Like var, but the command needs a point argument and the other color than the color at that point is assumed to move first.
varw
Like var, but White is assumed to move first.

Label

The label to use for this command in the menu.

Command

The command to send to the Go program. It can contain one of the following wildcards:

%c
Will be replaced by a color, which can be selected in the analyze window; the default is the color to play.
%f

Will be replaced by a file name entered by the user.

Note

This wildcard is deprecated and might not be supported in the future. It has been superseded by the more specific wildcards %r and %w.

%m
Will be replaced by the color to play.
%o
This wildcard is for commands that take an optional string argument and can be used for querying or setting a parameter of the Go program. The command should return the current value of the parameter, if no argument is given, and set the parameter to the argument otherwise. The command will be run first without an argument to retrieve the current value, which is used as default value in an input box presented to the user. If the user changes the value, the command will be run with the new value as an argument to set the parameter.
%p
Will be replaced by the a point selected by the user.
%P
Will be replaced by a list of points selected by the user. The points are selected by clicking on the board. The last point of the list is selected either by clicking with the Ctrl key pressed, double-clicking, or using the right mouse button.
%r

Will be replaced by a file name for opening a file selected by the user. If the path to the file contains spaces, it will be quoted with double quotes.

%s
Will be replaced by an argument entered by the user.
%w

Will be replaced by a file name for saving selected by the user. If the path to the file contains spaces, it will be quoted with double quotes.