Wyvern: A DGS Daemon

It's a situation we've all been in: you spend ten minutes reading out a complicated sequence, then spend the next week re-reading the sequence each day as the the moves seem to drag on and on. Well, now there's good news! The wyvern is the dragon's arch nemesis.

Thanks to pigjargon for the adorable logo.

2. Installation
3. Quick start
4. Details

Installation

Binaries

There are binaries for 64-bit Linux and for Windows that you can try. Please contact me if you can build binaries for Mac or 32-bit Linux; I can provide fairly detailed instructions and some limited help if you run into trouble.

From source

First, some terminology: a "terminal" is sometimes also called a "command prompt" in Windows; it can usually be found in the Start menu under "Accessories", or can be accessed from the "Run" dialog. Press and hold the Windows key and tap 'r' to open the dialog, then type "cmd" and press "OK".

1. Install GHC and cabal-install. The simplest way to do this for people not steeped in the Haskell world is to install the Haskell Platform. You can also download them separately: GHC and cabal-install.
2. Upgrade the regex libraries regex-posix and regex-compat from Hackage. This step need only be done for Windows installations that are using the 2010.2.0.0 release of the Haskell Platform. You can do this by opening up a terminal and entering
cabal install --reinstall regex-posix
cabal install --reinstall regex-compat

3. Install the HaXml build tool. This can be done by opening up a terminal and typing
cabal install HaXml

4. Patch the encoding library. This step need only be done on Windows. You will need to install darcs and grab my patch. After that, do the following from a terminal:
darcs get http://code.haskell.org/encoding/
cd encoding
darcs apply "C:\path\to\encoding_ffi.dpatch"
cabal install --flags=-systemEncoding

5. Patch the HTTP library. This step need only be done on non-Linux systems; it is beneficial (though not required) for Linux users as well. You will need to install git and grab my two patches. After that, use a terminal:
git clone git://code.galois.com/HTTPbis.git
cd HTTPbis
git am "C:\path\to\0002-gotta-bump-the-version-number.patch"
cabal install

6. Install the library dependencies. This can be done with cabal-install from a terminal:
cabal install ConfigFile
cabal install dgs
cabal install sgf

cabal unpack wyvern
cd wyvern-0.1
cabal configure
cabal build

This will leave an executable in the dist/build/wyvern directory, which you can put anywhere you like. For example, I put mine at /usr/local/bin/wyvern.

Quick start

This assumes you have already followed the installation instructions, and so have the wyvern or wyvern.exe executable stored somewhere.

1. Create a configuration file. You can ask wyvern to do this for you; here's a sample session (bold indicates user input):
~% wyvern -m b
Warning: File </home/dmwit/.wyvern/config> does not exist.
Create the configuration file now? [Yn] y

Your password will not be echoed to the screen, even as asterisks – don't worry, it's working!
2. Plan a move in one of your games. Download the fully-commented SGF file, edit it with your favorite SGF editor to add your move, and save it to the same directory as the configuration file was saved. If you ever forget what the right directory is, you can find out again by running wyvern --help.
3. Test that wyvern works properly by asking it to log in and make this move for you. Simply type wyvern -m b at a terminal, then check that your move has been made on DGS.
4. Assuming wyvern works correctly, schedule wyvern to run often. You should use your operating system's method for running a program periodically.
• In Windows, this is via the "Scheduled Tasks" widget, found in the start menu under All Programs → Accessories → System Tools.
• If you are a Mac OSX user, the preferred way is to use launchd. You will need to create ~/Library/LaunchAgents/wyvern.plist and ~/.launchd.conf; run the command man launchd.plist launchd.conf launchctl for more information. Alternatively, you may use cron, detailed in the next bullet for Linux.
• For Linux users, the preferred way is cron; you can edit your tasks using crontab -e. Here's the line from my crontab that runs wyvern every five minutes:
# minute hour day dayofweek month command
*/5 * * * * wyvern --mode batch

5. Enjoy! When you come upon a game where you can read far ahead, save your reading into an SGF file in the same directory as wyvern's configuration file.

Details

Wyvern has two modes, batch mode and interactive mode. Briefly, batch mode is for sending your moves to the server, and interactive mode is for getting your opponent's moves from the server to you.

