Copyright © 2001, 2002, 2004, 2014 Free Software Foundation, Inc.

     Permission is granted to copy, distribute and/or modify this document under the terms of the 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 GNU Manual,'' and with the Back-Cover Texts as in (a) below.  A copy of the license is included in the section entitled ``GNU Free Documentation License.''

     (a) The FSF's Back-Cover Text is: ``You have the freedom to copy and modify this GNU manual.''

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.

The chess.el library
********************

This chapter documents the low-level aspects of chess.el, mostly targeting developers interested in understanding the underlying APIs.

See Chessboard displays, and the chapters following it, if you are interested in the more user-visible aspects of chess.el.

Positions
=========

A chess position is a given layout of pieces on a chess board, also reflecting which 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 ASCII using 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 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 specification.

Chess puzzles are most often provided as a set of positions.

Creating positions
------------------

 -- Function: chess-pos-create &optional blank
     Create a new chess position, set at the starting position. If BLANK is non-nil, all of the squares will be empty. The current side-to-move is always white.

 -- Function: chess-pos-copy position
     Copy the given chess POSITION. If there are annotations or EPD opcodes set, these lists are copied as well, so that the two positions do not share the same lists.

 -- Variable: chess-starting-position
     Starting position of a chess game.

 -- Function: chess-fischer-random-position
     Generate a Fischer Random style position.

Position coordinates
--------------------

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

 -- Function: chess-index-rank index
     Return the rank component of the given INDEX.

 -- Function: chess-index-file index
     Return the file component of the given INDEX.

 -- Function: chess-rf-to-index rank file
     Convert RANK and FILE coordinates into an octal index.

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

 -- Function: chess-coord-to-index coord
     Convert a COORD string into an index value.

 -- Function: chess-index-to-coord index
     Convert the chess position INDEX into a coord string.

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

For queens and rooks:

 -- Constant: chess-direction-north
     Signify one step north, as seen from the perspective of the white player.

 -- Constant: chess-direction-east
     Signify one step east, as seen from the perspective of the white player.

 -- Constant: chess-direction-south
     Signify one step south, as seen from the perspective of the white player.

 -- Constant: chess-direction-west
     Signify one step west, as seen from the perspective of the white player.

For queens and bishops:

 -- Constant: chess-direction-northeast
     Signify one step northeast, as seen from the perspective of the white player.

 -- Constant: chess-direction-southeast
     Signify one step southeast, as seen from the perspective of the white player.

 -- Constant: chess-direction-southwest
     Signify one step southwest, as seen from the perspective of the white player.

 -- Constant: chess-direction-northwest
     Signify one step northwest, as seen from the perspective of the white player.

 -- Function: chess-next-index index direction
     Create a new INDEX from an old one, by advancing it into DIRECTION. If the resulting index is not valid (outside the board), nil is returned.

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 (* chess-direction-north 2) will give a typical initial white pawn push.

