git.sesse.net Git - pgn-extract/blob - help.html

   1 <!DOCTYPE HTML>
   2 <html>
   3 <head>
   4     <title>pgn-extract: a Portable Game Notation (PGN) manipulator</title>
   5     <link rel="author" href="mailto:d.j.barnes@kent.ac.uk">
   6     <meta http-equiv="Content-Type" content="text/html;charset=utf-8" >
   7     <meta name="Author" content="David J. Barnes">
   8     <meta name="Description" content="Usage description for pgn-extract">
   9     <meta name="Keywords"
  10           content="PGN format process remove duplicates
  11                    Portable Game Notation chess">
  12         <link href="style.css" rel="stylesheet" type="text/css" media="all">
  13 </head>
  14 <body>
  15 <div id="body">
  16
  17 <div id="banner-wrapper">
  18   <div id="banner">
  19 <h1>pgn-extract:<br />
  20 A Portable Game Notation (PGN) Manipulator for Chess Games<br />
  21 Version 17-19 by
  22 <a href="http://www.cs.kent.ac.uk/~djb/">David J. Barnes</a></h1>
  23   </div>
  24 </div>
  25
  26 <div id="page-wrapper">
  27     <div id="page">
  28 <h2>Overview</h2>
  29 <p>This page documents the free, open-source program <a href="http://www.cs.kent.ac.uk/~djb/pgn-extract">pgn-extract</a>, which is designed
  30 to support the processing, searching and extraction of chess games from files
  31 written in PGN format.
  32 There are several ways to specify the criteria on
  33 which to extract: textual move sequences, the position reached after a
  34 sequence of moves, information in the tag fields, and material balance
  35 in the ending.
  36 Full ANSI C source and a 32-bit Windows binary for the program are available
  37 under the terms of the <a href="#license">GNU General Public License</a>.
  38 The program includes a semantic analyser which will
  39 report errors in game scores and it is also able to detect duplicate
  40 games found in one or more of its input files.
  41
  42 <p>The range of input move formats accepted is fairly wide and includes
  43 recognition of lower-case piece letters for English and upper-case
  44 piece letters for Dutch and German.
  45 The default output is in English Standard
  46 Algebraic Notation (SAN), although there is some support for output
  47 in different notations.
  48
  49 <p>Extracted games may be written out either including or excluding
  50 comments, NAGs, and variations. Games may be given ECO classifications
  51 derived from the accompanying file eco.pgn, or a customised version
  52 provided by the user.
  53
  54 <p>Plus, lots of other useful features that have gradually found their
  55 way into what was once a relatively simple program!
  56
  57 <h2>Index</h2>
  58 <ul>
  59     <li><a href="#flag-summary">Flag/Command-line Argument Summary</a>
  60     <li><a href="#usage">Usage and Flags/Command-line Arguments</a>
  61     <li><a href="#input">Game Input Format</a>
  62     <li><a href="#-W">Output Format and Language (-W)</a>
  63     <li>Files:
  64         <ul>
  65         <li><a href="#output">Output Files (-o, --output, -a, --append)</a>
  66         <li><a href="#separate-output">Separate Output Files (-#, -E)</a>
  67         <li><a href="#-l">Log files (-l, -L)</a>
  68         <li><a href="#-f">File of PGN Files (-f)</a>
  69         <li><a href="#-A">Storing argument Descriptions in a File (-A)</a>
  70         </ul>
  71     <li><a href="#-r">Check for Errors (-r)</a>
  72     <li>Match criteria:
  73         <ul>
  74         <li><a href="#variations">Variation criteria</a>:
  75             <ul>
  76                 <li><a href="#-x">Positional Variations (-x)</a>
  77                 <li><a href="#-v">Textual Variations (-v)</a>
  78                 <li><a href="#-P">Textual Variation Permutations (-P)</a>
  79             </ul>
  80         <li><a href="#-t">Tag Criteria (-t and -T)</a>
  81             <ul>
  82             <li><a href="#fen-t">FEN positional matches with -t</a>
  83             <li><a href="#date-t">Date and Elo Matches with -t</a>
  84             <li><a href="#-T">Tag Criteria on the Command Line (-T)</a>
  85             <li><a href="#date-T">Date Matches with -T</a>
  86             </ul>
  87         <li><a href="#-b">Setting bounds on the number of moves in a game (-b)</a>
  88         <li><a href="#-M">Matching only games that end in checkmate
  89             (-M or --checkmate)</a>
  90         <li><a href="#stalemate">Matching only games that end in stalemate
  91             (--stalemate)</a>
  92         <li><a href="#underpromotion">Matching only games that contain an
  93         underpromotion (--underpromotion)</a>
  94         <li><a href="#-S">Soundex Matching (-S)</a>
  95         <li><a href="#-z">Material Matches (-z)</a>
  96         </ul>
  97     <li>Duplicate detection:
  98     <ul>
  99         <li><a href="#duplicates">Duplicate Games (-d, --duplicates and -D or --noduplicates, plus -Z)</a>
 100         <li><a href="#fuzzydepth">Positional Duplicates Match
 101         (--fuzzydepth)</a>
 102         <li><a href="#-U">Suppression of Unique Games (-U or --nounique)</a>
 103         <li><a href="#-c">Check Files for Duplicates (-c, --checkfile)</a>
 104     </ul>
 105     <li>Suppressing elements in the output:
 106       <ul>
 107         <li><a href="#suppress">Suppress annotations in the output (-C -N -V)</a>
 108         <li><a href="#nomovenumbers">Suppressing move numbers (--nomovenumbers)</a>
 109         <li><a href="#noresults">Suppressing results (--noresults)</a>
 110         <li><a href="#notags">Suppressing Tags (--notags)</a>
 111         <li><a href="#plylimit">Limiting the number of plies output (--plylimit)</a>
 112       </ul>
 113     <li>Tags:
 114       <ul>
 115         <li><a href="#-e">ECO Classification (-e)</a>
 116         <li><a href="#-7">The Seven Tag Roster (-7 or --seven)</a>
 117         <li><a href="#-R">User-defined Tag Roster Ordering (-R)</a>
 118         <li><a href="#addhashcode">Add a Tag containing a hashcode for the game (--addhashcode)</a>
 119         <li><a href="#totalplycount">Add a Tag containing the total ply count (--totalplycount)</a>
 120       </ul>
 121     <li>Adding annotations to games:
 122       <ul>
 123         <li><a href="#addhashcode">Add a Tag containing a hashcode for the game (--addhashcode)</a>
 124         <li><a href="#evaluation">Include a position evaluation after each move
 125                     (--evaluation)</a>
 126         <li><a href="#-F">Forsyth-Edwards Notation (FEN) description of the final position (-F)</a>
 127         <li><a href="#fencomments">Include a FEN comment after each move
 128                     (--fencomments)</a>
 129         <li><a href="#markmatches">Add a game comment for positional
 130         and material matches (--markmatches)</a>
 131         <li><a href="#totalplycount">Add a Tag containing the total ply count (--totalplycount)</a>
 132       </ul>
 133     <li><a href="#-n">Outputting Games not matched (-n)</a>
 134     <li><a href="#--selectonly">Outputting a single matched game (--selectonly)</a>
 135     <li><a href="#-w">Output Line Length (-w or --linelength)</a>
 136     <li><a href="#keepbroken">Retain games with errors in them (--keepbroken)</a>
 137
 138     <li>Documentation:
 139       <ul>
 140         <li><a href="#mailing">Mailing List</a>
 141         <li><a href="#limitations">Limitations</a>
 142         <li><a href="#files">The Files</a>
 143         <li><a href="#portability">Portability</a>
 144         <li><a href="#acknowledgements">Acknowledgements</a>
 145         <li><a href="#license">License</a>
 146         <li><a href="#history">A History of Changes to the Original Release</a>
 147       </ul>
 148 </ul>
 149
 150 <h2 id="flag-summary">Flag/Command-line Argument Summary</h2>
 151 <p>There follows a brief summary of the different flags taken by pgn-extract, such
 152 as is produced by the -h flag.
 153 However, you are strongly advised to read the remainder
 154 of this file before attempting to use pgn-extract in earnest.
 155 <ul>
 156       <li>-7 - output only the seven tag roster for each game. Other tags (apart
 157             from FEN and possibly ECO/Opening/Variation) are discarded
 158             (See <a href="#-e">-e</a>).
 159       <li>-aoutputfile - the file to which extracted games are to be appended.
 160             See <a href="#output">-o</a> flag for overwriting an existing file.
 161       <li>-Aargsfile - read the program's arguments from argsfile.
 162       <li>-b[elu]num - restricted bounds on the number of moves in a game.
 163           <ul>
 164                <li>lnum set a lower bound of 'num' moves,
 165                <li>unum set an upper bound of 'num' moves,
 166                <li>otherwise num (or enum) means equal-to 'num' moves.
 167           </ul>
 168       <li>-cfile[.pgn] - Use file as a list of check files for duplicates.
 169       <li>-C - don't include comments in the output. Ordinarily these are retained.
 170       <li>-dduplicatefile - the file to which duplicate extracted games are
 171             to be written.
 172       <li>-D - don't output duplicate extracted game scores.
 173       <li>-eECO_file - perform ECO classification of games. The optional
 174             ECO_file should contain a PGN format list of ECO lines
 175             Default is to use eco.pgn from the current directory.
 176       <li>-E[123 etc.] - split output into separate files according to ECO.
 177         <ul>
 178             <li>E1 : Produce files from ECO letter, A.pgn, B.pgn, ...
 179             <li>E2 : Produce files from ECO letter and first digit, A0.pgn, ...
 180             <li>E3 : Produce files from full ECO code, A00.pgn, A01.pgn, ...
 181             <li>Further digits may be used to produce non-standard further
 182             refined division of games.
 183         </ul>
 184         All files are opened in append mode.
 185       <li>-ffile_list  - file_list contains the list of PGN files to be
 186             searched - one per line (see <a href="#-f">-f</a>).
 187       <li>-F - output a FEN string comment of the final game position.
 188       <li>-h - print a list of command-line options.
 189       <li>-? - same as --help.
 190       <li>-llogfile  - Create a new logfile for the diagnostics rather than
 191                     using stderr (see <a href="#-l">-l</a>).
 192       <li>-Llogfile  - Append all diagnostics to logfile (see <a href="#-l">-l</a>).
 193       <li>-M - Match only games which end in checkmate.
 194       <li>-noutputfile - Write all valid games not otherwise output to outputfile.
 195       <li>-N - don't include NAGs in the output. Ordinarily these are retained.
 196       <li>-ooutputfile - the file to which extracted games are to be written.
 197             Any existing contents of the file are lost (see <a href="#output">-a</a> flag).
 198       <li>-P - don't match permutations of the textual variations (<a href="#-v">-v</a>).
 199       <li>-r - report any errors but don't extract (<a href="#-r">-r</a>).
 200       <li>-Rtagorder - Use the tag ordering specified in the file tagorder.
 201       <li>-s - silent mode don't report each game as it is extracted.
 202       <li>-S - Use a simple soundex algorithm for tag matches. If used, this
 203             option must precede the -t or -T options.
 204       <li>-ttagfile - file of player, date, result, or FEN extraction criteria.
 205       <li>-Tcriterion - player, date, eco code, hashcode, annotator or result, extraction criteria.
 206       <li>-U - don't output games that only occur once. (Use with -d to
 207             identify duplicates in multiple files.)
 208       <li>-vvariations - the file variations contains the textual lines of interest.
 209       <li>-V - don't include variations in the output. Ordinarily these are retained.
 210       <li>-wwidth - set width as an approximate line width for output.
 211       <li>-W - don't rewrite the moves into Standard Algebraic Notation.
 212       <li>-W[cm|epd|halg|lalg|elalg|san|uci] - specify the output format to use.
 213         <ul>
 214              <li>Default (i.e., without this flag) is SAN.
 215              <li>-W (without anything following) selects the input format.
 216              I don't know if the output produced is still valid.
 217              <li>-Wepd is EPD format.
 218              <li>-Whalg is hyphenated long algebraic.
 219              <li>-Wlalg is long algebraic
 220              <li>-Welalg[PNBRQK] is enhanced long algebraic. Use the characters
 221              PNBRQK for language specific output, e.g: -WelalgBSLTDK for German.
 222              <li>-Wsan[PNBRQK] Use the characters PNBRQK for language
 223              specific output, e.g: -WsanBSLTDK for German.
 224              <li>-Wuci is output compatible with the UCI protocol.
 225              <li>-Wcm is a legacy option that output ChessMaster format.
 226         </ul>
 227       <li>-xvariations - the file variations contains the lines resulting in
 228              positions of interest.
 229       <li>-zendings - the file endings contains the end positions of interest.
 230       <li>-Z - use the file virtual.tmp as an external hash table for duplicates.
 231             Use when MallocOrDie messages occur with big datasets.
 232       <li>-#num - output num games per file, to files named 1.pgn, 2.pgn, etc.
 233       <li>--addhashcode - output a HashCode tag.
 234       <li>--append - append matched games to an existing output file
 235             (see <a href="#output">-a</a>).
 236       <li>--checkfile - Use file as a list of check files for duplicates
 237             (see <a href="#-c">-c</a>).
 238       <li>--checkmate - only output games that end in checkmate
 239       <li>--duplicates - file to write duplicate games to
 240             (see <a href="#duplicates">-a</a>).
 241       <li>--evaluation - include a position evaluation after each move.
 242       <li>--fencomments - include a position evaluation after each move.
 243       <li>--fuzzydepth plies - positional duplicates match.
 244       <li>--help - see <a href="#-h">-h</a>
 245       <li>--keepbroken - retain games with errors.
 246       <li>--linelength - see <a href="#-w">-w</a>
 247       <li>--markmatches comment - mark positional and material matches with
 248       the given comment.
 249       see <a href="#fen-t">-t</a>, <a href="-x">-x</a>
 250       <li>--nochecks - don't output + and # after moves.
 251       <li>--nocomments - see <a href="#-C">-C</a>
 252       <li>--noduplicates - see <a href="#-D">-D</a>
 253       <li>--nomovenumbers - don't output move numbers.
 254       <li>--nonags - see <a href="#-N">-N</a>
 255       <li>--noresults - don't output results.
 256       <li>--notags - don't output any tags.
 257       <li>--nounique - see <a href="#-U">-U</a>
 258       <li>--output - write matched games to an output file
 259             (see <a href="#output">-a</a>).
 260       <li>--plylimit - limit the number of plies output.
 261       <li>--seven - see <a href="#-7">-7</a>
 262       <li>--selectonly N - only output the Nth matched game (N > 0)
 263       <li>--stalemate - only output games that end in stalemate.
 264       <li>--totalplycount - include a tag with the total number of plies in a game.
 265       <li>--version - print current version number and exit.
 266 </ul>
 267
 268 <h2 id="usage">Usage and Flags/Command-line Arguments</h2>
 269 <p>pgn-extract takes an arbitrary number of game scores as input and outputs
 270 zero or more of these games, typically in English Standard Algebraic
 271 Notation (SAN). Which of the input games are output, and the style
 272 of the output, depend upon the particular set of command line flags
 273 passed to pgn-extract.
 274 The general form for calling pgn-extract is as follows:
 275 <pre>
 276 pgn-extract [flags] [input-game-files]
 277 </pre>
 278
 279 <p>In its simplest form, calling pgn-extract with no arguments will cause
 280 it to read games from its standard input, check them and reproduce those
 281 without errors in SAN notation on its standard output.
 282
 283 <h2 id="input">Game Input Format</h2>
 284 <p>This program's principle aim is to be able to read PGN files and output
 285 games of interest. It follows that the input should look reasonably like PGN to
 286 start with.  This means that it doesn't cope well with files that
 287 contain news article or mail headers, for instance, although it does
 288 make an attempt to skip text that is obviously not game related between
 289 games.  Having said that, it does not require the move text be in
 290 Standard Algebraic Notation (SAN).  It will accept quite a few common
 291 formats including:
 292 <ul>
 293     <li>Algebraic
 294     <li>Long Algebraic
 295     <li>various commonly-used intervening characters, such as : - x
 296     <li>Dutch and German upper case piece letters.
 297     (Support for Russian piece letters is in prototype.)
 298     <li> lower-case English piece characters (except that it will always prefer
 299     'b' to mean a pawn move rather than a Bishop move).
 300 </ul>
 301 <p>It does not
 302 require that there be any move numbers or PGN headers preceding a game,
 303 as long as the move text is terminated by a valid result designation:
 304 *, 1-0, 0-1, 1/2-1/2 (1/2 is also accepted).
 305 This makes the program reasonably suitable for entering raw game text and
 306 having it reformatted in proper SAN with a full set of headers.
 307
 308 <h2 id="-f">File of PGN files (-f)</h2>
 309 <p>Normally, the input files from which games are to be extracted are listed on the
 310 command line:
 311 <pre>
 312 pgn-extract file1.pgn [file2.pgn ...]
 313 </pre>
 314
 315 <p>An alternative to listing the game files on the command line is to list
 316 their names, one per line, in a file which is then given after the -f flag:
 317 <pre>
 318 pgn-extract -ffile_list
 319 </pre>
 320
 321 <p>In order to save the output in a file rather than standard output,
 322 use <a href="#output">-o, --output, -a, --append</a> to indicate the output
 323 file name, for instance:
 324 <pre>
 325 pgn-extract -oall.pgn file1.pgn file2.pgn file3.pgn
 326 pgn-extract --output all.pgn file1.pgn file2.pgn file3.pgn
 327 </pre>
 328
 329 <p>While pgn-extract can be used simply to check and reformat all the input games,
 330 it is more usual to use it to select subsets of the input games.
 331 Several different criteria are available on
 332 which to extract: <a href="#variations">move variations</a>,
 333 <a href="#-t">information in the tag fields</a>, and
 334 <a href="#-z">material balance
 335 in the ending</a>, for instance.
 336 All of these criteria are described in detail below.
 337
 338 <h2 id="output">Output Files (-o, --output, -a, --append)</h2>
 339 <p>In order to output all matched games to a single new file, the -o flag is used:
 340 <pre>
 341 pgn-extract -onew.pgn file1.pgn file2.pgn
 342 </pre>
 343 <p>This has the effect of creating new.pgn from the contents of file1.pgn
 344 and file2.pgn.
 345 The games
 346 in both source files are checked and rewritten, if necessary, into SAN.
 347 Any previous contents of new.pgn will be lost with the -o flag. In order to
 348 avoid this and append to an existing file, use the -a flag:
 349 <pre>
 350 pgn-extract -anew.pgn file1.pgn file2.pgn
 351 </pre>
 352 <p>Note that there must be no space between either -o or -a and the output file name.
 353
 354 <p>The long-form --output and --append are provided as alternatives to -o and -a,
 355 respectively. In these cases, there must be a space between the
 356 flag and the output filename. For instance:
 357 <pre>
 358 pgn-extract --output new.pgn file1.pgn file2.pgn
 359 pgn-extract --append new.pgn file1.pgn file2.pgn
 360 </pre>
 361
 362 <h2 id="-r">Check for Errors (-r)</h2>
 363 <p>Check the input files for errors but do not output any matched games.
 364 Useful for cleaning up files of games before proper processing.
 365 <pre>
 366 pgn-extract -r file.pgn
 367 </pre>
 368 <p>Useful with -s (silent mode) for checking a big file of games without
 369 having progress reported and just seeing the errors.
 370
 371 <h2 id="keepbroken">Retaining games with errors</h2>
 372 <p>Normally, pgn-extract reports games with errors but does not output them.
 373 Games with errors may be output with the --keepbroken argument.
 374 The errors are still reported by the
 375 moves from the point where the error was detected onwards are placed in a comment rather
 376 than being retained as part of the game.
 377
 378 <h2 id="-l">Log files (-l, -L)</h2>
 379 <p>Error messages and verbose reporting is done to the standard error
 380 output unless the -l or -L flag is used.
 381 Both are immediately followed by the name of a file to which a log
 382 should be written.
 383 The -l flag creates a new log file, while -L appends to an existing log file:
 384 <pre>
 385 pgn-extract -llog.txt file.pgn
 386 pgn-extract -Llog.txt file.pgn
 387 </pre>
 388 <p>This option is useful in combination with <a href="#-r">-r</a> (report)
 389 to generate diagnostic information without outputting games while game
 390 data is being checked and cleaned.
 391 <p>A log file will contain only error reports if the <a href="#-s"">-s</a>
 392 (silent) flag is used.
 393
 394 <h2 id="variations">Variations (-v, -x and -P)</h2>
 395 <p>There are two distinct ways to specify variations of interest;
 396 positional variations (the <a href="#-x">the -x</a> flag) and
 397 textual variations (the <a href="#-v">-v</a> flag).
 398 The major difference between the two is that positional variations
 399 specify a complete move sequence whose end position is the primary
 400 point of interest, whereas textual variations allow incomplete and
 401 fuzzy move sequence matches on the text of a game to select games.
 402 Whilst it is possible to use both
 403 flags together, this would be unusual as a game must match with both to
 404 be extracted.
 405
 406 <ul>
 407 <li id="-x"><p>Positional Variations (-x)<br />
 408 <p>The variations in which you are interested should be placed in a file
 409 whose name is supplied with the -x flag. For instance:
 410 <pre>
 411 pgn-extract -xvars
 412 </pre>
 413 <p>where each variation is
 414 listed on a single line in the file vars (the filename is immaterial).
 415 The following set of moves:
 416 <pre>
 417 e4 c5 Nf3 d6 d4 cxd4 Nxd4 Nf6 Nc3 a6
 418 </pre>
 419 <p>indicates that you wish to pick up all games reaching the Najdorf
 420 variation position of the Sicilian Defence.
 421 Games reaching the end position of this sequence are
 422 selected regardless of the route that was taken to reach it.  This
 423 allows various transpositional sequences to be specified by quoting
 424 just one line to reach the required point.  Therefore, games employing
 425 the following move order will be picked up by quoting the line above.
 426 <pre>
 427 e4 c5 Nc3 d6 Nge2 Nf6 d4 cxd4 Nxd4 a6
 428 </pre>
 429 <p>A position is considered to match a required variation if it generates
 430 the same board hash value. In the interests of reasonable efficiency,
 431 no attempt is made to actually examine the state
 432 of the board. There is, therefore, the potential for false hits but in
 433 my usage of pgn-extract I have not found this to be a problem.
 434
 435 <p>With this option, games are only searched to a depth approximately equal
 436 to the length of the longest positional variation, in order to make
 437 processing of large data sets faster than with a search of the whole
 438 game.
 439
 440 <p>A comment line may be placed in a variation file by using a '%' as the
 441 first character of the line. Move numbers are optional within the
 442 list of moves.
 443
 444 <p>Positional matches are also available using a FEN description of the
 445 desired position.
 446 See the description of the <a href="#-t">-t flag</a>
 447 for how to specify a FEN position,
 448 and <a href="#-F">the -F flag</a>
 449 for a simple way to generate a FEN description from
 450 a game score.
 451
 452 <li id="-v"><p>Textual Variations (-v) <br />
 453 <p>With this option, the matching is purely textual in nature,
 454 in contrast to the <a href="#-x">-x</a> flag.  The -v flag works by
 455 string matching on the input text of moves,
 456 so there is no facility for picking up transpositions automatically.
 457 The variations in which you are interested should be placed in a file
 458 whose name is supplied with the -v flag. For instance:
 459 <pre>
 460 pgn-extract -vvars
 461 </pre>
 462 <p>Each variation should be listed on a single line
 463 in the file vars (the filename is immaterial).
 464 The move sequence:
 465 <pre>
 466 e4 c5 Nf3 d6 d4 cxd4 Nxd4 Nf6 Nc3 a6
 467 </pre>
 468 <p>indicates that you wish to pick up all games following the normal move
 469 order of the Najdorf variation of the Sicilian Defence, and
 470 <pre>
 471 d4 Nf6 c4 e6 Nc3 Bb4
 472 </pre>
 473 <p>that you are interested in Nimzo-Indian games.
 474 The order in which the moves are played by either White or Black
 475 is immaterial. All combinations are tried, so the ordering:
 476 <pre>
 477 c4 e6 Nc3 Bb4 d4 Nf6
 478 </pre>
 479 <p>will produce the same set of matches as the previous ordering of the
 480 Nimzo-Indian moves (see <a href="#-P">the -P flag</a> for how
 481 to prevent this).
 482
 483 <p>A comment line may be placed in a variation file by using a '%' as the
 484 first character of the line. Move numbers are optional within the
 485 list of moves.
 486
 487 <p>As transpositions are not picked up automatically with this flag,
 488 if you also wanted to
 489 recognise the following as a Najdorf, you would have to add this line
 490 to the variations file in addition to that given above:
 491 <pre>
 492 e4 c5 Nc3 d6 Nge2 Nf6 d4 cxd4 Nxd4 a6
 493 </pre>
 494 <p>However, because of the way in which the matching is done, it is
 495 possible to specify slight alternatives on the way in which individual
 496 moves are written.  Notational alternatives for a single move are just
 497 written separated from each other with a non-move character.  This
 498 variation specifies both the shorter and longer ways of writing the
 499 captures in a Najdorf:
 500 <pre>
 501 e4 c5 Nf3 d6 d4 cxd4|cd Nxd4|Nd4 Nf6 Nc3 a6
 502 </pre>
 503 <p>However, given the variety of possible ways of writing various moves in
 504 non-SAN format, e.g.
 505 <pre>
 506 cxd4|cd|c5d4|c5-d4
 507 </pre>
 508 <p>variation lists can get quite messy and I believe that this approach is
 509 best avoided by ensuring that the input is proper SAN and only using
 510 SAN notation in the variations file. In this way, the alternative-separator
 511 can then be used purely for indicating genuine alternative moves at
 512 that point, e.g.
 513 <pre>
 514 e4 c5 Nf3 d6 d4|d3
 515 </pre>
 516 <p>An important point when listing moves is that check and mate indicators
 517 should be included where appropriate, otherwise moves incorporating
 518 these characters in games to be searched will fail to match.
 519
 520 <p>There is little point in using the -v flag in preference to
 521 the <a href="#-x">-x</a> flag
 522 if you are only interested in finding games that reach a particular
 523 position.  The real use for -v is when you wish to pick up games
 524 in a more general way.  For instance, the character '*' may be used in
 525 place of any move to indicate that you don't care what was played at
 526 that point.  So the following:
 527 <pre>
 528 * b6
 529 </pre>
 530 <p>means that you are interested in all games in which Black replied
 531 1 ... b6 regardless of White's first move.
 532 The sequence:
 533 <pre>
 534 d4 * c4 * Nc3 *
 535 </pre>
 536 <p>will pick up Nimzo-Indian, Grunfeld, King's Indian, etc. defences.
 537 This notation is not possible with <a href="#-x">positional variations</a>.
 538
 539 <p>In addition, the character '!' may be used in front of any move to
 540 indicate that you wish to disallow particular moves from matching at
 541 this point.  For instance, if you want to find Sicilian games where
 542 White did not reply with Nf3 at move 2 you would specify:
 543 <pre>
 544 e4 c5 !Nf3
 545 </pre>
 546 <p>If you wished to disallow 2.Ne2 as well then
 547 <pre>
 548 e4 c5 !Nf3|Ne2
 549 </pre>
 550 <p>does the job.  (Adding parentheses makes no difference as the '!' is
 551 applied to all of the following move string.)
 552
 553 <p>Care should be taken combining '!', '*' and variation permutations (see <a
 554 href="#-P">the -P flag</a>).
 555 Disallowed moves take precedence over '*' moves.  If a single
 556 disallowed move is found in a game within the length of the variation,
 557 that game is excluded.  This was the most sensible interpretation that
 558 I could find to place on this usage.
 559
 560 <li id="-P"><p>Textual Variation Permutations (-P)<br />
 561 <p>Normally, all permutations of a textual variation (see <a href=
 562 "#-v">the -v flag</a>) are tried against the
 563 moves of a game.  This cuts down on the number of separate
 564 transpositional orderings that it is necessary to list, at the cost of
 565 slower matching of each game.  If the following were used to look for
 566 Nimzo-Indian games:
 567 <pre>
 568 d4 Nf6 c4 e6 Nf6 Nc3 Bb4
 569 </pre>
 570 <p>a side-effect would be that it will also pick up games which start as:
 571 <pre>
 572 1. c4 Nf6 2. Nc3 e6 3. d4 Bb4
 573 </pre>
 574 <p>for instance.
 575 The -P flag requests that textual variations are matched against the
 576 moves of the game strictly in the order in which they are listed,
 577 without trying different orders.  So, if you want to find only those
 578 games that follow a particular move order, use this flag to suppress
 579 permutations.
 580 </ul>
 581
 582 <h2 id="duplicates" id="-d" id="-D">Duplicate Games (-d, --duplicates and -D or --noduplicates, plus -Z)</h2>
 583 <p>If either the -d, --duplicates or -D flag is used, pgn-extract
 584 attempts to recognise duplicate extracted games.
 585 Using the -d or --duplicates flag indicates that you wish copies of the
 586 duplicate
 587 games to be written to the indicated file:
 588 <pre>
 589 pgn-extract -ddupes.pgn -ounique.pgn file.pgn
 590 pgn-extract --duplicates dupes.pgn --output unique.pgn file.pgn
 591 </pre>
 592 <p>will both extract from file.pgn the unique set of games into unique.pgn and
 593 the duplicates (i.e., the second and subsequent copies of a game)
 594 to dupes.pgn.
 595 A comment identifying in which file a
 596 duplicate was found precedes the first duplicate found in that file and
 597 each duplicate game has a prefix comment indicating the file in which
 598 the first version was found.
 599 Note that there must be no space between <code>-d</code> and the filename
 600 but a space between if <code>--duplicates</code> is used.
 601
 602 <p>With the -D flag duplicate games are suppressed
 603 from the output. These two flags are mutually exclusive, therefore.
 604
 605 <p>Duplicates are identified by comparing a hash value for the board of
 606 the end positions of extracted games and an additional cumulative hash
 607 value generated from the move sequence.
 608 If these both values match then games are considered to be
 609 duplicates.
 610 This is not guaranteed to be exact but it gives a good approximation.
 611 If the position is important but the move sequence is not then use
 612 <a href="#fuzzydepth">--fuzzydepth</a>.
 613
 614 <p>You should note that games are only considered to be duplicates on the
 615 basis of the moves played.  It may be that a game considered to be a
 616 duplicate contains annotations and variations not present in the one
 617 found earlier, so it might be necessary to do some swapping around to
 618 obtain those you really wish to retain. You should, therefore, use the
 619 -D flag with caution if you are trying to reorganise your master
 620 collection rather than selecting out specific games for examination.
 621 (See also <a href="#-U">the -U flag</a>.)
 622
 623 <p>Detecting duplicates requires memory for the storage of a hash table
 624 containing information on each game.
 625 Large databases can result in a MallocOrDie error.
 626 If this is the case, try using the -Z flag which
 627 forces pgn-extract to store its hash table externally, in a file called
 628 virtual.tmp. Each game requires 16 bytes of file space. Clearly, if a
 629 very large database is being processed, there is a risk of filling up
 630 the available file space if there is insufficient available.
 631
 632 <h2 id="fuzzydepth">Positional Duplicates Match</h2>
 633 <p>This flag allows a match on the basis of board position at the
 634 indicated number of plies or the end of the game.
 635 The flag is followed by the ply depth at which matches are to be
 636 considered. The value 0 is used to request matching at the end of
 637 games. It should always be used in combination with at least
 638 one of: <a href="#duplicates">-d/--duplicates, -D/--noduplicates</a>, <a href="#-U">-U</a>.
 639
 640 <p>In contrast to the <a href="#duplicates">--duplicates</a> matching,
 641 the match does not consider the move sequence used to reach the
 642 match position.
 643
 644 <p>For example:
 645 <pre>
 646 pgn-extract --fuzzydepth 40 -D games.pgn
 647 </pre>
 648 <p>would suppress from the output multiple copies of games reaching
 649 identical positions after 40 ply.
 650
 651 <p>The following example would suppress the unique games and
 652 store the games considered to be duplicate at their final
 653 position in dupes.pgn:
 654 <pre>
 655 pgn-extract --fuzzydepth 0 -U -ddupes.pgn games.pgn
 656 </pre>
 657
 658 <h2 id="-U">Suppression of Unique Games (-U or --nounique)</h2>
 659 <p>The -U flag suppresses output of the first occurrence of a particular
 660 game.  This is useful when combined with <a href="#duplicates">the -d flag</a>
 661 as a means of
 662 identifying just those games that are duplicated in a list of multiple
 663 files.  As the duplicate games are commented with the file in which
 664 they were located, it then becomes possible to prune a set of files
 665 containing common games.  For instance, suppose oldfile.pgn contains a
 666 set of games without duplicates, and you wish to know which games in
 667 newfile.pgn already occur in oldfile.pgn:
 668 <pre>
 669 pgn-extract -U -ddupes.pgn oldfile.pgn newfile.pgn
 670 </pre>
 671 <p>will write to dupes.pgn the duplicate games so that you can go through
 672 newfile.pgn and remove them.  Of course, if you simply want to hold the
 673 combined set of unique games in a single file you would use something like:
 674 <pre>
 675 pgn-extract -D -onewset.pgn oldfile.pgn newfile.pgn
 676 </pre>
 677 <p>See <a href="#duplicates">Duplicate Games</a> for dealing
 678 with MallocOrDie errors.
 679
 680 <h2 id="-c">Check Files for Duplicates (-c, --checkfile)</h2>
 681 <p>Check files contain games that are to be used in duplicate detection,
 682 but not to form part of the output. If the filename appended to the
 683 argument has a .pgn/.PGN suffix it is assumed to be a single file of
 684 games. If it does not have this suffix then it is assumed to be a file
 685 containing a list of the names of PGN game files, one per line, to be
 686 used as check files.
 687
 688 <p>A typical use for this is to select new games of
 689 interest from a file that probably contains games that exist elsewhere.
 690 In the following example, we wish to select Nimzo-Indian games from
 691 newfile.pgn that don't already occur in the master file nimzo.pgn:
 692 <pre>
 693 pgn-extract -cnimzo.pgn -vnimzo.var -D -onewnimzo.pgn newfile.pgn
 694 </pre>
 695 <p>The games in nimzo.pgn act as the source for duplicate detection so
 696 duplicates of these will be suppressed (<a href="#duplicates">the -D flag</a>).
 697 Only those games from
 698 newfile.pgn that are not in nimzo.pgn will be output to newnimzo.pgn.
 699 Contrast this behaviour with the following, which would create a new
 700 master file of games from the combination of nimzo.pgn and
 701 newfile.pgn:
 702 <pre>
 703 pgn-extract -vnimzo.var -D -onewnimzo.pgn nimzo.pgn newfile.pgn
 704 </pre>
 705
 706 <p>--checkfile is available as an alternative to -c and must be followed
 707 by a space before the filename, e.g.:
 708 <pre>
 709 pgn-extract --checkfile nimzo.pgn -vnimzo.var -D -onewnimzo.pgn newfile.pgn
 710 </pre>
 711
 712 <h2 id="-t">Matching on Tag Criteria (-t)</h2>
 713 <p>There are two ways to specify that you wish to use information in the
 714 tag fields as extraction criteria: the -t flag and
 715 <a href="#-T">the -T flag</a>.  The -t flag takes a file name
 716 argument and is the preferred method because of its ease of use and
 717 greater flexibility:
 718 <pre>
 719 pgn-extract -ttags games.pgn
 720 </pre>
 721 <p>where tags is an arbitrary file name.
 722 In the file are listed tag name and value pairs
 723 corresponding to the extraction criteria you wish to use.
 724 Each line of this file should be of the form:
 725 <pre>
 726 PGN-Tag-name Tag-string
 727 </pre>
 728 for instance:
 729 <pre>
 730 White "Tal"
 731 </pre>
 732 <p>(note the need to include double quotes around the tag value).
 733 This requests that only those games where Tal had the White pieces are
 734 to be considered for extraction.
 735 If you wish to limit the year in
 736 which those games were played you might list:
 737 <pre>
 738 White "Tal"
 739 Date "1962"
 740 </pre>
 741 <p>Multiple pairs with the same tag name are or-ed together so:
 742 <pre>
 743 % Find games in the period 1960-1962.
 744 Date "1960"
 745 Date "1961"
 746 Date "1962"
 747 </pre>
 748 <p>will select all games from the three listed years.
 749 Note that comments may be included in the tag file.
 750
 751 <p>In general, tags names that differ are and-ed together, so:
 752 <pre>
 753 White "Tal"
 754 Black "Fischer"
 755 Date "1962"
 756 Result "1-0"
 757 </pre>
 758 <p>selects only those games that Tal won with the White pieces against
 759 Fischer in 1962.
 760
 761 <p>It is important to note that:
 762 <pre>
 763 White "Tal"
 764 Black "Tal"
 765 </pre>
 766 <p>does not find all games played by Tal, but only those that he played
 767 against himself.  In order to overcome this, I have introduced a
 768 non-PGN tag that should only be used in the extraction criteria file:
 769 <pre>
 770 Player "Tal"
 771 Date "1962"
 772 </pre>
 773 <p>finds all games from 1962 in which Tal had either the White pieces or
 774 the Black.  In effect, the White and Black player lists are or-ed
 775 together rather than and-ed using this pseudo-tag.
 776
 777 <p>Prefix matching on tag values is done so that a criterion should be a prefix
 778 of the complete Tag string.  Thus,
 779 <pre>
 780 Player "Karpov"
 781 </pre>
 782 <p>would match:
 783 <pre>
 784 [White "Karpov"]
 785 [White "Karpov, A"]
 786 [White "Karpov, An"]
 787 [White "Karpov, Alexander"]
 788 </pre>
 789 <p>but not
 790 <pre>
 791 [White "Anatoli Karpov"]
 792 </pre>
 793 <p>See the <a href="#-S">-S</a> flag for a soundex facility with tag matching.
 794
 795 <p>All tag criteria except ECO classification are checked before the moves
 796 of the game in the interests of efficiency (tag checking is relatively
 797 fast whereas positional checking of the game is not). Only once the
 798 game has been processed is it checked to see whether an ECO tag match
 799 has been requested.  The consequence of this is that using <a href="#-e">the
 800 -e flag</a>
 801 in combination with ECO tag criteria you can search for games in
 802 particular ECO lines without an ECO tag having been present in the
 803 input form.
 804
 805 <ul>
 806 <li id="fen-t"><p>FEN positional matches with -t<br />
 807 <p>Use of a FEN tag with the -t flag has
 808 a special meaning. Rather than using this to match FEN tags in
 809 the header of a game, a FEN description is used to indicate a search
 810 for a positional match (similar to use of <a href="#-x">the -x</a> flag).
 811 If a FEN description is provided with the -t flag, the indicated
 812 position is searched for in each game processed, and only those
 813 games that reach the indicated position are output.
 814 A FEN tag-pair for the starting position would be described by:
 815 <pre>
 816 FEN "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1"
 817 </pre>
 818 <p>The position after the two moves e4 c5 would be:
 819 <pre>
 820 FEN "rnbqkbnr/pp1ppppp/8/2p5/4P3/8/PPPP1PPP/RNBQKBNR w KQkq c6 0 2"
 821 </pre>
 822 <p>See details of <a href="#-F">the -F flag</a> for a simple way to generate a FEN
 823 description from a game score.
 824
 825 <p>There is a variation on use of a FEN with -t flag.
 826 The pseudo tag FENPattern takes a FEN-like description of a board
 827 containing meta characters that allow a fuzzy board match.
 828 In addition to the standard FEN characters having their usual
 829 meaning (1, 2, ... 8, R, N, B, etc.), the following
 830 meta characters are used:
 831
 832 <ul>
 833   <li>? - match any square. The square may be occupied or unoccupied.
 834   <li>! - match any occupied square. The square may be occupied by a piece of any type and colour.
 835   <li>A - match a single White piece.
 836   <li>a - match a single Black piece.
 837   <li>* - match zero or more squares, occupied or unoccupied.
 838   <li>[<em>xyz</em>] - match any of <em>xyz</em>, where <em>xyz</em> represents
 839   any of the English piece-letter names (KQRNBPkqrnbp) and is case-sensitive.
 840   In addition, 'A' and 'a' (as defined above) are available.
 841   For instance: [Qq] matches either a White or Black queen;
 842   [BbNn] matches any White or Black bishop or knight;
 843   [Ar] matches any White piece or a Black rook.
 844   <li>[^<em>xyz</em>] If the first character inside the square brackets
 845   is '^' then the match is inverted; i.e., match any piece that is <em>not</em>
 846   listed. For instance, [^BbNn] matches any piece that is not
 847   a White or Black bishop or knight.
 848 </ul>
 849 <p>Ranks within the pattern are separated with a '/' character, as usual,
 850 but there should be no characters other than the board position.
 851 <p>
 852 For instance:
 853 <pre>
 854 FENPattern "rnbqkbnr/*/*/*/*/*/*/RNBQKBNR"
 855 </pre>
 856 <p>would match any board in which at least every non-pawn piece is
 857 on its starting square.
 858 <pre>
 859 FENPattern "?????rk?/?????aaa/*/*/*/8/P[BP]P*/??KR????"
 860 </pre>
 861 <p>would match a board in which Black has a Kingside castled position behind three
 862 Black pieces (not necessarily pawns),
 863 White has a Queenside castled position with
 864 either a White pawn or bishop on b2 and the third rank is empty.
 865 </ul>
 866
 867 <li id="date-t"><p>Date and Elo Matches with -t<br />
 868 <p>From a <a href="#-t">-t tag file</a>,
 869 more complex matching of dates and Elo values may be performed by
 870 placing an operator between the tag name and the tag string to be
 871 matched:
 872 <pre>
 873 Date &lt; "1962"
 874 </pre>
 875 <p>would only match games played before 1962. Only the year value
 876 participates in the matching process, as this is done using integer
 877 values rather than strings.
 878 <pre>
 879 WhiteElo &gt;= "2500"
 880 </pre>
 881 <p>only matches games where White is a strong player. Probably of more
 882 general use is another pseudo-tag that I have introduced purely for
 883 this purpose: Elo.
 884 <pre>
 885 Elo &gt;= "2500"
 886 </pre>
 887 <p>matches games in which either player has an Elo tag matching that
 888 relationship.
 889 The operators allowed are &gt;, &gt;=, &lt;, &lt;=, =, and &lt;&gt; (not
 890 equal to).
 891 </ul>
 892
 893 <h2 id="-T">Tag Criteria on the Command Line (-T)</h2>
 894 <p>An alternative to the <a href="#-t">-t flag</a> is the
 895 -T flag, for use where command line arguments are
 896 more convenient - perhaps where pgn-extract is being invoked from another
 897 program.  The tag coverage is not as extensive as with a tag file, and
 898 the syntax is rather cumbersome.  It is used as follows: after the -T
 899 comes a single letter from the limited set [abdeprw] to select string
 900 prefixes of the tag fields of a game.  For instance:
 901 <ul>
 902   <li>-TaAnnotator - Extract games Annotated by Annotator.
 903   <li>-TbPlayer - Extract games where Player has the Black pieces.
 904   <li>-TdDate   - Extract games played on Date.
 905   <li>-TeEco - Extract games with ECO designation Eco.
 906   <li>-ThHashCode - Extract games with HashCode designation HashCode.
 907   <li>-TpPlayer - Extract games where Player has either colour.
 908   <li>-TrResult - Extract games with result Result.
 909   <li>-TwPlayer - Extract games where Player has the White pieces.
 910 </ul>
 911 <p>For example,
 912 <pre>
 913 pgn-extract -TwTal -TbFischer file.pgn
 914 </pre>
 915 <p>would extract games from file.pgn in which Tal had the White pieces and
 916 Fischer the Black.
 917
 918 <p>Criteria of the same tag type are or-ed together, so
 919 <pre>
 920 pgn-extract -Tr1-0 -Tr0-1 file.pgn
 921 </pre>
 922 <p>extracts only decisive games.
 923
 924 <p>Criteria of different tag types are and-ed together so
 925 <pre>
 926 pgn-extract -TwTal -Td1962 -Tr1-0 file.pgn
 927 </pre>
 928 <p>would extract only those games in which Tal played with the White
 929 pieces in 1962 and won.
 930
 931 <p>The ECO classification (see <a href="#-e">the -e flag</a>)
 932 is performed before attempting to match an ECO tag, so:
 933 <pre>
 934 pgn-extract -TeA01 -e file.pgn
 935 </pre>
 936 <p>will perform ECO classification on the input file and extract games
 937 with ECO classification A01 (Nimzo-Larsen attack), for instance.
 938
 939 <ul>
 940 <li id="date-T"><p>Date Matches with -T<br />
 941 <p>A simple form of relational date matching is available.
 942 A date year may be prefixed with either 'b' or 'a' in order
 943 to match games played either before or after the specified date. This
 944 assumes that the date is stored in the game's date tag string in the
 945 normal form: YYYY.MM.DD
 946
 947 <p>So,
 948 <pre>
 949 pgn-extract -Tdb1962 file.pgn
 950 </pre>
 951 <p>will look for games played before 1962. A much fuller capability
 952 is available in tag files with <a href="#-t">the -t flag</a>.
 953 </ul>
 954
 955 <h2 id="-A">Argument Descriptions in a File (-A)</h2>
 956 <p>It can be inconvenient to repeatedly type long argument lists
 957 on the command line. The -A flag makes it possible to list
 958 arguments in a file, rather than on a command line.  Each
 959 argument line within the file must be immediately preceded by
 960 a ':' (colon) character. Consider selecting games by Tal from
 961 a file caro.pgn and writing them to talgames.pgn. Using
 962 command line arguments, this would have the following form:
 963 <pre>
 964 pgn-extract -TpTal -otalgames.pgn caro.pgn
 965 </pre>
 966 <p>We can do the same job placing the argument list in the file args:
 967 <pre>
 968 % Select games by Tal.
 969 :-TpTal
 970 % Where to output the matched games.
 971 :-otalgames.pgn
 972 </pre>
 973 <p>and the same selection made with:
 974 <pre>
 975 pgn-extract -Aargs caro.pgn
 976 </pre>
 977 <p>Note that comments may be included using a '%' character.
 978
 979 <p>Each argument should be listed on its own line, and all the
 980 arguments are available in this way.
 981 The PGN source files may also be listed in the argument file.
 982 They must be listed one per line, with a preceding colon
 983 character. So an alternative for the above would be:
 984 <pre>
 985 % Select games by Tal.
 986 :-TpTal
 987 % Where to output the matched games.
 988 :-otalgames.pgn
 989 % The game files to be read.
 990 :caro.pgn
 991 </pre>
 992 <p>and the command invoked as simply:
 993 <pre>
 994 pgn-extract -Aargs
 995 </pre>
 996
 997 <p>The <a href="#-t">-t</a>, <a href="#-v">-v</a>, <a href="#-x">-x</a>,
 998 <a href="#-z">-z</a>, and <a href="#-R">-R</a>
 999 flags have slightly special treatment in an argument file.