Batch mode

In batch mode, wyvern looks in the configuration directory for SGF files describing DGS games. If it finds any valid files, it asks DGS which of the files correspond to games where it is your turn to play. It will then do one of three things.

• If the move your opponent made exactly matches the move you predicted, and you gave only one response to that move, wyvern will make a move. If your opponent made a comment, and you didn't predict the exact comment they were going to make, this rule does not apply; this is to make sure that you don't miss any repartee!
Wyvern currently does not support anything more complicated than playing a single move. Placing handicap stones, making a comment, passing, scoring, etc. must all be done via DGS' web interface.
• If the game has gone beyond your predicted sequence, the file will be deleted. In case you predicted a move, but your opponent makes a comment, this rule almost certainly applies.
• In all other cases, the file is left as-is, and no moves are sent to DGS.

You can get more information about which rule fired and why by increasing the verbosity; see the configuration section for instructions.

To avoid destroying unrelated files, wyvern will only process files satisfying all of the following conditions:

• The filename must be of the form "player-player-gameid-date.sgf". Player names are freeform, but a gameid or date must have only the digits (0-9).
• Your username must appear in one of the two "player" positions in the filename.
• The file must parse as valid SGF.

In normal circumstances, SGF files downloaded directly from DGS satisfy all of these conditions.

Interactive mode

In interactive mode, wyvern downloads the SGFs for any games that are waiting for a move but for which you have not yet given a move sequence. After downloading each file, it will launch the SGF editor of your choice so that you can make a move. If the SGF editor reports an error, the file will be removed. See the configuration section for instructions on choosing an SGF editor.

Wyvern will skip any game for which there is already a corresponding SGF file. As in batch mode, only files satisfying the following constraints are considered:

• The filename must be of the form "player-player-gameid-date.sgf". Player names are freeform, but a gameid or date must have only the digits (0-9).
• Your username must appear in one of the two "player" positions in the filename.
• The file must parse as valid SGF.

Interactive mode itself saves its files as "<username>-opponent-<game>-0.sgf", where <username> is filled in with your username and <gameid> is filled in with the appropriate game ID.

Configuration

Wyvern can by configured using command-line parameters or via the configuration file. Command-line parameters take precedence over things specified in the configuration file. If any configuration is set twice, the first one seen is taken. Parameters use the usual GNU syntax, so all of the following mean the same thing:

wyvern -vvm b
wyvern --verbose -m batch -v --mode i
wyvern --verbose --mode=b --verbose


The configuration file is a sequence of key-value pairs separated by a colon. Lines beginning with a hash are ignored. You may optionally specify a section in square brackets as the first line, but for now, only the DEFAULT section is used. If a key is specified more than once, the last value is used. Any whitespace at the beginning or end of the value is stripped. Wyvern itself can generate these files for you, and will prompt you to do so if it can't find a file named config in the configuration directory.

For reference, all of the possible settings are included below. The short and long form columns show how to specify the setting on the command line; the key column tells how to specify the setting in the configuration file (if that's possible).

Short form Long form Key Effect
-m --mode mode Choose whether to run in batch or interactive mode. Valid values are "batch", "b", "interactive", or "i". This defaults to "interactive".
--user
--pass
-e --editor
--launcher
editor Set the program to use for SGF editing in interactive mode. Any occurrences of "#f" in the argument will be replaced by the name of the file to edit. If "#f" does not appear at all, the name of the file to edit will be appended to this command. This defaults to "cgoban #f".
-s --server
--url
server Chooses which instance of DGS to log in to. This defaults to "www.dragongoserver.net", which should be right for most people. If you run your own Dragon server, then you should set this to the URL of your server.
-c --configuration
--dir
Set the directory to look in for the configuration file and for SGF files. If you play on multiple servers, or if you play under multiple accounts, you can keep separate configurations for each and use this option. There is a system-specific default for this value; use the "-h" parameter to find out what it is.
-h
-?
--help Display a summary of the command-line options, then exit. This also displays the defaults for each setting.
-v --verbose Give more information about what wyvern is doing and why. This may be specified up to three times (any additional times have no effect) to get increasingly noisy output.
git clone http://dmwit.com/wyvern/.git