Chapter 7. Analyze Commands
GoGui allows to define analyze commands.
An analyze command is sent to the Go program and the response is displayed
graphically on the board.
Analyze commands can be run from the analyze dialog or (if they have a
single point and an optional color argument) from the context menu of a field
on the board.
In the analyze 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.
Analyze commands are defined in the
configuration file ~/.gogui/analyze-commands.
All files beginning with ~/.gogui/analyze-commands
are loaded.
If none exists, a default file is created.
The Go program can also implement the GTP extension command
gogui_analyze_commands, which allows GoGui to query
program specific analyze commands from the program when a new program is
attached.
There is one line per command in the format:
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,
"w" or "white" as white, 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 shown, 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 commands.
The reponse contains one command and its arguments per line.
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.
See the
dummy_gfx command in GtpDummy 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.
Syntax highlighting is disabled, if GoGui is started with option -fast.
hpstring-
Combines
pstring and hstring.
none-
The response is not displayed.
param-
The response to the command is a list of program parameters.
An 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.
Optionally, a line can have a type identifier for the value before the key.
Currently, the types "[string]" and "[bool]" (boolean parameter using "1" for
true and "0" for false) are supported.
No whitespaces are allowed in the parameter keys, but underscores will be
replaced by spaces in the labels of the dialog.
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 containing points.
All 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.
A string should not be longer than 3-4 characters, to fit on a point on the
board, and may not contain white spaces.
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.
Text not containing points is ignored.
They will be displayed as numbered 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;
default is the color which is to play.
%f
Will be replaced by a filename entered by the user.
If the path to the file contains spaces, it will be quoted with double quotes.
Warning
There are Go programs that implement filename arguments to GTP commands
in a way that does not allow the path to the file to contain spaces
(e.g. printsgf in GNU Go 3.6).
%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.
%s-
Will be replaced by an argument entered by the user.