Chapter 7. Analyze Commands
Prev |  | Next

## 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

## 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, "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.

## 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; 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.

Prev |  | Next
Chapter 6. GTP Shell | Home | Chapter 8. Live Graphics