\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 Emacs Chess: chess.el
@c %**end of header

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

@ifinfo
Copyright @copyright{} 2001, 2002 John Wiegley.

Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1 or
any later version published by the Free Software Foundation.
@end ifinfo

@synindex vr fn
@c The titlepage section does not appear in the Info file.
@titlepage
@sp 4
@c The title is printed in a large font.
@center @titlefont{User's Guide}
@sp
@center @titlefont{to}
@sp
@center @titlefont{Emacs Chess: chess.el}
@ignore
@sp 2
@center release 2.0
@c -release-
@end ignore
@sp 3
@center John Wiegley
@c -date-

@c  The following two commands start the copyright page for the printed
@c  manual.  This will not appear in the Info file.
@page
@vskip 0pt plus 1filll
Copyright @copyright{} 2001, 2002 John Wiegley.

Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1 or
any later version published by the Free Software Foundation.
@end titlepage

@contents

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

@ifinfo
@node Top, Emacs Chess: chess.el, (dir), (dir)
@top Emacs Chess: chess.el

Chess.el is an Emacs chess client and library, designed to be used for
writing chess-related programs, or for playing games of chess against
various chess engines, including Internet servers.  The library can be
used for analyzing variations, browsing historical games, or a
multitude of other purposes.

The purpose of this manual is to help you understand how Chess.el is
structured for use as a library, and also how to use it as a client.
@end ifinfo

@chapter The chess.el library
@cindex library

@section Positions

A chess @dfn{position} is a given layout of pieces on a 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.

@subsection Creating positions

@c lispfun chess-pos-create

@c lispfun chess-pos-copy

@defvar chess-starting-position
@end defvar

@c lispfun chess-fischer-random-position

@subsection Position coordinates

First of all, a coordinate system of octal indices is
used, where ?\044 signifies rank 4 file 4 (i.e., "e4").  Rank is
numbered 0 to 7, top to bottom, and file is 0 to 7, left to right.

@c lispfun chess-index-rank

@c lispfun chess-index-file

@c lispfun chess-rf-to-index

For those who wish to use ASCII coordinates, such as "e4", there
are two conversion functions:

@c lispfun chess-coord-to-index

@c lispfun chess-index-to-coord

@c lispfun chess-incr-index

@subsection Position details

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

@c lispfun chess-pos-piece

@c lispfun chess-pos-piece-p

@c lispfun chess-pos-set-piece

@c lispfun chess-pos-search

@c lispfun chess-search-position

@c lispfun chess-pos-can-castle

@c lispfun chess-pos-set-can-castle

@c lispfun chess-pos-en-passant

@c lispfun chess-pos-set-en-passant

@c lispfun chess-pos-status

@c lispfun chess-pos-set-status

@c lispfun chess-pos-side-to-move

@c lispfun chess-pos-set-side-to-move

@c lispfun chess-pos-move

Missing documentation for 'chess-pos-move'

@subsection Annotations

@c lispfun chess-pos-annotations

@c lispfun chess-pos-add-annotation

@subsection FEN notation

@c lispfun chess-fen-to-pos

@c lispfun chess-pos-to-fen

@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.

@subsection Creating plies

@c lispfun chess-ply-create

@c lispfun chess-legal-plies

@subsection Ply details

@c lispfun chess-ply-pos

@c lispfun chess-ply-set-pos

@c lispfun chess-ply-changes

@c lispfun chess-ply-set-changes

@c lispfun chess-ply-source

@c lispfun chess-ply-target

@subsection The "next" position

@c lispfun chess-ply-next-pos

@c lispfun chess-ply-final-p

@subsection Algebraic notation

@c lispfun chess-ply-to-algebraic

@c lispfun chess-algebraic-to-ply

@defvar chess-algebraic-regexp
@end defvar

@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.

@subsection Creating variations

@c lispfun chess-var-create

@subsection Variation positions

@c lispfun chess-var-pos

@c lispfun chess-var-index

@c lispfun chess-var-seq

@c lispfun chess-var-side-to-move

@subsection Varation plies

@c lispfun chess-var-ply

@c lispfun chess-var-plies

@c lispfun chess-var-to-algebraic

@subsection Making a move in a variation

@c lispfun chess-var-move

@c lispfun chess-var-add-ply

@section Games

A @dfn{game} includes its main variation, incidental information about
the game (who played it, where, when, who won, etc), and any
sub-variations of interest to those studying the game afterwards.

Where TAGS is an alist that associates arbitrary English tag names to
their values.

A game may be represented in ASCII using standard PGN notation.
Representing them graphically or verbally is similar to what is done
for variations.

@c lispfun chess-game-add-hook

@c lispfun chess-game-add-ply

@c lispfun chess-game-hooks

@c lispfun chess-game-plies

@c lispfun chess-game-remove-hook

@c lispfun chess-game-run-hooks

@c lispfun chess-game-set-hooks

@c lispfun chess-game-set-plies

@subsection Creating games

@c lispfun chess-game-create

@subsection Game tags

@c lispfun chess-game-tags

@c lispfun chess-game-set-tags

@c lispfun chess-game-tag

@c lispfun chess-game-set-tag

@c lispfun chess-game-del-tag

@subsection Game positions

@c lispfun chess-game-pos

@c lispfun chess-game-index

@c lispfun chess-game-seq

@c lispfun chess-game-side-to-move

@subsection Game plies

@c lispfun chess-game-ply

@subsection Making a move

@c lispfun chess-game-move

@subsection PGN notation

@c lispfun chess-pgn-to-game

@c lispfun chess-game-to-pgn

@c lispfun chess-pgn-insert-plies

@subsubsection PGN mode

@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.

@subsection Opening Databases

@defvar chess-database-modules
List of database modules to try when `chess-database-open' is called.
@end defvar

@c lispfun chess-database-open

@subsection Querying Databases

@c lispfun chess-database-count

@c lispfun chess-database-read

@c lispfun chess-database-query

@subsection Modifying Databases

@c lispfun chess-database-write

@c lispfun chess-database-replace

@subsection Finalising Databases

@c lispfun chess-database-save

@c lispfun chess-database-close

@chapter Modules

Positions, plies and variations are typically accessed in reference to
a game object, which has a main variation containing the plies and
positions that represent the number of moves made within that game up
to the final position.

Another thing that the game object does is to manage events that occur
within that game.  If a move is made from the final position, for
example, it will cause a new ply to be created, adding it to the end
of the main variation.  Then, a `move' event is triggered within the
game and passed to any chess modules which are currently associated
with that game.  The concept of modules allows far more complex
aspects of chess playing to be dealt with, while allowing the library
itself to still operate solely in terms of the game object.

For example, although the plies of a game object contain all the
information the computer needs to follow the game, a user needs much
more.  He wants to see the pieces move.  To support this, a display
module (see next chapter) can be created, and linked to the game.  The
first effect of this association will be to create a chess board
display and show the game's final position on it.  Now whenever plies
are added to the game, the chess board will be updated to show the
effect of that move on the board.  The display module realizes that a
move has been made by receiving the `move' event which is passed to
all modules associated with the game object.

There may be any number of modules associated with a chess game, and
they may do anything you like.  Basically, for a module call
chess-sample, a function must exist called `chess-sample-handler'.
This takes two or more arguments: a game object, the event symbol, and
whatever other arguments were passed along with the event symbol.

When an event is triggered on a game object (and this may happen as a
byproduct of manipulating the game, or events may be manually
generated), every associated module, in order, is called with that
event and whatever arguments were passed along with the event.  The
game object is passed also, so that the module knows which game this
event has occurred in reference to.

Once called, the module can do whatever it likes.  Some events expect
certain values to be returned, to indicate success or failure in
processing the event.  There are many different events, each depicting
something specific that might happen in the context of playing or
manipulating a chess game.  Some events relate only to the chess game
itself, some are triggered by the various chess engines that might be
associated with that game.  Modules may even trigger events in
response to event.  The game itself remains unaware of events, except
for the fact that it will pass them along to every module associated
with that game.

This is how displays get updated, for example, because once a 'move'
event is triggered, each display knows that it must now look at the
new final position and update its display.  It may even trigger new
events special to displays, to cause a refresh to happen after update
calculations have been performed, for example.  All such details are
left to the module, and the game does not interfere with such
intra-module messaging.

Looked at as an object-oriented design, these are typical polymorphic
events.  Certain generic situations frequently occur, such as moves,
which trigger events so that everyone concerned with the game can be
updated as to the move that occurred.  This way, no one need to
actively query the game to find out if something new has happened.
The game will notify every listening module by sending an event.

The core library, which consists of code to manipulate games, does not
define any modules.  The rest of the chess.el library is strictly a
set of module implementations, of various types.  Display modules
react to moves, and may modify the game based on user input; engine
modules react to moves by notifying the engine of the move; network
client modules react to moves by sending the move text over the
network.  Engine and network modules may also trigger new events when
the engine or network player has decided on their move, and this move
is then applied to the game object.

At the moment, no negotiation is done to determine which module may
modify the game object.  All modules have equal privilege.  This means
it is the programmer's duty not to associate conflicting modules with
a single game object.  If two artificial intelligence engines were
linked, for example, they would quickly start stepping on each other's
toes.  But it perfectly fine to have one artificial intelligence
engine, and another passive engine whose only purpose is to relay the
moves to a networked observer on another computer.  The possibilities
are endless.

Modules are very easy to write, although engines and displays are
rather different from each other in their principles.  There is a base
engine, and a base display, which receive the same events as any other
module.  But then there are derived engines and derived displays which
trigger a whole family of events specific to those module types.  If
you suspect a bug in your module, put a breakpoint in your handler
function, and wait for the offending event to come through.  Then you
can watch what your module does in response to that event.  If it
leaves the game object alone, it should be easy to locate the problem,
since it will always be within the module itself.  But if your module
also modifies the game object in response to certain events, you may
induce a feedback loop that is much more difficult to sort out.  Test
often and keep in mind that *many* events might end up coming through
as a result of the game changes your module makes!

That, in essence, is how the module system works.  From the game
object's perspective, it is a very simple mechanism, much like a
function ring or a hook.  The hook is called at certain points, so
that any listener can react to changes in the game.  But from each
module's perspective, it is a rich way to allow inter-operation
between both passive and reactive modules, all of them acting together
to enrich the context of play involving the central game object.

The only other rule to be mentioned is that each module instance
should be associated with only one game object at a time, although a
game object may have unlimited modules of any type linked to it.
Otherwise, trying to update a chess board based on input from two
different games would get impossible to sort out.  Better to create a
new board for every game---the way ordinary humans would do it in the
real world.

@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.

@c lispfun chess-display-create

@c lispfun/c chess-display-destroy

@chapter Chessboard displays

@c lispfun chess-display-active-p

@c lispfun chess-display-clear-board

@c lispfun chess-display-game

@c lispfun chess-display-highlight

@c lispfun chess-display-index

@c lispfun chess-display-invert

@c lispfun chess-display-move

@c lispfun chess-display-move-backward

@c lispfun chess-display-move-first

@c lispfun chess-display-move-forward

@c lispfun chess-display-move-last

@c lispfun chess-display-perspective

@c lispfun chess-display-ply

@c lispfun chess-display-position

@c lispfun chess-display-quit

@c lispfun chess-display-set-game

@c lispfun chess-display-set-index

@c lispfun chess-display-set-perspective

@c lispfun chess-display-set-ply

@c lispfun chess-display-set-position

@c lispfun chess-display-set-variation

@c lispfun chess-display-update

@c lispfun chess-display-variation

@chapter Engines

@c lispfun chess-engine-create

@c lispfun chess-engine-set-option

@c lispfun/c chess-engine-destroy

@c lispfun chess-engine-set-position

@c lispfun chess-engine-position

@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

@c lispfun chess-engine-send

@unnumbered Concept Index

@printindex cp

@unnumbered Function and Variable Index

@printindex fn

@unnumbered Key Index

@printindex ky
@bye