Chapter 7. Analyze Commands
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
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.
The label to use for this command in the menu.
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.