WBTM is a program for running automated round-robin, swiss- and gauntlet tournaments for Winboard chess engines on one computer. You can download the latest version from here.
Changes from version 0.42 are marked with dark green.
New items from version 0.42 are marked with dark
red.
There is no particular installation, the program runs fine with just the plain executable. However to use WBTM in a sensible manner I advice you to read through this manual and try out the features it has to offer.
You can still use player files from old WBTM-versions, but since everything can be integrated to winboard.ini, that is no longer the preferred way.
2.1 Winboard.ini as player file
From version 0.15 on, you can use winboard.ini as player file. All the settings you can make in player file, you can make in winboard.ini. When you install new winboard engines you usually have two options: to run them from command line, or edit winboard.ini so that they will appear in the starting dialog. If you use the latter alternative, you can use the command ReadPlayers just as you would in the player file's case. All files that are not recognized as player files, are treated as winboard.ini-files. Command Read without parameters tries to find your winboard.ini automatically and read it.
In version 0.15 there were restrictions with engine options. From 0.30 on, every valid winboard engine list should also be a valid WBTM-player list. If you have troubles with it, let me know.
There is an exception indeed. Within the section where engines are defined, all comments are treated as options to the engines. It occurred that although WBTM works fine with /name and /group -options, Winboard does not. The solution only works with versions 0.32 upwards. The solution is to put /group and /name -options last in the line and after a semicolon. That way Winboard will treat them as comments, but WBTM will recognize them and treat the semicolon as whitespace.
The program name (with options, if needed) is obligatory. Many engines are located in their own directories, what means that the /fd=directory_path option is needed. WBTM assumes, that the first thing on a line is program name (with it's options).
For WBTM you can also specify two options, which are not recognized by Winboard and therefore they do no harm in normal Winboard use. Those options are /name and /group. The /name option let's you specify a name for the engine, which will be shown in WBTM. This is convenient if you want to use the same engine with several options or configurations. The option /group is ment for large player lists. If you have all 100+ engines installed and they all are in the same Winboard.ini, it is not so nice to pick say only the ten highest ranked engines. With /group you can divide the player list to several groups, which can then be handled with commands addgroup and available. An engine can belong to several groups. Here's an example of winboard.ini:
/firstChessProgramNames={
bestia /fd c:\chess\winboard ; /group="a b"
Crafty /fd=c:\chess\winboard
/firstInitString="-init\n-a\n-b\n-xboard" ;
/group="a c"
nerowb /fd c:\chess\winboard ; /group="b"
Ozwald043 /fd=c:\chess\ozwald\oz043 ; /name="NewOzwald"
/group="d"
freyr /fd c:\chess\winboard /xreuse ; /group="d"
Sjeng8 /fd c:\chess\winboard /group="c"
yace023 /fd c:\chess\winboard ; /name="OldYace"
/group="c d"
"morphy_322 -x" /fd c:\chess\winboard /xreuse ;
/name="Morphy"
"faile -hash16" /fd c:\chess\winboard ;
/group="d" /name="Some Version Of Faile"
mint /fd c:\chess\winboard ; /group="a"
MAD /fd c:\chess\winboard\francesca /xreuse ;
/group="a"
LG2000v3 /fd=c:\chess\winboard\LG2000 /xreuse ;
/group="a"
}
Note that the parameters given to specific engines here may be totally incorrect for those particular engines.
Winboard accepts two formats of the player lists:
/firstProgramNames={GNUChess
"Crafty" /fd="c:\program files\crafty"
"yace" /fd=d:\chess programs\yace"
}
and
/firstProgramNames="GNUChess
\"Crafty\" /fd=\"c:\\program files\\crafty\"
\"yace\" /fd=\"d:\\chess programs\\yace\"
"
The difference is the characters, that enclose the section. In the first one they are { and }, in second they are double quotes. I prefer the first alternative, because it is simpler, and it is also mentioned in the winboard.hlp. If you use the second alternative, you must make sure that quotes (both single and double) and backslash are preceded by backslash, otherwise there is no way to know what you mean.
WBTM supports both these formats.
From 0.40 on there is yet another WBTM-specific option: /rating. It should be used like /group and /name, but the value is an integer. The command AddAllPlayers uses it with its new option -rank to add players in strength order rather than the order in winboard.ini. This is a useful feature in swiss tourneys where the player's order is meaningful.
Once you have set up your player file running a tourney can be quite simple. Let's assume your Winboard.ini is all set up and Winboard path is c:\chess\winboard\winboard.exe. Then you can create and run a tourney with the following commands to the WBTM prompt:
Reset
Set type RoundRobin
Set WinboardPath c:\chess\winboard.exe
ReadPlayers
AddAllPlayers
CreateRRGames
Spool -all
Run
Now let's see what happens here. The reset command is quite obvious, it clears (or resets) all variables of the tourney. Then we must set the tourney's type to Round Robin. Then the program needs to know where Winboard's executable resides. Next the players are read to the player list (note that the player list presents only the players that can be added to tourney, you still have to add them by hand). Then all players on the list are added to the tourney. Now we can create games for a round-robin tourney with CreateRRGames. At this point we have created the tourney, since all players and games between them exist. The next step is playing the games. For that the games must be spooled, which means that WBTM creates a command line for each game, and when game is about to be started, WBTM creates a temporatry bat file for that game, one that calls Winboard with correct parameters so that the two engines play their game with correct options. WBTM no longer creates all bat-files at once, but you can change the command lines within WBTM. WBTM's runner executes all spooled games one by one and collects the results (and creates a results report in HTML and copies the games as PGN to a single file). By default the runner is set to STOP, and you can set it to RUN-state with command run. If things go smoothly, in the end you have a file named default.pgn with all the games and table.htm with the results table in your current directory.
To run a swiss tourney is complicated than running round robin tourneys, but not much. When all the players wanted to play are added, the number of rounds to be played must be set.
Reset
Set type Swiss
Set WinboardPath c:\chess\winboard.exe
ReadPlayers
AddAllPlayers
SetRounds 5
Pair
Spool -all
Run
Now let's see what happens here different than round robin tourney. The whole idea of swiss tourneys is that every player will not meet all the other players, which means thet the whole tourney can be finished in less time. That means that there must be some way to determine which players will meet on each round. Swiss pairing system tries always to pair players, who have scored the same number of points on the previous rounds. There are some principles and many rules in pairing a swiss round, and the most important one is that no players shall meet each other more than once during the tourney. The command Pair will do the pairing automatically in normal cases. There are situations when it will fail, but this topic is handled more detailed under the pairing section.
In a swiss tourney games can only be created for one round at a time, since the next round's pairings depend on previous round's results. Therefore in this example the Pair + Spool -all -commands will have to be typed five times, every time after a round is ready.
Gauntlet is not a tourney in the same sense as round robin and swiss, there won't be same kind of ranking after the tourney. In a Gauntlet tourney one player plays against all the other players one or more games. In this case the variable Rounds means individual games between engines, which is more like the variable SubRounds in round robin and swiss tourneys.
The result table will tell the gauntlet player's (the one who plays all other) score separately and then each opponent's scores against the gauntlet player.
| BlackOptions | FilesPath | Hashtables | Inc |
| Mps | Name | PgnFile | Ponder |
| Rounds | SubRounds | Tablebases | Time |
| Type | WhiteOptions |
Tourney specific options for Winboard. For example if you want to show board coordinates while the programs play, you can set Options to /coords. Note that player specific options override tourney specific ones, and there are a couple of parameters that are needed by WBTM.
Don't ask me what is the difference between white and black options or why they both are there. We all make mistakes!
This is the directory where all files (pgn) of the tourney reside. By default it is set to empty, which means any one directory you currently are in. The last character should be \, otherwise it is added.
This is text-only setting, and currently the text you set here will appear in the HTML-result file, nowhere else. You are supposed to tell the hashtable settings used in the tourney.
Time control consists of three parts: base time, increment and moves per session. Base time is the time player has in his clock when the game begins. If inc > 0, then player's time is incremented by increment seconds after each move made. If inc = 0, then mps can be > 0. Then player's time is incremented with base time each time mps moves are made.
This setting sets the increment.
Time control consists of three parts: base time, increment and moves per session. Base time is the time player has in his clock when the game begins. If inc > 0, then player's time is incremented by increment seconds after each move made. If inc = 0, then mps can be > 0. Then player's time is incremented with base time each time mps moves are made.
This setting sets the moves per session value.
This is text-only setting, and currently the text you set here will appear in the HTML-result file as name of the page.
Sets the name (and optionally location too) of the pgn-file where the games are collected. If PgnFile includes '\'-characters, it is interpreted as a whole path, otherwise only filename, which will reside in FilesPath-directory.
Sets ponder on or off. Pondering means, that engine can think on opponent's time. It is recommended that ponder is only used with multi-cpu computers.
Sets the number of rounds in swiss tourney. Minimum is so, that 2^rounds >= number of players. That ensures that only one player can win all his games. Maximum is number of players / 2. If you want to have more rounds, play a round robin tourney.
How many games every engine shall play against every other engine. A normal round-robin tourney runs with SubRounds = 1, double with SubRounds = 2 etc.
This is text-only setting, and currently the text you set here will appear in the HTML-result file, nowhere else. You are supposed to type here the tablebases used in the tourney.
Time control consists of three parts: base time, increment and moves per session. Base time is the time player has in his clock when the game begins. If inc > 0, then player's time is incremented by increment seconds after each move made. If inc = 0, then mps can be > 0. Then player's time is incremented with base time each time mps moves are made.
This setting sets the base time, which is given in seconds!
Tourney type. und Robin, Swiss or Gauntlet.
Tourney specific options for Winboard. For example if you want to show board coordinates while the programs play, you can set Options to /coords. Note that player specific options override tourney specific ones, and there are a couple of parameters that are needed by WBTM.
| AutoRun | AutoSave | BatchDir | Computer |
| EchoCommands | Extension | LogFileSize | MaxBatchFileLines |
| PicsDir | RunnerInterval | SaveDebugFiles | SaveFile |
| ScheduleInterval | SwissMaxStrongSize | SwissMaxWeakSize | SwissPairTimeout |
| WinboardPath |
If you set AutoRun on, it will spool games one by one as long as there are games. Games with unknown result will be replayed. If tourney type is swiss, a new round will be paired automatically when a round is finished. All tourneys end when all the games are finished with known results.
If you set AutoSave on, the tourney will automatically be saved after every game. The save file will be the file where tourney was saved last time, or tourney.ini in the starting directory. Tourney will also be saved before quitting, if you exit with command quit.
Specifies the batch dir where WBTM tries to find command files. See 5.9 CommandFiles.
This is text-only setting. This string will indicate the computer you have used in the tourney, and will appear in the HTML-result file.
If you want to see the command line that is really executed at each point (after alias expansions and such), you set EchoCommands on.
Sets the command file extension, ie. files with this extension are treated as command files. See 5.9 CommandFiles.
WBTM writes all its input and output to a log file. Every now and then it checks that this file's size does not get too large. If it does, then the file is split to two parts and the older one is discarded. This setting sets the limit for the log file size.
Handling commands is quite expensive since WBTM must check for several alias-substitutions. If you accidentally call a file that is not a command file WBTM may choke under the workload and you may lose data. A typical batch file is not very large (or why is it so large?), and this setting allows WBTM to discard all files which are too long (thus probably not batch files either).
This is the directory where all image files for HTML-resulttable reside. Initially it is set to empty, when all the images must be in same dir as the html-file. This setting is relative, so it will simply be appended in fromt of the file name. It is your own responsibility to make sure that the directory exists. If you generate the html-file to a directory, where is no subdirectory with the images, no pictures will be shown.
Another thing you have to handle yourself is tha last character of PicsDir. If the image files are on disk, the last character should be '\', whereas in web it should be '/'. This is a thing that can't be automatically determined, so it is pu to you to make it work. Or go the simplest path, and use characters instead of pictures, see the -xg-option of table.
The runner checks for games to be started and finished games with a constant interval. This setting allows you to set runner do this more often or seldom. Value is in milliseconds.
This setting determines what is done to winboard.debug files that Winboard produces. Possible values are ALWAYS saved, AUTOMATICally saved and NEVER saved. Automatic saving means that only those files where the game's result wsn't found are saved. The save file name is gXXX.debug, where XXX is the game's number.
Sets the current save file, ie. tile, where WBTM saves tourney by default, if you don't specify a file or when autosave is on.
The scheduler checks if it is supposed to set runner on or off with a constant interval. This setting allows you to set scheduler do this more often or seldom. Value is in milliseconds.
Sets the max bracket size where strong color preference will be forced. See 5.6 Pairing swiss rounds for further information.
Sets the max bracket size where weak color preference will be forced. See 5.6 Pairing swiss rounds for further information.
Sometimes pairing swiss rounds may end up in a deadlock. In such situations it is reasonable to either help WBTM in the pairing or to try another way of pairing. This setting allows you to determine how long WBTM should try before it can decide of being in a deadlock. Value is in seconds, and a reasonable setting is ~10 seconds depending on your computer.
Now this is an important setting. In order to be able to generate working bat-files WBTM has to know where Winboard.exe is. Before spooling any games Tourney Manager tries to open the Winboard.exe-file, so there must exist one by that name, otherwise you won't spool a game.
| Path | Games | HTML | GridPoints |
| Grid | Number | Sort | TotalPoints |
| Comparison | Buchholz | SB | Rank |
| Bar | BarGraphic | AutoSort |
For explanation about result table parameters, refer to command Table.
You can set default parameters for a set of parameters. These values will be used when you create new tourneys by starting WBTM or with the command reset. For example if you set TourneyDefaultPgnFile to " MyFile.pgn ", then for every new tourney the PgnFile -variable will have the value " MyFile.pgn ".
Besides commands and settings there are a couple of things you should know.
You will probably have some settings which apply to every tourney you run. Such settings can be for example your winboard path. You can save your favourite settings with the plain Save command. Save without parameters saves the current tourney to file ‘tourney.ini’ in the same directory where WBTM’s executable lies. This file is automatically loaded every time WBTM starts. This fact gives you also possibility to type ‘save’ before you exit, when you will continue from the very same situation next time you run WBTM. Note that ‘save’ saves everything from a tourney, that includes games, their status and players, but not the player list.
To run really automated tourneys you can use WBTM with a command file. You just type all the commands you want to a file and then run WBTM with that file as parameter. For example:
Tourney.exe command_file.tcf
The command line option -c is no longer valid. By default WBTM will continue its execution. If you want to end WBTM after the command file is run, set quit as the last command. Another thing worth mentioning is that the command file name must be a valid WBTM command file, so the extension must be the same as defined in WBTM.ini.
If you give a command that is not recognized by Tourney Manager, it is treated as a system command. It means that you can use commands such as dir, type, copy, del etc. In WBTM prompt too. The command cd is an exception, it doesn’t work the way I imagined. Therefore it’s replaced with the C-function chdir.
Runner is a vital part in making WBTM's tourneys automatic. Runner works in its own thread. To the user runner has two states: it is either on or off. When runner is on, it waits until there is a game with status SPOOLED in the tourney. Then runner launches Winboard to play that game. The runner thread will be waiting for the end of the game. Nowadays WBTM could launch another winboard, but it would not be wise, since usually there would be an engine using the CPU time and thus making all further results useless. When the game is over, runner reads the result and waits for next spooled game. Runner can be started or stopped either immediately or in the future, you can specify starting and stopping time (and date). When runner is on, that only means that runner has the permission to start spooled games, it doesn't affect Winboard any way.
Games can also be played outside WBTM and runner. You just have to execute the bat-files in files-directory. Runner will always check if spooled games are already played outside WBTM. This is determined by existence of pgn-file of the same number as the game. For example the bat file for game number 14 is named g14.bat and it's pgn-file g14.pgn. So if game 14 is spooled and runner is on it will check if there exists a file named g14.pgn. If it does, then result for game number 14 is searched from that file no matter what it really includes, it can even be a jpg-photo of yourself.
The paragraph above is no longer true from 0.60 on!
You can specify how many games a player plays against each of the opponents. That number is controlled by the SubRounds-setting. You can create games with the command CreateRRGames, which will create games required to run a Round Robin tourney with current players or Pair, which will create games for a swiss tourney according to its parameters. CreateRRGames deletes all existing games, so it is quite dangerous command.
When a game is created, it's status is NOTHING DONE. That is true, it is simply created, but that is all. No bat-files or anything else exists for it, it only has two players assigned, and a round - subround -property. When you want to see some action, you must spool the game. Spooling means that a command line is created for the game and it's status is changed to SPOOLED. When game is run, a temporary bat-file is created, but user no longer has access to this file, but the command line value of a game can be accessed with the command Game.
If the tourney setting AutoRun is on, WBTM will automatically spool games when runner is on and there are no spooled games. In swiss tourneys new games will be paired, if a round is finished.
After the game is run (the bat file is executed and Winboard is finished with the game) the result is read from the pgn-file. At the same time game's status is also changed to READY. If result wasn't found the result-property is set to UNFINISHED or UNKNOWN. Games with this result and status READY are marked with '*' on result table. Usually something has gone wrong with these games, for example one engine has not started playing at all. If you decide that these games should be played again you can do it with Replay. If you decide that a player is having too many difficulties you can forfeit all it's resulting games, ie. set the results as win for the opponent. To set the result or status of a single game use the command game.
You can always observe the status of a tourney with command TextTable. It produces a result grid with player's standings, results of individual games, total points, comparison points and a bar visualizing the amount of points scored. If there exists at least one game with status other that READY the players will be sort according their numbers. When the tourney is finished, players are sord according to their standings.
The comparison points are Sonneborn-Berger-points, because if two players have the same score in Round-Robin tourney, their Buchholz points are also identical.
The bar indicating player's points has three possible characters: # means a whole point, \ means half a point, and | is only a separator making it easier to see how many points a player has scored.
A somewhat nicer-looking result table is generated with command Table. It produces an equal table in html-format. Note that if you want the bar shown with the gif-pictures while publishing the table in web, you have to make sure that the path to the gifs is correct. I don't know how to solve the problem with these paths so that they could easily be visible both in web and on local computer. If you have a suggestion, mail me!
Mainly for debugging purposes WBTM keeps a log of it's console input and output. A file named WBTM.log is automatically created when you execute WBTM. It will reside in the directory where you called WBTM. It is overwritten every time WBTM is started.
If you use the system command 'dir' for the current directory, you will always see a file named 'tmpfile.$$$'. That file is needed for logging system commands' output, and it is automatically deleted after the logging is done (which is in practice immediately).
5.5 Saving winboard.debug-files
Sometimes something goes wrong with running the games and it may be an engine's fault. In such situations it would be nice to see the winboard.debug-file, if it revealed what went wrong. For that there is a tourney option: SaveDebugFiles. It can have three different values: NEVER, AUTO, and ALWAYS. Never and always are obvious, but auto saves winboard.debug for those games, where result was set to UNKNOWN or UNFINISHED (something went wrong because the game was not finished). Saved files get the name gXXX.debug, where XXX is the game's number.
I won't write a tutorial how the swiss pairing is done. If you are not familiar with the matter, I suggest you just use plain Pair and take whatever it gives you. But if you know how swiss pairing works, there are some points which may be useful. WBTM tries to make pairing according to FIDE rules. First step is to create brackets. That can be done with CreateBrackets, when you can specify whether to create the brackets from top to bottom (highest score first) or vice versa and how big brackets will be created, ie. what is the acceptable difference in scores within players in same bracket. These special cases are only needed in special cases, where normal pair fails. It doesn't really fail, but it can get stuck to situations where making pairing would get a really long time. In these cases creating the brackets upwards starting from the lowest players usually helps.
You can see the created brackets with ShowBrackets. If you are not satisfied with the pairing WBTM made, you can do it completely or partially manually with giving parameters to Pair. You can specify two players, who will be paired, if they have not met each other. You can specify a bracket to be paired, or you can give the same parameters to pair as you gave to CreateBrackets. It is also possible to alter the timeout value. That means that Pair will usually try 10 seconds to make pairing, after which it resigns and tries other settings. The settings go in following order:
Finally Pair may come to a point where all the players are in one bracket. Pairing this can fail too, but then you should really do the whole pairing manually. This pairing routine has been tested with thousands of simulated tourneys, which have shown that the basic pairing works fine with tourneys where Rounds < 15, which would already allow far more players than there are different Winboard engines (written 18.9.2001).
By default WBTM tries to accomplish pairing so, that every player gets alternating colors each round. Many times this is not possible (without violating other, more important rules) or finding the best possible pairing would take a very long time. Therefore WBTM implements two limits: SwissMaxWeakSize and SwissMaxStrongSize. The former sets a limit for bracket size when weak color preference (changing colors in each round) is forced, and the latter sets an according limit for strong color preference (difference of games player on white and black <= 2).
From 0.41 on, after pairing of a bracket is ready (regardless of the bracket size) WBTM will look for available changes in pairing: if it finds two pairs within the bracket where by changing opponents between these two pairs color preference of one or two players can be met better, these changes will be made.
For example, in a large bracket (where neither strong nor weak color preference is forced) WBTM has paired players 1 vs 5 and 11 vs 15. Players 1 and 5 would both want black pieces and 11 and 15 want white pieces. Now, if 1 has not met 11 and 5 has not met 15, the pairing will be changed to 1 vs 11 and 5 vs 15.
This similar procedure will be tried to improve color preference level. For example, player 1 has strong preference for black on one pair, and 5 has weak preference for black on another pair. Player 1 is forced to get white pieces and 5 gets black pieces in the current pairing. Now if 1 and 5 can change places in pairing, this change will be made. This way 5 with only weak preference will get opposite color, whereas 1 with strong preference will meet its preference.
From version 0.40 on, there is a separate settings file, quite like winboard.ini is for Winboard. All other settings than tourney-related (those which can and will vary in each individual tourney) will automatically be saved to file WBTM.ini in the program directory. If this file does not exist, it will automatically be created when WBTM starts. This file is designed so that you can edit it manually with a text editor, each variable is commented. Lines which begin with '#' character are comments. You can write whatever you want to the file, but WBTM will only read those variables it recognizes and everything will be overwritten when you exit WBTM.
Command aliases are written to WBTM.ini too, so if you define a set of aliases on one session, the same set will be available on the next session, unless you edit or delete WBTM.ini in the meantime.
You can set an unlimited amount of command aliases. Let's suppose that you frequently use the texttable-command, but with two completely different parameter sets. One you want to sort by player number, ignore player rankings and comparison points. The other you want to sort by player ranking, and this time you want to ignore player numbers, the bar and want to see comparison points. This means that you find yourself typing strings like 'tex -xauto -xsort -xrank -xcomp -number -bar' and 'tex -xauto -sort -rank -comp -xnumber -xbar' all over and over. Command aliases are intended to solve this problem: you can specify a string, which will always be expanded to another string. In the example case you could name two aliases:
alias table1
"tex -xauto -xsort -xrank -xcomp -number -bar"
alias table2
"tex -xauto -sort -rank -comp -xnumber -xbar"
Now when you type 'table1', WBTM will expand your alias and the command line that is actually executed is 'tex -xauto -xsort -xrank -xcomp -number -bar'. You can always see the final command line if you set EchoCommands to TRUE. Aliases don't care whether they are in a middle of a word: if we define the following
alias a HELLO
Then typing 'table' would expand to 'tHELLOble'. Then if we had another alias which defines the string 'HELLO', that substring would be further expanded. Aliases can be undefined with command unalias. But will that work, since if I define an alias 'dummy' to expand to '1234', typing 'unalias dummy' will expand to 'unalias 1234', and there won't be such alias. That is true. Aliases are expanded everywhere, except within a pair of quotes. So if you want that the actual command line looks like 'unalias dummy', you actually type each token with the quotes. So your command line looks like the following:
'unalias' 'dummy'
If yu type 'unalias dummy' That will be interpreted as one single token, where a match of a command 'unalias' would be found, but no arguments whatsoever. You can specify single command line items with single- and double quotes.Everything typed in double quotes is treated as a one single command line token. If you want a double quote character (") in a string, you should precede it with a backslash (\). So in command line "Hello, \"World\"" means one token 'Hello, "World"'. Single quotes act the same way with the exception that double-quoted tokens can reside within single quotes.
Another new thing about command lines is that you can add newline characters to a command line. That has only practical use in aliases, which can act like small batch files. Actually there is no upper limit on size of an alias, but it is sensible to keep them small. Newline is presented by c-style '\n'. The backslash is a special character, and if you want to type it into commandline without it's special effect, you should use a double-backslash (\\).
Disabling aliases
Sometimes it is useful to disable aliases so that you will know that whatever you type won't be changed before the command gets executed. This can be done by typing an exclamation point (!) as the first character of the line. This is useful when deleting aliases and actually there are things that would otherwise be very annoying to do if aliases were enabled. This option also disables the newline-character.
The exclamation point will be removed before the command is executed, so if you want to have it as the first character of the line, you can type two of them.
With the newline character you are able to run several commands with typing only one line. However the intended way to run several successive commands is a command file. It is a simple text file, where each line is read and executed just like you had typed it in command line.
To be able to call a command file WBTM must recognize the file to be a command file. This is done via file's extension. By default, every file with extension TCF (Tourney Command File) is treated as a command file. The extension is a general variable, so you can change it to something more suitable, if TCF is not good for you.
When you type a command, WBTM checks whether it can recognize your command to be a command file call. It will check both the name without the extension and with it in four locations (in the following order):
Batch dir is a general setting, and it is intended to be a repository of your personal command files. Files dir is a tourney setting and program dir is the directory where the WBTM-executable resides. If none of these choices match to a command file call, the call will be treated as a command. Note that aliases will be evaluated before command file calls, so if you have an alias with the same name as a command file call, the alias will be evaluated first.
Note: From 0.60 on command files still work the way described above, but if the first line in a command file is a function declaration, then that file will be treated as a function, not a command file.
5.10 Events and system variables
An event is something, which will trigger WBTM to call a command by itself. Currently there are four events: GameBegin, GameEnd, RoundBegin and RoundEnd. When a game is started, WBTM will put a command "GameBegin" in the command queue and execute it. By default all these commands have empty aliases, so they will be equal to empty commands. You can set these aliases to whatever you want, so that you can for example change tourney settings automatically after every round or you can output information about every finished game to a file.
To support these events WBTM also sets automatically the following aliases:
| GameBegin | ||||||||||||||||||
|
||||||||||||||||||
| GameEnd | ||||||||||||||||||
|
||||||||||||||||||
| RoundBegin | ||||||||||||||||||
|
||||||||||||||||||
| RoundEnd | ||||||||||||||||||
|
There is not much you can do with these variables, yet. But suggestions and wishes are welcome!
There is a set of settings, whose value behaves like an alias. These variable names must be preceded with a percent-sign (%) in order to get the value substituted. For example, to echo your Winboard Path you could do the following:
comment %WinboardPath
which would just type the winboard path without other side effects.
Currently supported variables are listed below.
| AutoRun | AutoSave | BlackOptions | Computer |
| EchoCommands | Extension | FilesPath | Hashtable |
| Inc | LogFileSize | Mps | Name |
| PicsDir | PgnFile | Ponder | Round |
| Rounds | RunnerInterval | SaveDebugFiles | SaveFile |
| ScheduleInterval | SubRounds | SwissPairTimeout | Tablebase |
| Time | TimeControl | Type | WhiteOptions |
| WinboardPath |
Commands differ from functions so, that functions can be anywhere in an expression, but command must be on its own line as such.
Let's start with player list related commands, since creating players and adding them to the tourney is always the first thing you do when starting a tourney.
| CreatePlayer | DeletePlayer | WritePlayers | ReadPlayers |
| Available | AddPlayer | RemovePlayer | AddAllPlayers |
| AddGroup |
Creates a new player to playerlist. A player created with CreatePlayer is not added to current tourney by default. A player can only enter tourney with commands AddPlayer or AddAllPlayers.
The user will be asked for new player's
- Name
- Dir - the directory where program's exe-file resides
InitString - engine options for winboard. If the engine must be started with some options, for example engine.exe -hash32 -xboard, then initstring would be '-hash32 -xboard'. You shouldn't type the quotes, they are added automatically if needed. Options - options for winboard. If the engine needs some special winboard option, for example /initstring 'Hello, world!', then it should be put here. Note that these options are added last on the winboard command line, so if engine needs it's own special time control, it can be specified here. ProgramExe - Name of engine's exe-file, for example Engine_012.exe.
Deletes player from playerlist, so that <player> can no longer be added to tourneys. Doesn't affect players already in a tourney. If you want to remove a player from tourney, use RemovePlayer instead.
Player can be referred by name or number. If referred by name, the whole name (case-sensitive) must be typed.
WritePlayers (wri) <player-file_path>
You can save a player list with WritePlayers. It should be noted, that saving player list writes over the existing file. If you want to append a player to file, you should first read the list from file. This command must not be used with winboard.ini!
ReadPlayers (readp) <player-file_path>
When creating a tourney you must add players. Players can only be added from a player list. To create players to list you can either create every player by hand with CreatePlayer, or read formerly created players from a player file. If you don't specify a file, then winboard.ini is automatically tried.
Shows all available players, that is players created with CreatePlayer or read from file with ReadPlayers, whose name begin with <player>. If <player> is omitted, shows all available players.
Adds <player> to tourney. Player can be referred by name or number.
Removes player from tourney. Player can be referred by name or number. If referred by name, the whole name (case-sensitive) must be typed.
If AutoSave is on, tourney will be saved before executing this command.
Adds all available players to tourney one by one. Behaves similarly to adding players by hand. If you give the option -rank, then players are added in strength order, strongest first. You can set the rating in winboard.ini with the WBTM special option /rating.
Adds all available players whose group setting include <group> to tourney one by one. Behaves similarly to adding players by hand.
Once you have created all the players you want and written them to a player file, you don't have to create them again. When starting a new tourney, you just read the players to player list, and then add all the players you want to the tourney.
| Reset | Load | Save | CreateRRGames |
| CreateBrackets | ShowBrackets | Pair | Spool |
| Run | Stop | Player | Game |
| RemoveGame | ShowGames | ShowPlayers | Get |
| Set | Table | TextTable | Replay |
| UnSpool | ReSpool | ForfeitPlayer | GetAllResults |
| HouseKeep | CreateGauntlet |
Clears the whole tourney, and sets the variable-values to defaults. If AutoSave is on, tourney will be saved before executing this command.
Loads a tourney from file. If <file_path> is omitted, a file named 'tourney.ini' from current directory is loaded if it exists. When loading a tourney, all variables concerning that tourney are loaded, that includes the schedule information, but not runner status. If a game is running on winboard when tourney is saved, it is not likely that the same game is still in progress when tourney is loaded again.
A tourney can be saved to a file. Saving includes all variables, players and schedule related settings. The runner status is not saved, because there is no way to determine whether winboard is running a game from this tourney or not. If winboard is not running, the save command is purposed to save the whole situation, so that an identical situation could be restored later with Load.
If <file_path> is omitted, the situation will be saved to file named 'tourney.ini' in current directory, it that is possible.
If AutoSave is on, this command also sets the save file.
When all players are added and tourney parameters (time control, subrounds, directories, files etc.) are set, the games can be created with CreateRRGames. Like it's name suggests, it creates all games for Round Robin tourney with current players. CreateRRGames deletes all existing games!
If AutoSave is on, tourney will be saved before executing this command.
CreateGauntletGames (createg) <gauntlet_player>
Like CreateRRGames, but for Gauntlet-type tourney. The argument <gauntlet_player> specifies the player who will meet all the other players.
Pair [<bracket>] [<player1> <player2>] [-size <size>] [-time <seconds>] [-down/-up]
Pairs a swiss round. Without parameters pairs using the basic method. If you give one number as parameter, a bracket by that number will be paired. If you give two players (numbers or names) they will be paired. Bracket size may be specified with -size, timeout with -time and direction of pairing with -up and -down. For details see Pairing swiss rounds.
CreateBrackets (createb) [-size <size>] [-down/-up]
Creates brackets for swiss tourney. Bracket size may be specified with -size, timeout with -time and direction of pairing with -up and -down. For details see Pairing swiss rounds.
ShowBrackets (showb) [<bracket>]
Shows either all brackets (no parameters) or a specified bracket.
Spool (spo) [<item> [<number>]]
Spools the item to Runner. When a game is spooled, it's status is changed and a bat-file is created. The Runner seeks spooled games and if it is not currently running any, it will run the next spooled game.
You can spool the next game, a game by number, the next round, a specified round, all games of a particular player or all remaining games. If <item> is omitted, the next game will be spooled. The next game will be determined by round, so that game will be selected from lowest round with games with status NOTHING DONE. The same applies to determining next round.
If <item> is a number, then game by that number is spooled. To specify a round, use 'round' as <item>, and 'player' when specifying a player.
Here's a summary:
spool Spools the next game. spool 3 Spools game number 3. spool -round Spools the next round. spool -round 3 Spools round 3. spool -player 3 Spools all games of player number 3. spool -player Ozw Spools all games of all players whose name begins with 'Ozw'. spool -all Spools all remaining games. Run [[<start_date>] <start_time>]
Sets runner on. That means that spooled games will be run with Winboard one by one. <start_time> specifies the time when runner will be activated. When runner is on, that only means that runner has the permission to start spooled games, it doesn't affect Winboard.
Start time is of format hh:mm:ss, where minutes and seconds can be omitted.
Start date is of format dd.mm.yyyy.
Stop [[<stop_date>] <stop_time>]
Behaves like the run command, but stops runner instead of starting it.
Player <player> [<variable> <value>]
You can set and view player's variables with this command. If you omit <variable> and <value>, player's variables are shown.
Possible variables to alter are the same which occur in the player file: Name, directory, executable, init string, white options, black options and group.
Game <number> [<command> <param>]
Modify some data of a specific game. A game can only be referred by number.
<command> can be result, status or cmdline. If <command> is not specified, game data will be shown.
Command Result sets the game's result. <param> can then be one of the following:
1-0 (white win)
0-1 (black win)
1/2-1/2 (draw)
unfinished
<command> Status sets the game's status. <param> can then be one of the following:
0 (Nothing done)
1 (Spooled)
2 (Ready)
If status is set to READY, the game's result will be set to UNKNOWN.
<command> CmdLine sets the game's command line, which is used when winboard is called to run the game. I strongly suggest that when you use this command, you get a WBTM-generated value and then edit it, not create one yourself.
RemoveGame (remg) [<number>] [-all] [-player <number>/<name>] [-white <number>/<name>] [-black <number>/<name>] [-round <number>] [-subround <number>] [-status <status>] [-result <result>]
Removes games. If -all is given, then all existing games will be removed. Otherwise all the given conditions must hold at the same time. If we wanted to remove all games, where player 'Ozwald' has played on white and black has won, we would give the command
remg -white Ozwald -result 0-1 -status READY
The alternatives for status are: nothing (nothing done), spooled and ready. The alternatives for result are: white or 1-0 for white win, black or 0-1 for black win, draw or 1/2, unknown and both lose.
If AutoSave is on, tourney will be saved before executing this command.
ShowGames (showg) [<number>] [-all] [-player <number>/<name>] [-white <number>/<name>] [-black <number>/<name>] [-round <number>] [-subround <number>] [-status <status>] [-result <result>]
Shows games. If -all is given, then all existing games will be shown. Otherwise all the given conditions must hold at the same time. If we wanted to show all games, where player 'Ozwald' has played on white and black has won, we would give the command
showg -white Ozwald -result 0-1 -status READY
The alternatives for status are: nothing (nothing done), spooled and ready. The alternatives for result are: white or 1-0 for white win, black or 0-1 for black win, draw or 1/2, unknown and both lose.
ShowPlayers (showp) [<number> / <name>]
Plain ShowPlayers without parameters shows a list of players at current tourney. You can also specify one player by number or one or several players by name. Name can be the name as whole or only the beginning, when all players matching that string will be showed. If parameters are present, a more detailed info will be shown. That info includes number, name, program exe, options, init string, program directory, current rank in tourney, points scored so far, buchholz and sonneborn-berger -comparisons and a list of games there player has played.
Shows the current value of <variable>. Type 'Get' to see a list of available variables. If you specify variable 'All', you get a list of all the variables at once.
Sets the value of <variable>. The only non-trivial variable is TimeControl, which format is MPS TIME INC. MPS specifies how many moves are to be completed within TIME. TIME is just plain minutes or min:sec. INC is time bonus (seconds) player gets for every move.
There is a new tourney option: SaveDebugFiles. It can have three different values: NEVER, AUTO, and ALWAYS. Never and always are obvious, but auto saves winboard.debug for those games, where result was set to UNKNOWN or UNFINISHED (something went wrong because the game was not finished). Saved files get the name gXXX.debug, where XXX is the game's number.
Table [-[x]<option>] ... [<html-file>]
Writes result table in html-format to <html-file>. If <html-file> is omitted, table is written to file 'table.htm' in files directory. There are now nine options. If you give only the option-letter, that option is turned on. If you prefix that letter by 'x', that option is turned off. For example -sort would turn sorting on and -xcomparison would turn the comparison-column off. These options are static, which means that these options apply till they are changed. So giving the options as before, all the result tables would be formatted sorted and without comparison columns, until they were altered again. The only columns which are always present are player names and total points scored.
In swiss tourneys, if sorting is on, the opponents of a player are now referred as players ranking rather than player's number, as was before. An example: Let's say Crafty is player number 2 and is ranked first. On the first round it defeated Ozwald, number 5, who is now ranked 10. Formerly Crafty's result cell in round 1 would have said +W5 and Ozwald's -B2, but now they say +10W for crafty and -1B for Ozwald.
To summarize the situation now: if table is not sorted, the rank-column tells player's current ranking. If table is sorted, the player's number carries no information.
Before: Now:
Rank No Name 1 2 1. 2. Crafty +W3 2. 1. ... 3. 4. ... 4. 5. ... 5. 6. ... 6. 3. Ozwald -B2 --->
Rank No Name 1 2 1. 2. Crafty +W6 2. 1. ... 3. 4. ... 4. 5. ... 5. 6. ... 6. 3. Ozwald -B1
Option Explanation -sort Sort the table according to player rankings. If this is off, players are displayed order of their numbers. -number Show player numbers. -grid Show games grid, ie. individual results of games between each player. -gridp Show grid points as total score against that opponent instead of result of every game. If SubRounds = 3, then a grid cell would have either text "2.0" (on) or "=1=" (off). -comparison Show comparison points. In Round Robin tourneys only Sonneborn-Berger comparison is shown, in Swiss tourneys also Buchholz comparison is shown. -rank Show player rank. -bar Show bar indicating player's points. -autosort AutoSort on/off. If auto sort is on, it will override -s. If this is on, sorting will only be applied on finished tourneys. TextTable (tex) [-[x]<option>] ... [<txt-file>]
Writes result table in text-format to <txt-file>. If <txt-file> is omitted, table is written to stdout, which normally means the console. See Table for options.
During a tourney there will often be games where either program has had some problem and therefore the game status is READY, but result is UNKNOWN. With Replay, all these UNKNOWN games will be spooled again. It is your choice as tourney organizer to decide when a program should be adjudicated to lose and when to replay.
To adjudicate you can use ForfeitPlayer or Game.
If you change command lines of spooled games, no actual damage is done, since command ReSpool will spool every game with status SPOOLED again. The spooling order will be random.
This command will unspool every spooled game. That means that the games' status will be changed to NOTHING DONE and the game command lines are deleted.
All games of player <player> are adjudicated as a win for the opponent. This command only affects games with status other than READY. You can also change game's status with the command Game.
Player can be referred by name or number.
Gets the results for each spooled game, if it is available (that means it seeks a pgn-file for that particular game). This command is quite useless, there shouldn't be any occasion when it has to be used since the end of game is detected from winboard.debug, not from the existence of pgn-file.
This command does housekeeping tasks, ie. things that are done when there is time and Winboard is not running. That involves
- checking the log file size
- Saving the tourney if AutoSave is on
- in case of swiss tourney pairing a round if AutoRun is on
You should not have to give this command ever, but it is there if you need to.
| AddLog | Alias changed | Comment | Dump new |
| Eval new | Quit | PrintLine new | RemoveLog |
| Stack new | Unalias changed | View |
This command launches Winboard in pgn-viewer mode (if you have set winboard path correctly) and loads automatically the pgn-save file. Move time interval is set to 0, so you will automatically see game's last position, from which you can easily find games where a program has not made moves at all, and perhaps decide to replay them.
WBTM has lacked the possibility to output text to a file. Now you can add as many log files as you want, and all output will go to them.
Removes a log file. You can remove only those log files you have added yourself, so you can't remove the log file WBTM creates itself.
Alias <alias_name> <alias_value>
Adds an alias definition. After this command if you type <alias_name> somewhere in the command line, it is replaced by <alias_value> before the line gets executed. See 5.8 Command aliases.
Removes an alias definition. Note that the alias will be replaced in this command too, so you should use the form !unalias <alias_name>, when aliases are disabled on that command. Alias name "-all" will remove all aliases. You can also type <alias_name> quoted, when that alias won't be replaced.
This is a dummy command, which only echoes everything on the line that comes after the command.
Isn't it quite obvious, what this command does? Well, if AutoSave is on, the tourney is also saved before exiting.
Stack shows the if- and while-statement stack. If you type nested if- and while-statements from commandline, you can see open if- and while statements with this command. It has no side-effects other than displaying the stack. Example:
if 1 < 2
while 1 < 2
while 1 < 2
if 1 < 2
else
stack
Block stack:
If While While ElseWe see that we are in an else-branch of an if statement, which lies within two nested whiles and an if branch.
Simply outputs <line>, which can be a variable or a function or anything. <line> is outputted in dequoted form, so escapized characters etc. are displayed in de-escapized form. For example printl "Hello\nworld!\n" would print like
Hello
world!Outputs the contents of current symbol table, ie. all existing variables.
Evaluates and shows the value of <Expression>.
From version 0.60 on, there is a possibility to write programs which WBTM will translate and run. This help file does not even try to be a programming tutorial, I assume that you are already familiar with some programming language and know how to write programs.
There are two data types in WBTM: strings and numbers.
Generally strings are always delimited by double quotes ("). The double-quoted form works always. If it doesn't, tell me, it is probably a bug. In a double-quoted string some characters are replaced with combination of two characters. These characters are:
| Backslash | \ | -> \\ | |
| Double quote | " | -> \" | |
| Single quote | ' | -> \' | |
| Tab | -> \t | ||
| Newline | -> \n | ||
| Carriage return | -> \r |
This coding is required if you want to be able to have these characters in a string literal.
Single quoted strings act like double quoted versions, but WBTM will automatically convert them to double quoted ones in most cases.
Non-quoted strings
If WBTM was only for programming purposes, I would not allow non quoted strings as string literals, all non quoted strings could be commands, reserved words or variable names. But because WBTM is not only a programming language, I accept non quoted strings as string literals for convenience. It means that if you want to have a string literal "WBTM", you can also type it without the quotes. However, the quoted version is always recommended, because it is faster and safer. Why is that? Because all non quoted strings are treated as variable names (if they begin with $) or functions, if one exists. An example:
You want to write $a = "test", but to save a couple of key presses you write $a = test. Now WBTM will see that you want to assign a value to $a, and it tries to parse the remaining string. In the first version it immediately sees that the value is "test", and will make the assignment. In the second case WBTM will check all four locations where functions can reside for a function file "test" or test.tcf (or whatever your batch extension is), and only after it has realized that no such function exists will it assign the value "test". And even worse: if a function named "test" exists, it will be called and you may end up with completely different value and behaviour than you wanted. Therefore it is always wise to use the quoted form, but if you know what you are doing, you can use the other one, too.
Numbers
There is not much to say about numbers, except that they are all floating point numbers. Some commands and functions will convert the numbers to integers if that is needed.
All variable names begin with the dollar-sign $. Just about any string which doesn't contain whitespaces should be ok as a variable name, as long as the first character is $.
Scope
Variables defined directly from the command line (and in command file) are global, so they are always visible. Functions have their own symbol tables, so they will only see variables defined in that function and system variables like the ones set by events. If you set a system variable value in a function, that value is also set in the global symbol table.
Assignment
There are five assignment operators: =, +=, -=, *= and /=. The first is the simple assignment operator, and the following four are just shorthands. For example $a += 1 means the same as $a = $a + 1.
Arithmetic operators
Currently there are the four basic operators +, -, * and /. + also works with strings as concatenation operator. Division operator does not allow division by zero, if you try it, the divisor will be replaced by 1.
While-statement
While-statement enables looping: you can execute a piece of code until as long as a contidion is satisfied. While statement has the syntax:
while
<condition>
<iterated code>
endwhile
<condition> consists of one or more comparisons, which can be chained with logical operators. Also parenthesis can be used. Comparison operators are ==, !=, <, <=, > and >=. Only the two first ones work with strings. Logical operators are && (and) and || (or). So far WBTM does not any kind of syntax checking between logical and comparison operators, you must self take care of their proper usage.
If-statement
If-statement enables branching: depending on a condition you can execute a piece of code or another code. If statement has the syntax:
if
<condition>
<true-branch>
[else
<false-branch>]
endif
<Condition> is like in while-statement. If <condition> evaluates true, then <true-branch> is executed, and if else-part exists, it will be executed if <condition> evaluates to false.
EndAll
The reserved word EndAll will end all open if- and while-statements. So you can type 10 nested Whiles and Ifs and then instead of writing 10 EndIfs and EndWhiles in the correct order you can type just one EndAll.
There are two types of functions: WBTM built in functions and user-defined.
Calling functions
The normal syntax is
$return_value = FuncName(Arg1, Arg2...)
and short syntax is
$return_value = FuncName Arg1 Arg2...
The normal form is recommended, since it works always. If it doesn't, let me know, because it is probably a bug. The short syntax exists mainly to enable user-written commands. Of course they will still be functions, but syntax is same as with commands.
Declaring functions
Function declaration is similar to Matlab-functions. A function resides in a text file, which has the same name as the function + current batch file extension. The first line of the function file must have the function declaration, which has the following syntax:
function [$retval] = FuncName([$arg1] [, $arg2] [...])
For example, let's create a function, which returns its argument value +1. If the function name is inc, then we should create file named inc.tcf (if we use the default extension), and the file would contain the following lines:
function $ret =
inc($val)
# Example function for WBTM help
# Increase argument value by 1
#
$ret = $val + 1;
The lines beginning with #-character are comments, but the lines which come right after the syntax line are displayed as help, if you give the command 'help FuncName'.
When calling functions, the function name is treated as path, so the function name can be for example c:\chess\winboard\wbtm\inc. WBTM will try both the function name itself and a version where the current batch file extension is added to the name. There are four locations, which will be checked: the current directory, batch file -directory, files path and program (WBTM) directory. Let's assume the current directory is c:\winboard, batch dir is c:\batch, files path is c:\files and program directory is c:\WBTM. Now if we try to call function inc with command $a = inc(1), WBTM will try to find the function file with following file names in the following order:
c:\winboard\inc
c:\winboard\inc.tcf
c:\batch\inc
c:\batch\inc.tcf
c:\files\inc
c:\files\inc.tcf
c:\WBTM\inc
c:\WBTM\inc.tcf
Note that if you use relative path like ../inc then WBTM would look the c:\-dir for four times!
In order to make programs useful there are some built in functions, which offer you to get data of the games and players and tourney too. Here are the current functions:
Tourney related functions (all begin with 'TourneyGet'):
| BlackOptions | FilesPath | Games | GauntletPlayer |
| Hashtables | PgnFile | Players | Ponder |
| Round | Rounds | SubRounds | Tablebases |
| Type | WhiteOptions |
Returns BlackOptions -string of current tourney.
Returns FilesPath -string of current tourney.
Returns number of games in current tourney.
Returns gauntlet player number (if any) in current tourney.
Returns Hashtables -string of current tourney.
Returns PgnFile -string of current tourney.
Returns number of players in current tourney.
Returns pondering setting of current tourney.
Returns current round number in current tourney.
Returns number of rounds in current tourney.
Returns number of subrounds in current tourney.
Returns Tablebases -string setting of current tourney.
Returns current tourney type.
Returns WhiteOptions -string of current tourney.
Game related functions (all begin with 'GameGet'):
| Black | CmdLine | PgnFile | Result |
| Round | Status | SubRound | White |
Returns number of black player in game <GameNumber>.
Returns command line of game <GameNumber>.
Returns pgn file name of game <GameNumber>.
Returns result of game <GameNumber>.
Returns round of game <GameNumber>.
Returns Status of game <GameNumber>.
Returns subround of game <GameNumber>.
Returns number of white player in game <GameNumber>.
Player related functions (all begin with 'PlayerGet'):
| BlackOptions | Buchholz | Dir | Exe |
| Group | InitString | Name | Opponents |
| Points | Rank | SB | WhiteOptions |
PlayerGetBlackOptions(<Player>)
Returns BlackOptions -string of <Player>.
Returns Buchholz comparison points of <Player>.
Returns Dir -string of <Player>.
Returns Exe -string of <Player>.
Returns Group -string of <Player>.
Returns Initstring of <Player>.
Returns <Player> name.
Returns Opponents -string of <Player>.
Returns points scored by <Player> in current tourney.
Returns rank <Player>.
Returns Sonneborn-Berber comparison points of <Player> in current tourney.
PlayerGetWhiteOptions(<Player>)
Returns WhiteOptions -string of <Player>.
| dequote | find | find_fo | find_fno |
| find_lo | find_lno | len | nextgame |
| num | numf | quote | str |
| strequ | strf | substr | trim |
| trim_left | trim_right |
Returns <string> in dequoted form. Dequoting removes outmost quotes (if there are any), and converts escapized characters (\", \', \n, \r, \t, \\) to non-escaped versions.
Find(<source-string>, <string-to-be-found> [, <pos>])
Searches <source-string> for <string-to-be-found> and returns the beginning position of <string-to-be-found> or -1 if no match was found. For example find("Tourney manager", "ney") would return 4. If <pos> > 0, search begins at position <pos>.
Find_fo(<source-string>, <search_chars> [,<pos>])
Searches <source-string> for first occurrence of characters in <search_chars> and returns the lowest position of matched character or -1 if no match was found. If <pos> > 0, search begins at position <pos>. For example find("Tourney manager", "na", 5) would return 9.
Find_fno(<source-string>, <search_chars> [,<pos>])
Searches <source-string> for first occurrence of characters not in <search_chars> and returns the lowest position of matched character or -1 if no match was found. If <pos> > 0, search begins at position <pos>. For example find("Tourney manager", "ABCy") would return 6.
Find_lo(<source-string>, <search_chars> [,<pos>])
Like Find_fo, but searches for last occurrence of <search_chars> and <pos> sets last possible position.
Find_lno(<source-string>, <search_chars> [,<pos>])
Like Find_fno, but searches for last occurrence of <search_chars> and <pos> sets last possible position.
Returns <string> length.
NextGame(<GameNumber> [,"-all"] [, "-player", <number>/<name>] [,"-white", <number>/<name>] [,"-black", <number>/<name>] [, "-round", <number>] [, "-subround", <number>] [, "-status", <status>] [, "-result", <result>])
This function makes it possible to iterate through existing games. Player numbers in a tourney always begin from 1, but game numbers don't. Now don't let the long syntax definition disturb you, it is not as complicated as it may seem. This is hot to use NextGame:
Get the first game number with $number = NextGame(0). <GameNumber> 0 means the beginning, WBTM will return number of first game in its table. Now you can do something with this number. Then you want to get the next game number. You call like this: $number = NextGame($number). Then get the next same way, until NextGame returns a value < 0, which means that no more games exist.
Now all the possible arguments just filter games which are accepted, just like the command ShowGames. You specify a condition, like "-player" and the following argument specifies an accepted value.
Here's an example, which will iterate through all games where either player is named "gnuchess" and print that game's number:
$gameno = NextGame("-pla", "gnuchess");
while $gameno >= 0
printl "Game number" + $gameno;
$gameno = NextGame($gameno, "-pla", "gnuchess");
endwhileReturns <string> converted to number.
Numf(<format_string>, <number>)
Returns a string formatted with c-printf-function format string. For example:
Numf("%05g", 2.1) would return "002.1".
Returns <string> quoted. Quoting will add double quotes to both ends of the string and the rest will be escapized.
Returns <number> as a string.
StrEqu(<string1>, <string2> [, <len>])
Compares strings <string1> and <string2>. If the strings are equal, returns 2.0, and if strings are equal only if case is ignored, returns 1.0, otherwise 0.0. If <len> is given, then only first <len> characters are compared. Examples:
StrEqu("WBTM", "WBTM") = 2
StrEqu("WBTM, "WBtm") = 1
StrEqu("WB", "WBtm", 2) = 2
StrEqu("WBTM, "WBt", 3) = 1Returns a string formatted with c-printf-function format string. For example:
strf("-%5s-", "WBTM") would return "- WBTM-".
Returns a substring of length <len> from <string> beginning from character <begin>. An example:
substr("Hello, world!", 2, 6) would return "llo, w".
If <len> < 0, substr will return the string from <begin> to end.
Returns <string>, where trailing and leading whitespaces are removed.
Returns <string>, where leading whitespaces are removed.
Returns <string>, where trailing whitespaces are removed.
WBTM is ~16000 lines of C++ code. I don't even dream of releasing a bug-free program of this scope at once. So if you have bugs, comments, questions, suggestions or think that something vital is missing from WBTM don’t hesitate to contact me. All feedback is welcome!
In this version the main thing is programming interface, which will evolve in the future. Local functions, break- and continue statements are things I'm planning to add some day. Also new built in functions will probably appear, and there you can give your suggestions.
One thing could be writing to winboard.ini-file, so that the engines-section could be altered within WBTM so that the syntax of settings would automatically go right.
One huge project is the GUI, which I have planned to make for a long time. Maybe it has eventually got its turn.
- Jori Ostrovskij -