\input texinfo  @c -*-texinfo-*-

@setfilename chess.info
@documentencoding UTF-8
@documentlanguage en
@settitle Emacs Chess: chess.el

@copying
Copyright @copyright{} 2001, 2002, 2004, 2014 Free Software Foundation, @abbr{Inc.}

@quotation
Permission is granted to copy, distribute and/or modify this document
under the terms of the @acronym{GNU} Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with no
Invariant Sections, with the Front-Cover Texts being ``A @acronym{GNU} Manual,''
and with the Back-Cover Texts as in (a) below.  A copy of the license
is included in the section entitled ``@acronym{GNU} Free Documentation License.''

(a) The @acronym{FSF}'s Back-Cover Text is: ``You have the freedom to copy and
modify this @acronym{GNU} manual.''
@end quotation
@end copying

@dircategory Emacs
@direntry
* Chess: (chess).     Chess.el is an Emacs chess client.
@end direntry
@setchapternewpage on

@ifinfo
@insertcopying
@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 1
@center @titlefont{to}
@sp 1
@center @titlefont{Emacs Chess: chess.el}
@ignore
@sp 2
@center release 2.0
@c -release-
@end ignore
@sp 3
@center John Wiegley and Mario Lang
@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
@insertcopying
@end titlepage

@contents

@c ================================================================
@c                   The real text starts here
@c ================================================================

@ifnottex
@node Top, The chess.el library
@top Emacs Chess: chess.el