Position details
----------------

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

 -- Function: chess-pos-piece position index
     Return the piece on POSITION at INDEX.

 -- Function: chess-pos-piece-p position index piece-or-color
     Return non-nil if the given PIECE-OR-COLOR is at POSITION/INDEX. If PIECE-OR-COLOR is t for white or nil for black, any piece of that color will do.

 -- Function: chess-pos-set-piece position index piece
     Set the piece on POSITION at INDEX to PIECE. PIECE must be one of ?K, ?Q, ?N, ?B, ?R, or ?P for white pieces, or one of the corresponding lowercase letters for black pieces.

 -- Function: chess-pos-search position piece-or-color
     Look anywhere on POSITION for PIECE-OR-COLOR, returning all coordinates. If PIECE-OR-COLOR is t for white or nil for black, any piece of that color will do.

 -- Function: chess-pos-search* position &rest pieces
     Look on POSITION for any of PIECES.

     The result is an alist where each element looks like (PIECE . INDICES). Pieces which did not appear in POSITION will be present in the resulting alist, but the cdr of their entries will be nil.

 -- Function: chess-search-position position target piece &optional check-only no-castling
     Look on POSITION from TARGET for a PIECE that can move there. This routine looks along valid paths of movement for PIECE.  It differs from chess-pos-search, which is a more basic function that doesn't take piece movement into account.

     If PIECE is t or nil, valid piece movements for any piece of that color will be considered (t for white, nil for black).  Otherwise, the letter-case of the 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 CHECK-ONLY is non-nil and PIECE is either t or nil, only consider pieces which can give check (not the opponent's king). If NO-CASTLING is non-nil, do not consider castling moves.

 -- Function: chess-pos-can-castle position side
     Return whether the king on POSITION can castle on SIDE. The SIDE argument must be either ?K for the king side, or ?Q for the queen side (use lowercase to query if black can castle).

 -- Function: chess-pos-set-can-castle position side value
     Set whether the king can castle on the given POSITION on SIDE.

     See chess-pos-can-castle.

     It is only necessary to call this function if setting up a position manually.  Note that all newly created positions have full castling privileges set, unless the position is created blank, in which case castling privileges are unset.  See chess-pos-create.

 -- Function: chess-pos-en-passant position
     Return the index of any pawn on POSITION that can be captured en passant. Returns nil if en passant is unavailable.

 -- Function: chess-pos-set-en-passant position index
     Set the index of any pawn on POSITION that can be captured en passant.

 -- Function: chess-pos-status position
     Return whether the side to move in the POSITION is in a special state. Return nil if not, otherwise one of the keywords: :check, :checkmate or :stalemate.

 -- Function: chess-pos-set-status position value
     Set whether the side to move in POSITION is in a special state. The VALUE should either be nil, to indicate that the POSITION is normal, or one of the symbols: check, checkmate, stalemate.

 -- Function: chess-pos-side-to-move position
     Return the color whose move it is in POSITION.

 -- Function: chess-pos-set-side-to-move position color
     Set the color whose move it is in POSITION.

 -- Function: chess-pos-passed-pawns position color &optional pawn-indices
     If COLOR has Passed Pawns in POSITION, return a list of their indices. Optionally, if INDICES is non-nil, those indices are considered as candidates.

     A Pawn whose advance to the eighth rank is not blocked by an opposing Pawn in the same file and who does not have to pass one on an adjoining file is called a passed Pawn.

 -- Variable: 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.

 -- Function: chess-pos-move position &rest changes
     Move a piece on the POSITION directly, using the indices in CHANGES. This function does not check any rules, it only makes sure you are not trying to move a blank square.

Annotations
-----------

 -- Function: chess-pos-annotations position
     Return the list of annotations for this position.

 -- Function: chess-pos-add-annotation position annotation
     Add an annotation for this position.

FEN notation
------------

FEN (Forsyth-Edwards Notation) encodes a chess position using a simple string.  The format is:

        POSITION SIDE CASTLING EN-PASSANT

The POSITION gives all eight ranks, by specifying a letter for each piece 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 POSITION string would be:

     3k////////

for the three spaces (a, b and c file), the black king, and then all the remaining ranks (which are all empty, so their spaces can be ignored).

The SIDE is w or b, to indicate whose move it is.

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

The EN-PASSANT signifies the target square of an en passant capture, such as e3 or a6.

 -- Function: chess-fen-to-pos fen
     Convert the FEN string FEN to a chess position.

 -- Function: chess-pos-to-fen position &optional full
     Convert a chess POSITION to a FEN string. If FULL is non-nil, represent trailing spaces as well.

This is how the starting position looks like:

      (chess-pos-to-fen chess-starting-position)
      => "rnbqkbnr/pppppppp/////PPPPPPPP/RNBQKBNR w KQkq -"

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

      (chess-pos-to-fen chess-starting-position t)
      => "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq -"

EPD notation
------------

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

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

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

 -- Function: chess-epd-to-pos &optional string
     Convert extended position description STRING to a chess position. If STRING is not specified, look for an EPD string in the current buffer, and advance point after the correctly parsed position.

 -- Function: chess-pos-to-epd position
     Convert a chess POSITION to a string representation in extended position description format.

 -- Function: chess-epd-read-file file
     Return a list of positions contained in FILE.

Operations
..........

An 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 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 pv (predicted variation) opcode requires its operands (moves) to appear in the order in which they would be played.  All other opcodes that allow for more than one operand should have operands appearing in ASCII order.  An example of the latter set is the bm (best move[s]) opcode; its operands are moves that are all immediately playable from the current position.

Opcode acd analysis count depth
...............................

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

Opcode acn analysis count nodes
...............................

The opcode acn takes a single non-negative integer operand.  It is used to represent the number of nodes examined in an analysis.  Note that the value may be quite large for some extended searches, and so use of (at least) a long (four byte) representation is suggested.

Opcode acs analysis count seconds
.................................

The opcode acs takes a single non-negative integer operand.  It is used to represent the number of seconds used for an analysis.  Note that the value may be quite large for some extended searches, and so use of (at least) a long (four byte) representation is suggested.

Opcode am avoid move(s)
.......................

The opcode am indicates a set of zero or more moves, all immediately playable from the current position, that are to be avoided in the opinion of the EPD writer.  Each operand is a SAN move; they appear in ASCII order.

Opcode bm best move(s)
......................

The opcode bm indicates a set of zero or more moves, all immediately playable from the current position, that are judged to the best available by the EPD writer.  Each operand is a SAN move; they appear in ASCII order.

Plies
=====

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

Creating plies
--------------

 -- Function: chess-ply-create position &optional valid-p &rest changes
     Create a ply from the given POSITION by applying the supplied CHANGES. This function will guarantee the resulting ply is valid, and will also annotate the ply with :check or other modifiers as necessary.  It will also extend castling, and will prompt for a promotion piece.

     Note: Do not pass in the rook move if CHANGES represents a castling maneuver.

 -- Function: chess-legal-plies position &rest keywords
     Return a list of all valid plies in POSITION. The allowed KEYWORDS are:

     :any
          Return t if any piece can move at all.

     :color BOOLEAN
          If BOOLEAN is t, return plies for white, if nil, return plies for black.

     :piece CHARACTER
          Return plies for a specific piece designated by CHARACTER.

     :file FILE
          Given a FILE, a number (0-7), return plies for any piece or color present on that FILE.  :piece or :color must be present.

     :index INDEX
          Return plies for the piece at INDEX.

     :target INDEX
          Return plies that go to a specific coordinate specified by INDEX.

     :candidates INDEX...
          If provided, only consider the source coordinates specified by the indices.

     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.

Ply details
-----------

 -- Function: chess-ply-pos ply
     Return the base position associated with PLY.

 -- Function: chess-ply-set-pos ply position
     Set the base position of PLY.

 -- Function: chess-ply-changes
     Return the coordinate transformations and keywords associated with this PLY.

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

 -- Function: chess-ply-set-changes
     Set the coordinate transformations and keywords associated with this PLY.

 -- Function: chess-ply-source ply
     Return the source square index value of PLY.

 -- Function: chess-ply-target ply
     Return the target square index value of PLY.

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

      (chess-ply-source (chess-ply-create chess-starting-position nil
                                          (chess-coord-to-index "e2")
                                          (chess-coord-to-index "e4")))
      => 52

The ``next'' position
---------------------

 -- Function: chess-ply-next-pos ply
     Return the position that results from executing PLY.

 -- Function: chess-ply-final-p ply
     Return non-nil if this is the last ply of a game/variation.

Algebraic notation
------------------

A thing to deal with in chess is algebraic move notation, such as 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:

 -- Function: chess-algebraic-to-ply position move &optional trust
     Convert the algebraic notation MOVE for POSITION to a ply.

     If optional argument TRUST is non-nil, accept check or checkmate symbols (+ and #) as given.

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:

 -- Function: chess-ply-to-algebraic ply &optional type
     Convert the given PLY to algebraic notation (a string).

     Optional argument TYPE specifies the kind of algebraic notation to generate:

     :san
          Generate short (or standard) algebraic notation.  This is the default.

     :lan
          Generate long algebraic notation (like Nb1-c3).

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

     :numeric
          Generate ICCF numeric notation as used in correspondence chess (like 2133).

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:

 -- Variable: chess-algebraic-regexp
     A regular expression that matches all possible algebraic moves. This regexp handles short, long and figurine algebraic notation.

Variations
==========

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

Creating variations
-------------------

 -- Function: chess-var-create &optional position
     Create a new chess variation object. Optionally, use the given starting POSITION.

Variation positions
-------------------

 -- Function: chess-var-pos variation &optional index
     Return the position related to VARIATION's INDEX ply.

 -- Function: chess-var-index variation
     Return the VARIATION's current position index.

 -- Function: chess-var-seq variation
     Return the current VARIATION sequence.

 -- Function: chess-var-side-to-move variation &optional index
     Return the color whose move it is in VARIATION at INDEX (or at the last position of VARIATION if INDEX is nil).

Variation plies
---------------

 -- Function: chess-var-ply variation &optional index
     Return VARIATION's INDEXth ply.

 -- Function: chess-var-plies variation
     Return the plies of VARIATION.

 -- Function: chess-var-to-algebraic variation &optional long
     Reveal the plies of VARIATION by converting them to algebraic notation.

Making a move in a variation
----------------------------

 -- Function: chess-var-move variation ply
     Make a move in the current VARIATION by applying the changes of PLY. This creates a new position and adds it to the main variation. The changes of the last ply reflect whether the var is currently in progress (nil), if it is drawn, resigned, mate, etc.

 -- Function: chess-var-add-ply variation ply
     Add the given PLY to VARIATION.

Games
=====

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

Game tags is an alist that associates arbitrary English tag names to their values.

A game may be represented in ASCII using PGN (Portable Game Notation). Representing them graphically or verbally is similar to what is done for variations (see Variations).

 -- Function: chess-game-add-hook game function &optional data prepend
     Add to GAME an event hook FUNCTION.

 -- Function: chess-game-add-ply game ply
     Add PLY to the main variation of GAME.

 -- Function: chess-game-hooks game
     Return the event hooks associated with GAME.

 -- Function: chess-game-plies game
     Return the main variation of GAME as a list of plies.

 -- Function: chess-game-remove-hook game function &optional data
     Remove from GAME all event hooks that match FUNCTION. If DATA is specified, only remove hooks with matching associated data.

 -- Function: chess-game-run-hooks game &rest args
     Run the event hooks of GAME and pass it ARGS.

 -- Function: chess-game-set-hooks game hooks
     Set the event hooks associated with GAME.

 -- Function: chess-game-set-plies game plies
     Set the list of plies which represents the main variation of GAME.

Creating games
--------------

 -- Function: chess-game-create &optional position tags
     Create a new chess game object. Optionally use the given starting POSITION. TAGS is the starting set of game tags (which can always be changed later using the various tag-related methods).

Game tags
---------

 -- Function: chess-game-tags game
     Return the tags alist associated with GAME.

 -- Function: chess-game-set-tags game tags
     Set the tags alist associated with GAME. After the TAGS alist was set the set-tags event is triggered.

 -- Function: chess-game-tag game tag
     Return the value for TAG in GAME.

 -- Function: chess-game-set-tag game tag value
     Set the TAG for GAME to VALUE.

 -- Function: chess-game-del-tag game tag
     Delete the specified TAG from GAME.

Game positions
--------------

 -- Function: chess-game-pos game &optional index
     Return the current position of GAME or a position of a given INDEX.

 -- Function: chess-game-index game
     Return the GAME's current position index.

 -- Function: chess-game-seq game
     Return the current GAME sequence number.

 -- Function: chess-game-side-to-move game &optional index
     Return the side, specified as color, whose move it is in GAME at INDEX (or at the last position if INDEX is nil). Value is t for white and nil for black.

Game plies
----------

 -- Function: chess-game-ply game &optional index
     Return a ply of GAME. If INDEX is non-nil, the last played ply is returned.

Making a move
-------------

 -- Function: chess-game-move game ply
     Make a move in the current GAME using PLY. This creates a new position and adds it to the main variation. The changes of the last ply reflect whether the game is currently in progress (nil), if it is drawn, resigned, mate, etc.

PGN notation
------------

 -- Function: chess-pgn-to-game &optional string
     Convert the PGN notation at point into a chess game. Optionally use the supplied STRING instead of the current buffer.

 -- Function: chess-game-to-pgn game &optional indented to-string
     Convert a chess GAME to PGN notation. If INDENTED is non-nil, indent the move texts. If TO-STRING is non-nil, return a string instead of inserting the resulting PGN text.

 -- Function: chess-pgn-insert-plies game index plies &optional for-black indented no-annotations
     NYI: Still have to implement the INDENTED argument.

PGN mode
........

 -- Function: chess-pgn-visualize
     Visualize the move for the PGN game under point. This does not require that the buffer be in PGN mode.

Collections
===========

A collection is a set of games archived for later perusal.  A set of games conceptually represents a large tree of branching variations, and can be used for studying current theory, examining Master preferences, etc.

Chess.el itself does not attempt to provide library services, nor does it ever represent library collections in memory.  Instead, it interacts with a chess database engine for the purpose of storing and retrieving games from the library, or performing library-wide analyses and searches.

Opening Databases
-----------------

 -- Variable: chess-database-modules
     List of database modules to try when chess-database-open is called.

 -- Function: chess-database-open file &optional module
     Open a game database specified by FILE. You can optionally specify the database MODULE to use.

     Returns the opened database object, or nil.

Querying Databases
------------------

 -- Function: chess-database-filename database
     Return the filename of an already opened DATABASE.

 -- Function: chess-database-read database index
     Return from DATABASE the chess game object at INDEX.

 -- Function: chess-database-query database &rest terms
     Run a query on DATABASE. The TERMS are partly dependent on the chess-database module in use. For the chess-scid module, using tree-search GAME means perform a tree search on the last position of GAME.

Modifying Databases
-------------------

 -- Function: chess-database-read-only-p database
     Return non-nil if DATABASE is read only.

Finalizing Databases
--------------------

Database Modules
----------------

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

chess-file
..........

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

EPD file collections are represented as a collection of games originating at the given position.  One might argue that conceptually, they represent a collection of positions, but it is more convenient to merge all collections into one uniform concept.

chess-scid
..........

This module implements basic reading and writing functionality for SCID (Shane's Chess Information Database) files.

Chess Opening Books
===================

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

ECO Classification
------------------

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

Polyglot opening book format support
------------------------------------

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

 -- User Option: chess-polyglot-book-file
     Path to default polyglot book file.

 -- Variable: chess-polyglot-book
     If non-nil, the buffer holding the currently loaded polyglot book data.

     This is used by UCI based engine modules as well as the internal AI.

 -- Function: chess-polyglot-book-open file
     Open a polyglot book FILE.

     Returns a buffer object which contains the binary data.

 -- Function: chess-polyglot-book-plies book position
     Return a list of plies found in BOOK for POSITION. The resulting list is ordered, most interesting plies come first. The :polyglot-book-weight ply keyword is used to store the actual move weights. Use chess-ply-keyword on elements of the returned list to retrieve them.

 -- Function: chess-polyglot-book-ply book position &optional strength
     If non-nil, a (randomly picked) ply from BOOK for POSITION. Random distribution is defined by the relative weights of the found plies. If non-nil, 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 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.

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 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 move event which is passed to all modules associated with the game object.

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

When an event is triggered on a game object (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 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 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.

Chessboard displays
*******************

The previous chapter described all the objects found in chess---positions, plies, variations, games and collections.  However, these objects can only be manipulated 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.

Generic display manipulation functions
======================================

 -- Function: chess-display-create game style perspective
     Create a chess display, for displaying chess objects. The GAME is the chess game object to use, STYLE should be the display type to use (a symbol), and PERSPECTIVE determines the viewpoint of the board: if non-nil, the board is viewed from White's perspective.

 -- Function: chess-display-active-p
     Return non-nil if the displayed chessboard reflects an active game. Basically, it means we are playing, not editing or reviewing.

 -- Function: chess-display-clear-board
     Setup the current board for editing.

 -- Function: chess-display-highlight display &rest args
     Highlight in DISPLAY the squares given in ARGS on the current position.

     The ARGS is a list of highlighting modes and position coordinates. The default highlighting mode is :selected which is supported by most displays.

 -- Function: chess-display-invert
     Invert the perspective of the current chess board.

 -- Function: chess-display-move display ply
     Move a piece on DISPLAY, by applying the given PLY. The position of PLY must match the currently displayed position.

 -- Function: chess-display-perspective display
     Return the current perspective of DISPLAY.

 -- Function: chess-display-position display
     Return the position currently viewed on DISPLAY.

 -- Function: chess-display-quit
     Quit the game associated with the current display.

 -- Function: chess-display-set-game display game &optional index
     Set the given DISPLAY to display the GAME object, optionally at 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.

 -- Function: chess-display-set-perspective display perspective
     Set PERSPECTIVE of DISPLAY.

 -- Function: chess-display-set-position display &optional position my-color
     Set the game associated with DISPLAY to use POSITION and MY-COLOR.

 -- Function: chess-display-set-variation display variation &optional index
     Set DISPLAY VARIATION. If 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.

 -- Function: chess-display-update display &optional popup
     Update the chessboard DISPLAY.  If POPUP is non-nil, make sure it is visible.

Chess display mode
==================

Chess display mode is a special major mode (see 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.

 -- User Option: chess-display-highlight-legal
     If non-nil, highlight valid target squares when a piece is selected.

Basic operations
----------------

C-i
TAB
     Invert the perspective of the current chess board (chess-display-invert).

,
     Show the previous move in the current game (chess-display-move-backward).

C-r
     Find previous move which algebraic notation matches a regular expression (chess-display-search-backward).

C-s
     Find next move which algebraic notation matches a regular expression (chess-display-search-forward).

.
     Show the next move in the current game (chess-display-move-forward).

<
     Move to the initial position of the current game (chess-display-move-first).

>
     Move to the last position of the current game (chess-display-move-last).

C-c C-d
     Offer to draw the current game (chess-display-draw).

C-c C-r
     Resign the current game (chess-display-resign).

M-w
C-u M-w
     Copy the currently displayed position to the kill ring as a FEN string (chess-display-kill-board).

     With prefix argument, copy the current game in PGN to the kill ring.

C-y
     Set the current display position via a FEN string from the kill ring (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 FEN string previously added to the kill ring from somewhere else.

X
     Quit this chessboard display (chess-display-quit).

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

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

RET
     Select the piece/square currently indicated by point (chess-display-select-piece) to move from/to.

Selecting pieces with the mouse
-------------------------------

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

down-mouse-1
down-mouse-2
drag-mouse-1
drag-mouse-2
     Select the piece/square currently indicated by the mouse pointer (chess-display-select-piece) to move from/to.

Entering moves with algebraic notation
--------------------------------------

a ... h
1 ... 8
N
B
R
Q
K
x
=
     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 N x is sufficient to select that move.

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

backspace
     Delete the last entered chess move character (chess-input-shortcut-delete).

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

Plain ASCII diagram displays
============================

The simplest display style available is chess-plain, a very customizable ASCII board diagram display.

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

      +---------------+
     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

 -- User Option: chess-plain-separate-frame
     If non-nil, display the chessboard in its own frame.

 -- User Option: chess-plain-border-style
     If non-nil, a vector of Characters used to draw borders.

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

 -- User Option: chess-plain-black-square-char
     Character used to indicate empty black squares.

 -- User Option: chess-plain-white-square-char
     Character used to indicate black white squares.

 -- User Option: chess-plain-piece-chars
     Alist of pieces and their corresponding characters.

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

 -- User Option: chess-plain-spacing
     Number of spaces between files.

To customize options of chess-plain, use M-x customize-group RET chess-plain RET.

ICS1 style ASCII displays
=========================

The chess-ics1 module is a more verbose ASCII chessboard display.

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

           +---+---+---+---+---+---+---+---+
         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

 -- User Option: chess-ics1-separate-frame
     If non-nil, display the chessboard in its own frame.

To customize options of chess-ics1, use M-x customize-group RET chess-ics1 RET.

Graphical displays
==================

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

 -- User Option: chess-images-directory
     A directory which contains images in XPM format.

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

     The only image format currently supported is XPM.

 -- User Option: chess-images-separate-frame
     If non-nil, display the chessboard in its own frame.

For all customization options of chess-images, use M-x customize-group RET chess-images RET.

Engines
*******

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.

Common functions
================

 -- Function: chess-engine-create module game &optional response-handler &rest handler-ctor-args
     Create a new chess engine MODULE (a symbol) associated with GAME. Optionally supply a new RESPONSE-HANDLER.

 -- Function: chess-engine-set-option engine option value
     Set ENGINE OPTION to VALUE by invoking its handler with the set-option event.

 -- Function: chess-engine-position engine
     Return the current position of the game associated with ENGINE.

 -- Function: chess-engine-command engine event &rest args
     Call the handler of ENGINE with EVENT (a symbol) and ARGS.

 -- Function: chess-engine-send engine string
     Send the given STRING to ENGINE. If chess-engine-process is a valid process object, use process-send-string to submit the data.  Otherwise, the send event is triggered and the engine event handler can take care of the data.

The Null Engine
===============

The most basic engine module is 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 FEN strings of specific positions.

To bring up a chessboard with no active engine attached, use C-u M-x chess RET none RET.

AI
==

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

To explicitly select this engine as an opponent, use C-u M-x chess RET ai RET.

 -- User Option: chess-ai-depth
     Defines the default search depth for this engine.

 -- User Option: chess-ai-quiescence-depth
     Defines the number of plies to search for a quiet position. This is in addition to chess-ai-depth.

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.

 -- Function: chess-ai-best-move position &optional depth eval-fn
     Find the supposedly best move (ply) for POSITION. DEPTH defaults to the value of chess-ai-depth.

Crafty
======

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 crafty program is installed and can be found in the program search path (exec-path), the chess-crafty engine module will automatically detect it.

If crafty is installed in a non-standard location, variable chess-crafty-path can be set to point to its executable file.

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

Fruit
=====

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 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 fruit command is installed and can be found in the program search path (exec-path), the chess-fruit engine module will automatically detect it.

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

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

Glaurung
========

Glaurung is another freely distributed strong computer chess engine.

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

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

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

GNU Chess
=========

GNU Chess (http://gnu.org/software/chess/) is free software, licensed under the terms of the 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 gnuchess program is installed and can be found in the program search path (exec-path), the chess-gnuchess engine module will automatically detect it.

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

If you have multiple engines installed you can explicitly select to play against GNU Chess by invoking C-u M-x chess RET gnuchess RET.

Phalanx
=======

Phalanx is an old, popular chess engine, with an interesting history.

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

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

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

Sjeng
=====

Sjeng (http://sjeng.org/) 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 sjeng program is installed and can be found in the program search path (exec-path), the chess-sjeng engine module will automatically detect it.

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

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

Stockfish
=========

Stockfish (http://www.stockfishchess.org/) 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 GNU General Public License.

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

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

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

Chess Session
*************

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

 -- Function: chess engine disable-popup engine-response-handler &rest engine-ctor-args
     Play a game against ENGINE.

     This function constructs all the necessary modules required for a chess session. In particular, it will start ENGINE and create a chess display as configured in 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 chess-session might be interesting to use.

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

To interactively start a chess session, invoke M-x chess RET.  This uses chess-default-display to determine the chessboard display to use, and chess-default-engine to determine an opponent.

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

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:

 -- Variable: chess-ics-server-list
     A list of servers to connect to. The format of each entry is:

     (SERVER PORT [HANDLE] [PASSWORD-OR-FILENAME] [HELPER] [HELPER ARGS...])

Internet Chess Servers based on FICS (Free Internet Chess Server) (http://www.freechess.org/) and ICC (Internet Chess Club) (http://www.chessclub.com/) are currently supported.

Connecting to a server
======================

To open a new connection to an Internet Chess Server, use:

 -- Function: 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 chess-ics-server-list and possibly identification credentials.

Chess ICS Mode
==============

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

RET
     Send the current line as input to the server (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 RET elsewhere in the ICS buffer to submit the current line as input.

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

C-c C-a
     Move to the beginning of the line, but after the prompt if any (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 C-c SPC the process mark may be in a previous line.)

C-c SPC
     Accumulate multiple lines of input, then send them together (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 RET.

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

C-c C-w
     Kill a word before point (backward-kill-word).

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

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

C-c C-r
C-M-l
     Scroll to display the beginning of the last batch of output at the top of the window; also move the cursor there (comint-show-output).

C-c C-e
     Scroll to put the end of the buffer at the bottom of the window (comint-show-maximum-output).

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

          (add-hook 'comint-output-filter-functions
                    'comint-truncate-buffer)

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.

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

ICS Command History Ring
------------------------

M-p
C-UP
     Fetch the next earlier old ICS command (comint-previous-input).

M-n
C-DOWN
     Fetch the next later old ICS command (comint-next-input).

M-r
     Begin an incremental regexp search of old ICS commands (comint-history-isearch-backward-regexp).

C-c C-x
     Fetch the next subsequent command from the history (comint-get-next-from-history).

C-c .
     Fetch one argument from an old ICS command (comint-input-previous-argument).

C-c C-l
     Display the buffer's history of ICS commands in another window (comint-dynamic-list-input-ring).

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

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

The history search command M-r begins an incremental regular expression search of previous ICS commands.  After typing 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, C-s and C-r search forward and backward for the next match (see Incremental Search (emacs)).  When you find the desired input, type 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 C-c C-x; that will fetch the following command---the one that follows the command you just repeated.  Then type RET to reexecute this command.  You can reexecute several successive commands by typing C-c C-x RET over and over.

The command C-c . (comint-input-previous-argument) copies an individual argument from a previous command, like ESC . in Bash.  The simplest use copies the last argument from the previous ICS command.  With a prefix argument N, it copies the Nth argument instead.  Repeating C-c . copies from an earlier ICS command instead, always using the same value of N (don't give a prefix argument when you repeat the 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.

ICS History Copying
-------------------

C-c C-p
     Move point to the previous prompt (comint-previous-prompt).

C-c C-n
     Move point to the following prompt (comint-next-prompt).

C-c RET
     Copy the input command at point, inserting the copy at the end of the buffer (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 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.

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

Moving to a previous input and then copying it with C-c RET or Mouse-2 produces the same results---the same buffer contents---that you would get by using M-p enough times to fetch that previous input from the history list.  However, C-c 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.

Seeking an opponent for a new game
==================================

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

For example:

     fics% seek 10 10 rated

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.

The sought game display
=======================

There is a special mode for displaying games sought by other users on an Internet Chess Server.  Provided you didn't turn off seek 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 chess-ics-ads-mode, a derivative of tabulated-list-mode.

 -- Function: chess-ics-ads-mode
     A mode for displaying ICS game seek advertisements.

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

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

     ?		describe-mode
     RET	chess-ics-sought-accept
     <mouse-2>	chess-ics-sought-accept

In this buffer, use mouse-2 or RET on a line to accept that particular game and play it.

Watching other games
====================

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

     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%

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.

GNU Free Documentation License
******************************

     [file fdl.texi not included]