\input texinfo @c -*-texinfo-*- @c "@(#)$Name$:$Id$" @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 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{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 Chess.el Chess.el is an Emacs chess environment, designed in a modular fashion to be used either as a library for writing chess-related programs, or as a plain client for playing chess, analyzing variations, or browsing historical games. 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 the optional modules which make it useful as a client. These modules also serve as an example of how to make use of the library. @end ifinfo @menu * The Chess.el library:: * Displays:: * Play sessions:: * Display modules:: * Ply sources:: @end menu @node The Chess.el library, Displays, 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 the chess board, reflecting also 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 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:: * Manipulating pieces:: * Position details:: * Annotations:: * FEN notation:: @end menu @node Creating positions, Position coordinates, Positions, Positions @subsection Creating positions @defun chess-pos-create &optional blank @end defun @defun chess-pos-copy position @end defun @defvar chess-starting-position @end defvar @node Position coordinates, Manipulating pieces, Creating positions, Positions @subsection Position coordinates @defun chess-index-rank index @end defun @defun chess-index-file index @end defun @defun chess-rf-to-index rank file @end defun @defun chess-coord-to-index coord @end defun @defun chess-index-to-coord index @end defun @defun chess-add-index index rank-move file-move @end defun @node Manipulating pieces, Position details, Position coordinates, Positions @subsection Manipulating pieces @defun chess-pos-piece position index @end defun @defun chess-pos-piece-p position index piece-or-color @end defun @defun chess-pos-set-piece position index piece @end defun @defun chess-pos-search position piece-or-color @end defun @node Position details, Annotations, Manipulating pieces, Positions @subsection Position details @defun chess-pos-can-castle position side @end defun @defun chess-pos-set-can-castle position side value @end defun @defun chess-pos-en-passant position @end defun @defun chess-pos-set-en-passant position index @end defun @defun chess-pos-status position @end defun @defun chess-pos-set-status position status @end defun @defun chess-pos-side-to-move position @end defun @defun chess-pos-set-side-to-move position color @end defun @node Annotations, FEN notation, Position details, Positions @subsection Annotations @defun chess-pos-annotation position @end defun @defun chess-pos-add-annotation position annotation @end defun @node FEN notation, , Annotations, Positions @subsection FEN notation @defun chess-fen-to-pos fen-string @end defun @defun chess-pos-to-fen position &optional full @end defun @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 @defun chess-ply-create position &rest changes @end defun @defun chess-legal-plies position color @end defun @node Ply details, The "next" position, Creating plies, Plies @subsection Ply details @defun chess-ply-pos ply @end defun @defun chess-ply-set-pos ply position @end defun @defun chess-ply-changes ply @end defun @defun chess-ply-set-changes ply changes @end defun @node The "next" position, Algebraic notation, Ply details, Plies @subsection The "next" position @defun chess-ply-next-pos ply @end defun @node Algebraic notation, , The "next" position, Plies @subsection Algebraic notation @defun chess-ply-to-algebraic ply &optional long @end defun @defun chess-algebraic-to-ply position move @end defun @defvar chess-algebraic-regexp @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. @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. @menu * Creating games:: * Game tags:: * Game positions:: * Game plies:: @end menu @node Creating games, Game tags, Games, Games @subsection Creating games @defun chess-game-create &optional tags position @end defun @node Game tags, Game positions, Creating games, Games @subsection Game tags @defun chess-game-tags game @end defun @defun chess-game-set-tags game tags @end defun @defun chess-game-tag game tag @end defun @defun chess-game-set-tag game tag value @end defun @defun chess-game-del-tag game tag @end defun @node Game positions, Game plies, Game tags, Games @subsection Game positions @defun chess-game-pos game &optional index @end defun @defun chess-game-index game @end defun @defun chess-game-seq game @end defun @defun chess-game-side-to-move game @end defun @node Game plies, , Game positions, Games @subsection Game plies @defun chess-game-ply game &optional index @end defun @subsection Making a move @defun chess-game-move game ply @end defun @subsection PGN notation @defun chess-pgn-to-game @end defun @defun chess-game-to-pgn game &optional indented @end defun @defun chess-pgn-insert-plies index plies &optional for-black indented no-ann @end defun @subsubsection PGN mode @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, or 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. @node Displays, Play sessions, The Chess.el library, Top @chapter 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. @defun chess-display-create style perspective &optional session search-func Create a display, using the given @var{style}. The initial @var{perspective}---non-nil for white, nil for black---determines the orientation, which can be inverted by the user afterward. If @var{session} is given, the display is linked to that @var{session}, and any moves made on the board that pertain to the current game's final position, will be transmitted to the @var{session}. If there is no @var{session}, then moves are made directly to the game itself. Thus, use @var{session} when you want to play, and don't when you want to review/edit games. @var{search-func} can be a function which is used to search out legal chess moves when editing position, plies and variations. Since game object already know the search function to use for that game, this argument is ignored when a game object is being manipulated. The default value is @code{chess-standard-search-position}. The return value is a display object, which must be passed to all of the other functions in the section. It is the buffer containing the chessboard. @end defun @defun chess-display-destroy display Destroy the given @var{display} object, freeing all memory used by it. @end defun @defun chess-display-set-perspective display perspective Change the perspective on @var{display} to @var{perspective}, which must be non-nil for a board from white's perspective, and nil for a board from black's perspective. @end defun @defun chess-display-search-function display Return the search function being used by the @var{display} to validate moves. @end defun @defun chess-display-search-position display position target piece @end defun @defun chess-display-set-position display position &optional search-func @end defun @defun chess-display-position display @end defun @defun chess-display-set-ply display ply &optional search-func @end defun @defun chess-display-ply display @end defun @defun chess-display-set-variation display plies &optional index search-func @end defun @defun chess-display-variation display @end defun @defun chess-display-set-game display game &optional index @end defun @defun chess-display-game display @end defun @defun chess-display-set-index display index @end defun @defun chess-display-index display @end defun @defun chess-display-update display @end defun @defun chess-display-move display start &optional target @end defun @defun chess-display-highlight display index &optional mode @end defun @node Play sessions, Display modules, Displays, Top @chapter Play sessions @node Display modules, Ply sources, Play sessions, Top @chapter Display modules @node Ply sources, , Display modules, Top @chapter Ply sources @menu * Chess engines:: @end menu @node Chess engines, , Ply sources, Ply sources @section Engines @defun chess-engine-create style callback &optional session @end defun @defun chess-engine-set-option engine option value @end defun @defun chess-engine-option engine option @end defun @c 'ponder @c 'search-depth @c 'wall-clock @defun chess-engine-destroy engine @end defun @defun chess-engine-set-position engine position ; uses 'edit' command @end defun @defun chess-engine-position engine @end defun @defun chess-engine-set-game engine game @end defun @defun chess-engine-game engine @end defun @defun chess-engine-index engine @end defun @defun chess-engine-move engine ply @end defun @defun chess-engine-command engine string @end defun @unnumbered Concept Index @printindex cp @unnumbered Function and Variable Index @printindex fn @unnumbered Key Index @printindex ky @bye