@file{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 @file{chess.el} is
structured for use as a library, and also how to use it as a client.
@end ifnottex

@menu
* The chess.el library::        Basic objects required to deal with Chess
* Modules::                     The module-system explained
* Chessboard displays::         Different types of chessboards in a buffer
* Engines::                     Internal and external chess-playing engines
* Chess Session::               Tying it all together
* Internet Chess Servers::      Playing chess with other people
* GNU Free Documentation License::
* Concept Index::
* Function and Variable Index::
* Key Index::
@end menu

@node The chess.el library
@chapter The @file{chess.el} library
@cindex library

  This chapter documents the low-level aspects of @file{chess.el}, mostly targeting
developers interested in understanding the underlying @acronym{API}s@.

@xref{Chessboard displays}, and the chapters following it,
if you are interested in the more user-visible aspects of @file{chess.el}.

@menu
* Positions::
* Plies::
* Variations::
* Games::
* Collections::
* Chess Opening Books::
@end menu

@node Positions
@section Positions
@cindex position

A chess @dfn{position} is a given layout of pieces on a chess board,
also reflecting which @dfn{side} (i.e., player) 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 @acronym{ASCII} using @acronym{FEN} (or EPD), 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 @acronym{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 @acronym{FEN}
specification.

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
@subsection Creating positions
@cindex creating positions
@cindex position, creating

@defun chess-pos-create &optional blank
Create a new chess position, set at the starting position.
If @var{blank} is non-@code{nil}, all of the squares will be empty.
The current side-to-move is always white.
@end defun

@defun chess-pos-copy position
Copy the given chess @var{position}.
If there are annotations or @acronym{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

@defun chess-fischer-random-position
Generate a Fischer Random style position.
@end defun

@node Position coordinates
@subsection Position coordinates
@cindex coordinates
@cindex position coordinates

First of all, position coordinates use a coordinate system of octal indices,
where the index @samp{?\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.

@defun chess-index-rank index
Return the rank component of the given @var{index}.
@end defun

@defun chess-index-file index
Return the file component of the given @var{index}.
@end defun

@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 @acronym{ASCII} coordinates, such as "e4", there
are two conversion functions:

@defun chess-coord-to-index coord
Convert a @var{coord} string into an index value.
@end defun

@defun chess-index-to-coord index
Convert the chess position @var{index} into a coord string.
@end defun

For fast manipulation of chess position indices, the following
constants and functions are provided:

@cindex queen
@cindex rook
For queens and rooks:

@cindex north
@defvr Constant chess-direction-north
Signify one step north, as seen from the perspective of the white player.
@end defvr

@cindex east
@defvr Constant chess-direction-east
Signify one step east, as seen from the perspective of the white player.
@end defvr

@cindex south
@defvr Constant chess-direction-south
Signify one step south, as seen from the perspective of the white player.
@end defvr

@cindex west
@defvr Constant chess-direction-west
Signify one step west, as seen from the perspective of the white player.
@end defvr

@cindex queen
@cindex bishop
For queens and bishops:

@cindex northeast
@defvr Constant chess-direction-northeast
Signify one step northeast, as seen from the perspective of the white player.
@end defvr

@cindex southeast
@defvr Constant chess-direction-southeast
Signify one step southeast, as seen from the perspective of the white player.
@end defvr

@cindex southwest
@defvr Constant chess-direction-southwest
Signify one step southwest, as seen from the perspective of the white player.
@end defvr

@cindex northwest
@defvr Constant chess-direction-northwest
Signify one step northwest, as seen from the perspective of the white player.
@end defvr

@defun chess-next-index index direction
Create a new @var{index} from an old one, by advancing it into @var{direction}.
If the resulting index is not valid (outside the board), @code{nil} is returned.
@end defun

Due to the underlying technique used to efficiently detect off-board squares,
a direction specifier should at most do two steps in any direction.
Directions can be combined, so that @code{(* chess-direction-north 2)}
will give a typical initial white pawn push.

@node Position details
@subsection Position details

Given an octal index value, you can look up what's on a particular
square, or set that square's value:

@defun chess-pos-piece position index
Return the piece on @var{position} at @var{index}.
@end defun

@defun chess-pos-piece-p position index piece-or-color
Return non-@code{nil} if the given @var{piece-or-color} is at @var{position}/@var{index}.
If @var{piece-or-color} is @code{t} for white or @code{nil} for black, any piece of that
color will do.
@end defun

@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 @code{?K}, @code{?Q}, @code{?N}, @code{?B},
@code{?R}, or @code{?P} for white pieces, or one of the corresponding
lowercase letters for black pieces.
@end defun

@defun chess-pos-search position piece-or-color
Look anywhere on @var{position} for @var{piece-or-color}, returning all coordinates.
If @var{piece-or-color} is @code{t} for white or @code{nil} for black, any piece of that
color will do.
@end defun

@defun chess-pos-search* position &rest pieces
Look on @var{position} for any of @var{pieces}.

The result is an alist where each element looks like @w{@code{(@var{piece} . @var{indices})}}.
Pieces which did not appear in @var{position} will be present in the resulting
alist, but the @code{cdr} of their entries will be @code{nil}.
@end defun

@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 valid paths of movement for @var{piece}.  It
differs from @code{chess-pos-search}, which is a more basic function that
doesn't take piece movement into account.

If @var{piece} is @code{t} or @code{nil}, valid piece movements for any piece of that
color will be considered (@code{t} for white, @code{nil} for black).  Otherwise, the
letter-case of the @var{piece} determines color.

The return value is a list of candidates, which means a list of
indices that indicate where a piece may have moved from.

If @var{check-only} is non-@code{nil} and @var{piece} is either @code{t} or @code{nil}, only consider
pieces which can give check (not the opponent's king).
If @var{no-castling} is non-@code{nil}, do not consider castling moves.
@end defun

@defun chess-pos-can-castle position side
Return whether the king on @var{position} can castle on @var{side}.
The @var{side} argument must be either @samp{?K} for the king side, or @samp{?Q} for the queen side (use
lowercase to query if black can castle).
@end defun

@defun chess-pos-set-can-castle position side value
Set whether the king can castle on the given @var{position} on @var{side}.

See @code{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
privileges set, unless the position is created blank, in which case
castling privileges are unset.  See @code{chess-pos-create}.
@end defun

@defun chess-pos-en-passant position
Return the index of any pawn on @var{position} that can be captured en passant.
Returns @code{nil} if en passant is unavailable.
@end defun

@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

@defun chess-pos-status position
Return whether the side to move in the @var{position} is in a special state.
Return @code{nil} if not, otherwise one of the keywords: @code{:check},
@code{:checkmate} or @code{:stalemate}.
@end defun

@defun chess-pos-set-status position value
Set whether the side to move in @var{position} is in a special state.
The @var{value} should either be @code{nil}, to indicate that the @var{position} is normal,
or one of the symbols: @code{check}, @code{checkmate}, @code{stalemate}.
@end defun

@defun chess-pos-side-to-move position
Return the color whose move it is in @var{position}.
@end defun

@defun chess-pos-set-side-to-move position color
Set the color whose move it is in @var{position}.
@end defun

@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-@code{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

@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
@subsection Annotations
@cindex annotations

@defun chess-pos-annotations position
Return the list of annotations for this position.
@end defun

@defun chess-pos-add-annotation position annotation
Add an annotation for this position.
@end defun

@node FEN notation
@subsection FEN notation
@cindex FEN notation

@acronym{@dfn{FEN}, Forsyth-Edwards Notation} encodes a chess position using
a simple string.  The format is:

@example
   @var{position} @var{side} @var{castling} @var{en-passant}
@end example

The @var{position} gives all eight ranks, by specifying a letter for each
piece in the position, and a number for any intervening spaces; ranks are
separated by slashes.
Trailing spaces need not be counted.  Uppercase letters signify
white pieces, and lowercase black.  For example, if your position only had
a black king on d8, your @var{position} string would be:

@example
3k////////
@end example

@noindent
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 @var{side} is @samp{w} or @samp{b}, to indicate whose move it is.

The @var{castling} can contain @samp{K}, @samp{Q}, @samp{k} or @samp{q}, to signify
whether the white or black king can still castle on the king or queen side.
If neither color can castle on any side, @samp{-} should be provided.

The @var{en-passant} signifies the target square of an en passant capture, such as
@samp{e3} or @samp{a6}.

@defun chess-fen-to-pos fen
Convert the @acronym{FEN} string @var{fen} to a chess position.
@end defun

@defun chess-pos-to-fen position &optional full
Convert a chess @var{position} to a @acronym{FEN} string.
If @var{full} is non-@code{nil}, represent trailing spaces as well.
@end defun

This is how the starting position looks like:

@vindex chess-starting-position
@lisp
 (chess-pos-to-fen chess-starting-position)
 @result{} "rnbqkbnr/pppppppp/////PPPPPPPP/RNBQKBNR w KQkq -"
@end lisp

Some external programs might have problems parsing terse
@acronym{FEN} strings.  If you are unsure, use the more verbose form:

@lisp
 (chess-pos-to-fen chess-starting-position t)
 @result{} "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq -"
@end lisp

@node EPD notation
@subsection EPD notation
@cindex EPD notation

@acronym{@dfn{EPD}, Extended Position Description} is a standard for describing chess
positions along with an extended set of structured attribute values using the
@acronym{ASCII} character set.  It is intended for data and command interchange
among chess-playing programs.  It is also intended for the representation of
portable opening library repositories.

A single @acronym{EPD} uses one text line of variable length composed of four data fields,
followed by zero or more operations.  The four fields of the @acronym{EPD} specification
are the same as the first four fields of the @acronym{FEN} specification (@pxref{FEN notation}).

A text file composed exclusively of @acronym{EPD} data records should have a file name
with the @file{.epd} extension.

@defun chess-epd-to-pos &optional string
Convert extended position description @var{string} to a chess position.
If @var{string} is not specified, look for an @acronym{EPD} string in the current buffer,
and advance point after the correctly parsed position.
@end defun

@defun chess-pos-to-epd position
Convert a chess @var{position} to a string representation in extended
position description format.
@end defun

@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
@subsubsection Operations
@cindex EPD operations
@cindex opcodes

An @acronym{EPD} operation is composed of an opcode followed by zero or
more operands, and terminated by a semicolon.

Multiple operations are separated by a single space character.  If there is at
least one operation present in an @acronym{EPD} record, 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 @samp{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 @acronym{ASCII} order.  An example of the latter set is the @samp{bm}
(best move[s]) opcode; its operands are moves that are all immediately playable
from the current position.

@node Opcode "acd" analysis count depth
@subsubsection Opcode @samp{acd} analysis count depth
@cindex @samp{acd} opcode

The opcode @samp{acd} takes a single non-negative integer operand.  It is used to
represent the depth of the ply (@pxref{Plies}) examined in an analysis.

@node Opcode "acn" analysis count nodes
@subsubsection Opcode @samp{acn} analysis count nodes
@cindex @samp{acn} opcode

The opcode @samp{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
@subsubsection Opcode @samp{acs} analysis count seconds
@cindex @samp{acs} opcode

The opcode @samp{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)
@subsubsection Opcode @samp{am} avoid move(s)
@cindex @samp{am} opcode

The opcode @samp{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 @acronym{EPD}
writer.  Each operand is a @acronym{SAN} move; they appear in @acronym{ASCII} order.

@node Opcode "bm" best move(s)
@subsubsection Opcode @samp{bm} best move(s)
@cindex @samp{bm} opcode

The opcode @samp{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 @acronym{EPD}
writer.  Each operand is a @acronym{SAN} move; they appear in @acronym{ASCII} order.

@node Plies
@section Plies
@cindex ply

A @dfn{ply} is the differential between two positions.  In other words, 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 @acronym{ASCII} by printing the @acronym{FEN} string
of the base position, and then printing the positional transformation in algebraic
notation.  Since the starting position is usually known, the @acronym{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, @abbr{etc.},
so long as the current position is maintained at both sides.
Transmitting the base position's @acronym{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
@subsection Creating plies
@cindex creating plies
@cindex ply, creating

@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 valid, and will also
annotate the ply with @code{: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

@defun chess-legal-plies position &rest keywords
Return a list of all valid plies in @var{position}.
The allowed @var{keywords} are:

@table @code
@item :any
Return @code{t} if any piece can move at all.

@item :color @var{boolean}
If @var{boolean} is @code{t}, return plies for white, if @code{nil}, return
plies for black.

@item :piece @var{character}
Return plies for a specific piece designated by @var{character}.

@item :file @var{file}
Given a @var{file}, a number (0-7), return plies for any piece or color
present on that @var{file}.  @code{:piece} or @code{:color} must be present.

@item :index @var{index}
Return plies for the piece at @var{index}.

@item :target @var{index}
Return plies that go to a specific coordinate specified by @var{index}.

@item :candidates @var{index}@enddots{}
If provided, only consider the source coordinates specified by the indices.
@end table

These will constrain the plies generated to those matching the above
criteria.

NOTE: All of the returned plies will reference the same copy of the
position object passed in.
@end defun

@node Ply details
@subsection Ply details
@cindex ply details

@defun chess-ply-pos ply
Return the base position associated with @var{ply}.
@end defun

@defun chess-ply-set-pos ply position
Set the base position of @var{ply}.
@end defun

@defun chess-ply-changes
Return the coordinate transformations and keywords associated with this @var{ply}.

Value is a list made of a pair of indices (or two pairs, in case of
castling) followed by optional keywords.
@end defun

@defun chess-ply-set-changes
Set the coordinate transformations and keywords associated with this @var{ply}.
@end defun

@defun chess-ply-source ply
Return the source square index value of @var{ply}.
@end defun

@defun chess-ply-target ply
Return the target square index value of @var{ply}.
@end defun

For example, here is how to find the source square of a freshly created ply:

@lisp
 (chess-ply-source (chess-ply-create chess-starting-position nil
                                     (chess-coord-to-index "e2")
                                     (chess-coord-to-index "e4")))
 @result{} 52
@end lisp

@node The "next" position
@subsection The ``next'' position

@defun chess-ply-next-pos ply
Return the position that results from executing @var{ply}.
@end defun

@defun chess-ply-final-p ply
Return non-@code{nil} if this is the last ply of a game/variation.
@end defun

@node Algebraic notation
@subsection Algebraic notation
@cindex algebraic notation

A thing to deal with in chess is algebraic move notation, such as
@samp{Nxf3+}.  This notation is a shorthand way of representing where
a piece is moving from and to, by specifying the piece involved,
where it's going, and whether or not a capture or check is
involved.

You can convert from algebraic notation to a ply using the following function:

@defun chess-algebraic-to-ply position move &optional trust
Convert the algebraic notation @var{move} for @var{position} to a ply.

If optional argument @var{trust} is non-@code{nil}, accept check or checkmate
symbols (@samp{+} and @samp{#}) as given.
@end defun

The function also checks if a move is valid, and will raise an
error if not.

To convert from a ply to algebraic notation, use:

@cindex standard algebraic notation
@cindex short algebraic notation
@cindex long algebraic notation
@cindex figurine algebraic notation
@cindex numeric notation
@defun chess-ply-to-algebraic ply &optional type
Convert the given @var{ply} to algebraic notation (a string).

Optional argument @var{type} specifies the kind of algebraic notation to
generate:

@table @code
@item :san
Generate short (or standard) algebraic notation.  This is the default.

@item :lan
Generate long algebraic notation (like @samp{Nb1-c3}).

@item :fan
Generate figurine algebraic notation (uppercase letters will
be replaced by Unicode chess figures).

@item :numeric
Generate ICCF numeric notation as used in correspondence
chess (like @samp{2133}).
@end table
@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 short, long and figurine algebraic notation.
@end defvar

@node Variations
@section Variations
@cindex variation

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 @acronym{ASCII} by stating the @acronym{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::
* Variation plies::
* Making a move in a variation::
@end menu

@node Creating variations
@subsection Creating variations
@cindex creating variations
@cindex variation, creating

@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
@subsection Variation positions
@cindex variation positions

@defun chess-var-pos variation &optional index
Return the position related to @var{variation}'s @var{index} ply.
@end defun

@defun chess-var-index variation
Return the @var{variation}'s current position index.
@end defun

@defun chess-var-seq variation
Return the current @var{variation} sequence.
@end defun

@defun chess-var-side-to-move variation &optional index
Return the color whose move it is in @var{variation} at @var{index} (or at the last position
of @var{variation} if @var{index} is @code{nil}).
@end defun

@node Variation plies
@subsection Variation plies
@cindex variation plies

@defun chess-var-ply variation &optional index
Return @var{variation}'s @var{index}th ply.
@end defun

@defun chess-var-plies variation
Return the plies of @var{variation}.
@end defun

@defun chess-var-to-algebraic variation &optional long
Reveal the plies of @var{variation} by converting them to algebraic
notation.
@end defun

@node Making a move in a variation
@subsection Making a move in a variation
@cindex variation, make a move

@defun chess-var-move variation ply
Make a move in the current @var{variation} by applying the changes of @var{ply}.
This creates a new position and adds it to the main variation.
The @samp{changes} of the last ply reflect whether the var is currently in
progress (@code{nil}), if it is drawn, resigned, mate, etc.
@end defun

@defun chess-var-add-ply variation ply
Add the given @var{ply} to @var{variation}.
@end defun

@node Games
@section Games
@cindex game

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.

@dfn{Game tags} is an alist that associates arbitrary English tag names to
their values.

A game may be represented in @acronym{ASCII} using @acronym{@dfn{PGN},
Portable Game Notation}.
Representing them graphically or verbally is similar to what is done
for variations (@pxref{Variations}).

@defun chess-game-add-hook game function &optional data prepend
Add to @var{game} an event hook @var{function}.
@end defun

@defun chess-game-add-ply game ply
Add @var{ply} to the main variation of @var{game}.
@end defun

@defun chess-game-hooks game
Return the event hooks associated with @var{game}.
@end defun

@defun chess-game-plies game
Return the main variation of @var{game} as a list of plies.
@end defun

@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 hooks with matching associated data.
@end defun

@defun chess-game-run-hooks game &rest args
Run the event hooks of @var{game} and pass it @var{args}.
@end defun

@defun chess-game-set-hooks game hooks
Set the event hooks associated with @var{game}.
@end defun

@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
@subsection Creating games
@cindex creating games
@cindex game, creating

@defun chess-game-create &optional position tags
Create a new chess game object.
Optionally use the given starting @var{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
@subsection Game tags
@cindex game tags
@cindex tags

@defun chess-game-tags game
Return the tags alist associated with @var{game}.
@end defun

@defun chess-game-set-tags game tags
Set the tags alist associated with @var{game}.
After the @var{tags} alist was set the @samp{set-tags} event is triggered.
@end defun

@defun chess-game-tag game tag
Return the value for @var{tag} in @var{game}.
@end defun

@defun chess-game-set-tag game tag value
Set the @var{tag} for @var{game} to @var{value}.
@end defun

@defun chess-game-del-tag game tag
Delete the specified @var{tag} from @var{game}.
@end defun

@node Game positions
@subsection Game positions
@cindex game positions

@defun chess-game-pos game &optional index
Return the current position of @var{game} or a position of a given @var{index}.
@end defun

@defun chess-game-index game
Return the @var{game}'s current position index.
@end defun

@defun chess-game-seq game
Return the current @var{game} sequence number.
@end defun

@defun chess-game-side-to-move game &optional index
Return the side, specified as color, whose move it is in @var{game} at @var{index} (or at the last position
if @var{index} is @code{nil}).
Value is @code{t} for white and @code{nil} for black.
@end defun

@node Game plies
@subsection Game plies
@cindex game plies

@defun chess-game-ply game &optional index
Return a ply of @var{game}.
If @var{index} is non-@code{nil}, the last played ply is returned.
@end defun

@node Making a move
@subsection Making a 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 @samp{changes} of the last ply reflect whether the game is currently in
progress (@code{nil}), if it is drawn, resigned, mate, etc.
@end defun

@node PGN notation
@subsection PGN notation
@cindex PGN notation

@defun chess-pgn-to-game &optional string
Convert the @acronym{PGN} notation at point into a chess game.
Optionally use the supplied @var{string} instead of the current buffer.
@end defun

@defun chess-game-to-pgn game &optional indented to-string
Convert a chess @var{game} to @acronym{PGN} notation.
If @var{indented} is non-@code{nil}, indent the move texts.
If @var{to-string} is non-@code{nil}, return a string instead of inserting the resulting
@acronym{PGN} text.
@end defun

@defun chess-pgn-insert-plies game index plies &optional for-black indented no-annotations
@emph{NYI}: Still have to implement the @var{indented} argument.
@end defun

@menu
* PGN mode::
@end menu

@node PGN mode
@subsubsection PGN mode
@cindex PGN mode

@defun chess-pgn-visualize
Visualize the move for the @acronym{PGN} game under point.
This does not require that the buffer be in PGN mode.
@end defun

@node Collections
@section Collections
@cindex collection

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.

@file{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::
* Finalizing Databases::
* Database Modules::
@end menu

@node Opening Databases
@subsection Opening Databases
@cindex opening database
@cindex collection database
@cindex database, opening

@defvar chess-database-modules
List of database modules to try when @code{chess-database-open} is called.
@end defvar

@defun chess-database-open file &optional module
Open a game database specified by @var{file}.
You can optionally specify the database @var{module} to use.

Returns the opened database object, or nil.
@end defun

@node Querying Databases
@subsection Querying Databases
@cindex querying databases

@defun chess-database-filename database
Return the filename of an already opened @var{database}.
@end defun

@c lispfun chess-database-count

@defun chess-database-read database index
Return from @var{database} the chess game object at @var{index}.
@end defun

@defun chess-database-query database &rest terms
Run a query on @var{database}.
The @var{terms} are partly dependent on the chess-database module in use.
For the @samp{chess-scid} module, using @code{tree-search @var{game}} means
perform a tree search on the last position of @var{game}.
@end defun

@node Modifying Databases
@subsection Modifying Databases
@cindex modifying databases
@cindex database, modifying

@defun chess-database-read-only-p database
Return non-@code{nil} if @var{database} is read only.
@end defun

@c lispfun chess-database-write

@c lispfun chess-database-replace

@node Finalizing Databases
@subsection Finalizing Databases

@c lispfun chess-database-save

@c lispfun chess-database-close

@node Database Modules
@subsection Database Modules
@cindex database modules

Currently, there are two subclasses of the above defined
database base-class:

@menu
* chess-file::
* chess-scid::
@end menu

@node chess-file
@subsubsection chess-file
@cindex chess-file module

This module does not use an external chess database program
to store and retrieve games.  It uses the @acronym{PGN} of @acronym{EPD} format parsing
routines provided in @file{chess-pgn.el} and @file{chess-epd.el} to implement collections
for ordinary @acronym{PGN} and @acronym{EPD} files.

@acronym{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
@subsubsection chess-scid
@cindex chess-scid module

This module implements basic reading and writing functionality
for @acronym{@dfn{SCID}, Shane's Chess Information Database} files.

@node Chess Opening Books
@section Chess Opening Books
@cindex chess opening books modules

There are two different modules/libraries provided for looking up
chess positions in opening books.

@menu
* ECO Classification::
* Polyglot opening book format support::
@end menu

@node ECO Classification
@subsection ECO Classification
@cindex ECO classification
@cindex chess-eco module

@vindex chess-default-modules
Module @code{chess-eco} provides a database of well known names
for chess opening positions.  If this module is activated (see variable
@code{chess-default-modules}), known chess opening positions will be announced
in the minibuffer during a game.

@node Polyglot opening book format support
@subsection Polyglot opening book format support
@cindex polyglot opening book format

The popular and freely documented Polyglot opening book format
is supported.  There is a default polyglot book file shipped with @file{chess.el}
to support engines which do not have built-in support for looking up positions
in opening books (such as some @acronym{UCI} protocol based engines).

@defopt chess-polyglot-book-file
Path to default polyglot book file.
@end defopt

@defvar chess-polyglot-book
If non-@code{nil}, the buffer holding the currently loaded polyglot book data.

This is used by @acronym{UCI} based engine modules as well as the internal AI.
@end defvar

@defun chess-polyglot-book-open file
Open a polyglot book @var{file}.

Returns a buffer object which contains the binary data.
@end defun

@findex chess-ply-keyword
@defun chess-polyglot-book-plies book position
Return a list of plies found in @var{book} for @var{position}.
The resulting list is ordered, most interesting plies come first.
The @code{:polyglot-book-weight} ply keyword is used to store the actual move weights.
Use @code{chess-ply-keyword} on elements of the returned list to retrieve them.
@end defun

@vindex chess-polyglot-book-strength
@defun chess-polyglot-book-ply book position &optional strength
If non-@code{nil}, a (randomly picked) ply from @var{book} for @var{position}.
Random distribution is defined by the relative weights of the found plies.
If non-@code{nil}, @var{strength} defines the bias towards better moves.
A value below 1.0 will penalize known good moves while a value
above 1.0 will prefer known good moves.  The default is the value
of @code{chess-polyglot-book-strength}.
A strength value of 0.0 will completely ignore move weights, and evenly
distribute the probability that a move gets picked.
@end defun

@node Modules
@chapter Modules
@cindex 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 @samp{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 (@pxref{Chessboard displays}) 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 @samp{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
@samp{chess-sample}, a function must exist called @code{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 (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 @samp{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 @file{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 is 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 @emph{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
@chapter Chessboard displays
@cindex chessboard display
@cindex display

The previous chapter described all the objects found in
chess---positions, plies, variations, games and collections.  However,
these objects can only be manipulated programmatically 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::
* Chess display mode::
* Plain ASCII diagram displays::
* ICS1 style ASCII displays::
* Graphical displays::
@end menu

@node Generic display manipulation functions
@section Generic display manipulation functions
@cindex display manipulation functions

@defun chess-display-create game style perspective
Create a chess display, for displaying chess objects.
The @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-@code{nil}, the board is viewed from White's perspective.
@end defun

@c lispfun chess-display-destroy

@defun chess-display-active-p
Return non-@code{nil} if the displayed chessboard reflects an active game.
Basically, it means we are playing, not editing or reviewing.
@end defun

@defun chess-display-clear-board
Setup the current board for editing.
@end defun

@c lispfun chess-display-game

@defun chess-display-highlight display &rest args
Highlight in @var{display} the squares given in @var{args} on the current position.

The @var{args} is a list of highlighting modes and position coordinates.
The default highlighting mode is @code{:selected} which is supported
by most displays.
@end defun

@c lispfun chess-display-index

@defun chess-display-invert
Invert the perspective of the current chess board.
@end defun

@defun chess-display-move display ply
Move a piece on @var{display}, by applying the given @var{ply}.
The position of @var{ply} must match the currently displayed position.
@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

@defun chess-display-perspective display
Return the current perspective of @var{display}.
@end defun

@c lispfun chess-display-ply

@defun chess-display-position display
Return the position currently viewed on @var{display}.
@end defun

@defun chess-display-quit
Quit the game associated with the current display.
@end defun

@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

@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}.  If @var{popup} is non-@code{nil},
make sure it is visible.
@end defun

@c lispfun chess-display-variation

@node Chess display mode
@section Chess display mode
@cindex chess display mode

@dfn{Chess display mode} is a special major mode (@pxref{Major Modes, , , emacs})
that allows to select pieces to move with the mouse or by moving
point to the desired square/piece.  Additionally, you can enter
moves in a variant of algebraic notation via the keyboard.

All the chessboard displays described in following sub-sections
share the basic behavior provided by chess display mode.
They basically only differ in appearance of the various chessboards.

@defopt chess-display-highlight-legal
If non-nil, highlight valid target squares when a piece is selected.
@end defopt

@menu
* Basic operations::
* Selecting pieces with the keyboard::
* Selecting pieces with the mouse::
* Entering moves with algebraic notation::
@end menu

@node Basic operations
@subsection Basic operations

@table @kbd
@kindex C-i
@kindex TAB
@item C-i
@itemx @key{TAB}
@findex chess-display-invert
Invert the perspective of the current chess board (@code{chess-display-invert}).

@kindex ,
@item ,
@findex chess-display-move-backward
Show the previous move in the current game (@code{chess-display-move-backward}).

@cindex algebraic notation, searching moves
@kindex C-r
@item C-r
@findex chess-display-search-backward
Find previous move which algebraic notation matches a regular expression
(@code{chess-display-search-backward}).

@kindex C-s
@item C-s
@findex chess-display-search-forward
Find next move which algebraic notation matches a regular expression
(@code{chess-display-search-forward}).

@kindex .
@item .
@findex chess-display-move-forward
Show the next move in the current game (@code{chess-display-move-forward}).

@kindex <
@item <
@findex chess-display-move-first
Move to the initial position of the current game (@code{chess-display-move-first}).

@kindex >
@item >
@findex chess-display-move-last
Move to the last position of the current game (@code{chess-display-move-last}).

@kindex C-c C-d
@item C-c C-d
@findex chess-display-draw
Offer to draw the current game (@code{chess-display-draw}).

@kindex C-c C-r
@item C-c C-r
@findex chess-display-resign
Resign the current game (@code{chess-display-resign}).

@kindex M-w
@kindex C-u M-w
@item M-w
@itemx C-u M-w
@findex chess-display-kill-board
Copy the currently displayed position to the kill ring as a @acronym{FEN} string
(@code{chess-display-kill-board}).

With prefix argument, copy the current game in @acronym{PGN} to the kill ring.

@kindex C-y
@item C-y
@findex chess-display-yank-board
Set the current display position via a @acronym{FEN} string from the kill ring
(@code{chess-display-yank-board}).

This is useful to copy positions from one chessboard
display to another, as well as quickly setting up a position
from a @acronym{FEN} string previously added to the kill ring from
somewhere else.

@kindex X
@item X
@findex chess-display-quit
Quit this chessboard display (@code{chess-display-quit}).

This destroys the session (and all related modules) associated with this
chessboard display.
@end table

@node Selecting pieces with the keyboard
@subsection Selecting pieces with the keyboard

In character based chessboard displays, point can be moved around
in the buffer as usual.  You can indicate the initial square/piece
and the target square/piece by moving point to the desired position
and pressing @kbd{@key{RET}}.

@table @kbd
@kindex RET
@item @key{RET}
@findex chess-display-select-piece
Select the piece/square currently indicated by point
(@code{chess-display-select-piece}) to move from/to.
@end table

@node Selecting pieces with the mouse
@subsection Selecting pieces with the mouse

Similarly, you can also use the mouse (if available) to indicate
the source and target square of your move.

@table @kbd
@kindex down-mouse-1
@kindex down-mouse-2
@kindex drag-mouse-1
@kindex drag-mouse-2
@item down-mouse-1
@itemx down-mouse-2
@itemx drag-mouse-1
@itemx drag-mouse-2
@findex chess-display-select-piece
Select the piece/square currently indicated by the mouse pointer
(@code{chess-display-select-piece}) to move from/to.
@end table

@node Entering moves with algebraic notation
@subsection Entering moves with algebraic notation
@cindex algebraic notation, entering moves with

@table @asis
@kindex a
@kindex b
@kindex c
@kindex d
@kindex e
@kindex f
@kindex g
@kindex h
@kindex 1
@kindex 2
@kindex 3
@kindex 4
@kindex 5
@kindex 6
@kindex 7
@kindex 8
@kindex N
@kindex B
@kindex R
@kindex Q
@kindex K
@kindex x
@kindex =
@item @kbd{a} @dots{} @kbd{h}
@itemx @kbd{1} @dots{} @kbd{8}
@itemx @kbd{N}
@itemx @kbd{B}
@itemx @kbd{R}
@itemx @kbd{Q}
@itemx @kbd{K}
@itemx @kbd{x}
@itemx @kbd{=}
@findex chess-input-shortcut
Enter move in algebraic notation.

The move will be accepted as soon as it is unambiguous.
So in most situations, you do not need to type the complete
algebraic move string.  For instance, if there is only one piece
which can be taken by one of your knights, typing @kbd{N x} is
sufficient to select that move.

Additionally, the characters @kbd{x} and @kbd{=} are optional,
as there is no difference between @kbd{N x e 4} and @kbd{N e 4}.

@kindex backspace
@item @key{backspace}
@findex chess-input-shortcut-delete
Delete the last entered chess move character (@code{chess-input-shortcut-delete}).

This is useful if you have accidentally typed a wrong character,
and the move was not unambiguous yet.
@end table

@node Plain ASCII diagram displays
@section Plain ASCII diagram displays
@cindex ASCII diagram display

The simplest display style available is @code{chess-plain}, a very customizable
@acronym{ASCII} board diagram display.

This is how the starting position looks in its default configuration:

@example
 +---------------+
8|r n b q k b n r|
7|p p p p p p p p|
6|. . . . . . . .|
5|. . . . . . . .|
4|. . . . . . . .|
3|. . . . . . . .|
2|P P P P P P P P|
1|R N B Q K B N R|
 +---------------+
  a b c d e f g h
@end example

@defopt chess-plain-separate-frame
If non-@code{nil}, display the chessboard in its own frame.
@end defopt

@defopt chess-plain-border-style
If non-@code{nil}, a vector of Characters used to draw borders.

Otherwise, omit to draw any border around the chessboard diagram.
@end defopt

@defopt chess-plain-black-square-char
Character used to indicate empty black squares.
@end defopt

@defopt chess-plain-white-square-char
Character used to indicate black white squares.
@end defopt

@defopt chess-plain-piece-chars
Alist of pieces and their corresponding characters.
@end defopt

@defopt chess-plain-upcase-indicates
Defines what an upcase char should indicate.
The default is @code{'color}, meaning a upcase char is a white piece, a
lowercase char a black piece.  Possible values: @code{'color} (default),
@code{'square-color}.  If set to @code{'square-color}, an uppercase character
indicates a piece on a black square.  (Note that you also need to
modify @code{chess-plain-piece-chars} to avoid real confusion.)
@end defopt

@defopt chess-plain-spacing
Number of spaces between files.
@end defopt

@kindex M-x customize-group RET chess-plain RET
@cindex customize chess-plain display
To customize options of @code{chess-plain}, use
@kbd{M-x customize-group @key{RET} chess-plain @key{RET}}.

@node ICS1 style ASCII displays
@section ICS1 style ASCII displays
@cindex ICS1 display

The @code{chess-ics1} module is a more verbose @acronym{ASCII} chessboard display.

This is how the starting position looks with this chessboard display:

@example
      +---+---+---+---+---+---+---+---+
    8 | r | n | b | q | k | b | n | r |
      +---+---+---+---+---+---+---+---+
    7 | p | p | p | p | p | p | p | p |
      +---+---+---+---+---+---+---+---+
    6 |   |   |   |   |   |   |   |   |
      +---+---+---+---+---+---+---+---+
    5 |   |   |   |   |   |   |   |   |
      +---+---+---+---+---+---+---+---+
    4 |   |   |   |   |   |   |   |   |
      +---+---+---+---+---+---+---+---+
    3 |   |   |   |   |   |   |   |   |
      +---+---+---+---+---+---+---+---+
    2 | P | P | P | P | P | P | P | P |
      +---+---+---+---+---+---+---+---+
    1 | R | N | B | Q | K | B | N | R |
      +---+---+---+---+---+---+---+---+
        a   b   c   d   e   f   g   h
@end example

@defopt chess-ics1-separate-frame
If non-@code{nil}, display the chessboard in its own frame.
@end defopt

@kindex M-x customize-group RET chess-ics1 RET
@cindex customize ics1 display
To customize options of @code{chess-ics1}, use
@kbd{M-x customize-group @key{RET} chess-ics1 @key{RET}}.

@node Graphical displays
@section Graphical displays
@cindex graphical display
@cindex chess-images module

The graphical chessboard display (@code{chess-images}) uses image files
to create a visually appealing chessboard in a buffer.

@defopt chess-images-directory
A directory which contains images in @acronym{XPM} format.

If you want to draw your own images, each image file must be named
@file{@var{color}-@var{piece}.xpm}, where @var{color} is either black or white,
and @var{piece} is one of rook, knight, bishop, queen, king or pawn.

The only image format currently supported is @acronym{XPM}.
@end defopt

@defopt chess-images-separate-frame
If non-@code{nil}, display the chessboard in its own frame.
@end defopt

@kindex M-x customize-group RET chess-images RET
@cindex customize chess-images display
For all customization options of @code{chess-images}, use
@kbd{M-x customize-group @key{RET} chess-images @key{RET}}.

@node Engines
@chapter Engines
@cindex engines

@dfn{Engines} represent opponents 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::
* The Null Engine::
* AI::
* Crafty::
* Fruit::
* Glaurung::
* GNU Chess::
* Phalanx::
* Sjeng::
* Stockfish::
@end menu

@node Common functions
@section Common functions
@cindex engines, common functions

@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

@defun chess-engine-set-option engine option value
Set @var{engine} @var{option} to @var{value} by invoking its handler with
the @samp{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 @code{chess-engine-process} is a valid process object, use @code{process-send-string}
to submit the data.  Otherwise, the @samp{send} event is triggered and the engine
event handler can take care of the data.
@end defun

@node The Null Engine
@section The Null Engine
@cindex null engine
@cindex chess-none

The most basic engine module is @code{chess-none}, a stub module that does
nothing.  This is useful for a game of chess against another human, where
both use the same computer to enter moves and display the current chess position.

It can also be useful for creating @acronym{FEN} strings of specific positions.

@kindex C-u M-x chess RET none RET
To bring up a chessboard with no active engine attached, use
@kbd{C-u M-x chess @key{RET} none @key{RET}}.

@node AI
@section AI
@cindex AI engine

The @acronym{AI} engine module defines a pure Emacs Lisp implementation
of an opponent.  Contrary to all other engine modules mentioned later on,
it does not require any external programs to be installed.

@kindex C-u M-x chess RET ai RET
To explicitly select this engine as an opponent,
use @kbd{C-u M-x chess @key{RET} ai @key{RET}}.

@defopt chess-ai-depth
Defines the default search depth for this engine.
@end defopt

@defopt chess-ai-quiescence-depth
Defines the number of plies to search for a quiet position.
This is in addition to @code{chess-ai-depth}.
@end defopt

If you'd like to employ the search and evaluation functions provided
by this module programmatically, the following function is the top-level
entry point.

@defun chess-ai-best-move position &optional depth eval-fn
Find the supposedly best move (ply) for @var{position}.
@var{depth} defaults to the value of @code{chess-ai-depth}.
@end defun

@node Crafty
@section Crafty
@cindex crafty

@dfn{Crafty} is a chess program written by Michael Byrne, UAB professor
Dr.@ Robert Hyatt, Tracy Riegle, Peter Skinner and Ted Langreck.  It is directly
derived from Cray Blitz, winner of the 1983 and 1986 World Computer Chess
Championships.

If the @command{crafty} program is installed and can be found in the program
search path (@code{exec-path}), the @code{chess-crafty} engine module will
automatically detect it.

@vindex chess-crafty-path
If @command{crafty} is installed in a non-standard location, variable
@code{chess-crafty-path} can be set to point to its executable file.

@kindex C-u M-x chess RET crafty RET
If you have multiple engines installed you can explicitly select
to play against Crafty by invoking @kbd{C-u M-x chess @key{RET} crafty @key{RET}}.

@node Fruit
@section Fruit
@cindex fruit

@dfn{Fruit} is a chess engine developed by Fabien Letouzey. It was
commercially available from September 2005 until July 2007.  Now it is freeware
and you can download it for free from @uref{http://www.fruitchess.com/}.
The development on Fruit by Fabien Letouzey has ceded and it is unlikely to
continue.

Fruit was vice world computer chess champion 2005.

If the @command{fruit} command is installed and can be found in the program
search path (@code{exec-path}),
the @code{chess-fruit} engine module will automatically detect it.

@vindex chess-fruit-path
If Fruit is installed in a non-standard location, variable
@code{chess-fruit-path} can be set to point to its executable file.

@kindex C-u M-x chess RET fruit RET
If you have multiple engines installed you can explicitly select
to play against Fruit by invoking @kbd{C-u M-x chess @key{RET} fruit @key{RET}}.

@node Glaurung
@section Glaurung
@cindex glaurung

@dfn{Glaurung} is another freely distributed strong computer chess engine.

If the @command{glaurung} program is installed and can be found in the
program search path (@code{exec-path}),
the @code{chess-glaurung} engine module will automatically detect it.

@vindex chess-glaurung-path
If Glaurung is installed in a non-standard location, variable
@code{chess-glaurung-path} can be set to point to its executable file.

@kindex C-u M-x chess RET glaurung RET
If you have multiple engines installed you can explicitly select
to play against Glaurung by invoking @kbd{C-u M-x chess @key{RET} glaurung @key{RET}}.

@node GNU Chess
@section GNU Chess
@cindex gnuchess

@uref{http://gnu.org/software/chess/, @dfn{@acronym{GNU} Chess}} is free
software, licensed under the terms of the @acronym{GNU} General Public License, and is
maintained by collaborating developers.
As one of the earliest computer chess programs with full source code available,
it's one of the oldest for Unix-based systems and has since been ported to many
other platforms.

If the @command{gnuchess} program is installed and can be found in the
program search path (@code{exec-path}),
the @code{chess-gnuchess} engine module will automatically detect it.

@vindex chess-gnuchess-path
If @acronym{GNU} Chess is installed in a non-standard location, variable
@code{chess-gnuchess-path} can be set to point to its executable file.

@kindex C-u M-x chess RET gnuchess RET
If you have multiple engines installed you can explicitly select
to play against @acronym{GNU} Chess by invoking
@kbd{C-u M-x chess @key{RET} gnuchess @key{RET}}.

@node Phalanx
@section Phalanx
@cindex phalanx

@dfn{Phalanx} is an old, popular chess engine, with an interesting history.

If the @command{phalanx} program is installed and can be found in the
program search path (@code{exec-path}),
the @code{chess-phalanx} engine module will automatically detect it.

@vindex chess-phalanx-path
If Phalanx is installed in a non-standard location, variable
@code{chess-phalanx-path} can be set to point to its executable file.

@kindex C-u M-x chess RET phalanx RET
If you have multiple engines installed you can explicitly select
to play against Phalanx by invoking @kbd{C-u M-x chess @key{RET} phalanx @key{RET}}.

@node Sjeng
@section Sjeng
@cindex sjeng

@uref{http://sjeng.org/, @dfn{Sjeng}} is a championship-winner automated chess engine
developed by Gian-Carlo Pascutto from Belgium.  While its original
version was free, recent developments are for sale.

If the @command{sjeng} program is installed and can be found in the
program search path (@code{exec-path}),
the @code{chess-sjeng} engine module will automatically detect it.

@vindex chess-sjeng-path
If Sjeng is installed in a non-standard location, variable
@code{chess-sjeng-path} can be set to point to its executable file.

@kindex C-u M-x chess RET sjeng RET
If you have multiple engines installed you can explicitly select
to play against Sjeng by invoking @kbd{C-u M-x chess @key{RET} sjeng @key{RET}}.

@node Stockfish
@section Stockfish
@cindex stockfish

@uref{http://www.stockfishchess.org/, @dfn{Stockfish}} is one of the strongest
chess engines in the world, appearing near or at the top of most chess engine
rating lists.
Stockfish is also free software, licensed under the terms of the
@acronym{GNU} General Public License.

If the @command{stockfish} program is installed and can be found in the
program search path (@code{exec-path}),
the @code{chess-stockfish} engine module will automatically detect it.

@vindex chess-stockfish-path
If Stockfish is installed in a non-standard location, variable
@code{chess-stockfish-path} can be set to point to its executable file.

@kindex C-u M-x chess RET stockfish RET
If you have multiple engines installed you can explicitly select
to play against Stockfish by invoking @kbd{C-u M-x chess @key{RET} stockfish @key{RET}}.

@node Chess Session
@chapter Chess Session
@cindex chess session

A @dfn{chess session} assembles all modules mentioned in previous
chapters into a working system to interact with.  A session typically
consists of at least one display module, one engine module,
and possibly a number of optional modules.  All these modules
share a common game object which is used to keep track of the
currently active game.

@defun chess engine disable-popup engine-response-handler &rest engine-ctor-args
Play a game against @var{engine}.

This function constructs all the necessary modules required for a chess session.
In particular, it will start @var{engine} and create a chess display as
configured in @code{chess-default-display}.

This is the main entry-point for interactively launching
a chessboard display with associated engine.

If you want to launch a chess session as part of your own code,
the probably more expressive alias @code{chess-session} might be interesting
to use.
@end defun

You can have several active chess sessions.
In fact, some features later described in this manual make use
of this, @pxref{Internet Chess Servers}.

@kindex M-x chess RET
@vindex chess-default-display
@vindex chess-default-engine
To interactively start a chess session, invoke
@kbd{M-x chess @key{RET}}.  This uses @code{chess-default-display}
to determine the chessboard display to use, and
@code{chess-default-engine} to determine an opponent.

@kindex C-u M-x chess RET
If you want to play against a specific engine, provide
a prefix argument as in @kbd{C-u M-x chess @key{RET}}, which will
prompt for an engine module.  The module name has the common
prefix @samp{chess-} stripped.  So you enter @kbd{gnuchess}
to indicate you'd like to play against the @code{chess-gnuchess} module.

@node Internet Chess Servers
@chapter Internet Chess Servers
@cindex internet chess servers

Based on the services provided above, there is also a special 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 played or examined,
play tournaments, chat with fellow chess players, participate in team games,
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:

  (@var{server} @var{port} [@var{handle}] [@var{password-or-filename}] [@var{helper}] [@var{helper args}@enddots{}])
@end defvar

Internet Chess Servers based on
@uref{http://www.freechess.org/, @acronym{FICS, Free Internet Chess Server}}
and @uref{http://www.chessclub.com/, @acronym{ICC, Internet Chess Club}}
are currently supported.

@menu
* Connecting to a server::
* Chess ICS Mode::
* Command History::
* Seeking an opponent for a new game::
* The sought game display::
* Watching other games::
@end menu

@node Connecting to a server
@section Connecting to a server
@cindex connecting to internet chess 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.

If called interactively, you will be prompted to enter a server
(from @code{chess-ics-server-list} and possibly identification credentials.
@end defun

@node Chess ICS Mode
@section Chess ICS Mode
@cindex Chess ICS mode
@cindex mode, ICS

  The major mode for ICS buffers is Chess ICS mode.  Many of its special
commands are bound to the @kbd{C-c} prefix.  Here is a list of ICS mode
commands:

@table @kbd
@item @key{RET}
@kindex RET
@findex comint-send-input
Send the current line as input to the server
(@code{comint-send-input}).  Any prompt at the beginning of the
line is omitted.  If point is at the end of
buffer, this is like submitting the command line in an ordinary
interactive shell.  However, you can also invoke @key{RET} elsewhere
in the ICS buffer to submit the current line as input.

@item C-d
@kindex C-d
@findex comint-delchar-or-maybe-eof
Either delete a character or send @acronym{EOF, End Of File}
(@code{comint-delchar-or-maybe-eof}).  Typed at the end of the ICS
buffer, this sends @acronym{EOF} to the server and terminates the
connection.  Typed at any other
position in the buffer, this deletes the character at point, as usual.

@item C-c C-a
@kindex C-c C-a
@findex comint-bol-or-process-mark
Move to the beginning of the line, but after the prompt if any
(@code{comint-bol-or-process-mark}).  If you repeat this command twice
in a row, the second time it moves back to the process mark, which is
the beginning of the input that you have not yet sent to the server.
(Normally that is the same place---the end of the prompt on this
line---but after @kbd{C-c @key{SPC}} the process mark may be in a
previous line.)

@item C-c @key{SPC}
@kindex C-c SPC
@findex comint-accumulate
Accumulate multiple lines of input, then send them together
(@code{comint-accumulate}).  This
command inserts a newline before point, but does not send the preceding
text as input to the server---at least, not yet.  Both lines, the one
before this newline and the one after, will be sent together (along with
the newline that separates them), when you type @key{RET}.

@item C-c C-u
@kindex C-c C-u
@findex comint-kill-input
Kill all text pending at end of buffer to be sent as input
(@code{comint-kill-input}).  If point is not at end of buffer,
this only kills the part of this text that precedes point.

@item C-c C-w
@kindex C-c C-w
@findex backward-kill-word
Kill a word before point (@code{backward-kill-word}).

@item C-c C-o
@kindex C-c C-o
@findex comint-delete-output
Delete the last batch of output from an ICS server command
(@code{comint-delete-output}).  This is useful if a server command spews
out lots of output that just gets in the way.

@item C-c C-s
@kindex C-c C-s
@findex comint-write-output
Write the last batch of output from an ICS server command to a file
(@code{comint-write-output}).  With a prefix argument, the file is
appended to instead.  Any prompt at the end of the output is not
written.

@item C-c C-r
@itemx C-M-l
@kindex C-c C-r
@kindex C-M-l
@findex comint-show-output
Scroll to display the beginning of the last batch of output at the top
of the window; also move the cursor there (@code{comint-show-output}).

@item C-c C-e
@kindex C-c C-e
@findex comint-show-maximum-output
Scroll to put the end of the buffer at the bottom of the window
(@code{comint-show-maximum-output}).

@item M-x comint-truncate-buffer
@findex comint-truncate-buffer
@vindex comint-buffer-maximum-size
This command truncates the ICS buffer to a certain maximum number of
lines, specified by the variable @code{comint-buffer-maximum-size}.
Here's how to do this automatically each time you get output from the
server:

@example
(add-hook 'comint-output-filter-functions
          'comint-truncate-buffer)
@end example
@end table

@cindex Comint mode
@cindex mode, Comint
  ICS mode is a derivative of Comint mode, a general-purpose mode for
communicating with interactive subprocesses.  Most of the features of
ICS mode actually come from Comint mode, as you can see from the
command names listed above.

@node Command History
@section ICS Command History
@cindex command history

  ICS buffers support two ways of repeating earlier commands.  You
can use keys like those used for the minibuffer history; these work
much as they do in the minibuffer, inserting text from prior commands
while point remains always at the end of the buffer.  You can move
through the buffer to previous inputs in their original place, then
resubmit them or copy them to the end.

@menu
* ICS Command Ring::
* ICS History Copying::
@end menu

@node ICS Command Ring
@subsection ICS Command History Ring
@cindex command history ring

@table @kbd
@findex comint-previous-input
@kindex M-p
@item M-p
@itemx C-@key{UP}
Fetch the next earlier old ICS command (@code{comint-previous-input}).

@kindex M-n
@findex comint-next-input
@item M-n
@itemx C-@key{DOWN}
Fetch the next later old ICS command (@code{comint-next-input}).

@kindex M-r
@findex comint-history-isearch-backward-regexp
@item M-r
Begin an incremental regexp search of old ICS commands
(@code{comint-history-isearch-backward-regexp}).

@item C-c C-x
@kindex C-c C-x
@findex comint-get-next-from-history
Fetch the next subsequent command from the history
(@code{comint-get-next-from-history}).

@item C-c .
@kindex C-c .
@findex comint-input-previous-argument
Fetch one argument from an old ICS command
(@code{comint-input-previous-argument}).

@item C-c C-l
@kindex C-c C-l
@findex comint-dynamic-list-input-ring
Display the buffer's history of ICS commands in another window
(@code{comint-dynamic-list-input-ring}).
@end table

  ICS buffers provide a history of previously entered
commands.  To reuse commands from the history, use the editing
commands @kbd{M-p}, @kbd{M-n}, @kbd{M-r} and @kbd{M-s}.  These work
just like the minibuffer history commands (@pxref{Minibuffer
History, , , emacs}), except that they operate within the ICS buffer rather
than the minibuffer.

  @kbd{M-p} fetches an earlier ICS command to the end of the ICS
buffer.  Successive use of @kbd{M-p} fetches successively earlier
commands, each replacing any text that was already present as
potential input.  @kbd{M-n} does likewise except that it finds
successively more recent ICS commands from the buffer.
@kbd{C-@key{UP}} works like @kbd{M-p}, and @kbd{C-@key{DOWN}} like
@kbd{M-n}.

  The history search command @kbd{M-r} begins an incremental regular
expression search of previous ICS commands.  After typing @kbd{M-r},
start typing the desired string or regular expression; the last
matching ICS command will be displayed in the current line.
Incremental search commands have their usual effects---for instance,
@kbd{C-s} and @kbd{C-r} search forward and backward for the next match
(@pxref{Incremental Search, , , emacs}).  When you find the desired input, type
@key{RET} to terminate the search.  This puts the input in the command
line.  Any partial input you were composing before navigating the
history list is restored when you go to the beginning or end of the
history ring.

  Often it is useful to reexecute several successive ICS commands that
were previously executed in sequence.  To do this, first find and
reexecute the first command of the sequence.  Then type @kbd{C-c C-x};
that will fetch the following command---the one that follows the command
you just repeated.  Then type @key{RET} to reexecute this command.  You
can reexecute several successive commands by typing @w{@kbd{C-c C-x
@key{RET}}} over and over.

  The command @kbd{C-c .}@: (@code{comint-input-previous-argument})
copies an individual argument from a previous command, like
@kbd{@key{ESC} .}@: in Bash.  The simplest use copies the last argument from the
previous ICS command.  With a prefix argument @var{n}, it copies the
@var{n}th argument instead.  Repeating @kbd{C-c .}@: copies from an
earlier ICS command instead, always using the same value of @var{n}
(don't give a prefix argument when you repeat the @kbd{C-c .}@:
command).

  These commands get the text of previous ICS commands from a special
history list, not from the ICS buffer itself.  Thus, editing the ICS
buffer, or even killing large parts of it, does not affect the history
that these commands access.

@node ICS History Copying
@subsection ICS History Copying
@cindex history copying
@cindex copying command history

@table @kbd
@kindex C-c C-p
@findex comint-previous-prompt
@item C-c C-p
Move point to the previous prompt (@code{comint-previous-prompt}).

@kindex C-c C-n
@findex comint-next-prompt
@item C-c C-n
Move point to the following prompt (@code{comint-next-prompt}).

@kindex C-c RET
@findex comint-copy-old-input
@item C-c @key{RET}
Copy the input command at point, inserting the copy at the end of the
buffer (@code{comint-copy-old-input}).  This is useful if you move
point back to a previous command.  After you copy the command, you can
submit the copy as input with @key{RET}.  If you wish, you can edit
the copy before resubmitting it.  If you use this command on an output
line, it copies that line to the end of the buffer.

@item Mouse-2
If @code{comint-use-prompt-regexp} is @code{nil} (the default), copy
the old input command that you click on, inserting the copy at the end
of the buffer (@code{comint-insert-input}).  If
@code{comint-use-prompt-regexp} is non-@code{nil}, or if the click is
not over old input, just yank as usual.
@end table

  Moving to a previous input and then copying it with @w{@kbd{C-c
@key{RET}}} or @kbd{Mouse-2} produces the same results---the same
buffer contents---that you would get by using @kbd{M-p} enough times
to fetch that previous input from the history list.  However, @w{@kbd{C-c
@key{RET}}} copies the text from the buffer, which can be different
from what is in the history list if you edit the input text in the
buffer after it has been sent.

@node Seeking an opponent for a new game
@section Seeking an opponent for a new game
@cindex seeking opponents

After you connected to a server, one of the first things you will
want to do is find an opponent for a new game.  You can use the
ICS command @samp{seek} to announce your availability for a chess game
to interested people.

For example:

@example
fics% seek 10 10 rated
@end example

This will announce your availability to play a rated game with 10 minutes
initial time-control for each player, and 10 seconds added
for every move made.

@node The sought game display
@section The sought game display
@cindex sought game display
@cindex seek advertisements

There is a special mode for displaying games sought by other users
on an Internet Chess Server.  Provided you didn't turn off seek advertisements
manually (for instance by setting the seek variable to 0 (off) on the
ICS server by issuing "set seek 0"), the first seek advertisement
automatically pops up a new window which is in @code{chess-ics-ads-mode}, a
derivative of @code{tabulated-list-mode}.

@c lispfun chess-ics-ads-mode

@defun chess-ics-ads-mode
A mode for displaying ICS game seek advertisements.

This mode runs the hook @code{chess-ics-ads-mode-hook}, as the final step
during initialization.

key             binding
---             -------

?		describe-mode
@var{ret}	chess-ics-sought-accept
<mouse-2>	chess-ics-sought-accept


@end defun

@kindex RET
In this buffer, use @kbd{mouse-2} or @kbd{@key{RET}} on a line to accept that
particular game and play it.

@node Watching other games
@section Watching other games
@cindex watching other games

You can also watch other games currently being played on @acronym{ICS}.
Even services like @samp{LectureBot} from @acronym{FICS} can
be used.

@example
fics% observe lecturebot
You are now observing game 5.
Game 5: LectureBot (0) LectureBot (0) unrated untimed 0 0

LectureBot(TD)(----)[5] kibitzes: (Note: A passed pawn is a pawn that
          does not have enemy pawns blocking the path either on the
          same or adjacent files).
LectureBot(TD)(----)[5] kibitzes: Connected passed pawns are a pain to
          have to deal with. They are usually a winning advantage if
          they cannot be blockaded. The blockading piece has to give
          up duties elsewhere. It's almost like being a piece up.
fics% unobserv lecturebot
Removing game 5 from observation list.
fics%
@end example

Once you start to observe a particular game or player, the
current position will pop up in a chessboard display.
As you are an observer, you will not be able to enter new moves.
However, you should be able to navigate back and forth in the history
of the game.

If a new move is made by any party in the game and you are currently
displaying the last position in the game, the chessboard display
will automatically update to reflect the new position and show
the last move in the mode line.

@node GNU Free Documentation License
@appendix GNU Free Documentation License
@include fdl.texi

@node Concept Index
@unnumbered Concept Index

@printindex cp

@node Function and Variable Index
@unnumbered Function and Variable Index

@printindex fn

@node Key Index
@unnumbered Key Index

@printindex ky
@bye
