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.

Table of contents

1. Table of contents
2. Installation
   1. Binaries
   2. From source
3. Quick start
4. Details
   1. Batch mode
   2. Interactive mode
   3. Configuration
   4. Meta-information

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\0001-prevent-infinite-loop-when-reading-EOF.patch"
   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
   

7. Download and build wyvern. This is as easy as

   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.
   Username: dmwit
   Password: 
   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".
-u	--username --user	username	The username to use to log in to DGS.
-p	--password --pass	password	The password to use to log in to DGS.
-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. Warning: At the third verbosity level, wyvern may print your password!

Meta-information

Version 0.1 of wyvern was released on 14 February, 2010. New releases will be announced on the Haskell mailing list. Please mail bug reports to FogBugz. If you're into that sort of thing, there is a git repository hosted here; get it with

git clone http://dmwit.com/wyvern/.git

< ichneumon