1 \input texinfo @c -*-texinfo-*-
5 @c Documentation for Chess.el.
6 @c Copyright (C) 2001, 2002 John Wiegley.
8 @c This file is free software; you can redistribute it and/or modify it
9 @c under the terms of the GNU General Public License as published by the
10 @c Free Software Foundation; either version 2 of the License, or (at
11 @c your option) any later version.
13 @c This file is distributed in the hope that it will be useful, but
14 @c WITHOUT ANY WARRANTY; without even the implied warraonty of
15 @c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
16 @c General Public License for more details.
18 @c You should have received a copy of the GNU General Public License
19 @c along with Eshell; see the file COPYING. If not, write to the Free
20 @c Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA.
23 @setfilename chess.info
24 @settitle Emacs Chess: chess.el
29 * Chess: (chess). Chess.el is an Emacs chess client.
34 Copyright @copyright{} 2001, 2002 John Wiegley.
36 Permission is granted to copy, distribute and/or modify this document
37 under the terms of the GNU Free Documentation License, Version 1.1 or
38 any later version published by the Free Software Foundation.
42 @c The titlepage section does not appear in the Info file.
45 @c The title is printed in a large font.
46 @center @titlefont{User's Guide}
48 @center @titlefont{to}
50 @center @titlefont{Emacs Chess: chess.el}
60 @c The following two commands start the copyright page for the printed
61 @c manual. This will not appear in the Info file.
63 @vskip 0pt plus 1filll
64 Copyright @copyright{} 2001, 2002 John Wiegley.
66 Permission is granted to copy, distribute and/or modify this document
67 under the terms of the GNU Free Documentation License, Version 1.1 or
68 any later version published by the Free Software Foundation.
73 @c ================================================================
74 @c The real text starts here
75 @c ================================================================
78 @node Top, Emacs Chess: chess.el, (dir), (dir)
79 @top Emacs Chess: chess.el
81 Chess.el is an Emacs chess client and library, designed to be used for
82 writing chess-related programs, or for playing games of chess against
83 various chess engines, including Internet servers. The library can be
84 used for analyzing variations, browsing historical games, or a
85 multitude of other purposes.
87 The purpose of this manual is to help you understand how Chess.el is
88 structured for use as a library, and also how to use it as a client.
91 @chapter The chess.el library
96 A chess @dfn{position} is a given layout of pieces on a chess board,
97 also reflecting which side is next to move, and what privileges are
98 currently available to each side (castling short or long, en passant
101 A position may be represented in ASCII using FEN (or EPD) notation, or
102 graphically by displaying a chess board. It is rather inconvenient to
103 render them verbally.
105 The position can be represented on a remote terminal using X windows, or
106 by transmitting the FEN string via a network connection, or clipboard,
107 to another chess board rendering tool. It may of course also be
108 represented physically, by setting up the pieces to match the FEN
111 Chess puzzles are most often provided as a set of positions.
113 @subsection Creating positions
115 @c lispfun chess-pos-create
117 @c lispfun chess-pos-copy
119 @defvar chess-starting-position
120 Starting position of a chess game.
123 @c lispfun chess-fischer-random-position
125 @subsection Position coordinates
127 First of all, a coordinate system of octal indices is
128 used, where ?\044 signifies rank 4 file 4 (i.e., "e4"). Rank is
129 numbered 0 to 7, top to bottom, and file is 0 to 7, left to right.
131 @c lispfun chess-index-rank
133 @c lispfun chess-index-file
135 @c lispfun chess-rf-to-index
137 For those who wish to use ASCII coordinates, such as "e4", there
138 are two conversion functions:
140 @c lispfun chess-coord-to-index
142 @c lispfun chess-index-to-coord
144 There is also one helper function for iterative changes of an index:
146 @c lispfun chess-incr-index
148 @subsection Position details
150 With an octal index value, you can look up what's on a particular
151 square, or set that square's value:
153 @c lispfun chess-pos-piece
155 @c lispfun chess-pos-piece-p
157 @c lispfun chess-pos-set-piece
159 @c lispfun chess-pos-search
161 @c lispfun chess-search-position
163 @c lispfun chess-pos-can-castle
165 @c lispfun chess-pos-set-can-castle
167 @c lispfun chess-pos-en-passant
169 @c lispfun chess-pos-set-en-passant
171 @c lispfun chess-pos-status
173 @c lispfun chess-pos-set-status
175 @c lispfun chess-pos-side-to-move
177 @c lispfun chess-pos-set-side-to-move
179 @c lispfun chess-pos-passed-pawns
181 @defvar chess-pos-always-white
182 When set, it is assumed that white is always on move.
183 This is really only useful when setting up training positions.
184 This variable automatically becomes buffer-local when changed.
187 @c lispfun chess-pos-move
189 @subsection Annotations
191 @c lispfun chess-pos-annotations
193 @c lispfun chess-pos-add-annotation
195 @subsection FEN notation
197 FEN notation encodes a chess position using a simple string. The
200 POSITION SIDE CASTLING EN-PASSANT
202 The POSITION gives all eight ranks, by specifying a letter for each
203 piece on the position, and a number for any intervening spaces.
204 Trailing spaces need not be counted. Uppercase letters signify
205 white, and lowercase black. For example, if your position only had
206 a black king on d8, your POSITION string would be:
210 For the three spaces (a, b and c file), the black king, and then
211 all the remaining ranks (which are all empty, so their spaces can
214 The SIDE is w or b, to indicate whose move it is.
216 CASTLING can contain K, Q, k or q, to signify whether the white or
217 black king can still castle on the king or queen side. EN-PASSANT
218 signifies the target sqaure of an en passant capture, such as "e3" or "a6".
220 The starting chess position always looks like this:
222 rnbqkbnr/pppppppp/////PPPPPPPP/RNBQKBNR/ w KQkq -
224 And in "full" mode (where all spaces are accounted for):
226 rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq -
228 @c lispfun chess-fen-to-pos
230 @c lispfun chess-pos-to-fen
232 @subsection EPD notation
234 EPD is "Extended Position Description"; it is a standard for describing chess
235 positions along with an extended set of structured attribute values using the
236 ASCII character set. It is intended for data and command interchange among
237 chessplaying programs. It is also intended for the representation of portable
238 opening library repositories.
240 A single EPD uses one text line of variable length composed of four data field
241 followed by zero or more operations. The four fields of the EPD specification
242 are the same as the first four fields of the FEN specification.
244 A text file composed exclusively of EPD data records should have a file name
245 with the suffix ".epd".
247 @c lispfun chess-epd-to-pos
249 @c lispfun chess-pos-to-epd
251 @c lispfun chess-epd-read-file
253 @subsubsection Operations
255 An EPD operation is composed of an opcode followed by zero or more operands and
256 is concluded by a semicolon.
258 Multiple operations are separated by a single space character. If there is at
259 least one operation present in an EPD line, it is separated from the last
260 (fourth) data field by a single space character.
262 Some opcodes that allow for more than one operand may have special ordering
263 requirements for the operands. For example, the "pv" (predicted variation)
264 opcode requires its operands (moves) to appear in the order in which they would
265 be played. All other opcodes that allow for more than one operand should have
266 operands appearing in ASCII order. An example of the latter set is the "bm"
267 (best move[s]) opcode; its operands are moves that are all immediately playable
268 from the current position.
270 @subsubsection Opcode "acd" analysis count depth
272 The opcode "acd" takes a single non-negative integer operand. It is used to
273 represent the ply depth examined in an analysis.
275 @subsubsection Opcode "acn" analysis count nodes
277 The opcode "acn" takes a single non-negative integer operand. It is used to
278 represent the number of nodes examined in an analysis. Note that the value may
279 be quite large for some extended searches and so use of (at least) a long (four
280 byte) representation is suggested.
282 @subsubsection Opcode "acs" analysis count seconds
284 The opcode "acs" takes a single non-negative integer operand. It is used to
285 represent the number of seconds used for an analysis. Note that the value may
286 be quite large for some extended searches and so use of (at least) a long (four
287 byte) representation is suggested.
289 @subsubsection Opcode "am" avoid move(s)
291 The opcode "am" indicates a set of zero or more moves, all immediately playable
292 from the current position, that are to be avoided in the opinion of the EPD
293 writer. Each operand is a SAN move; they appear in ASCII order.
295 @subsubsection Opcode "bm" best move(s)
297 The opcode "bm" indicates a set of zero or more moves, all immediately playable
298 from the current position, that are judged to the best available by the EPD
299 writer. Each operand is a SAN move; they appear in ASCII order.
303 A @dfn{ply} is the differential between two positions. Or, it is the
304 coordinate transformations applied to one position in order to arrive at
305 the following position. It is also informally called "a move".
307 A ply may be represented in ASCII by printing the FEN string of the base
308 position, and then printing the positional transformation in algebraic
309 notation. Since the starting position is usually known, the FEN string
310 is optional. A ply may be represented graphically by moving the chess
311 piece(s) involved. It may be rendered verbally by voicing which piece
312 is to move, where it will move to, and what will happen a result of the
313 move (piece capture, check, etc).
315 Plies may be sent over network connections, postal mail, e-mail, etc.,
316 so long as the current position is maintained at both sides.
317 Transmitting the base position's FEN string along with the ply offers a
318 form of confirmation during the course of a game.
320 @subsection Creating plies
322 @c lispfun chess-ply-create
324 @c lispfun chess-legal-plies
326 @subsection Ply details
328 @c lispfun chess-ply-pos
330 @c lispfun chess-ply-set-pos
332 @c lispfun chess-ply-changes
334 @c lispfun chess-ply-set-changes
336 @c lispfun chess-ply-source
338 @c lispfun chess-ply-target
340 @subsection The "next" position
342 @c lispfun chess-ply-next-pos
344 @c lispfun chess-ply-final-p
346 @subsection Algebraic notation
348 A thing to deal with in chess is algebraic move notation, such as
349 Nxf3+. (I leave description of this notation to better manuals
350 than this). This notation is a shorthand way of representing where
351 a piece is moving from and to, by specifying the piece is involved,
352 where it's going, and whether or not a capture or check is
355 You can convert from algebraic notation to a ply (one pair in most
356 cases, but two for a castle) using the following function (NOTE:
357 POSITION determines which side is on move (by calling
358 `chess-pos-side-to-move')):
360 @c lispfun chess-algebraic-to-ply
362 The function also checks if a move is legal, and will raise an
365 To convert from a ply to algebraic notation, use:
367 @c lispfun chess-ply-to-algebraic
369 Lastly, there is a regexp for quickly checking if a string is in
370 algebraic notation or not, or searching out algebraic strings in a
373 @defvar chess-algebraic-regexp
374 A regular expression that matches all possible algebraic moves.
375 This regexp handles both long and short form.
380 A @dfn{variation} is a sequence of plies that occur after some starting
381 position. If the starting position represents the initial setup of a
382 chess board, and if the final ply results in completion of the game, it
383 is called the "main variation". Otherwise, variations typically
384 represented interesting tangents during a game---but not actually
385 played---as envisioned by the player, an annotator, or someone studying
388 Variations may be represented in ASCII by stating the FEN string for
389 starting position, followed by the list of plies that follow that
390 position. They are difficult to represent graphically, except for
391 showing each position in turn with a slight pause between---or by
392 allowing the user to navigate each of the subsequent positions in turn.
393 They may be represented verbally by announcing each of the plies in
394 turn, as mentioned above.
396 @subsection Creating variations
398 @c lispfun chess-var-create
400 @subsection Variation positions
402 @c lispfun chess-var-pos
404 @c lispfun chess-var-index
406 @c lispfun chess-var-seq
408 @c lispfun chess-var-side-to-move
410 @subsection Varation plies
412 @c lispfun chess-var-ply
414 @c lispfun chess-var-plies
416 @c lispfun chess-var-to-algebraic
418 @subsection Making a move in a variation
420 @c lispfun chess-var-move
422 @c lispfun chess-var-add-ply
426 A @dfn{game} includes its main variation, incidental information about
427 the game (who played it, where, when, who won, etc), and any
428 sub-variations of interest to those studying the game afterwards.
430 Where TAGS is an alist that associates arbitrary English tag names to
433 A game may be represented in ASCII using standard PGN notation.
434 Representing them graphically or verbally is similar to what is done
437 @c lispfun chess-game-add-hook
439 @c lispfun chess-game-add-ply
441 @c lispfun chess-game-hooks
443 @c lispfun chess-game-plies
445 @c lispfun chess-game-remove-hook
447 @c lispfun chess-game-run-hooks
449 @c lispfun chess-game-set-hooks
451 @c lispfun chess-game-set-plies
453 @subsection Creating games
455 @c lispfun chess-game-create
457 @subsection Game tags
459 @c lispfun chess-game-tags
461 @c lispfun chess-game-set-tags
463 @c lispfun chess-game-tag
465 @c lispfun chess-game-set-tag
467 @c lispfun chess-game-del-tag
469 @subsection Game positions
471 @c lispfun chess-game-pos
473 @c lispfun chess-game-index
475 @c lispfun chess-game-seq
477 @c lispfun chess-game-side-to-move
479 @subsection Game plies
481 @c lispfun chess-game-ply
483 @subsection Making a move
485 @c lispfun chess-game-move
487 @subsection PGN notation
489 @c lispfun chess-pgn-to-game
491 @c lispfun chess-game-to-pgn
493 @c lispfun chess-pgn-insert-plies
495 @subsubsection PGN mode
497 @c lispfun chess-pgn-visualize
501 A @dfn{collection} is a set of games archived for later perusal. A set
502 of games conceptually represents a large tree of branching variations,
503 and can be used for studying current theory, examining Master
506 Chess.el itself does not attempt to provide library services, nor does it
507 ever represent library collections in memory. Instead, it interacts
508 with a chess database engine for the purpose of storing and retrieving
509 games from the library, or performing library-wide analyses and
512 @subsection Opening Databases
514 @defvar chess-database-modules
515 List of database modules to try when `chess-database-open' is called.
518 @c lispfun chess-database-open
520 @subsection Querying Databases
522 @c lispfun chess-database-filename
524 @c lispfun chess-database-count
526 @c lispfun chess-database-read
528 @c lispfun chess-database-query
530 @subsection Modifying Databases
532 @c lispfun chess-database-read-only-p
534 @c lispfun chess-database-write
536 @c lispfun chess-database-replace
538 @subsection Finalising Databases
540 @c lispfun chess-database-save
542 @c lispfun chess-database-close
544 @subsection Database Modules
546 Currently, there are two subclasses of the above defined
549 @subsubsection chess-file
551 This module does not use an external chess database program
552 to store and retrieve games. It uses the PGN of EPD format parsing
553 routines provided in `chess-pgn.el' and `chess-epd.el' to implement Collections
554 for ordinary PGN and EPD files.
556 EPD file collections are represented as a collection of games originating
557 at the given position. One might argue that conceptually, they represent
558 a collection of positions, but it is more convenient to merge all
559 collections into one uniform concept.
561 @subsubsection chess-scid
563 This modules implement basic reading and writing functionality
564 for SCID (Shane's Chess Information Database) files.
568 Positions, plies and variations are typically accessed in reference to
569 a game object, which has a main variation containing the plies and
570 positions that represent the number of moves made within that game up
571 to the final position.
573 Another thing that the game object does is to manage events that occur
574 within that game. If a move is made from the final position, for
575 example, it will cause a new ply to be created, adding it to the end
576 of the main variation. Then, a `move' event is triggered within the
577 game and passed to any chess modules which are currently associated
578 with that game. The concept of modules allows far more complex
579 aspects of chess playing to be dealt with, while allowing the library
580 itself to still operate solely in terms of the game object.
582 For example, although the plies of a game object contain all the
583 information the computer needs to follow the game, a user needs much
584 more. He wants to see the pieces move. To support this, a display
585 module (see next chapter) can be created, and linked to the game. The
586 first effect of this association will be to create a chess board
587 display and show the game's final position on it. Now whenever plies
588 are added to the game, the chess board will be updated to show the
589 effect of that move on the board. The display module realizes that a
590 move has been made by receiving the `move' event which is passed to
591 all modules associated with the game object.
593 There may be any number of modules associated with a chess game, and
594 they may do anything you like. Basically, for a module called
595 chess-sample, a function must exist called `chess-sample-handler'.
596 This takes two or more arguments: a game object, the event symbol, and
597 whatever other arguments were passed along with the event symbol.
599 When an event is triggered on a game object (and this may happen as a
600 byproduct of manipulating the game, or events may be manually
601 generated), every associated module, in order, is called with that
602 event and whatever arguments were passed along with the event. The
603 game object is passed also, so that the module knows which game this
604 event has occurred in reference to.
606 Once called, the module can do whatever it likes. Some events expect
607 certain values to be returned, to indicate success or failure in
608 processing the event. There are many different events, each depicting
609 something specific that might happen in the context of playing or
610 manipulating a chess game. Some events relate only to the chess game
611 itself, some are triggered by the various chess engines that might be
612 associated with that game. Modules may even trigger events in
613 response to event. The game itself remains unaware of events, except
614 for the fact that it will pass them along to every module associated
617 This is how displays get updated, for example, because once a 'move'
618 event is triggered, each display knows that it must now look at the
619 new final position and update its display. It may even trigger new
620 events special to displays, to cause a refresh to happen after update
621 calculations have been performed, for example. All such details are
622 left to the module, and the game does not interfere with such
623 intra-module messaging.
625 Looked at as an object-oriented design, these are typical polymorphic
626 events. Certain generic situations frequently occur, such as moves,
627 which trigger events so that everyone concerned with the game can be
628 updated as to the move that occurred. This way, no one need to
629 actively query the game to find out if something new has happened.
630 The game will notify every listening module by sending an event.
632 The core library, which consists of code to manipulate games, does not
633 define any modules. The rest of the chess.el library is strictly a
634 set of module implementations, of various types. Display modules
635 react to moves, and may modify the game based on user input; engine
636 modules react to moves by notifying the engine of the move; network
637 client modules react to moves by sending the move text over the
638 network. Engine and network modules may also trigger new events when
639 the engine or network player has decided on their move, and this move
640 is then applied to the game object.
642 At the moment, no negotiation is done to determine which module may
643 modify the game object. All modules have equal privilege. This means
644 it is the programmer's duty not to associate conflicting modules with
645 a single game object. If two artificial intelligence engines were
646 linked, for example, they would quickly start stepping on each other's
647 toes. But it perfectly fine to have one artificial intelligence
648 engine, and another passive engine whose only purpose is to relay the
649 moves to a networked observer on another computer. The possibilities
652 Modules are very easy to write, although engines and displays are
653 rather different from each other in their principles. There is a base
654 engine, and a base display, which receive the same events as any other
655 module. But then there are derived engines and derived displays which
656 trigger a whole family of events specific to those module types. If
657 you suspect a bug in your module, put a breakpoint in your handler
658 function, and wait for the offending event to come through. Then you
659 can watch what your module does in response to that event. If it
660 leaves the game object alone, it should be easy to locate the problem,
661 since it will always be within the module itself. But if your module
662 also modifies the game object in response to certain events, you may
663 induce a feedback loop that is much more difficult to sort out. Test
664 often and keep in mind that *many* events might end up coming through
665 as a result of the game changes your module makes!
667 That, in essence, is how the module system works. From the game
668 object's perspective, it is a very simple mechanism, much like a
669 function ring or a hook. The hook is called at certain points, so
670 that any listener can react to changes in the game. But from each
671 module's perspective, it is a rich way to allow inter-operation
672 between both passive and reactive modules, all of them acting together
673 to enrich the context of play involving the central game object.
675 The only other rule to be mentioned is that each module instance
676 should be associated with only one game object at a time, although a
677 game object may have unlimited modules of any type linked to it.
678 Otherwise, trying to update a chess board based on input from two
679 different games would get impossible to sort out. Better to create a
680 new board for every game---the way ordinary humans would do it in the
683 @chapter Chessboard displays
685 The previous chapter described all the objects found in
686 chess---positions, plies, variations, games and collections. However,
687 these objects can only be manipulated programmitically using the
688 functions given so far. In order to present them in a meaningful
689 fashion to a human reader, it is necessary to create and use a display
692 @section Generic display manipulation functions
694 @c lispfun chess-display-create
696 @c lispfun chess-display-destroy
698 @c lispfun chess-display-active-p
700 @c lispfun chess-display-clear-board
702 @c lispfun chess-display-game
704 @c lispfun chess-display-highlight
706 @c lispfun chess-display-index
708 @c lispfun chess-display-invert
710 @c lispfun chess-display-move
712 @c lispfun chess-display-move-backward
714 @c lispfun chess-display-move-first
716 @c lispfun chess-display-move-forward
718 @c lispfun chess-display-move-last
720 @c lispfun chess-display-perspective
722 @c lispfun chess-display-ply
724 @c lispfun chess-display-position
726 @c lispfun chess-display-quit
728 @c lispfun chess-display-set-game
730 @c lispfun chess-display-set-index
732 @c lispfun chess-display-set-perspective
734 @c lispfun chess-display-set-ply
736 @c lispfun chess-display-set-position
738 @c lispfun chess-display-set-variation
740 @c lispfun chess-display-update
742 @c lispfun chess-display-variation
744 @section Plain ASCII diagram displays
746 The simplest display style available is chess-plain, a very customisable
747 ASCII board diagram display.
749 @defvar chess-plain-separate-frame
750 If non-nil, display the chessboard in its own frame.
753 @defvar chess-plain-draw-border
754 Non-nil if a border should be drawn (using `chess-plain-border-chars').
757 @defvar chess-plain-border-chars
758 A list of Characters used to draw borders.
761 @defvar chess-plain-black-square-char
762 Character used to indicate empty black squares.
765 @defvar chess-plain-white-square-char
766 Character used to indicate black white squares.
769 @defvar chess-plain-piece-chars
770 Alist of pieces and their corresponding characters.
773 @defvar chess-plain-upcase-indicates
774 Defines what a upcase char should indicate.
775 The default is 'color, meaning a upcase char is a white piece, a
776 lowercase char a black piece. Possible values: 'color (default),
777 'square-color. If set to 'square-color, a uppercase character
778 indicates a piece on a black square. (Note that you also need to
779 modify `chess-plain-piece-chars' to avoid real confusion.)
782 @defvar chess-plain-spacing
783 Number of spaces between files.
786 @section ICS1 style ASCII displays
788 @defvar chess-ics1-separate-frame
789 If non-nil, display the chessboard in its own frame.
792 @section Graphical displays
796 Engines are the representation of an opponent in Chess. THe main type
797 of engine interfaces with an external chess program. However, there
798 can be other uses for engine objects, such as providing networked engined
799 for playing with opponent over different types of transports.
801 @section Common functions
803 @c lispfun chess-engine-create
805 @c lispfun chess-engine-set-option
807 @c lispfun chess-engine-destroy
809 @c lispfun chess-engine-set-position
811 @c lispfun chess-engine-position
813 @c lispfun chess-engine-set-game
815 @c lispfun chess-engine-game
817 @c lispfun chess-engine-index
819 @c lispfun chess-engine-move
821 @c lispfun chess-engine-command
823 @c lispfun chess-engine-send
833 @chapter Internet Chess Servers
835 Based on the services provided above, there is also a speical mode
836 for communication with Internet Chess Servers.
838 ON an Internet Chess Server you can seek to play against other
839 human or computer players, observe other games being player or examined,
840 play tournaments, chat with fellow chess players, participate in a team game,
841 or do various other interesting chess related things.
843 A default set of well known servers is defined in the following variable:
845 @defvar chess-ics-server-list
846 A list of servers to connect to.
847 The format of each entry is:
849 (SERVER PORT [HANDLE] [PASSWORD-OR-FILENAME] [HELPER] [HELPER ARGS...])
852 @section Connecting to a server
854 To open a new connection to an Internet Chess Server, use:
858 @section Seeking an opponent for a new game
860 After you connected to a server, one of the first things you will
861 want to do is find an oponent for a new game. You can use the
862 ICS command "seek" to announce your availability for a chess game
863 to interested people.
865 @section The sought game display
867 There is a special mode for displaying games sought by other users
868 on an Internet Chess Server. Provided you didn't turn off seek ads
869 manually (for instance by setting the seek variable to 0 (off) on the
870 ICS server by issueing "set seek 0"), the first seek advertisment
871 automatically pops up a new window which is in `chess-ics-sought-mode'.
873 @c lispfun chess-ics-sought-mode
875 In this buffer, use mouse-2 or @kbd{RET} on a line to accept that
876 particular game and play it.
878 @unnumbered Concept Index
882 @unnumbered Function and Variable Index
886 @unnumbered Key Index