1000 Where the tags, variations, positions, endings and/or roster ordering
1001 are to be read from
1002 files of those names, say, then the format of these arguments in the
1003 argument file might be as you would expect:
1004 <pre>
1005 :-ttags
1006 :-vvariations
1007 :-xpositions
1008 :-zendings
1009 :-Rroster
1010 </pre>
1011 <p>However, within an argument file, the file names are optional and,
1012 where omitted, the data that would have been stored in a file for
1013 these flags is listed on lines immediately following.
1014 For instance, an alternative to:
1015 <pre>
1016 :-TpTal
1017 </pre>
1018 <p>we could say:
1019 <pre>
1020 :-t
1021 Player "Tal"
1022 </pre>
1023 <p>Notice that no colon should be present on the lines following the
1024 flag line.
1025 In the following example, we select games won by Tal as White
1026 reaching a particular position in the Caro Kann:
1027 <pre>
1028 :-t
1029 White "Tal"
1030 Result "1-0"
1031 :-otalwins.pgn
1032 :-x
1033 e4 c6 d4 d5 exd5 cxd5
1034 % Which game files to process.
1035 :caro.pgn
1036 </pre>
1037 <p>The arguments file may, itself, also contain -A arguments. This should
1038 make it possible to build up hierarchies of game selection criteria
1039 if desired. However, beware that there is no check for circularities
1040 in the dependencies.
1041
1042 <h2 id="-n">Outputting Games not Matched (-n)</h2>
1043 <p>The -n flag will cause all valid games not output via other criteria to
1044 be saved in a given file. The purpose of this is to make it easier to
1045 reorganise files in different ways. For instance, if you wish to remove
1046 all of the games played by Tal from one file, you might do:
1047 <pre>
1048 pgn-extract -TpTal -otalgames.pgn -nothers.pgn file.pgn
1049 </pre>
1050 <p>After which, the file others.pgn will contain all of the valid games
1051 from the original file, with the exception of Tal's.
1052
1053 <h2 id="--selectonly">Outputting a single matched game (--selectonly)</h2>
1054 <p>The --selectonly flag takes a single numerical argument N (N &gt; 0) to
1055 request that only the Nth matched game is output. For instance, if only the first
1056 game played against Fischer is required from a file of Tal games, the following
1057 would be used:
1058 <pre>
1059 pgn-extract -TpFischer --selectonly 1 talgames.pgn
1060 </pre>
1061 <p>Note that, once the required game has been output, the program will terminate and
1062 not continue processing the rest of the input files.
1063
1064 <h2 id="notags">Don't Output Any Tags (--notags)</h2>
1065 <p>The tags for a game will not be output.
1066
1067 <h2 id="suppress">Suppress annotations in the output (-C -N -V)</h2>
1068 <p>If comments (-C or --nocomments),
1069 NAGs (-N or --nonags) and/or variations (-V or --novars) are not required in
1070 the output then these can be suppressed by using one or more of these flags.
1071
1072 <h2 id="nomovenumbers">Suppressing move numbers (--nomovenumbers)</h2>
1073 <p>Move numbers can be suppressed from the output with --nomovenumbers.
1074 Used in combination with
1075 <a href="#notags">--notags</a>,
1076 <a href="#noresults">--noresults</a>,
1077 <a href="#suppress">-C, -N, and -V</a>
1078 this can be used to output just the moves of a game:
1079 <pre>
1080 pgn-extract --nomovenumbers --noresults --notags -C -N -V file.pgn
1081 </pre>
1082 <p>If it is desired to have all the moves on a single line, use the <a href=
1083 "#-w">-w</a> flag as well.
1084 <p>See also the <a href="#plylimit">--plylimit</a> flag.
1085
1086 <h2 id="noresults">Suppressing results (--noresults)</h2>
1087 <p>Results at the ends of games and variations
1088 can be suppressed from the output with --noresults.
1089 See <a href="#nomovenumbers">suppressing move numbers</a> for a possible use.
1090
1091 <h2 id="plylimit">Limiting the number of plies (&gt;= 0) output
1092                 (--plylimit)</h2>
1093 <p>The number of moves (actually plies) output for a game can be limited
1094 by using --plylimit. This must be followed by the maximum
1095 number of plies to be output for a game.
1096 For instance,
1097 <pre>
1098 pgn-extract --plylimit 10 --nomovenumbers --notags file.pgn
1099 </pre>
1100 <p>will output games up to a maximum of 10 plies (including variation lines),
1101 without game tags and no line numbers.
1102
1103 <p>Note: If the game has not ended before the ply limit is reached then *
1104 will be used as the terminating result to indicate an incomplete game (see
1105 <a href="#noresults">--noresults</a> for how to suppress this.)
1106
1107 <h2 id="-b">Setting bounds on the number of moves in a game (-b)</h2>
1108 <p>The -b flag allows you to select games which have a number of moves
1109 within the bounds you set. You can set a lower bound on the number of moves
1110 by using -bl ('l' = lower bound), or an upper limit
1111 by using -bu ('u' = upper bound). Both are followed by
1112 the number of moves so
1113 <pre>
1114 pgn-extract -bu20 file.pgn
1115 </pre>
1116 <p>will find brevities of 20 moves or less, whilst
1117 <pre>
1118 pgn-extract -bl60 file.pgn
1119 </pre>
1120 <p>will find games of 60 moves or move. Bounds may be combined so
1121 <pre>
1122 pgn-extract -bl30 -bu40 file.pgn
1123 </pre>
1124 <p>will find games in the range [30..40] moves. If neither 'l' nor 'u'
1125 is used, but just a number following the -b, this means that the number
1126 of moves must exactly match that number. Alternatively, 'e' can be
1127 used to stand for 'equal to'. The following are equivalent and find
1128 all games of exactly 35 moves.
1129 <pre>
1130 pgn-extract -b35 file.pgn
1131 pgn-extract -be35 file.pgn
1132 </pre>
1133
1134 <h2 id="-M">Matching only games that end in checkmate (-M or --checkmate)</h2>
1135 <p>The -M flag requests that only games that end in checkmate are matched:
1136 <pre>
1137 pgn-extract -M file.pgn
1138 </pre>
1139
1140 <h2 id="stalemate">Matching only games that end in stalemate (--stalemate)</h2>
1141 <p>The --stalemate flag requests that only games that end in stalemate are matched:
1142 <pre>
1143 pgn-extract --stalemate file.pgn
1144 </pre>
1145
1146 <h2 id="underpromotion">Matching only games that contain an underpromotion
1147 (--underpromotion)</h2>
1148 <p>The --underpromotion flag requests that only games that contain an
1149 underpromotion are matched:
1150 <pre>
1151 pgn-extract --underpromotion file.pgn
1152 </pre>
1153
1154 <h2 id="-e">ECO Classification (-e)</h2>
1155 <p>A <a href="ftp://ftp.cs.kent.ac.uk/pub/djb/pgn-extract/eco.pgn">PGN
1156 file of ECO classifications</a> is distributed with this version. I
1157 believe that this was put together by Ewart Shaw, Franz Hemmer and
1158 others, to whom appropriate thanks is due.  The -e flag requests
1159 pgn-extract to add/replace ECO classifications in the games it outputs.
1160 This is done by firstly reading a file of ECO lines in PGN format
1161 (eco.pgn in the current directory, by default) and building a table of
1162 resulting positions. As the games are then read they are looked up in
1163 the table to find a classification. The deepest match is found.
1164 A match is allowed within six half moves of the length of the ECO line.
1165 The supplied file has ECO, Opening, and Variation tag strings for many
1166 lines. If present, pgn-extract will add/replace these as well as
1167 SubVariation tags if available.
1168
1169 <p>An alternative file to the default eco.pgn may be supplied in two
1170 ways:
1171 <ul>
1172     <li><p>Appending a file name to the -e flag
1173 <pre>
1174 -emy_eco_codes.pgn
1175 </pre>
1176 <p>Note that there must not be a space between the -e and
1177 the name of the file, otherwise the default ECO file will be assumed.
1178     <li><p>By setting the environment variable ECO_FILE to the full path name
1179 of the file.
1180 Under Windows this can be done with
1181 <pre>
1182 set ECO_FILE=full-eco-file-path
1183 </pre>
1184 <p>at the Cmd window prompt, or more permanently via the
1185 System/Environment/Advanced area.
1186 Under UNIX csh this can be done with
1187 <pre>
1188 setenv ECO_FILE full-eco-file-path
1189 </pre>
1190 <p>in the .cshrc, for instance.
1191 </ul>
1192
1193 <p>Having the ECO data read as plain text on program startup has the
1194 obvious disadvantage that there is a high initial time overhead. On the
1195 other hand, it has the advantage that users may add their own
1196 classifications to the file very easily.  It is fairly demanding of
1197 memory, so you advised not to combine this with duplicate detection
1198 (<a href="#-U">-U</a>,
1199 <a href="#duplicates">-D and -d</a>), which can also consume a lot
1200 of memory with big databases.
1201
1202 <p>Because an ECO tag match with either the <a href="#-t">-t flag</a> or
1203 the <a href="#-T">-T flag</a> is delayed until after ECO
1204 classification, this makes it relatively easy to select games with
1205 particular ECO codes even if they weren't present in the source form.
1206
1207 <p>Usage of -e with the Seven Tag Roster flag (<a href="#-7">-7</a>)
1208 results in the ECO
1209 tags (ECO, Opening, Variation, SubVariation) being included in the
1210 output games.
1211
1212 <h2 id="separate-output">Separate Output Files (-#, -E)</h2>
1213 <p>The -# and -E flags permit the output to be split into multiple files.
1214 However, be warned that where the input involves a lot of games,
1215 these flags might result in
1216 the creation of a large number of output files.
1217
1218 <p>The -# flag takes an unsigned integer argument specifying the maximum number
1219 of games to output to a single file. Successive output files are numbered 1.pgn,
1220 2.pgn, etc. Any existing contents of these files are always overwritten on each
1221 run of pgn-extract.
1222 <pre>
1223 pgn-extract -#250 file.pgn
1224 </pre>
1225 <p>will check and split file.pgn into separate files of, at most, 250 games each.
1226 <pre>
1227 pgn-extract -#1 file.pgn
1228 </pre>
1229 <p>will split file.pgn into separate files containing only a single game each.
1230
1231 <p>The -E flag normally takes a numeric argument of value 1, 2, or 3. This is
1232 used to indicate the level of subdivision required based upon the ECO tag
1233 found in a game.
1234 <pre>
1235 pgn-extract -E3 file.pgn
1236 </pre>
1237 <p>will fully subdivide file.pgn into separate files based on the full ECO
1238 code of each game, with names such as B03.pgn, A01.pgn, D45.pgn, etc.
1239 If a game does not contain an ECO tag, or the tag appears to be malformed,
1240 it will be written to a file called, noeco.pgn. All of these files are
1241 written to in append mode, so that existing contents are not lost. However,
1242 beware of using an input file whose name is the same as one that will be
1243 written to by this operation. This could lead to infinite operation.
1244
1245 <p>Level 1 classification uses just the initial letter of the ECO
1246 classification to append to files A.pgn, B.pgn, etc. Level 2 uses the initial
1247 letter and first digit, producing A0.pgn, B3.pgn, etc.
1248
1249 <p>In fact, values greater than 3 may be used to produce separation of even
1250 finer granularity if more than two digits have been used in the classification
1251 of a game.
1252
1253 <h2 id="-S">Soundex Matching (-S)</h2>
1254 <p>There is a simple soundex algorithm available that attempts soundex
1255 matches on White, Black, Site, Event, and Annotator tags if the -S flag
1256 is used in combination with either the <a href="#-t">-t flag</a> or
1257 the <a href="#-T">-T flag</a>.  The -S flag should
1258 precede all -t and -T arguments.  It should be noted that the soundex
1259 matching does produce false matches.
1260
1261 <h2 id="-w">Output Line Length (-w or --linelength)</h2>
1262 <p>The -w flag allows an approximate line length to be set for output.
1263 Normally games are output with lines up to a maximum of 75 characters.
1264 Use the -w flag if you want longer output lines.
1265 For instance, you might want all the moves of a game to appear on a single
1266 line. You would get this effect by specifying -w1000 (say):
1267 <pre>
1268 pgn-extract -w1000 file.pgn
1269 </pre>
1270 <p>If some games are more than 1000 characters long then just increase the value.
1271
1272 <h2 id="-W">Output Format and Language (-W)</h2>
1273 <p>By default, pgn-extract rewrites the game score into English Standard Algebraic
1274 Notation (SAN) because it is reasonably flexible about the input form
1275 that it will accept.  To prevent it from rewriting the original form of
1276 the moves it reads, use the -W flag.
1277 <ul>
1278   <li>By itself, -W outputs the moves using the input text.
1279   <li>Using -Whalg writes the moves in hyphenated long algebraic (e.g., e2-e4).
1280   <li>Using -Wlalg writes the moves in long algebraic form (e.g., e2e4).
1281   <li>Using -Welalg writes the moves in enhanced long algebraic form (e.g.,
1282   Ne2e4, e5d6ep). The purpose of enhanced long algebraic form is to reduce the
1283   amount of chess-specific knowledge that a post-procesing program might
1284   need in order to interpret a chess game.
1285   For instance, in order to provide a visualisation.
1286   <li>Using -Wuci causes the moves of the game to be output in
1287   a format that should close to being suitable for input to a
1288   <a href="http://wbec-ridderkerk.nl/html/UCIProtocol.html">UCI-compatible</a> engine.
1289   The output format is the same as with -Wlalg but all comments, NAGs,
1290   variations, move numbers and checks removed.
1291   In addition the whole game is output on a single line.
1292 </ul>
1293
1294 <p>Output using non-English piece letters is possible using a variation
1295 of the -Wsan flag. This flag may have a six-letter suffix indicating
1296 the letters to be used in representing pawn, knight, bishop, rook,
1297 queen and king in game scores and diagrams. So:
1298 <pre>
1299 pgn-extract -WsanPNBRQK ...
1300 </pre>
1301 <p>would output in the (default) English notation, and
1302 <pre>
1303 pgn-extract -WsanBSLTDK ...
1304 </pre>
1305 <p>would output in German. Note that the letter for a pawn is required because
1306 board positions are sometimes output when an error is detected in
1307 a game score.
1308
1309 <p>-Wepd outputs in EPD (Extended Position Description).
1310 A game is output as a sequence of EPD descriptions of
1311 the position at the start of the game, and following each move.
1312 Each EPD line contains the FEN board description, the active colour,
1313 castling availability and en passant target square. A c0 comment contains
1314 a synopsis of the player, event, site and date tags from the game's header.
1315
1316 <p>-Wuci outputs in long-algebraic notation (-Wlalg) but also strips the
1317 game of everything apart from its moves, tags and result.
1318 It provides the equivalent of using the following multiple arguments:
1319 <pre>
1320 -Wlalg -C -N -V -w5000 --nomovenumbers --nochecks
1321 </pre>
1322 Use the --noresults and --notags options if tags and results are also
1323 to be removed.
1324
1325 <p>-Wcm is an obsolete legacy flag and
1326 outputs the moves in what I believe to be (or used to be) ChessMaster format.
1327
1328 <h2 id="-F">Forsyth-Edwards Notation (FEN) Descriptions (-F)</h2>
1329 <p>The -F flag provides a convenience method for generating
1330 a suitable FEN description of an arbitrary position.
1331 The -F flag causes pgn-extract to output a FEN description of the final
1332 position reached in a game, within the text of a comment.
1333 For instance, suppose you were interested in finding games that
1334 reach the position after the following moves.
1335 <pre>
1336 d4 Nf6 c4 e6 Nf3 b6 Nc3 Bb7 e3 Bb4 Bd3 O-O O-O Bxc3 bxc3 c5 *
1337 </pre>
1338 <p>Storing these moves in the file fen.pgn and running
1339 <pre>
1340 pgn-extract -F fen.pgn
1341 </pre>
1342 <p>would generate the score:
1343 <pre>
1344 [Event "?"]
1345 [Site "?"]
1346 [Date "????.??.??"]
1347 [Round "?"]
1348 [White "?"]
1349 [Black "?"]
1350 [Result "*"]
1351
1352 1. d4 Nf6 2. c4 e6 3. Nf3 b6 4. Nc3 Bb7 5. e3 Bb4 6. Bd3 O-O 7. O-O Bxc3 8.
1353 bxc3 c5
1354 { "rn1q1rk1/pb1p1ppp/1p2pn2/2p5/2PP4/2PBPN2/P4PPP/R1BQ1RK1/ w - c6 0 9" } *
1355 </pre>
1356 <p>The <a href="#-t">-t flag</a>
1357 makes it possible to use Forsyth-Edwards Notation (FEN) in the
1358 description of a position
1359 to be matched. For instance, the FEN string above
1360 could be cut and pasted to <a href="#-A">an argument file</a> and used with
1361 the <a href="#-t">-t flag</a> to supply matches:
1362 <pre>
1363 :-t
1364 FEN "rn1q1rk1/pb1p1ppp/1p2pn2/2p5/2PP4/2PBPN2/P4PPP/R1BQ1RK1/ w - c6 0 9"
1365 </pre>
1366 <p>See <a href="#fencomments">--fencomments</a> for the option to add
1367 a FEN comment after every move, including the final one.
1368
1369 <h2 id="-z">Material Matches (-z)</h2>
1370 <p>The -z flag takes a filename of material balances for which you wish to
1371 search in games.  The basic structure of the file is one or
1372 more lines of the form
1373 <pre>
1374 pieces1 pieces2
1375 </pre>
1376 <p>Pieces1 and pieces2 are lists of English piece letters for the material
1377 for the two sides that you wish to look for in a game.
1378 For instance:
1379 <pre>
1380 rp nb
1381 </pre>
1382 <p>looks for an game in which a lone Rook and Pawn for one side are
1383 competing against a lone Knight and Bishop for the other.
1384
1385 <p>Text may be added after the piece lists as a form of comment.
1386
1387 <p>A comment line may be placed in a material balance file by using a '%'
1388 as the first character of the line.
1389
1390 <p>The <a href="#markmatches">--markmatches</a> flag may
1391 be used to add a comment at the point that the match is found.
1392 <p>The case of the
1393 letters is immaterial, there is no need to include Kings in the
1394 description, and the order of the pieces does not matter.  Apart from
1395 Kings, if a piece letter is not listed for a side then that piece
1396 is not present within that side's material.
1397 A match will be tested for from both White and Black's point of view, so the
1398 example above matches the same games as:
1399 <pre>
1400 nb rp
1401 </pre>
1402 <p>Some notation may be added after any piece letter, typically to
1403 indicate something about the number of occurrences of that piece on one
1404 side.
1405
1406 <p>The following are valid for each piece:
1407 <ul>
1408     <li>* (zero or more of that piece).
1409     <li>+ (one or more of that piece).
1410     <li>d (exactly d occurrences of that piece, where d is a digit).
1411     <li>d+ (d or more occurrences of that piece).
1412     <li>d- (d or fewer occurrences of that piece).
1413 </ul>
1414 <p>So:
1415 <pre>
1416 QR2B2N2P8 QR2B2N2P8
1417 </pre>
1418 <p>is the starting material position, and QR+B*N*P7- represents material
1419 in which we require at least one pawn to be missing from one side and
1420 they should have a Queen and Rook, but we don't care about the minor
1421 pieces.
1422
1423 <p>In addition, some extra notation is available to specify material
1424 relative to the opponent's.
1425 These are placed after the piece letter to which they refer.
1426 <ul>
1427     <li>= (the number of these pieces must be the same as the opponent's).
1428     <li># (the number of these pieces must be different the opponent's).
1429     <li>&gt; (the number of these pieces more than the opponent has).
1430     <li>&lt; (the number of these pieces less than the opponent has).
1431 </ul>
1432 <p>So,
1433 <pre>
1434 R+P+ R=P#
1435 </pre>
1436 <p>looks for Rook and Pawn games with an equal number of Rooks but
1437 unbalanced pawns.
1438
1439 <p>In addition &gt; and &lt; may be preceded by a digit:
1440 <ul>
1441     <li>d&gt;
1442     (the number of these pieces must be at least d more than the opponent's).
1443     <li>d&lt;
1444     (the number of these pieces must be at least d less than the opponent's).
1445 </ul>
1446 <p>Two more notations, &gt;=, &lt;= may be preceded by an optional digit
1447 (the default is 1).
1448 The meaning of this may not be intuitively obvious and, to an extent, they
1449 represent a notational compromise.
1450 <ul>
1451     <li>d&gt;=
1452     (the number of these pieces must be exactly d more than the opponent's).
1453     <li>d&lt;=
1454     (the number of these pieces must be exactly d less than the opponent's).
1455 </ul>
1456 <p>In this example, both sides have a pair or Rooks but one has exactly one
1457 pawn more than the other:
1458 <pre>
1459 r2p* r=p1&gt;=
1460 </pre>
1461 <p>Here is an example where one side has sacrificed a Rook and Pawn for
1462 Knight and Bishop and we don't care whether Queens are on or off the
1463 board, so long as they are balanced:
1464 <pre>
1465 q*r+n*b*p+ q=r&lt;n&gt;b&gt;p1&lt;
1466 </pre>
1467 <p>This example represents some of the imprecision that can occur with
1468 matches.  The meaning of 'r&lt;' is such that this could match positions
1469 in which one side as 2 Rooks and the other none. This can be corrected
1470 with:
1471 <pre>
1472 q*r+n*b*p+ q=r1&lt;=n&gt;b&gt;p1&lt;
1473 </pre>
1474 <p>enforcing strictly one Rook less. We ought also to correct the same
1475 problem with the minor pieces:
1476 <pre>
1477 q*r+n*b*p+ q=r1&lt;=n1&gt;=b1&gt;=p1&lt;
1478 </pre>
1479 <p>In practice, we probably want to allow general matching of minor pieces
1480 so the letter 'L' may be used to stand for a minor piece (Bishop or
1481 Knight). This example represents a similar sacrifice of Rook and Pawn for
1482 two minor pieces.
1483 <pre>
1484 q*r+l*p+ q=r1&lt;=l2&gt;=p1&lt;
1485 </pre>
1486 <p>I would advise against mixing the minor piece letter with Knight and
1487 Bishop letters in the piece set for a single side, however, as I am not
1488 convinced that it will produce exact results.
1489
1490 <ul>
1491 <li><p>Position Stability with -z<br />
1492 <p>The piece sets may be preceded by an optional number indicating the
1493 required stability of the position. Normally, if you are looking for a
1494 position with a particular set of material characteristics then you
1495 probably want that position to last for a reasonable number of moves in
1496 order to study its characteristics. The number before the piece sets is
1497 how many half-moves you wish that material balance to last. By default,
1498 this has a value of 2 so that fleeting positions in the middle of pairs
1499 of exchanges do not produce unwanted matches.
1500 This example looks for double-Rook and pawn games that last at least
1501 10 half-moves:
1502 <pre>
1503 10 R2P+ R=P*
1504 </pre>
1505 </ul>
1506
1507 <h2 id="-7">The Seven Tag Roster (-7 or --seven)</h2>
1508 <p>This flag discards tag pairs that are not part of the Seven Tag
1509 Roster:
1510 <pre>
1511 Event, Site, Date, Round, White, Black and Result.
1512 </pre>
1513 <p>However, if the original game included a FEN tag, this is
1514 included in the output, as the moves will make no sense
1515 otherwise. In addition, if <a href="#-e">the -e flag</a> has been used for ECO
1516 classification, any ECO, Opening, Variation and SubVariation tags
1517 are also output.
1518
1519 <h2 id="-R">User-defined Tag Roster Ordering (-R)</h2>
1520 <p>The -R flag makes it possible for to define the order in which
1521 tags for a game are listed in the output.
1522 The flag should be immediately followed by the name of a file
1523 that contains a list of tag names, one per line, for instance:
1524 <pre>
1525 pgn-extract -Rroster file.pgn
1526 </pre>
1527 <p>where roster might contain:
1528 <pre>
1529 % Output the tags of the seven tag roster alphabetically.
1530 Black
1531 Date
1532 Event
1533 Result
1534 Round
1535 Site
1536 White
1537 </pre>
1538 <p>The '%' character may be used to include comments in the file.
1539 Tags not listed in such a file will appear after the required
1540 tags have been output.
1541
1542 <h2 id="evaluation">Include a position evaluation after each move (--evaluation)</h2>
1543 <p>The --evaluation argument causes a comment to be appended to every move,
1544 which contains an evaluation of the position immediately following that
1545 move.
1546 The default evaluation is a simplified version of
1547 <a href="http://en.wikipedia.org/wiki/Claude_Shannon">Shannon's board
1548 evaluation</a>. In this case, the evaluation is the difference between the
1549 value of White's position and Black's, where the value of a position is
1550 a weighted sum of the pieces plus a multiplier (0.1) applied to
1551 the number of available moves for that player.
1552
1553 <p>I see this primarily as being a hook for people who wish to embed their
1554 own evaluations in the output.
1555 See the <code>evaluate</code> function in <code>apply.c</code> if you wish to
1556 write your own.
1557
1558 <h2 id="fencomments">Include a comment with a FEN string for
1559 the position after each move (--fencomments)</h2>
1560 <p>The --fencomments argument causes a comment to be appended to every move,
1561 which contains a FEN string for the position immediately following that
1562 move. See <a href="#-F">-F</a> for adding a comment after just the
1563 final move.
1564
1565 <h2 id="markmatches">Add a game comment on positional and material matches
1566 (--markmatches)</h2>
1567 <p>Add a game comment with the text immediately following --markmatches
1568 after the move which causes a positional or material match.
1569 For instance:
1570 <pre>
1571 pgn-extract -xvars --markmatches MATCH file.pgn
1572 </pre>
1573 <p>would add the comment <em>{ MATCH }</em> after every move that
1574 caused a match from the positional matches specified in the <em>vars</em> file.
1575 <p>See <a href="#-x">-x</a> for positional matches with moves,
1576 <a href="#fen-t">-t</a> for positional matches with FEN patterns,
1577 and <a href="#-z">-z</a> for material matches.
1578
1579 <h2 id="addhashcode">Add a Tag containing a hashcode for the game (--addhashcode)</h2>
1580 <p>Add the tag HashCode to the tags. This contains a hashcode value
1581 generated from the moves of the game. Identical move sequences will
1582 produce the same hash code.
1583
1584 <h2 id="totalplycount">Add a Tag containing the total ply count (--totalplycount)</h2>
1585 <p>Add the tag TotalPlyCount to the tags. This contains a count of
1586 the number of ply present in the game being output.
1587 Unless <a href="#suppress">variations have been suppressed</a> this will include
1588 all moves in variations as well as the main line.
1589
1590 <h2 id="mailing">Mailing List</h2>
1591 <p>I don't run a proper mailing list but if you find the program useful
1592 and would like or to offer suggestions that you think
1593 others might be interested in, then drop me a line at
1594 <a href="mailto:d.j.barnes@kent.ac.uk">d.j.barnes@kent.ac.uk</a>
1595
1596 <h2 id="limitations">Limitations</h2>
1597 <p>The moves, variations, and commentary of each game are held internally
1598 and reformatted when a game is extracted, rather than reproducing the
1599 original text of the game source.
1600
1601 <p>Lower-case 'b' as the first character of a move is taken to be a move
1602 of the b-pawn if one to match the move can be found. Otherwise, Bishop
1603 moves are tried as an alternative.  There is no back-up on failure if
1604 picking a valid pawn move was the wrong choice.
1605
1606 <p>Lower-case 'b' as the first character of a Bishop move is not
1607 acceptable in the variations files.
1608
1609 <p>Duplicate detection is not guaranteed to be exact.
1610 The -Z flag has slightly more potential to avoid false duplicates
1611 as it compares separate values for the end position and move sequence,
1612 whereas these are XORed to save space when -Z is not used.
1613 However, this will only make a difference and avoid false
1614 matches if
1615 two different games at the same hashtable index
1616 also produce identical XORed values.
1617
1618 <p>The results of the -x, -v, and -t/-T search criteria are AND-ed
1619 together.  There might be occasions when you wanted to search for games
1620 that matched either positional variations or textual variations at the
1621 same time, for instance.  This requires multiple runs of pgn-extract.
1622
1623 <p>The -Wsan variation that allows selection of the output language
1624 is tied to single-character piece descriptions. This does
1625 not support Russian usage, for instance, in which the King
1626 is described as a character pair.
1627
1628 <h2 id="files">The Files</h2>
1629 <p>The sources include a Makefile for the GNU make program, gmake.
1630 I also use this with the <a href="http://www.mingw.org/">Minimalist
1631 GNU for Windows</a> compiler
1632 to produce a Windows command-line executable (see <a
1633 href="#portability">Portability</a>).
1634
1635 <p>The distribution comes with the following files.
1636 <table>
1637     <tr>
1638     <td>COPYING</td><td>GNU General Public License</td>
1639     </tr>
1640     <tr>
1641     <td>Makefile</td><td>A build file suitable for use with the GNU make utility.
1642     <br />Windows users might like to use the
1643     <a href="<a href="http://www.mingw.org/">mingw - Minimalist GNU for Windows</a> version.</td>
1644     </tr>
1645     <tr>
1646     <td>apply.[ch]</td><td>functions concerned with applying moves to a board.</td>
1647     </tr>
1648     <tr>
1649     <td>argsfile.[ch]</td><td>functions concerned with command line argument processing.</td>
1650     </tr>
1651     <tr>
1652     <td>bool.h</td><td>Boolean type definition.</td>
1653     </tr>
1654     <tr>
1655     <td>decode.[ch]</td><td>functions for decoding the text of a move.</td>
1656     </tr>
1657     <tr>
1658     <td>defs.h</td><td>definitions relating to boards.</td>
1659     </tr>
1660     <tr>
1661     <td>eco.[ch]</td><td>functions for looking up ECO classifications.</td>
1662     </tr>
1663     <tr>
1664     <td>eco.pgn</td><td>PGN file of ECO classifications.</td>
1665     </tr>
1666     <tr>
1667     <td>end.[ch]</td><td>functions for looking for matching endgames.</td>
1668     </tr>
1669     <tr>
1670     <td>fenmatcher.[ch]</td><td>pattern matching for the FENPattern
1671     pseudo tag.</td>
1672     </tr>
1673     <tr>
1674     <td>grammar.[ch]</td><td>the parser.</td>
1675     </tr>
1676     <tr>
1677     <td>hashing.[ch]</td><td>duplicate detection hash tables.</td>
1678     </tr>
1679     <tr>
1680     <td>help.html</td><td>This file.</td>
1681     </tr>
1682     <tr>
1683     <td>lex.[ch]</td><td>the lexical analyser.</td>
1684     </tr>
1685     <tr>
1686     <td>lines.[ch]</td><td>functions for reading lines.</td>
1687     </tr>
1688     <tr>
1689     <td>lists.[ch]</td><td>functions for holding the extraction criteria.</td>
1690     </tr>
1691     <tr>
1692     <td>map.[ch]</td><td>functions for implementing move semantics.</td>
1693     </tr>
1694     <tr>
1695     <td>moves.[ch]</td><td>functions for collecting moves and variations.</td>
1696     </tr>
1697     <tr>
1698     <td>mymalloc.[ch]</td><td>functions for memory allocation.</td>
1699     </tr>
1700     <tr>
1701     <td>output.[ch]</td><td>functions concerned with outputting the games.</td>
1702     </tr>
1703     <tr>
1704     <td>taglist.h</td><td>constants for tag and pseudo-tag names</td>
1705     </tr>
1706     <tr>
1707     <td>tokens.h</td><td>type definition for lexical tokens.</td>
1708     </tr>
1709     <tr>
1710     <td>typedef.h</td><td>type definitions.</td>
1711     </tr>
1712 </table>
1713
1714 <h2 id="portability">Portability</h2>
1715 <p>pgn-extract is regularly used under Windows/DOS
1716 (using <a href="http://www.mingw.org/">Minimalist
1717 GNU for Windows</a>),
1718 and various versions of Linux and Mac OSX.
1719
1720 <h2 id="acknowledgements">Acknowledgements</h2>
1721 <p>I would like to thank all those who used the program and made
1722 suggestions for things to add.  In particular, thanks to Michael Kerry
1723 whose help led to better determination of game boundaries in earlier
1724 versions, and V. Armando Sole whose own filter
1725 program was the inspiration for adding textual variation permutations.
1726 John Brogan suggested adding the ! notation to the variation file and
1727 provided the spur for duplicate detection.
1728 He also supplied the original code for soundex matching (-S).
1729 <p>Jaroslav Poriz, Ron Leamon, Ed Leonard, Charles
1730 Frohman, and Robert Wilhelm helped with testing at various times.
1731 Bernhard Maerz was instrumental in encouraging the inclusion of ECO
1732 classification and material balance matches.
1733 He and Peter Otterstaetter
1734 suggested the relational operators in tag files, with Peter also
1735 providing the spur to make duplicate detection work with bigger game files
1736 (-Z) and doing some very useful testing for me.
1737 <p>Kayvan Sylvan requested
1738 long algebraic output and identified an error in ECO classification.
1739 Cameron Hayne suggested matching on the number of moves in a game.
1740 Owen D. Lyne suggested extension of the -E flag,
1741 and both tested and provided diagnostic data to help refine the
1742 ECO classification aspects of the program.
1743 Karl-Martin Skontorp provided the incentive and testing help that
1744 enabled me to add the -Wepd option.
1745 <p>FEN pattern matching is based on pattern matching code by Rob Pike.
1746 Taken from:
1747 http://www.cs.princeton.edu/courses/archive/spr09/cos333/beautiful.html
1748 and ideas from Kernighan and Plauger's "Software Tools".
1749 <p>Finally, thanks, of course, to Steven Edwards
1750 for his work on developing the PGN standard.
1751
1752 <h2 id="license">License</h2>
1753 <p>pgn-extract: a Portable Game Notation (PGN) extractor.<br>
1754 This program is free software; you can redistribute it and/or modify
1755 it under the terms of the GNU General Public License as published by
1756 the Free Software Foundation; either version 1, or (at your option)
1757 any later version.
1758
1759 <p>This program is distributed in the hope that it will be useful,
1760 but WITHOUT ANY WARRANTY; without even the implied warranty of
1761 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
1762 GNU General Public License for more details.
1763
1764 <p>You should have received a copy of the GNU General Public License
1765 along with this program; if not, write to the Free Software
1766 Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
1767
1768 <p>David Barnes may be contacted as
1769 <a href="mailto:d.j.barnes@kent.ac.uk">d.j.barnes@kent.ac.uk</a>, <a href="http://twitter.com/kentdjb/">@kentdjb</a> on Twitter,
1770 or via
1771 <a href="http://www.cs.kent.ac.uk/people/staff/djb/">http://www.cs.kent.ac.uk/people/staff/djb/</a>
1772
1773 <h2 id="history">Change History</h2>
1774 <ul>
1775     <li>28th October 2014. Added --selectonly after a suggestion by Francis Steen.
1776     <li>2nd September 2014. Corrected an error in the generation of hashcodes
1777     when a promotion is made.
1778     <li>31st May 2014. Added --addhashcode.
1779     <li>25th May 2014. Added --totalplycount for Erich K&ouml;rber.
1780     <li>5th March 2014. Added --keepbroken to allow broken games to be output.
1781     Added at the request of Mark Crowther primarily to deal with the problem of live
1782     recording where the kings are moved to the centre of the board at the end of
1783     a game and erroneously included in the score.
1784
1785     <li>6th September 2013. Corrected failure to 'or' together multiple
1786     dates with -T and -t.
1787
1788     <li>16th May 2013. Corrected an error in the whole-move number in
1789     FEN output, thanks to Vincent Fleuranceau.
1790
1791     <li>14th May 2013. Null move notation (--) in variations recognised.
1792
1793     <li>16th April 2013. Added --fuzzydepth. This is due to Owen D. Lyne who
1794     requested this functionality years ago - sorry for taking so long, Owen!
1795
1796     <li>11th April 2013. Added -Wuci.
1797
1798     <li>29th March 2013. Added --version.
1799
1800     <li>26th March 2013. Fixed crash when a string to be output is longer than the output line length.
1801
1802     <li>12th March 2013. Added long-form versions of -a, -c, -d and -o:
1803     --append, --checkfile, --duplicates and --output.
1804
1805     <li>9th February 2013. Added pattern matching based on
1806     FEN descriptions and --markmatches for JS.
1807
1808     <li>23rd December 2012. Added --fencomments for Tyler Eaves.
1809
1810     <li>2nd December 2012. Allowed 0 for --plylimit.
1811
1812     <li>22nd September 2008. Added --stalemate for Wieland Belka.
1813
1814     <li>15th September 2008. Added --nochecks and fixed -A so that it
1815     handles long-form arguments properly.
1816
1817     <li>22nd December 2007. Added --notags, --plylimit, --nomovenumbers and
1818     <a href="#noresults">--noresults</a>
1819     after a suggestion by Wieland Belka to be able to create opening books.
1820
1821     <br>Added --evaluation for Folkert van Heusden.
1822
1823     <br>Added --stalemate for Norm Pollock.
1824
1825     <br>Added calculation of the half-move clock to FEN strings.
1826
1827     <br>Most of the arguments taking filenames can now be separated from
1828     the filename with a space.
1829
1830     <br>Gradually adding long-form alternatives for arguments, e.g.
1831     --seven, --notags, etc.
1832
1833     <li>24th April 2007. Fixed a bug with mate annotation. Added the -M flag for
1834     checkmate matches, which is due to Richard Jones.
1835
1836     <li>19th October 2005. Added language-specific letters to -Welalg
1837     following a suggestion from Folkert van Heusden.
1838
1839     <li>1st May 2004: Fixed an error with ECO classification that
1840     was causing the file list to be out of sync.
1841
1842     <li>29th April 2004: Buffered game text before outputting it,
1843     so that trailing spaces on lines (which violate the PGN spec)
1844     can be deleted.<br>
1845     Games with zero moves are now acceptable.
1846     <li>26th April 2004: Slight modification to one of the hashing
1847
1848     values made in order to try to avoid clashes in ECO matches.
1849     ECO matches now have a discretion of up to 6 half moves.
1850
1851     <li>13th February 2002: Added -Welalg as an output format following
1852     a suggestion from Rafal Furdzik.
1853
1854     <li>27th March 2001
1855       <ul>
1856         <li>Added output of EPD via -Wepd.
1857         <li>Fixed a long standing error in FEN castling rights. These were
1858             not being withdrawn if a Rook was captured on its home square.
1859             Pointed out by Karl-Martin Skontorp, who also provided the
1860             incentive to add -Wepd.
1861       </ul>
1862
1863     <li>26th April 2000
1864     Added the -R flag for tag ordering.
1865
1866     <li>22nd April 2000
1867     Completed implementation of -A to work with all flags.
1868
1869     <li>21st April 2000
1870       <ul>
1871         <li>Added the -F flag.
1872         <li>Added support for reading Russian source files.
1873       </ul>
1874
1875     <li>11th April 2000
1876       <ul>
1877         <li>Added the -A flag.
1878         <li>Extended usage of -Wsan to support output in different languages.
1879         <li>Usage of -e with -7 retains an ECO tag in matched games.
1880         <li>FEN tags with the -t flag are used as positional matches
1881         (equivalent to -x matches).
1882         <li>Non-standard tags are now retained in game output.
1883       </ul>
1884
1885     <li>12th January 2000
1886     C compiler with Red Hat Linux 6 was no longer happy with
1887     static initialisations involving stdin, stdout and stderr.
1888     Changes made to lex.c and main.c to work around this.
1889     Pointed out by Mladen Bestvina.
1890
1891     <li>18th October 1999
1892     Numbers greater than 3 allowed with -E, at the request of Owen Lyne.
1893
1894     <li>15th December 1997
1895     Treat \r as WHITESPACE (for DOS files).
1896
1897     <li>8th June 1997
1898     Added -b flag to set bounds on the number of moves in a game to
1899     be matched.
1900
1901     <li>2nd May 1997
1902     Corrected small error when strings were not terminated properly.
1903     In tags, this resulted in the corrected tag ending in ]"] instead
1904     of "].
1905
1906     <li>17th February 1997
1907     Added a little more error recovery.
1908
1909     <li>15th November 1996
1910     Added -Z.
1911
1912     <li>23rd Sep 1996
1913     It is no longer necessary to omit move numbers from the variations
1914     files (-v and -x). This makes it easier to cut and paste games
1915     of interest into these files.
1916
1917     <li>28th Jun 1996
1918     It is no longer necessary to terminate the tag file (-t).
1919     Relational operators added in the tag file (-t).
1920     Added -E flag.
1921
1922     <li>7th May 1996
1923     Corrected failure to make ECO classification when combined with -x.
1924     Added lalg and halg as long algebraic output formats.
1925
1926     <li>9th Oct 1995
1927     Add -#
1928
1929     <li>25th Sep 1995:
1930     Default to reading stdin if no file arguments are provided.
1931
1932     <li>24th Jul 1995:
1933     Added setup from FEN tags.
1934
1935     <li>18th Jul 1995:
1936       <ul>
1937         <li>Added material balance matches with -z.
1938         <li>Added 'L' as a minor piece letter in ending files.
1939       </ul>
1940
1941     <li>14th Jul 1995:
1942     Made the order of arguments immaterial.
1943
1944     <li>5th Jul 1995:
1945       <ul>
1946         <li>Added ECO classification with -e.
1947         <li>Fixed false partial substring matches with -v, e.g. textual
1948         variation move Nc6 is now no longer matched by game move c6.
1949       </ul>
1950
1951     <li>22nd Mar 1995:
1952     Made permutation matching with -v the default and added -P
1953     to suppress it.
1954
1955     <li>Jan 1995: Added -n and -L.
1956
1957     <li>17th Nov 1994: Liberated the program from using YACC and Lex.
1958
1959     <li>13th Oct 1994: Released test version with ChessMaster output.
1960
1961     <li>20th Sep 1994: Added move rewriting and -W flag.
1962
1963     <li>7th Sep 1994: Added -D flag.
1964
1965     <li>6th Sep 1994: Added -C and -V flags and soundex matching.
1966
1967     <li>5th Sep 1994:
1968       <ul>
1969         <li>Integrated the positional variation code from a separately
1970     developed program.
1971         <li>Added -N flag.
1972         <li>Added ! to the textual variation syntax.
1973         <li>Removed the writing to extract.pgn that was present in an
1974     earlier unreleased version.
1975         <li>Added -d flag.
1976       </ul>
1977
1978     <li>8th Jul 1994:
1979       <ul>
1980         <li>Added -o flag.
1981         <li>Discarded writing to standard output in DOS version because of
1982         extensive problems trying to make this work with redirected
1983         output.  Instead, output is written to the file extract.pgn.
1984       </ul>
1985
1986     <li>6th Jul 1994: Added -7 flag.
1987
1988     <li>9th May 1994: Added -p flag for variation permutations.
1989
1990     <li>6th May 1994: Added * as a don't-care move in variations files.
1991
1992     <li>26th Apr 1994: Added the -t flag for files of extraction criteria.
1993
1994     <li>25th Apr 1994: Added the -T flag for extraction criteria.
1995
1996     <li>22nd Apr 1994: Added the -f flag for handling lists of PGN files.
1997
1998     <li>13th Apr 1994:
1999       <ul>
2000         <li>Cleaned up the game-length determination by reading/writing files
2001     in binary-mode.
2002         <li>Added -a flag for appending to existing .pgn files.
2003         <li>Added multiple input files.
2004         <li>Made verbose output the default behaviour.
2005       </ul>
2006 </ul>
2007 <hr>
2008 </div>
2009 </div>
2010
2011   <div id="footer">
2012 <address>
2013 <p>Copyright (C) 1994-2014 David J. Barnes<br />
2014 <a href="mailto:d.j.barnes@kent.ac.uk">d.j.barnes@kent.ac.uk</a><br />
2015 <a href="http://www.cs.kent.ac.uk/~djb/">http:www.cs.kent.ac.uk/~djb/</a><br />
2016 Date of this version: 28th October 2014<br>
2017 Version Number: 17-19<br>
2018 </address>
2019   </div>
2020 </div>
2021 </body>