The Go Text Protocol
This library wraps GNU Go's version of the Go Text Protocol or GTP. It runs GNU Go in a separate process and communicates with the program over a pipe using the GTP protocol. This makes it easy to:
- Manage full games of Go
- Work with SGF files
- Analyze Go positions
This library is available as a gem, so you can install it with a command like:
gem install go_gtp
The above command may need super user privileges.
This library requires an install of GNU Go to communicate with. You will need to install that separately.
This code would load an SGF file and show the current state of the game in that file:
require "go/gtp" go = Go::GTP.run_gnugo go.loadsgf("game.sgf") or abort "Failed to load file" puts go.showboard go.quit
This shows the two main types of GTP methods. Methods like
showboard() return the indicated content. In this case, you actually get back a
Go::GTP::Board object which can indexed into, or just converted into a
String for display as it is used here.
Other methods, like
loadsgf(), are just called for their side effects and they don't return anything. For these, you get a boolean result telling you if the call succeeded (
true) or triggered an error (
false). You can always check the
success?() of either type of call after the fact and retrieve the
last_error() when there is one, so these return values are just a convenience. As another convenience, these boolean methods can be called with Ruby's query syntax as well:
When working with a GNU Go process, it's a good idea to remember to call
quit() so the pipe can be closed. One way to ensure that happens is to use the block form of
run_gnugo() to have it done for you. Given that, the following example is another way to handle loading and displaying a game:
require "go/gtp" Go::GTP.run_gnugo do |go| go.loadsgf?("game.sgf") or abort "Failed to load file" puts go.showboard end # quit called automatically after this block
You can customize how GNU Go is invoked, by passing parameters to
run_gnugo(). Probably the two most useful are the
:directory where the executable lives and any
:arguments you would like to pass it. For example:
require "go/gtp" go = Go::GTP.run_gnugo( directory: "/usr/local/bin", arguments: "--boardsize 9" ) # ...
Of course, you could also set the board size after the connection is open with
See the example directory for more ideas about how to use this library.
The method names are literally the command names right out of the GTP documentation. That's intended to make it easy to figure out what you can do with this library. Return values are Rubified into nice objects, when it makes sense to do so.