diff options
Diffstat (limited to 'doc/chess.texi')
| -rw-r--r-- | doc/chess.texi | 1576 |
1 files changed, 1576 insertions, 0 deletions
diff --git a/doc/chess.texi b/doc/chess.texi new file mode 100644 index 0000000..3d2d6db --- /dev/null +++ b/doc/chess.texi @@ -0,0 +1,1576 @@ +\input texinfo @c -*-texinfo-*- + +@c Documentation for Chess.el. +@c Copyright (C) 2001, 2002 John Wiegley. + +@c This file is free software; you can redistribute it and/or modify it +@c under the terms of the GNU General Public License as published by the +@c Free Software Foundation; either version 2 of the License, or (at +@c your option) any later version. + +@c This file is distributed in the hope that it will be useful, but +@c WITHOUT ANY WARRANTY; without even the implied warraonty of +@c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +@c General Public License for more details. + +@c You should have received a copy of the GNU General Public License +@c along with Eshell; see the file COPYING. If not, write to the Free +@c Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA. + +@c %**start of header +@setfilename chess.info +@settitle Emacs Chess: chess.el +@c %**end of header + +@dircategory Emacs +@direntry +* Chess: (chess). Chess.el is an Emacs chess client. +@end direntry +@setchapternewpage on + +@ifinfo +Copyright @copyright{} 2001, 2002 John Wiegley. + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.1 or +any later version published by the Free Software Foundation. +@end ifinfo + +@synindex vr fn +@c The titlepage section does not appear in the Info file. +@titlepage +@sp 4 +@c The title is printed in a large font. +@center @titlefont{User's Guide} +@sp +@center @titlefont{to} +@sp +@center @titlefont{Emacs Chess: chess.el} +@ignore +@sp 2 +@center release 2.0 +@c -release- +@end ignore +@sp 3 +@center John Wiegley +@c -date- + +@c The following two commands start the copyright page for the printed +@c manual. This will not appear in the Info file. +@page +@vskip 0pt plus 1filll +Copyright @copyright{} 2001, 2002 John Wiegley. + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.1 or +any later version published by the Free Software Foundation. +@end titlepage + +@contents + +@c ================================================================ +@c The real text starts here +@c ================================================================ + +@ifinfo +@node Top, The chess.el library, (dir), (dir) +@top Emacs Chess: chess.el + +Chess.el is an Emacs chess client and library, designed to be used for +writing chess-related programs, or for playing games of chess against +various chess engines, including Internet servers. The library can be +used for analyzing variations, browsing historical games, or a +multitude of other purposes. + +The purpose of this manual is to help you understand how Chess.el is +structured for use as a library, and also how to use it as a client. +@end ifinfo + +@menu +* The chess.el library:: +* Modules:: +* Chessboard displays:: +* Engines:: +* Internet Chess Servers:: +* Concept Index:: +* Function and Variable Index:: +* Key Index:: +@end menu + +@node The chess.el library, Modules, Top, Top +@chapter The chess.el library +@cindex library + +@menu +* Positions:: +* Plies:: +* Variations:: +* Games:: +* Collections:: +@end menu + +@node Positions, Plies, The chess.el library, The chess.el library +@section Positions + +A chess @dfn{position} is a given layout of pieces on a chess board, +also reflecting which side is next to move, and what privileges are +currently available to each side (castling short or long, en passant +capture, etc). + +A position may be represented in ASCII using FEN (or EPD) notation, or +graphically by displaying a chess board. It is rather inconvenient to +render them verbally. + +The position can be represented on a remote terminal using X windows, or +by transmitting the FEN string via a network connection, or clipboard, +to another chess board rendering tool. It may of course also be +represented physically, by setting up the pieces to match the FEN +notation. + +Chess puzzles are most often provided as a set of positions. + +@menu +* Creating positions:: +* Position coordinates:: +* Position details:: +* Annotations:: +* FEN notation:: +* EPD notation:: +@end menu + +@node Creating positions, Position coordinates, Positions, Positions +@subsection Creating positions + +@c lispfun chess-pos-create + +@defun chess-pos-create &optional blank +Create a new chess position, set at the starting position. +If @var{blank} is non-nil, all of the squares will be empty. +The current side-to-move is always white. +@end defun + +@c lispfun chess-pos-copy + +@defun chess-pos-copy position +Copy the given chess @var{position}. +If there are annotations or @var{epd} opcodes set, these lists are copied as +well, so that the two positions do not share the same lists. +@end defun + +@defvar chess-starting-position +Starting position of a chess game. +@end defvar + +@c lispfun chess-fischer-random-position + +@defun chess-fischer-random-position +Generate a Fischer Random style position. +@end defun + +@node Position coordinates, Position details, Creating positions, Positions +@subsection Position coordinates + +First of all, a coordinate system of octal indices is +used, where ?\044 signifies rank 4 file 4 (i.e., "e4"). Rank is +numbered 0 to 7, top to bottom, and file is 0 to 7, left to right. + +@c lispfun chess-index-rank + +@defun chess-index-rank index +Return the rank component of the given @var{index}. +@end defun + +@c lispfun chess-index-file + +@defun chess-index-file index +Return the file component of the given @var{index}. +@end defun + +@c lispfun chess-rf-to-index + +@defun chess-rf-to-index rank file +Convert @var{rank} and @var{file} coordinates into an octal index. +@end defun + +For those who wish to use ASCII coordinates, such as "e4", there +are two conversion functions: + +@c lispfun chess-coord-to-index + +@defun chess-coord-to-index coord +Convert a @var{coord} string into an index value. +@end defun + +@c lispfun chess-index-to-coord + +@defun chess-index-to-coord index +Convert the chess position @var{index} into a coord string. +@end defun + +There is also one helper function for iterative changes of an index: + +@c lispfun chess-incr-index + +@defun chess-incr-index index rank-move file-move +Create a new @var{index} from an old one, by adding @var{rank-move} and @var{file-move}. +@end defun + +@node Position details, Annotations, Position coordinates, Positions +@subsection Position details + +With an octal index value, you can look up what's on a particular +square, or set that square's value: + +@c lispfun chess-pos-piece + +@defun chess-pos-piece position index +Return the piece on @var{position} at @var{index}. +@end defun + +@c lispfun chess-pos-piece-p + +@defun chess-pos-piece-p position index piece-or-color +Return non-nil if at @var{position}/@var{index} there is the given @var{piece-or-color}. +If @var{piece-or-color} is t for white or nil for black, any piece of that +color will do. +@end defun + +@c lispfun chess-pos-set-piece + +@defun chess-pos-set-piece position index piece +Set the piece on @var{position} at @var{index} to @var{piece}. +@var{piece} must be one of K Q N B R or P. Use lowercase to set black +pieces. +@end defun + +@c lispfun chess-pos-search + +@defun chess-pos-search position piece-or-color +Look on @var{position} anywhere for @var{piece-or-color}, returning all coordinates. +If @var{piece-or-color} is t for white or nil for black, any piece of that +color will do. +@end defun + +@c lispfun chess-search-position + +@defun chess-search-position position target piece &optional check-only no-castling +Look on @var{position} from @var{target} for a @var{piece} that can move there. +This routine looks along legal paths of movement for @var{piece}. It +differs from `chess-pos-search', which is a more basic function that +doesn't take piece movement into account. + +If @var{piece} is t or nil, legal piece movements for any piece of that +color will be considered (t for white, nil for black). Otherwise, the +case of the @var{piece} determines color. + +The return value is a list of candidates, which means a list of +indices which indicate where a piece may have moved from. + +If @var{check-only} is non-nil and @var{piece} is either t or nil, only consider +pieces which can give check (not the opponents king). +If @var{no-castling} is non-nil, do not consider castling moves. +@end defun + +@c lispfun chess-pos-can-castle + +@defun chess-pos-can-castle position side +Return whether the king on @var{position} can castle on @var{side}. +@var{side} must be either ?K for the kingside, or ?Q for the queenside (use +lowercase to query if black can castle). +@end defun + +@c lispfun chess-pos-set-can-castle + +@defun chess-pos-set-can-castle position side value +Set whether the king can castle on the given @var{position} on @var{side}. + +See `chess-pos-can-castle'. + +It is only necessary to call this function if setting up a position +manually. Note that all newly created positions have full castling +priveleges set, unless the position is created blank, in which case +castling priveleges are unset. See `chess-pos-copy'. +@end defun + +@c lispfun chess-pos-en-passant + +@defun chess-pos-en-passant position +Return the index of any pawn on @var{position} that can be captured en passant. +Returns nil if en passant is unavailable. +@end defun + +@c lispfun chess-pos-set-en-passant + +@defun chess-pos-set-en-passant position index +Set the index of any pawn on @var{position} that can be captured en passant. +@end defun + +@c lispfun chess-pos-status + +@defun chess-pos-status position +Return whether the side to move in the @var{position} is in a special state. +nil is returned if not, otherwise one of the symbols: `check', +`checkmate', `stalemate'. +@end defun + +@c lispfun chess-pos-set-status + +@defun chess-pos-set-status position value +Set whether the side to move in @var{position} is in a special state. +@var{value} should either be nil, to indicate that the @var{position} is normal, +or one of the symbols: `check', `checkmate', `stalemate'. +@end defun + +@c lispfun chess-pos-side-to-move + +@defun chess-pos-side-to-move position +Return the color whose move it is in @var{position}. +@end defun + +@c lispfun chess-pos-set-side-to-move + +@defun chess-pos-set-side-to-move position color +Set the color whose move it is in @var{position}. +@end defun + +@c lispfun chess-pos-passed-pawns + +@defun chess-pos-passed-pawns position color &optional pawn-indices +If @var{color} has Passed Pawns in @var{position}, return a list of their indices. +Optionally, if @var{indices} is non-nil those indices are considered as candidates. + +A Pawn whose advance to the eighth rank is not blocked by an +opposing Pawn in the same file and who does not have to pass one +on an adjoining file is called a passed Pawn. +@end defun + +@defvar chess-pos-always-white +When set, it is assumed that white is always on move. +This is really only useful when setting up training positions. +This variable automatically becomes buffer-local when changed. +@end defvar + +@c lispfun chess-pos-move + +@defun chess-pos-move position &rest changes +Move a piece on the @var{position} directly, using the indices in @var{changes}. +This function does not check any rules, it only makes sure you are not +trying to move a blank square. +@end defun + +@node Annotations, FEN notation, Position details, Positions +@subsection Annotations + +@c lispfun chess-pos-annotations + +@defun chess-pos-annotations position +Return the list of annotations for this position. +@end defun + +@c lispfun chess-pos-add-annotation + +@defun chess-pos-add-annotation position annotation +Add an annotation for this position. +@end defun + +@node FEN notation, EPD notation, Annotations, Positions +@subsection FEN notation + +FEN notation encodes a chess position using a simple string. The +format is: + + POSITION SIDE CASTLING EN-PASSANT + +The POSITION gives all eight ranks, by specifying a letter for each +piece on the position, and a number for any intervening spaces. +Trailing spaces need not be counted. Uppercase letters signify +white, and lowercase black. For example, if your position only had +a black king on d8, your POSITION string would be: + + 3k//////// + +For the three spaces (a, b and c file), the black king, and then +all the remaining ranks (which are all empty, so their spaces can +be ignored). + +The SIDE is w or b, to indicate whose move it is. + +CASTLING can contain K, Q, k or q, to signify whether the white or +black king can still castle on the king or queen side. EN-PASSANT +signifies the target sqaure of an en passant capture, such as "e3" or "a6". + +The starting chess position always looks like this: + + rnbqkbnr/pppppppp/////PPPPPPPP/RNBQKBNR/ w KQkq - + +And in "full" mode (where all spaces are accounted for): + + rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - + +@c lispfun chess-fen-to-pos + +@defun chess-fen-to-pos fen +Convert a @var{fen-}like notation string to a chess position. +@end defun + +@c lispfun chess-pos-to-fen + +@defun chess-pos-to-fen position &optional full +Convert a chess @var{position} to @var{fen-}like notation. +If @var{full} is non-nil, represent trailing spaces as well. +@end defun + +@node EPD notation, , FEN notation, Positions +@subsection EPD notation + +EPD is "Extended Position Description"; it is a standard for describing chess +positions along with an extended set of structured attribute values using the +ASCII character set. It is intended for data and command interchange among +chessplaying programs. It is also intended for the representation of portable +opening library repositories. + +A single EPD uses one text line of variable length composed of four data field +followed by zero or more operations. The four fields of the EPD specification +are the same as the first four fields of the FEN specification. + +A text file composed exclusively of EPD data records should have a file name +with the suffix ".epd". + +@c lispfun chess-epd-to-pos + +@defun chess-epd-to-pos &optional string +Convert extended position description to a chess position. +If @var{string} is not specified, look for an @var{epd} string in the current buffer, +and advance point after the correctly parsed position. +@end defun + +@c lispfun chess-pos-to-epd + +@defun chess-pos-to-epd position +Convert a chess @var{position} to a string representation in extended +position description format. +@end defun + +@c lispfun chess-epd-read-file + +@defun chess-epd-read-file file +Return a list of positions contained in @var{file}. +@end defun + +@menu +* Operations:: +* Opcode "acd" analysis count depth:: +* Opcode "acn" analysis count nodes:: +* Opcode "acs" analysis count seconds:: +* Opcode "am" avoid move(s):: +* Opcode "bm" best move(s):: +@end menu + +@node Operations, Opcode "acd" analysis count depth, EPD notation, EPD notation +@subsubsection Operations + +An EPD operation is composed of an opcode followed by zero or more operands and +is concluded by a semicolon. + +Multiple operations are separated by a single space character. If there is at +least one operation present in an EPD line, it is separated from the last +(fourth) data field by a single space character. + +Some opcodes that allow for more than one operand may have special ordering +requirements for the operands. For example, the "pv" (predicted variation) +opcode requires its operands (moves) to appear in the order in which they would +be played. All other opcodes that allow for more than one operand should have +operands appearing in ASCII order. An example of the latter set is the "bm" +(best move[s]) opcode; its operands are moves that are all immediately playable +from the current position. + +@node Opcode "acd" analysis count depth, Opcode "acn" analysis count nodes, Operations, EPD notation +@subsubsection Opcode "acd" analysis count depth + +The opcode "acd" takes a single non-negative integer operand. It is used to +represent the ply depth examined in an analysis. + +@node Opcode "acn" analysis count nodes, Opcode "acs" analysis count seconds, Opcode "acd" analysis count depth, EPD notation +@subsubsection Opcode "acn" analysis count nodes + +The opcode "acn" takes a single non-negative integer operand. It is used to +represent the number of nodes examined in an analysis. Note that the value may +be quite large for some extended searches and so use of (at least) a long (four +byte) representation is suggested. + +@node Opcode "acs" analysis count seconds, Opcode "am" avoid move(s), Opcode "acn" analysis count nodes, EPD notation +@subsubsection Opcode "acs" analysis count seconds + +The opcode "acs" takes a single non-negative integer operand. It is used to +represent the number of seconds used for an analysis. Note that the value may +be quite large for some extended searches and so use of (at least) a long (four +byte) representation is suggested. + +@node Opcode "am" avoid move(s), Opcode "bm" best move(s), Opcode "acs" analysis count seconds, EPD notation +@subsubsection Opcode "am" avoid move(s) + +The opcode "am" indicates a set of zero or more moves, all immediately playable +from the current position, that are to be avoided in the opinion of the EPD +writer. Each operand is a SAN move; they appear in ASCII order. + +@node Opcode "bm" best move(s), , Opcode "am" avoid move(s), EPD notation +@subsubsection Opcode "bm" best move(s) + +The opcode "bm" indicates a set of zero or more moves, all immediately playable +from the current position, that are judged to the best available by the EPD +writer. Each operand is a SAN move; they appear in ASCII order. + +@node Plies, Variations, Positions, The chess.el library +@section Plies + +A @dfn{ply} is the differential between two positions. Or, it is the +coordinate transformations applied to one position in order to arrive at +the following position. It is also informally called "a move". + +A ply may be represented in ASCII by printing the FEN string of the base +position, and then printing the positional transformation in algebraic +notation. Since the starting position is usually known, the FEN string +is optional. A ply may be represented graphically by moving the chess +piece(s) involved. It may be rendered verbally by voicing which piece +is to move, where it will move to, and what will happen a result of the +move (piece capture, check, etc). + +Plies may be sent over network connections, postal mail, e-mail, etc., +so long as the current position is maintained at both sides. +Transmitting the base position's FEN string along with the ply offers a +form of confirmation during the course of a game. + +@menu +* Creating plies:: +* Ply details:: +* The "next" position:: +* Algebraic notation:: +@end menu + +@node Creating plies, Ply details, Plies, Plies +@subsection Creating plies + +@c lispfun chess-ply-create + +@defun chess-ply-create position &optional valid-p &rest changes +Create a ply from the given @var{position} by applying the supplied @var{changes}. +This function will guarantee the resulting ply is legal, and will also +annotate the ply with :check or other modifiers as necessary. It will +also extend castling, and will prompt for a promotion piece. + +Note: Do not pass in the rook move if @var{changes} represents a castling +maneuver. +@end defun + +@c lispfun chess-legal-plies + +@defun chess-legal-plies position &rest keywords +Return a list of all legal plies in @var{position}. +@var{keywords} allowed are: + + :any return t if any piece can move at all + :color <t or nil> + :piece <piece character> + :file <number 0 to 7> [can only be used if :piece is present] + :index <coordinate index> + :target <specific target index> + :candidates <list of inddices> + +These will constrain the plies generated to those matching the above +criteria. + +@var{note}: All of the returned plies will reference the same copy of the +position object passed in. +@end defun + +@node Ply details, The "next" position, Creating plies, Plies +@subsection Ply details + +@c lispfun chess-ply-pos + +@defun chess-ply-pos ply +Returns the base position associated with @var{ply}. +@end defun + +@c lispfun chess-ply-set-pos + +@defun chess-ply-set-pos ply position +Set the base position of @var{ply}. +@end defun + +@c lispfun chess-ply-changes + +@c lispfun chess-ply-set-changes + +@c lispfun chess-ply-source + +@defun chess-ply-source ply +Returns the source square index value of @var{ply}. +@end defun + +@c lispfun chess-ply-target + +@defun chess-ply-target ply +Returns the target square index value of @var{ply}. +@end defun + +@node The "next" position, Algebraic notation, Ply details, Plies +@subsection The "next" position + +@c lispfun chess-ply-next-pos + +@c lispfun chess-ply-final-p + +@defun chess-ply-final-p ply +Return non-nil if this is the last ply of a game/variation. +@end defun + +@node Algebraic notation, , The "next" position, Plies +@subsection Algebraic notation + +A thing to deal with in chess is algebraic move notation, such as +Nxf3+. (I leave description of this notation to better manuals +than this). This notation is a shorthand way of representing where +a piece is moving from and to, by specifying the piece is involved, +where it's going, and whether or not a capture or check is +involved. + +You can convert from algebraic notation to a ply (one pair in most +cases, but two for a castle) using the following function (NOTE: +POSITION determines which side is on move (by calling +`chess-pos-side-to-move')): + +@c lispfun chess-algebraic-to-ply + +@defun chess-algebraic-to-ply position move &optional trust +Convert the algebraic notation @var{move} for @var{position} to a ply. +@end defun + +The function also checks if a move is legal, and will raise an +error if not. + +To convert from a ply to algebraic notation, use: + +@c lispfun chess-ply-to-algebraic + +@defun chess-ply-to-algebraic ply &optional long +Convert the given @var{ply} to algebraic notation. +If @var{long} is non-nil, render the move into long notation. +@end defun + +Lastly, there is a regexp for quickly checking if a string is in +algebraic notation or not, or searching out algebraic strings in a +buffer: + +@defvar chess-algebraic-regexp +A regular expression that matches all possible algebraic moves. +This regexp handles both long and short form. +@end defvar + +@node Variations, Games, Plies, The chess.el library +@section Variations + +A @dfn{variation} is a sequence of plies that occur after some starting +position. If the starting position represents the initial setup of a +chess board, and if the final ply results in completion of the game, it +is called the "main variation". Otherwise, variations typically +represented interesting tangents during a game---but not actually +played---as envisioned by the player, an annotator, or someone studying +the game. + +Variations may be represented in ASCII by stating the FEN string for +starting position, followed by the list of plies that follow that +position. They are difficult to represent graphically, except for +showing each position in turn with a slight pause between---or by +allowing the user to navigate each of the subsequent positions in turn. +They may be represented verbally by announcing each of the plies in +turn, as mentioned above. + +@menu +* Creating variations:: +* Variation positions:: +* Varation plies:: +* Making a move in a variation:: +@end menu + +@node Creating variations, Variation positions, Variations, Variations +@subsection Creating variations + +@c lispfun chess-var-create + +@defun chess-var-create &optional position +Create a new chess variation object. +Optionally use the given starting @var{position}. +@end defun + +@node Variation positions, Varation plies, Creating variations, Variations +@subsection Variation positions + +@c lispfun chess-var-pos + +@defun chess-var-pos var &optional index +Return the position related to @var{var}'s @var{index} ply. +@end defun + +@c lispfun chess-var-index + +@defun chess-var-index var +Return the @var{var}'s current position index. +@end defun + +@c lispfun chess-var-seq + +@defun chess-var-seq var +Return the current @var{var} sequence. +@end defun + +@c lispfun chess-var-side-to-move + +@defun chess-var-side-to-move var &optional index +Return the color whose move it is in @var{var} at @var{index} (or at the last position +of the variation if @var{index} is nil). +@end defun + +@node Varation plies, Making a move in a variation, Variation positions, Variations +@subsection Varation plies + +@c lispfun chess-var-ply + +@defun chess-var-ply var &optional index +Return @var{var}'s @var{index}th ply. +@end defun + +@c lispfun chess-var-plies + +@defun chess-var-plies var +Return the plies of @var{var}. +@end defun + +@c lispfun chess-var-to-algebraic + +@defun chess-var-to-algebraic var &optional long +Reveal the plies of @var{var} by converting them to algebraic +notation. +@end defun + +@node Making a move in a variation, , Varation plies, Variations +@subsection Making a move in a variation + +@c lispfun chess-var-move + +@defun chess-var-move var ply +Make a move in the current @var{var} by applying the changes of @var{ply}. +This creates a new position and adds it to the main variation. +The 'changes' of the last ply reflect whether the var is currently in +progress (nil), if it is drawn, resigned, mate, etc. +@end defun + +@c lispfun chess-var-add-ply + +@defun chess-var-add-ply var ply +Return the position related to @var{var}'s @var{index} position. +@end defun + +@node Games, Collections, Variations, The chess.el library +@section Games + +A @dfn{game} includes its main variation, incidental information about +the game (who played it, where, when, who won, etc), and any +sub-variations of interest to those studying the game afterwards. + +Where TAGS is an alist that associates arbitrary English tag names to +their values. + +A game may be represented in ASCII using standard PGN notation. +Representing them graphically or verbally is similar to what is done +for variations. + +@c lispfun chess-game-add-hook + +@defun chess-game-add-hook game function &optional data prepend +Add to @var{game} an event hook @var{function}. +@end defun + +@c lispfun chess-game-add-ply + +@defun chess-game-add-ply game ply +Return the position related to @var{game}'s @var{index} position. +@end defun + +@c lispfun chess-game-hooks + +@defun chess-game-hooks game +Return the tags alist associated with @var{game}. +@end defun + +@c lispfun chess-game-plies + +@defun chess-game-plies game +Return the main variation of @var{game} as a list of plies. +@end defun + +@c lispfun chess-game-remove-hook + +@defun chess-game-remove-hook game function &optional data +Remove from @var{game} all event hooks that match @var{function}. +If @var{data} is specified, only remove those hooks whose associated data +matches. +@end defun + +@c lispfun chess-game-run-hooks + +@defun chess-game-run-hooks game &rest args +Run the event hooks of @var{game} and pass @var{args}. +@end defun + +@c lispfun chess-game-set-hooks + +@defun chess-game-set-hooks game hooks +Return the tags alist associated with @var{game}. +@end defun + +@c lispfun chess-game-set-plies + +@defun chess-game-set-plies game plies +Set the list of plies which represents the main variation of @var{game}. +@end defun + +@menu +* Creating games:: +* Game tags:: +* Game positions:: +* Game plies:: +* Making a move:: +* PGN notation:: +@end menu + +@node Creating games, Game tags, Games, Games +@subsection Creating games + +@c lispfun chess-game-create + +@defun chess-game-create &optional position tags +Create a new chess game object. +Optionally use the given starting @var{position} (see also +`chess-game-set-start-position'). +@var{tags} is the starting set of game tags (which can always be changed +later using the various tag-related methods). +@end defun + +@node Game tags, Game positions, Creating games, Games +@subsection Game tags + +@c lispfun chess-game-tags + +@defun chess-game-tags game +Return the tags alist associated with @var{game}. +@end defun + +@c lispfun chess-game-set-tags + +@defun chess-game-set-tags game tags +Set the tags alist associated with @var{game}. +After the @var{tags} alist was set the 'set-tags event is triggered. +@end defun + +@c lispfun chess-game-tag + +@defun chess-game-tag game tag +Return the value for @var{tag} in @var{game}. +@end defun + +@c lispfun chess-game-set-tag + +@defun chess-game-set-tag game tag value +Set a @var{tag} for @var{game} to @var{value}. +@end defun + +@c lispfun chess-game-del-tag + +@defun chess-game-del-tag game tag +Delete a @var{tag} from @var{game}. +@end defun + +@node Game positions, Game plies, Game tags, Games +@subsection Game positions + +@c lispfun chess-game-pos + +@defun chess-game-pos game &optional index +Return the current position of @var{game} or a position of a given @var{index}. +@end defun + +@c lispfun chess-game-index + +@defun chess-game-index game +Return the @var{game}'s current position index. +@end defun + +@c lispfun chess-game-seq + +@defun chess-game-seq game +Return the current @var{game} sequence. +@end defun + +@c lispfun chess-game-side-to-move + +@defun chess-game-side-to-move game &optional index +Return the color whose move it is in @var{game} at @var{index} (or at the last position +if @var{index} is nil). +@end defun + +@node Game plies, Making a move, Game positions, Games +@subsection Game plies + +@c lispfun chess-game-ply + +@defun chess-game-ply game &optional index +Return a ply of @var{game}. +If @var{index} is non-nil, the last played ply is returned. +@end defun + +@node Making a move, PGN notation, Game plies, Games +@subsection Making a move + +@c lispfun chess-game-move + +@defun chess-game-move game ply +Make a move in the current @var{game} using @var{ply}. +This creates a new position and adds it to the main variation. +The 'changes' of the last ply reflect whether the game is currently in +progress (nil), if it is drawn, resigned, mate, etc. +@end defun + +@node PGN notation, , Making a move, Games +@subsection PGN notation + +@c lispfun chess-pgn-to-game + +@defun chess-pgn-to-game &optional string +Convert @var{pgn} notation at point into a chess game. +Optionally use the supplied @var{string} instead of the current buffer. +@end defun + +@c lispfun chess-game-to-pgn + +@defun chess-game-to-pgn game &optional indented to-string +Convert a chess @var{game} to @var{pgn} notation. +If @var{indented} is non-nil, indent the move texts. +If @var{to-string} is non-nil, return a string instead of inserting the resulting +@var{pgn} text. +@end defun + +@c lispfun chess-pgn-insert-plies + +@defun chess-pgn-insert-plies game index plies &optional for-black indented no-annotations +@var{nyi}: Still have to implement @var{indented} argument. +@end defun + +@menu +* PGN mode:: +@end menu + +@node PGN mode, , PGN notation, PGN notation +@subsubsection PGN mode + +@c lispfun chess-pgn-visualize + +@defun chess-pgn-visualize +Visualize the move for the @var{pgn} game under point. +This does not require that the buffer be in @var{pgn} mode. +@end defun + +@node Collections, , Games, The chess.el library +@section Collections + +A @dfn{collection} is a set of games archived for later perusal. A set +of games conceptually represents a large tree of branching variations, +and can be used for studying current theory, examining Master +preferences, etc. + +Chess.el itself does not attempt to provide library services, nor does it +ever represent library collections in memory. Instead, it interacts +with a chess database engine for the purpose of storing and retrieving +games from the library, or performing library-wide analyses and +searches. + +@menu +* Opening Databases:: +* Querying Databases:: +* Modifying Databases:: +* Finalising Databases:: +* Database Modules:: +@end menu + +@node Opening Databases, Querying Databases, Collections, Collections +@subsection Opening Databases + +@defvar chess-database-modules +List of database modules to try when `chess-database-open' is called. +@end defvar + +@c lispfun chess-database-open + +@defun chess-database-open file &optional module +Returns the opened database object, or nil. +@end defun + +@node Querying Databases, Modifying Databases, Opening Databases, Collections +@subsection Querying Databases + +@c lispfun chess-database-filename + +@defun chess-database-filename database +Return the filename of an already opened @var{database}. +@end defun + +@c lispfun chess-database-count + +@c lispfun chess-database-read + +@defun chess-database-read database index +Return from @var{database} the chess game object at @var{index}. +@end defun + +@c lispfun chess-database-query + +@defun chess-database-query database &rest terms +Run a query on @var{database}. +@var{terms} is partly dependent on the chess-database module in use. +chess-scid: + tree-search @var{game}: Perform a tree search on the last position of @var{game}. +@end defun + +@node Modifying Databases, Finalising Databases, Querying Databases, Collections +@subsection Modifying Databases + +@c lispfun chess-database-read-only-p + +@defun chess-database-read-only-p database +Return non-nil if @var{database} is read only. +@end defun + +@c lispfun chess-database-write + +@c lispfun chess-database-replace + +@node Finalising Databases, Database Modules, Modifying Databases, Collections +@subsection Finalising Databases + +@c lispfun chess-database-save + +@c lispfun chess-database-close + +@node Database Modules, , Finalising Databases, Collections +@subsection Database Modules + +Currently, there are two subclasses of the above defined +database base-class: + +@menu +* chess-file:: +* chess-scid:: +@end menu + +@node chess-file, chess-scid, Database Modules, Database Modules +@subsubsection chess-file + +This module does not use an external chess database program +to store and retrieve games. It uses the PGN of EPD format parsing +routines provided in `chess-pgn.el' and `chess-epd.el' to implement Collections +for ordinary PGN and EPD files. + +EPD file collections are represented as a collection of games originating +at the given position. One might argue that conceptually, they represent +a collection of positions, but it is more convenient to merge all +collections into one uniform concept. + +@node chess-scid, , chess-file, Database Modules +@subsubsection chess-scid + +This modules implement basic reading and writing functionality +for SCID (Shane's Chess Information Database) files. + +@node Modules, Chessboard displays, The chess.el library, Top +@chapter Modules + +Positions, plies and variations are typically accessed in reference to +a game object, which has a main variation containing the plies and +positions that represent the number of moves made within that game up +to the final position. + +Another thing that the game object does is to manage events that occur +within that game. If a move is made from the final position, for +example, it will cause a new ply to be created, adding it to the end +of the main variation. Then, a `move' event is triggered within the +game and passed to any chess modules which are currently associated +with that game. The concept of modules allows far more complex +aspects of chess playing to be dealt with, while allowing the library +itself to still operate solely in terms of the game object. + +For example, although the plies of a game object contain all the +information the computer needs to follow the game, a user needs much +more. He wants to see the pieces move. To support this, a display +module (see next chapter) can be created, and linked to the game. The +first effect of this association will be to create a chess board +display and show the game's final position on it. Now whenever plies +are added to the game, the chess board will be updated to show the +effect of that move on the board. The display module realizes that a +move has been made by receiving the `move' event which is passed to +all modules associated with the game object. + +There may be any number of modules associated with a chess game, and +they may do anything you like. Basically, for a module called +chess-sample, a function must exist called `chess-sample-handler'. +This takes two or more arguments: a game object, the event symbol, and +whatever other arguments were passed along with the event symbol. + +When an event is triggered on a game object (and this may happen as a +byproduct of manipulating the game, or events may be manually +generated), every associated module, in order, is called with that +event and whatever arguments were passed along with the event. The +game object is passed also, so that the module knows which game this +event has occurred in reference to. + +Once called, the module can do whatever it likes. Some events expect +certain values to be returned, to indicate success or failure in +processing the event. There are many different events, each depicting +something specific that might happen in the context of playing or +manipulating a chess game. Some events relate only to the chess game +itself, some are triggered by the various chess engines that might be +associated with that game. Modules may even trigger events in +response to event. The game itself remains unaware of events, except +for the fact that it will pass them along to every module associated +with that game. + +This is how displays get updated, for example, because once a 'move' +event is triggered, each display knows that it must now look at the +new final position and update its display. It may even trigger new +events special to displays, to cause a refresh to happen after update +calculations have been performed, for example. All such details are +left to the module, and the game does not interfere with such +intra-module messaging. + +Looked at as an object-oriented design, these are typical polymorphic +events. Certain generic situations frequently occur, such as moves, +which trigger events so that everyone concerned with the game can be +updated as to the move that occurred. This way, no one need to +actively query the game to find out if something new has happened. +The game will notify every listening module by sending an event. + +The core library, which consists of code to manipulate games, does not +define any modules. The rest of the chess.el library is strictly a +set of module implementations, of various types. Display modules +react to moves, and may modify the game based on user input; engine +modules react to moves by notifying the engine of the move; network +client modules react to moves by sending the move text over the +network. Engine and network modules may also trigger new events when +the engine or network player has decided on their move, and this move +is then applied to the game object. + +At the moment, no negotiation is done to determine which module may +modify the game object. All modules have equal privilege. This means +it is the programmer's duty not to associate conflicting modules with +a single game object. If two artificial intelligence engines were +linked, for example, they would quickly start stepping on each other's +toes. But it perfectly fine to have one artificial intelligence +engine, and another passive engine whose only purpose is to relay the +moves to a networked observer on another computer. The possibilities +are endless. + +Modules are very easy to write, although engines and displays are +rather different from each other in their principles. There is a base +engine, and a base display, which receive the same events as any other +module. But then there are derived engines and derived displays which +trigger a whole family of events specific to those module types. If +you suspect a bug in your module, put a breakpoint in your handler +function, and wait for the offending event to come through. Then you +can watch what your module does in response to that event. If it +leaves the game object alone, it should be easy to locate the problem, +since it will always be within the module itself. But if your module +also modifies the game object in response to certain events, you may +induce a feedback loop that is much more difficult to sort out. Test +often and keep in mind that *many* events might end up coming through +as a result of the game changes your module makes! + +That, in essence, is how the module system works. From the game +object's perspective, it is a very simple mechanism, much like a +function ring or a hook. The hook is called at certain points, so +that any listener can react to changes in the game. But from each +module's perspective, it is a rich way to allow inter-operation +between both passive and reactive modules, all of them acting together +to enrich the context of play involving the central game object. + +The only other rule to be mentioned is that each module instance +should be associated with only one game object at a time, although a +game object may have unlimited modules of any type linked to it. +Otherwise, trying to update a chess board based on input from two +different games would get impossible to sort out. Better to create a +new board for every game---the way ordinary humans would do it in the +real world. + +@node Chessboard displays, Engines, Modules, Top +@chapter Chessboard displays + +The previous chapter described all the objects found in +chess---positions, plies, variations, games and collections. However, +these objects can only be manipulated programmitically using the +functions given so far. In order to present them in a meaningful +fashion to a human reader, it is necessary to create and use a display +object. + +@menu +* Generic display manipulation functions:: +* Plain ASCII diagram displays:: +* ICS1 style ASCII displays:: +* Graphical displays:: +@end menu + +@node Generic display manipulation functions, Plain ASCII diagram displays, Chessboard displays, Chessboard displays +@section Generic display manipulation functions + +@c lispfun chess-display-create + +@defun chess-display-create game style perspective +Create a chess display, for displaying chess objects. +Where @var{game} is the chess game object to use, @var{style} should be the display +type to use (a symbol) and @var{perspective} determines the viewpoint +of the board, if non-nil, the board is viewed from White's perspective. +@end defun + +@c lispfun chess-display-destroy + +@c lispfun chess-display-active-p + +@defun chess-display-active-p +Return non-nil if the displayed chessboard reflects an active game. +Basically, it means we are playing, not editing or reviewing. +@end defun + +@c lispfun chess-display-clear-board + +@defun chess-display-clear-board +Setup the current board for editing. +@end defun + +@c lispfun chess-display-game + +@c lispfun chess-display-highlight + +@defun chess-display-highlight display &rest args +Highlight the square at @var{index} on the current position. +The given highlighting @var{mode} is used, or the default if the style you +are displaying with doesn't support that mode. `selected' is a mode +that is supported by most displays, and is the default mode. +@end defun + +@c lispfun chess-display-index + +@c lispfun chess-display-invert + +@defun chess-display-invert +Invert the perspective of the current chess board. +@end defun + +@c lispfun chess-display-move + +@defun chess-display-move display ply &optional prev-pos pos +Move a piece on @var{display}, by applying the given @var{ply}. +The position of @var{ply} must match the currently displayed position. +If only @var{start} is given, it must be in algebraic move notation. +@end defun + +@c lispfun chess-display-move-backward + +@c lispfun chess-display-move-first + +@c lispfun chess-display-move-forward + +@c lispfun chess-display-move-last + +@c lispfun chess-display-perspective + +@defun chess-display-perspective display +Return the current perspective of @var{display}. +@end defun + +@c lispfun chess-display-ply + +@c lispfun chess-display-position + +@defun chess-display-position display +Return the position currently viewed on @var{display}. +@end defun + +@c lispfun chess-display-quit + +@defun chess-display-quit +Quit the game associated with the current display. +@end defun + +@c lispfun chess-display-set-game + +@defun chess-display-set-game display game &optional index +Set the given @var{display} to display the @var{game} object, optionally at @var{index}. +This is the function to call to cause a display to view a game. It +will also update all of the listening engines and other displays to +also view the same game. +@end defun + +@c lispfun chess-display-set-index + +@c lispfun chess-display-set-perspective + +@defun chess-display-set-perspective display perspective +Set @var{perspective} of @var{display}. +@end defun + +@c lispfun chess-display-set-ply + +@c lispfun chess-display-set-position + +@defun chess-display-set-position display &optional position my-color +Set the game associated with @var{display} to use @var{position} and @var{my-color}. +@end defun + +@c lispfun chess-display-set-variation + +@defun chess-display-set-variation display variation &optional index +Set @var{display} @var{variation}. +If @var{index} is not specified, this will cause the first ply in the variation +to be displayed, with the user able to scroll back and forth through the +moves in the variation. Any moves made on the board will extend/change the +variation that was passed in. +@end defun + +@c lispfun chess-display-update + +@defun chess-display-update display &optional popup +Update the chessboard @var{display}. @var{popup} too, if that arg is non-nil. +@end defun + +@c lispfun chess-display-variation + +@node Plain ASCII diagram displays, ICS1 style ASCII displays, Generic display manipulation functions, Chessboard displays +@section Plain ASCII diagram displays + +The simplest display style available is chess-plain, a very customisable +ASCII board diagram display. + +@defvar chess-plain-separate-frame +If non-nil, display the chessboard in its own frame. +@end defvar + +@defvar chess-plain-draw-border +Non-nil if a border should be drawn (using `chess-plain-border-chars'). +@end defvar + +@defvar chess-plain-border-chars +A list of Characters used to draw borders. +@end defvar + +@defvar chess-plain-black-square-char +Character used to indicate empty black squares. +@end defvar + +@defvar chess-plain-white-square-char +Character used to indicate black white squares. +@end defvar + +@defvar chess-plain-piece-chars +Alist of pieces and their corresponding characters. +@end defvar + +@defvar chess-plain-upcase-indicates +Defines what a upcase char should indicate. +The default is 'color, meaning a upcase char is a white piece, a +lowercase char a black piece. Possible values: 'color (default), +'square-color. If set to 'square-color, a uppercase character +indicates a piece on a black square. (Note that you also need to +modify `chess-plain-piece-chars' to avoid real confusion.) +@end defvar + +@defvar chess-plain-spacing +Number of spaces between files. +@end defvar + +@node ICS1 style ASCII displays, Graphical displays, Plain ASCII diagram displays, Chessboard displays +@section ICS1 style ASCII displays + +@defvar chess-ics1-separate-frame +If non-nil, display the chessboard in its own frame. +@end defvar + +@node Graphical displays, , ICS1 style ASCII displays, Chessboard displays +@section Graphical displays + +@node Engines, Internet Chess Servers, Chessboard displays, Top +@chapter Engines + +Engines are the representation of an opponent in Chess. THe main type +of engine interfaces with an external chess program. However, there +can be other uses for engine objects, such as providing networked engined +for playing with opponent over different types of transports. + +@menu +* Common functions:: +* Crafty:: +* Gnu Chess:: +* Phalanx:: +* Sjeng:: +@end menu + +@node Common functions, Crafty, Engines, Engines +@section Common functions + +@c lispfun chess-engine-create + +@defun chess-engine-create module game &optional response-handler &rest handler-ctor-args +Create a new chess engine @var{module} (a symbol) associated with @var{game}. +Optionally supply a new @var{response-handler}. +@end defun + +@c lispfun chess-engine-set-option + +@defun chess-engine-set-option engine option value +Set @var{engine} @var{option} to @var{value} by invoking its handler with the 'set-option +event. +@end defun + +@c lispfun chess-engine-destroy + +@c lispfun chess-engine-set-position + +@c lispfun chess-engine-position + +@defun chess-engine-position engine +Return the current position of the game associated with @var{engine}. +@end defun + +@c lispfun chess-engine-set-game + +@c lispfun chess-engine-game + +@c lispfun chess-engine-index + +@c lispfun chess-engine-move + +@c lispfun chess-engine-command + +@defun chess-engine-command engine event &rest args +Call the handler of @var{engine} with @var{event} (a symbol) and @var{args}. +@end defun + +@c lispfun chess-engine-send + +@defun chess-engine-send engine string +Send the given @var{string} to @var{engine}. +If `chess-engine-process' is a valid process object, use `process-send-string' +to submit the data. Otherwise, the 'send event is triggered and the engine +event handler can take care of the data. +@end defun + +@node Crafty, Gnu Chess, Common functions, Engines +@section Crafty + +@node Gnu Chess, Phalanx, Crafty, Engines +@section Gnu Chess + +@node Phalanx, Sjeng, Gnu Chess, Engines +@section Phalanx + +@node Sjeng, , Phalanx, Engines +@section Sjeng + +@node Internet Chess Servers, Concept Index, Engines, Top +@chapter Internet Chess Servers + +Based on the services provided above, there is also a speical mode +for communication with Internet Chess Servers. + +ON an Internet Chess Server you can seek to play against other +human or computer players, observe other games being player or examined, +play tournaments, chat with fellow chess players, participate in a team game, +or do various other interesting chess related things. + +A default set of well known servers is defined in the following variable: + +@defvar chess-ics-server-list +A list of servers to connect to. +The format of each entry is: + + (SERVER PORT [HANDLE] [PASSWORD-OR-FILENAME] [HELPER] [HELPER ARGS...]) +@end defvar + +@menu +* Connecting to a server:: +* Seeking an opponent for a new game:: +* The sought game display:: +@end menu + +@node Connecting to a server, Seeking an opponent for a new game, Internet Chess Servers, Internet Chess Servers +@section Connecting to a server + +To open a new connection to an Internet Chess Server, use: + +@c lispfun chess-ics + +@defun chess-ics server port &optional handle password-or-filename helper &rest helper-args +Connect to an Internet Chess Server. +@end defun + +@node Seeking an opponent for a new game, The sought game display, Connecting to a server, Internet Chess Servers +@section Seeking an opponent for a new game + +After you connected to a server, one of the first things you will +want to do is find an oponent for a new game. You can use the +ICS command "seek" to announce your availability for a chess game +to interested people. + +@node The sought game display, , Seeking an opponent for a new game, Internet Chess Servers +@section The sought game display + +There is a special mode for displaying games sought by other users +on an Internet Chess Server. Provided you didn't turn off seek ads +manually (for instance by setting the seek variable to 0 (off) on the +ICS server by issueing "set seek 0"), the first seek advertisment +automatically pops up a new window which is in `chess-ics-sought-mode'. + +@c lispfun chess-ics-sought-mode + +@defun chess-ics-sought-mode +A mode for displaying @var{ics} game seek advertisments. + +This mode runs the hook `chess-ics-sought-mode-hook', as the final step +during initialization. + +key binding +--- ------- + +@var{ret} chess-ics-sought-accept +@var{spc} chess-ics-sought-toggle-sort-direction +? describe-mode +s chess-ics-sought-toggle-sort-state +<mouse-2> chess-ics-sought-accept + + +@end defun + +In this buffer, use mouse-2 or @kbd{RET} on a line to accept that +particular game and play it. + +@node Concept Index, Function and Variable Index, Internet Chess Servers, Top +@unnumbered Concept Index + +@printindex cp + +@node Function and Variable Index, Key Index, Concept Index, Top +@unnumbered Function and Variable Index + +@printindex fn + +@node Key Index, , Function and Variable Index, Top +@unnumbered Key Index + +@printindex ky +@bye |