1 This is chess.info, produced by makeinfo version 5.2 from chess.texi.
5 * Chess: (chess). Chess.el is an Emacs chess client.
8 Copyright (C) 2001, 2002, 2014 Free Software Foundation, Inc.
10 Permission is granted to copy, distribute and/or modify this document
11 under the terms of the GNU Free Documentation License, Version 1.1 or
12 any later version published by the Free Software Foundation.
15 File: chess.info, Node: Top, Next: The chess.el library, Prev: (dir), Up: (dir)
20 Chess.el is an Emacs chess client and library, designed to be used for
21 writing chess-related programs, or for playing games of chess against
22 various chess engines, including Internet servers. The library can be
23 used for analyzing variations, browsing historical games, or a multitude
26 The purpose of this manual is to help you understand how Chess.el is
27 structured for use as a library, and also how to use it as a client.
31 * The chess.el library::
33 * Chessboard displays::
35 * Internet Chess Servers::
37 * Function and Variable Index::
41 File: chess.info, Node: The chess.el library, Next: Modules, Prev: Top, Up: Top
43 1 The chess.el library
44 **********************
46 This chapter documents the low-level aspects of chess.el, mostly
47 targeting developers interested in understand the underlying APIs.
49 *note Chessboard displays:: and following chapters if you are
50 interested in the more user-visible apsects of chess.el.
59 * Chess Opening Books::
62 File: chess.info, Node: Positions, Next: Plies, Prev: The chess.el library, Up: The chess.el library
67 A chess "position" is a given layout of pieces on a chess board, also
68 reflecting which side is next to move, and what privileges are currently
69 available to each side (castling short or long, en passant capture,
72 A position may be represented in ASCII using FEN (or EPD) notation,
73 or graphically by displaying a chess board. It is rather inconvenient
74 to render them verbally.
76 The position can be represented on a remote terminal using X windows,
77 or by transmitting the FEN string via a network connection, or
78 clipboard, to another chess board rendering tool. It may of course also
79 be represented physically, by setting up the pieces to match the FEN
82 Chess puzzles are most often provided as a set of positions.
86 * Creating positions::
87 * Position coordinates::
94 File: chess.info, Node: Creating positions, Next: Position coordinates, Prev: Positions, Up: Positions
96 1.1.1 Creating positions
97 ------------------------
99 -- Function: chess-pos-create &optional blank
100 Create a new chess position, set at the starting position. If
101 BLANK is non-nil, all of the squares will be empty. The current
102 side-to-move is always white.
104 -- Function: chess-pos-copy position
105 Copy the given chess POSITION. If there are annotations or EPD
106 opcodes set, these lists are copied as well, so that the two
107 positions do not share the same lists.
109 -- Variable: chess-starting-position
110 Starting position of a chess game.
112 -- Function: chess-fischer-random-position
113 Generate a Fischer Random style position.
116 File: chess.info, Node: Position coordinates, Next: Position details, Prev: Creating positions, Up: Positions
118 1.1.2 Position coordinates
119 --------------------------
121 First of all, a coordinate system of octal indices is used, where ?\044
122 signifies rank 4 file 4 (i.e., "e4"). Rank is numbered 0 to 7, top to
123 bottom, and file is 0 to 7, left to right.
125 -- Function: chess-index-rank index
126 Return the rank component of the given INDEX.
128 -- Function: chess-index-file index
129 Return the file component of the given INDEX.
131 -- Function: chess-rf-to-index rank file
132 Convert RANK and FILE coordinates into an octal index.
134 For those who wish to use ASCII coordinates, such as "e4", there are
135 two conversion functions:
137 -- Function: chess-coord-to-index coord
138 Convert a COORD string into an index value.
140 -- Function: chess-index-to-coord index
141 Convert the chess position INDEX into a coord string.
143 For fast manipulation of chess position indices, the following
144 constants and functions are provided:
146 For queens and rooks:
148 -- Constant: chess-direction-north
149 Signify one step north, as seen from the perspective of the white
152 -- Constant: chess-direction-east
153 Signify one step east, as seen from the perspective of the white
156 -- Constant: chess-direction-south
157 Signify one step south, as seen from the perspective of the white
160 -- Constant: chess-direction-west
161 Signify one step west, as seen from the perspective of the white
164 For queens and bishops:
166 -- Constant: chess-direction-northeast
167 Signify one step northeast, as seen from the perspective of the
170 -- Constant: chess-direction-southeast
171 Signify one step southeast, as seen from the perspective of the
174 -- Constant: chess-direction-southwest
175 Signify one step southwest, as seen from the perspective of the
178 -- Constant: chess-direction-northwest
179 Signify one step northwest, as seen from the perspective of the
182 -- Function: chess-next-index index direction
183 Create a new INDEX from an old one, by advancing it into DIRECTION.
184 If the resulting index is not valid, nil is returned.
186 Due to the underlying technique used to efficiently detect off-board
187 squares, a direction specifier should at most do two steps in any
188 direction. Directions can be combined, so that '(*
189 chess-direction-north 2)' will give a typical initial white pawn push.
192 File: chess.info, Node: Position details, Next: Annotations, Prev: Position coordinates, Up: Positions
194 1.1.3 Position details
195 ----------------------
197 With an octal index value, you can look up what's on a particular
198 square, or set that square's value:
200 -- Function: chess-pos-piece position index
201 Return the piece on POSITION at INDEX.
203 -- Function: chess-pos-piece-p position index piece-or-color
204 Return non-nil if at POSITION/INDEX there is the given
205 PIECE-OR-COLOR. If PIECE-OR-COLOR is t for white or nil for black,
206 any piece of that color will do.
208 -- Function: chess-pos-set-piece position index piece
209 Set the piece on POSITION at INDEX to PIECE. PIECE must be one of
210 K Q N B R or P. Use lowercase to set black pieces.
212 -- Function: chess-pos-search position piece-or-color
213 Look on POSITION anywhere for PIECE-OR-COLOR, returning all
214 coordinates. If PIECE-OR-COLOR is t for white or nil for black,
215 any piece of that color will do.
217 -- Function: chess-search-position position target piece &optional
218 check-only no-castling
219 Look on POSITION from TARGET for a PIECE that can move there. This
220 routine looks along legal paths of movement for PIECE. It differs
221 from 'chess-pos-search', which is a more basic function that
222 doesn't take piece movement into account.
224 If PIECE is t or nil, legal piece movements for any piece of that
225 color will be considered (t for white, nil for black). Otherwise,
226 the case of the PIECE determines color.
228 The return value is a list of candidates, which means a list of
229 indices which indicate where a piece may have moved from.
231 If CHECK-ONLY is non-nil and PIECE is either t or nil, only
232 consider pieces which can give check (not the opponents king). If
233 NO-CASTLING is non-nil, do not consider castling moves.
235 -- Function: chess-pos-can-castle position side
236 Return whether the king on POSITION can castle on SIDE. SIDE must
237 be either ?K for the kingside, or ?Q for the queenside (use
238 lowercase to query if black can castle).
240 -- Function: chess-pos-set-can-castle position side value
241 Set whether the king can castle on the given POSITION on SIDE.
243 See 'chess-pos-can-castle'.
245 It is only necessary to call this function if setting up a position
246 manually. Note that all newly created positions have full castling
247 priveleges set, unless the position is created blank, in which case
248 castling priveleges are unset. See 'chess-pos-copy'.
250 -- Function: chess-pos-en-passant position
251 Return the index of any pawn on POSITION that can be captured en
252 passant. Returns nil if en passant is unavailable.
254 -- Function: chess-pos-set-en-passant position index
255 Set the index of any pawn on POSITION that can be captured en
258 -- Function: chess-pos-status position
259 Return whether the side to move in the POSITION is in a special
260 state. nil is returned if not, otherwise one of the symbols:
261 'check', 'checkmate', 'stalemate'.
263 -- Function: chess-pos-set-status position value
264 Set whether the side to move in POSITION is in a special state.
265 VALUE should either be nil, to indicate that the POSITION is
266 normal, or one of the symbols: 'check', 'checkmate', 'stalemate'.
268 -- Function: chess-pos-side-to-move position
269 Return the color whose move it is in POSITION.
271 -- Function: chess-pos-set-side-to-move position color
272 Set the color whose move it is in POSITION.
274 -- Function: chess-pos-passed-pawns position color &optional
276 If COLOR has Passed Pawns in POSITION, return a list of their
277 indices. Optionally, if INDICES is non-nil those indices are
278 considered as candidates.
280 A Pawn whose advance to the eighth rank is not blocked by an
281 opposing Pawn in the same file and who does not have to pass one on
282 an adjoining file is called a passed Pawn.
284 -- Variable: chess-pos-always-white
285 When set, it is assumed that white is always on move. This is
286 really only useful when setting up training positions. This
287 variable automatically becomes buffer-local when changed.
289 -- Function: chess-pos-move position &rest changes
290 Move a piece on the POSITION directly, using the indices in
291 CHANGES. This function does not check any rules, it only makes
292 sure you are not trying to move a blank square.
295 File: chess.info, Node: Annotations, Next: FEN notation, Prev: Position details, Up: Positions
300 -- Function: chess-pos-annotations position
301 Return the list of annotations for this position.
303 -- Function: chess-pos-add-annotation position annotation
304 Add an annotation for this position.
307 File: chess.info, Node: FEN notation, Next: EPD notation, Prev: Annotations, Up: Positions
312 FEN notation encodes a chess position using a simple string. The format
315 POSITION SIDE CASTLING EN-PASSANT
317 The POSITION gives all eight ranks, by specifying a letter for each
318 piece on the position, and a number for any intervening spaces.
319 Trailing spaces need not be counted. Uppercase letters signify white,
320 and lowercase black. For example, if your position only had a black
321 king on d8, your POSITION string would be:
325 For the three spaces (a, b and c file), the black king, and then all
326 the remaining ranks (which are all empty, so their spaces can be
329 The SIDE is w or b, to indicate whose move it is.
331 CASTLING can contain K, Q, k or q, to signify whether the white or
332 black king can still castle on the king or queen side. EN-PASSANT
333 signifies the target sqaure of an en passant capture, such as "e3" or
336 The starting chess position always looks like this:
338 rnbqkbnr/pppppppp/////PPPPPPPP/RNBQKBNR/ w KQkq -
340 And in "full" mode (where all spaces are accounted for):
342 rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq -
344 -- Function: chess-fen-to-pos fen
345 Convert a FEN-like notation string to a chess position.
347 -- Function: chess-pos-to-fen position &optional full
348 Convert a chess POSITION to FEN-like notation. If FULL is non-nil,
349 represent trailing spaces as well.
352 File: chess.info, Node: EPD notation, Prev: FEN notation, Up: Positions
357 EPD is "Extended Position Description"; it is a standard for describing
358 chess positions along with an extended set of structured attribute
359 values using the ASCII character set. It is intended for data and
360 command interchange among chessplaying programs. It is also intended
361 for the representation of portable opening library repositories.
363 A single EPD uses one text line of variable length composed of four
364 data field followed by zero or more operations. The four fields of the
365 EPD specification are the same as the first four fields of the FEN
368 A text file composed exclusively of EPD data records should have a
369 file name with the suffix ".epd".
371 -- Function: chess-epd-to-pos &optional string
372 Convert extended position description to a chess position. If
373 STRING is not specified, look for an EPD string in the current
374 buffer, and advance point after the correctly parsed position.
376 -- Function: chess-pos-to-epd position
377 Convert a chess POSITION to a string representation in extended
378 position description format.
380 -- Function: chess-epd-read-file file
381 Return a list of positions contained in FILE.
386 * Opcode "acd" analysis count depth::
387 * Opcode "acn" analysis count nodes::
388 * Opcode "acs" analysis count seconds::
389 * Opcode "am" avoid move(s)::
390 * Opcode "bm" best move(s)::
393 File: chess.info, Node: Operations, Next: Opcode "acd" analysis count depth, Prev: EPD notation, Up: EPD notation
398 An EPD operation is composed of an opcode followed by zero or more
399 operands and is concluded by a semicolon.
401 Multiple operations are separated by a single space character. If
402 there is at least one operation present in an EPD line, it is separated
403 from the last (fourth) data field by a single space character.
405 Some opcodes that allow for more than one operand may have special
406 ordering requirements for the operands. For example, the "pv"
407 (predicted variation) opcode requires its operands (moves) to appear in
408 the order in which they would be played. All other opcodes that allow
409 for more than one operand should have operands appearing in ASCII order.
410 An example of the latter set is the "bm" (best move[s]) opcode; its
411 operands are moves that are all immediately playable from the current
415 File: chess.info, Node: Opcode "acd" analysis count depth, Next: Opcode "acn" analysis count nodes, Prev: Operations, Up: EPD notation
417 1.1.6.2 Opcode "acd" analysis count depth
418 .........................................
420 The opcode "acd" takes a single non-negative integer operand. It is
421 used to represent the ply depth examined in an analysis.
424 File: chess.info, Node: Opcode "acn" analysis count nodes, Next: Opcode "acs" analysis count seconds, Prev: Opcode "acd" analysis count depth, Up: EPD notation
426 1.1.6.3 Opcode "acn" analysis count nodes
427 .........................................
429 The opcode "acn" takes a single non-negative integer operand. It is
430 used to represent the number of nodes examined in an analysis. Note
431 that the value may be quite large for some extended searches and so use
432 of (at least) a long (four byte) representation is suggested.
435 File: chess.info, Node: Opcode "acs" analysis count seconds, Next: Opcode "am" avoid move(s), Prev: Opcode "acn" analysis count nodes, Up: EPD notation
437 1.1.6.4 Opcode "acs" analysis count seconds
438 ...........................................
440 The opcode "acs" takes a single non-negative integer operand. It is
441 used to represent the number of seconds used for an analysis. Note that
442 the value may be quite large for some extended searches and so use of
443 (at least) a long (four byte) representation is suggested.
446 File: chess.info, Node: Opcode "am" avoid move(s), Next: Opcode "bm" best move(s), Prev: Opcode "acs" analysis count seconds, Up: EPD notation
448 1.1.6.5 Opcode "am" avoid move(s)
449 .................................
451 The opcode "am" indicates a set of zero or more moves, all immediately
452 playable from the current position, that are to be avoided in the
453 opinion of the EPD writer. Each operand is a SAN move; they appear in
457 File: chess.info, Node: Opcode "bm" best move(s), Prev: Opcode "am" avoid move(s), Up: EPD notation
459 1.1.6.6 Opcode "bm" best move(s)
460 ................................
462 The opcode "bm" indicates a set of zero or more moves, all immediately
463 playable from the current position, that are judged to the best
464 available by the EPD writer. Each operand is a SAN move; they appear in
468 File: chess.info, Node: Plies, Next: Variations, Prev: Positions, Up: The chess.el library
473 A "ply" is the differential between two positions. Or, it is the
474 coordinate transformations applied to one position in order to arrive at
475 the following position. It is also informally called "a move".
477 A ply may be represented in ASCII by printing the FEN string of the
478 base position, and then printing the positional transformation in
479 algebraic notation. Since the starting position is usually known, the
480 FEN string is optional. A ply may be represented graphically by moving
481 the chess piece(s) involved. It may be rendered verbally by voicing
482 which piece is to move, where it will move to, and what will happen a
483 result of the move (piece capture, check, etc).
485 Plies may be sent over network connections, postal mail, e-mail,
486 etc., so long as the current position is maintained at both sides.
487 Transmitting the base position's FEN string along with the ply offers a
488 form of confirmation during the course of a game.
494 * The "next" position::
495 * Algebraic notation::
498 File: chess.info, Node: Creating plies, Next: Ply details, Prev: Plies, Up: Plies
503 -- Function: chess-ply-create position &optional valid-p &rest changes
504 Create a ply from the given POSITION by applying the supplied
505 CHANGES. This function will guarantee the resulting ply is legal,
506 and will also annotate the ply with :check or other modifiers as
507 necessary. It will also extend castling, and will prompt for a
510 Note: Do not pass in the rook move if CHANGES represents a castling
513 -- Function: chess-legal-plies position &rest keywords
514 Return a list of all legal plies in POSITION. KEYWORDS allowed
517 :any return t if any piece can move at all :color <t or nil> :piece
518 <piece character> :file <number 0 to 7> [can only be used if :piece
519 is present] :index <coordinate index> :target <specific target
520 index> :candidates <list of inddices>
522 These will constrain the plies generated to those matching the
525 NOTE: All of the returned plies will reference the same copy of the
526 position object passed in.
529 File: chess.info, Node: Ply details, Next: The "next" position, Prev: Creating plies, Up: Plies
534 -- Function: chess-ply-pos ply
535 Returns the base position associated with PLY.
537 -- Function: chess-ply-set-pos ply position
538 Set the base position of PLY.
540 -- Function: chess-ply-source ply
541 Returns the source square index value of PLY.
543 -- Function: chess-ply-target ply
544 Returns the target square index value of PLY.
547 File: chess.info, Node: The "next" position, Next: Algebraic notation, Prev: Ply details, Up: Plies
549 1.2.3 The "next" position
550 -------------------------
552 -- Function: chess-ply-next-pos ply
553 Return the position that results from executing PLY.
555 -- Function: chess-ply-final-p ply
556 Return non-nil if this is the last ply of a game/variation.
559 File: chess.info, Node: Algebraic notation, Prev: The "next" position, Up: Plies
561 1.2.4 Algebraic notation
562 ------------------------
564 A thing to deal with in chess is algebraic move notation, such as Nxf3+.
565 (I leave description of this notation to better manuals than this).
566 This notation is a shorthand way of representing where a piece is moving
567 from and to, by specifying the piece is involved, where it's going, and
568 whether or not a capture or check is involved.
570 You can convert from algebraic notation to a ply (one pair in most
571 cases, but two for a castle) using the following function (NOTE:
572 POSITION determines which side is on move (by calling
573 'chess-pos-side-to-move')):
575 -- Function: chess-algebraic-to-ply position move &optional trust
576 Convert the algebraic notation MOVE for POSITION to a ply.
578 The function also checks if a move is legal, and will raise an error
581 To convert from a ply to algebraic notation, use:
583 -- Function: chess-ply-to-algebraic ply &optional long
584 Convert the given PLY to algebraic notation. If LONG is non-nil,
585 render the move into long notation.
587 Lastly, there is a regexp for quickly checking if a string is in
588 algebraic notation or not, or searching out algebraic strings in a
591 -- Variable: chess-algebraic-regexp
592 A regular expression that matches all possible algebraic moves.
593 This regexp handles both long and short form.
596 File: chess.info, Node: Variations, Next: Games, Prev: Plies, Up: The chess.el library
601 A "variation" is a sequence of plies that occur after some starting
602 position. If the starting position represents the initial setup of a
603 chess board, and if the final ply results in completion of the game, it
604 is called the "main variation". Otherwise, variations typically
605 represented interesting tangents during a game--but not actually
606 played--as envisioned by the player, an annotator, or someone studying
609 Variations may be represented in ASCII by stating the FEN string for
610 starting position, followed by the list of plies that follow that
611 position. They are difficult to represent graphically, except for
612 showing each position in turn with a slight pause between--or by
613 allowing the user to navigate each of the subsequent positions in turn.
614 They may be represented verbally by announcing each of the plies in
615 turn, as mentioned above.
619 * Creating variations::
620 * Variation positions::
622 * Making a move in a variation::
625 File: chess.info, Node: Creating variations, Next: Variation positions, Prev: Variations, Up: Variations
627 1.3.1 Creating variations
628 -------------------------
630 -- Function: chess-var-create &optional position
631 Create a new chess variation object. Optionally use the given
635 File: chess.info, Node: Variation positions, Next: Varation plies, Prev: Creating variations, Up: Variations
637 1.3.2 Variation positions
638 -------------------------
640 -- Function: chess-var-pos var &optional index
641 Return the position related to VAR's INDEX ply.
643 -- Function: chess-var-index var
644 Return the VAR's current position index.
646 -- Function: chess-var-seq var
647 Return the current VAR sequence.
649 -- Function: chess-var-side-to-move var &optional index
650 Return the color whose move it is in VAR at INDEX (or at the last
651 position of the variation if INDEX is nil).
654 File: chess.info, Node: Varation plies, Next: Making a move in a variation, Prev: Variation positions, Up: Variations
659 -- Function: chess-var-ply var &optional index
660 Return VAR's INDEXth ply.
662 -- Function: chess-var-plies var
663 Return the plies of VAR.
665 -- Function: chess-var-to-algebraic var &optional long
666 Reveal the plies of VAR by converting them to algebraic notation.
669 File: chess.info, Node: Making a move in a variation, Prev: Varation plies, Up: Variations
671 1.3.4 Making a move in a variation
672 ----------------------------------
674 -- Function: chess-var-move var ply
675 Make a move in the current VAR by applying the changes of PLY.
676 This creates a new position and adds it to the main variation. The
677 'changes' of the last ply reflect whether the var is currently in
678 progress (nil), if it is drawn, resigned, mate, etc.
680 -- Function: chess-var-add-ply var ply
681 Return the position related to VAR's INDEX position.
684 File: chess.info, Node: Games, Next: Collections, Prev: Variations, Up: The chess.el library
689 A "game" includes its main variation, incidental information about the
690 game (who played it, where, when, who won, etc), and any sub-variations
691 of interest to those studying the game afterwards.
693 Where TAGS is an alist that associates arbitrary English tag names to
696 A game may be represented in ASCII using PGN (Portable Game
697 Notation). Representing them graphically or verbally is similar to what
698 is done for variations.
700 -- Function: chess-game-add-hook game function &optional data prepend
701 Add to GAME an event hook FUNCTION.
703 -- Function: chess-game-add-ply game ply
704 Add PLY to the main variation of GAME.
706 -- Function: chess-game-hooks game
707 Return the event hooks associated with GAME.
709 -- Function: chess-game-plies game
710 Return the main variation of GAME as a list of plies.
712 -- Function: chess-game-remove-hook game function &optional data
713 Remove from GAME all event hooks that match FUNCTION. If DATA is
714 specified, only remove those hooks whose associated data matches.
716 -- Function: chess-game-run-hooks game &rest args
717 Run the event hooks of GAME and pass ARGS.
719 -- Function: chess-game-set-hooks game hooks
720 Set the event hooks associated with GAME.
722 -- Function: chess-game-set-plies game plies
723 Set the list of plies which represents the main variation of GAME.
735 File: chess.info, Node: Creating games, Next: Game tags, Prev: Games, Up: Games
740 -- Function: chess-game-create &optional position tags
741 Create a new chess game object. Optionally use the given starting
742 POSITION (see also 'chess-game-set-start-position'). TAGS is the
743 starting set of game tags (which can always be changed later using
744 the various tag-related methods).
747 File: chess.info, Node: Game tags, Next: Game positions, Prev: Creating games, Up: Games
752 -- Function: chess-game-tags game
753 Return the tags alist associated with GAME.
755 -- Function: chess-game-set-tags game tags
756 Set the tags alist associated with GAME. After the TAGS alist was
757 set the 'set-tags event is triggered.
759 -- Function: chess-game-tag game tag
760 Return the value for TAG in GAME.
762 -- Function: chess-game-set-tag game tag value
763 Set a TAG for GAME to VALUE.
765 -- Function: chess-game-del-tag game tag
766 Delete a TAG from GAME.
769 File: chess.info, Node: Game positions, Next: Game plies, Prev: Game tags, Up: Games
774 -- Function: chess-game-pos game &optional index
775 Return the current position of GAME or a position of a given INDEX.
777 -- Function: chess-game-index game
778 Return the GAME's current position index.
780 -- Function: chess-game-seq game
781 Return the current GAME sequence number.
783 -- Function: chess-game-side-to-move game &optional index
784 Return the color whose move it is in GAME at INDEX (or at the last
785 position if INDEX is nil). 't' for white and 'nil' for black.
788 File: chess.info, Node: Game plies, Next: Making a move, Prev: Game positions, Up: Games
793 -- Function: chess-game-ply game &optional index
794 Return a ply of GAME. If INDEX is non-nil, the last played ply is
798 File: chess.info, Node: Making a move, Next: PGN notation, Prev: Game plies, Up: Games
803 -- Function: chess-game-move game ply
804 Make a move in the current GAME using PLY. This creates a new
805 position and adds it to the main variation. The 'changes' of the
806 last ply reflect whether the game is currently in progress (nil),
807 if it is drawn, resigned, mate, etc.
810 File: chess.info, Node: PGN notation, Prev: Making a move, Up: Games
815 -- Function: chess-pgn-to-game &optional string
816 Convert "PGN notation" at point into a chess game. Optionally use
817 the supplied STRING instead of the current buffer.
819 -- Function: chess-game-to-pgn game &optional indented to-string
820 Convert a chess GAME to "PGN notation". If INDENTED is non-nil,
821 indent the move texts. If TO-STRING is non-nil, return a string
822 instead of inserting the resulting PGN text.
824 -- Function: chess-pgn-insert-plies game index plies &optional
825 for-black indented no-annotations
826 NYI: Still have to implement INDENTED argument.
833 File: chess.info, Node: PGN mode, Prev: PGN notation, Up: PGN notation
838 -- Function: chess-pgn-visualize
839 Visualize the move for the PGN game under point. This does not
840 require that the buffer be in PGN mode.
843 File: chess.info, Node: Collections, Next: Chess Opening Books, Prev: Games, Up: The chess.el library
848 A "collection" is a set of games archived for later perusal. A set of
849 games conceptually represents a large tree of branching variations, and
850 can be used for studying current theory, examining Master preferences,
853 Chess.el itself does not attempt to provide library services, nor
854 does it ever represent library collections in memory. Instead, it
855 interacts with a chess database engine for the purpose of storing and
856 retrieving games from the library, or performing library-wide analyses
861 * Opening Databases::
862 * Querying Databases::
863 * Modifying Databases::
864 * Finalising Databases::
868 File: chess.info, Node: Opening Databases, Next: Querying Databases, Prev: Collections, Up: Collections
870 1.5.1 Opening Databases
871 -----------------------
873 -- Variable: chess-database-modules
874 List of database modules to try when 'chess-database-open' is
877 -- Function: chess-database-open file &optional module
878 Returns the opened database object, or nil.
881 File: chess.info, Node: Querying Databases, Next: Modifying Databases, Prev: Opening Databases, Up: Collections
883 1.5.2 Querying Databases
884 ------------------------
886 -- Function: chess-database-filename database
887 Return the filename of an already opened DATABASE.
889 -- Function: chess-database-read database index
890 Return from DATABASE the chess game object at INDEX.
892 -- Function: chess-database-query database &rest terms
893 Run a query on DATABASE. TERMS is partly dependent on the
894 chess-database module in use. chess-scid: tree-search GAME:
895 Perform a tree search on the last position of GAME.
898 File: chess.info, Node: Modifying Databases, Next: Finalising Databases, Prev: Querying Databases, Up: Collections
900 1.5.3 Modifying Databases
901 -------------------------
903 -- Function: chess-database-read-only-p database
904 Return non-nil if DATABASE is read only.
907 File: chess.info, Node: Finalising Databases, Next: Database Modules, Prev: Modifying Databases, Up: Collections
909 1.5.4 Finalising Databases
910 --------------------------
913 File: chess.info, Node: Database Modules, Prev: Finalising Databases, Up: Collections
915 1.5.5 Database Modules
916 ----------------------
918 Currently, there are two subclasses of the above defined database
927 File: chess.info, Node: chess-file, Next: chess-scid, Prev: Database Modules, Up: Database Modules
932 This module does not use an external chess database program to store and
933 retrieve games. It uses the PGN of EPD format parsing routines provided
934 in 'chess-pgn.el' and 'chess-epd.el' to implement Collections for
935 ordinary PGN and EPD files.
937 EPD file collections are represented as a collection of games
938 originating at the given position. One might argue that conceptually,
939 they represent a collection of positions, but it is more convenient to
940 merge all collections into one uniform concept.
943 File: chess.info, Node: chess-scid, Prev: chess-file, Up: Database Modules
948 This modules implement basic reading and writing functionality for SCID
949 (Shane's Chess Information Database) files.
952 File: chess.info, Node: Chess Opening Books, Prev: Collections, Up: The chess.el library
954 1.6 Chess Opening Books
955 =======================
957 There are two different modules/libraries provided for looking up chess
958 positions in opening books.
962 * ECO Classification::
963 * Polyglot opening book format support::
966 File: chess.info, Node: ECO Classification, Next: Polyglot opening book format support, Prev: Chess Opening Books, Up: Chess Opening Books
968 1.6.1 ECO Classification
969 ------------------------
971 Module 'chess-eco' provides a database of well known names for chess
972 opening positions. If this module is activated (see variable
973 'chess-default-modules') known chess opening positions will be announced
974 in the minibuffer during a game.
977 File: chess.info, Node: Polyglot opening book format support, Prev: ECO Classification, Up: Chess Opening Books
979 1.6.2 Polyglot opening book format support
980 ------------------------------------------
982 The popular and freely documented Polyglot opening book format is
983 supported. There is a default polyglot book file shipped with chess.el
984 to support engines which do not have built-in support for looking up
985 positions in opening books (such as some UCI protocol based engines).
987 -- Variable: chess-polyglot-book-file
988 Path to default polyglot book file.
990 -- Variable: chess-polyglot-book
991 If non-nil, the buffer holding the currently loaded polyglot book
994 This is used by UCI based engine modules as well as the internal
997 -- Function: chess-polyglot-book-open file
998 Open a polyglot book FILE.
1000 Returns a buffer object which contains the binary data.
1002 -- Function: chess-polyglot-book-plies book position
1003 Return a list of plies found in BOOK for POSITION. The resulting
1004 list is ordered, most interesting plies come first. The
1005 ':polyglot-book-weight' ply keyword is used to store the actual
1006 move weights. Use 'chess-ply-keyword' on elements of the returned
1007 list to retrieve them.
1009 -- Function: chess-polyglot-book-ply book position &optional strength
1010 If non-nil a (randomly picked) ply from BOOK for POSITION. Random
1011 distribution is defined by the relative weights of the found plies.
1012 If non-nil, STRENGTH defines the bias towards better moves. A
1013 value below 1.0 will penalize known good moves while a value above
1014 1.0 will prefer known good moves. The default is the value of
1015 'chess-polyglot-book-strength'. A strength value of 0.0 will
1016 completely ignore move weights and evenly distribute the
1017 probability that a move gets picked.
1020 File: chess.info, Node: Modules, Next: Chessboard displays, Prev: The chess.el library, Up: Top
1025 Positions, plies and variations are typically accessed in reference to a
1026 game object, which has a main variation containing the plies and
1027 positions that represent the number of moves made within that game up to
1030 Another thing that the game object does is to manage events that
1031 occur within that game. If a move is made from the final position, for
1032 example, it will cause a new ply to be created, adding it to the end of
1033 the main variation. Then, a 'move' event is triggered within the game
1034 and passed to any chess modules which are currently associated with that
1035 game. The concept of modules allows far more complex aspects of chess
1036 playing to be dealt with, while allowing the library itself to still
1037 operate solely in terms of the game object.
1039 For example, although the plies of a game object contain all the
1040 information the computer needs to follow the game, a user needs much
1041 more. He wants to see the pieces move. To support this, a display
1042 module (see next chapter) can be created, and linked to the game. The
1043 first effect of this association will be to create a chess board display
1044 and show the game's final position on it. Now whenever plies are added
1045 to the game, the chess board will be updated to show the effect of that
1046 move on the board. The display module realizes that a move has been
1047 made by receiving the 'move' event which is passed to all modules
1048 associated with the game object.
1050 There may be any number of modules associated with a chess game, and
1051 they may do anything you like. Basically, for a module called
1052 chess-sample, a function must exist called 'chess-sample-handler'. This
1053 takes two or more arguments: a game object, the event symbol, and
1054 whatever other arguments were passed along with the event symbol.
1056 When an event is triggered on a game object (and this may happen as a
1057 byproduct of manipulating the game, or events may be manually
1058 generated), every associated module, in order, is called with that event
1059 and whatever arguments were passed along with the event. The game
1060 object is passed also, so that the module knows which game this event
1061 has occurred in reference to.
1063 Once called, the module can do whatever it likes. Some events expect
1064 certain values to be returned, to indicate success or failure in
1065 processing the event. There are many different events, each depicting
1066 something specific that might happen in the context of playing or
1067 manipulating a chess game. Some events relate only to the chess game
1068 itself, some are triggered by the various chess engines that might be
1069 associated with that game. Modules may even trigger events in response
1070 to event. The game itself remains unaware of events, except for the
1071 fact that it will pass them along to every module associated with that
1074 This is how displays get updated, for example, because once a 'move'
1075 event is triggered, each display knows that it must now look at the new
1076 final position and update its display. It may even trigger new events
1077 special to displays, to cause a refresh to happen after update
1078 calculations have been performed, for example. All such details are
1079 left to the module, and the game does not interfere with such
1080 intra-module messaging.
1082 Looked at as an object-oriented design, these are typical polymorphic
1083 events. Certain generic situations frequently occur, such as moves,
1084 which trigger events so that everyone concerned with the game can be
1085 updated as to the move that occurred. This way, no one need to actively
1086 query the game to find out if something new has happened. The game will
1087 notify every listening module by sending an event.
1089 The core library, which consists of code to manipulate games, does
1090 not define any modules. The rest of the chess.el library is strictly a
1091 set of module implementations, of various types. Display modules react
1092 to moves, and may modify the game based on user input; engine modules
1093 react to moves by notifying the engine of the move; network client
1094 modules react to moves by sending the move text over the network.
1095 Engine and network modules may also trigger new events when the engine
1096 or network player has decided on their move, and this move is then
1097 applied to the game object.
1099 At the moment, no negotiation is done to determine which module may
1100 modify the game object. All modules have equal privilege. This means
1101 it is the programmer's duty not to associate conflicting modules with a
1102 single game object. If two artificial intelligence engines were linked,
1103 for example, they would quickly start stepping on each other's toes.
1104 But it perfectly fine to have one artificial intelligence engine, and
1105 another passive engine whose only purpose is to relay the moves to a
1106 networked observer on another computer. The possibilities are endless.
1108 Modules are very easy to write, although engines and displays are
1109 rather different from each other in their principles. There is a base
1110 engine, and a base display, which receive the same events as any other
1111 module. But then there are derived engines and derived displays which
1112 trigger a whole family of events specific to those module types. If you
1113 suspect a bug in your module, put a breakpoint in your handler function,
1114 and wait for the offending event to come through. Then you can watch
1115 what your module does in response to that event. If it leaves the game
1116 object alone, it should be easy to locate the problem, since it will
1117 always be within the module itself. But if your module also modifies
1118 the game object in response to certain events, you may induce a feedback
1119 loop that is much more difficult to sort out. Test often and keep in
1120 mind that *many* events might end up coming through as a result of the
1121 game changes your module makes!
1123 That, in essence, is how the module system works. From the game
1124 object's perspective, it is a very simple mechanism, much like a
1125 function ring or a hook. The hook is called at certain points, so that
1126 any listener can react to changes in the game. But from each module's
1127 perspective, it is a rich way to allow inter-operation between both
1128 passive and reactive modules, all of them acting together to enrich the
1129 context of play involving the central game object.
1131 The only other rule to be mentioned is that each module instance
1132 should be associated with only one game object at a time, although a
1133 game object may have unlimited modules of any type linked to it.
1134 Otherwise, trying to update a chess board based on input from two
1135 different games would get impossible to sort out. Better to create a
1136 new board for every game--the way ordinary humans would do it in the
1140 File: chess.info, Node: Chessboard displays, Next: Engines, Prev: Modules, Up: Top
1142 3 Chessboard displays
1143 *********************
1145 The previous chapter described all the objects found in
1146 chess--positions, plies, variations, games and collections. However,
1147 these objects can only be manipulated programmatically using the
1148 functions given so far. In order to present them in a meaningful
1149 fashion to a human reader, it is necessary to create and use a display
1154 * Generic display manipulation functions::
1155 * Chess display mode::
1156 * Plain ASCII diagram displays::
1157 * ICS1 style ASCII displays::
1158 * Graphical displays::
1161 File: chess.info, Node: Generic display manipulation functions, Next: Chess display mode, Prev: Chessboard displays, Up: Chessboard displays
1163 3.1 Generic display manipulation functions
1164 ==========================================
1166 -- Function: chess-display-create game style perspective
1167 Create a chess display, for displaying chess objects. Where GAME
1168 is the chess game object to use, STYLE should be the display type
1169 to use (a symbol) and PERSPECTIVE determines the viewpoint of the
1170 board, if non-nil, the board is viewed from White's perspective.
1172 -- Function: chess-display-active-p
1173 Return non-nil if the displayed chessboard reflects an active game.
1174 Basically, it means we are playing, not editing or reviewing.
1176 -- Function: chess-display-clear-board
1177 Setup the current board for editing.
1179 -- Function: chess-display-highlight display &rest args
1180 Highlight the square at INDEX on the current position. The given
1181 highlighting MODE is used, or the default if the style you are
1182 displaying with doesn't support that mode. 'selected' is a mode
1183 that is supported by most displays, and is the default mode.
1185 -- Function: chess-display-invert
1186 Invert the perspective of the current chess board.
1188 -- Function: chess-display-move display ply
1189 Move a piece on DISPLAY, by applying the given PLY. The position
1190 of PLY must match the currently displayed position.
1192 -- Function: chess-display-perspective display
1193 Return the current perspective of DISPLAY.
1195 -- Function: chess-display-position display
1196 Return the position currently viewed on DISPLAY.
1198 -- Function: chess-display-quit
1199 Quit the game associated with the current display.
1201 -- Function: chess-display-set-game display game &optional index
1202 Set the given DISPLAY to display the GAME object, optionally at
1203 INDEX. This is the function to call to cause a display to view a
1204 game. It will also update all of the listening engines and other
1205 displays to also view the same game.
1207 -- Function: chess-display-set-perspective display perspective
1208 Set PERSPECTIVE of DISPLAY.
1210 -- Function: chess-display-set-position display &optional position
1212 Set the game associated with DISPLAY to use POSITION and MY-COLOR.
1214 -- Function: chess-display-set-variation display variation &optional
1216 Set DISPLAY VARIATION. If INDEX is not specified, this will cause
1217 the first ply in the variation to be displayed, with the user able
1218 to scroll back and forth through the moves in the variation. Any
1219 moves made on the board will extend/change the variation that was
1222 -- Function: chess-display-update display &optional popup
1223 Update the chessboard DISPLAY. POPUP too, if that arg is non-nil.
1226 File: chess.info, Node: Chess display mode, Next: Plain ASCII diagram displays, Prev: Generic display manipulation functions, Up: Chessboard displays
1228 3.2 Chess display mode
1229 ======================
1231 Chess display mode is a special major mode (*note (emacs)Major Modes::)
1232 that allows to select pieces to move with the mouse or by moving point
1233 to the desired square/piece. Additionally, you can enter moves in a
1234 variant of algebraic notation via the keyboard.
1236 All the chessboard displays described in following sections share the
1237 basic behaviour provided by chess display mode. They basically only
1238 differ in appearance of the various chessboards.
1242 Invert the perspective of the current chess board.
1249 Select the piece/square currently indicated by point
1250 ('chess-display-select-piece') to move from/to.
1253 Show the previous move in the current game.
1256 Show the next move in the current game.
1259 Move to the initial position of the current game
1260 ('chess-display-move-first').
1263 Move to the last position of the current game
1264 ('chess-display-move-last').
1267 Offer to draw the current game ('chess-display-draw').
1270 Resign the current game ('chess-display-resign').
1273 Copy the currently displays position to the kill ring as a FEN
1274 string ('chess-display-kill-board').
1277 Quit this chessboard display ('chess-display-quit').
1280 File: chess.info, Node: Plain ASCII diagram displays, Next: ICS1 style ASCII displays, Prev: Chess display mode, Up: Chessboard displays
1282 3.3 Plain ASCII diagram displays
1283 ================================
1285 The simplest display style available is chess-plain, a very customisable
1286 ASCII board diagram display.
1288 -- Variable: chess-plain-separate-frame
1289 If non-nil, display the chessboard in its own frame.
1291 -- Variable: chess-plain-border-style
1292 If non-nil, a vector of Characters used to draw borders.
1294 Otherwise, omit to draw any border around the chessboard diagram.
1296 -- Variable: chess-plain-black-square-char
1297 Character used to indicate empty black squares.
1299 -- Variable: chess-plain-white-square-char
1300 Character used to indicate black white squares.
1302 -- Variable: chess-plain-piece-chars
1303 Alist of pieces and their corresponding characters.
1305 -- Variable: chess-plain-upcase-indicates
1306 Defines what a upcase char should indicate. The default is 'color,
1307 meaning a upcase char is a white piece, a lowercase char a black
1308 piece. Possible values: 'color (default), 'square-color. If set
1309 to 'square-color, a uppercase character indicates a piece on a
1310 black square. (Note that you also need to modify
1311 'chess-plain-piece-chars' to avoid real confusion.)
1313 -- Variable: chess-plain-spacing
1314 Number of spaces between files.
1317 File: chess.info, Node: ICS1 style ASCII displays, Next: Graphical displays, Prev: Plain ASCII diagram displays, Up: Chessboard displays
1319 3.4 ICS1 style ASCII displays
1320 =============================
1322 -- Variable: chess-ics1-separate-frame
1323 If non-nil, display the chessboard in its own frame.
1326 File: chess.info, Node: Graphical displays, Prev: ICS1 style ASCII displays, Up: Chessboard displays
1328 3.5 Graphical displays
1329 ======================
1331 The graphical chessboard display ('chess-images') uses image files to
1332 create a visually appealing chessboard in a buffer.
1334 -- Variable: chess-images-directory
1335 A directory which contains images in XPM format.
1337 If you want to draw your own images, each piece must be named
1338 'COLOR-PIECE.xpm', where COLOR is either black or white, and PIECE
1339 is one of rook, knight, bishop, queen, king or pawn.
1341 The only image format currently supported is XPM.
1344 File: chess.info, Node: Engines, Next: Internet Chess Servers, Prev: Chessboard displays, Up: Top
1349 Engines are the representation of an opponent in Chess. THe main type
1350 of engine interfaces with an external chess program. However, there can
1351 be other uses for engine objects, such as providing networked engined
1352 for playing with opponent over different types of transports.
1356 * Common functions::
1367 File: chess.info, Node: Common functions, Next: AI, Prev: Engines, Up: Engines
1369 4.1 Common functions
1370 ====================
1372 -- Function: chess-engine-create module game &optional response-handler
1373 &rest handler-ctor-args
1374 Create a new chess engine MODULE (a symbol) associated with GAME.
1375 Optionally supply a new RESPONSE-HANDLER.
1377 -- Function: chess-engine-set-option engine option value
1378 Set ENGINE OPTION to VALUE by invoking its handler with the
1381 -- Function: chess-engine-position engine
1382 Return the current position of the game associated with ENGINE.
1384 -- Function: chess-engine-command engine event &rest args
1385 Call the handler of ENGINE with EVENT (a symbol) and ARGS.
1387 -- Function: chess-engine-send engine string
1388 Send the given STRING to ENGINE. If 'chess-engine-process' is a
1389 valid process object, use 'process-send-string' to submit the data.
1390 Otherwise, the 'send event is triggered and the engine event
1391 handler can take care of the data.
1394 File: chess.info, Node: AI, Next: Crafty, Prev: Common functions, Up: Engines
1399 The "AI" engine module defines a pure Emacs Lisp implementation of an
1400 opponent. Contrary to all other engine modules mentioned later on, it
1401 does not require any external programs to be installed.
1403 To explicitly select this engine as an opponent, use 'C-u M-x chess
1406 -- User Option: chess-ai-depth
1407 Defines the default search depth for this engine.
1409 -- User Option: chess-ai-quiescence-depth
1410 Defines the number of plies to search for a quiet position. This
1411 is in addition to 'chess-ai-depth'.
1413 If you'd like to employ the search and evaluation functions provided
1414 by this module programmatically, the following function is the top-level
1417 -- Function: chess-ai-best-move position &optional depth eval-fn
1418 Find the supposedly best move (ply) for POSITION. DEPTH defaults
1419 to the value of 'chess-ai-depth'.
1422 File: chess.info, Node: Crafty, Next: Fruit, Prev: AI, Up: Engines
1427 Crafty is a chess program written by Michael Byrne, UAB professor Dr.
1428 Robert Hyatt, Tracy Riegle, Peter Skinner and Ted Langreck. It is
1429 directly derived from Cray Blitz, winner of the 1983 and 1986 World
1430 Computer Chess Championships.
1432 If Crafty is installed and can be found in the program search path,
1433 the 'chess-crafty' engine module will automatically detect it.
1435 If Crafty is installed in a non-standard location, variable
1436 'chess-crafty-path' can be set to point to the executable.
1438 If you have multiple engines installed you can explicitly select to
1439 play against Crafty by invoking 'C-u M-x chess <RET> crafty <RET>'.
1442 File: chess.info, Node: Fruit, Next: Glaurung, Prev: Crafty, Up: Engines
1447 Fruit is a chess engine developed by Fabien Letouzey. It was
1448 commercially available from September 2005 until July 2007. Now it is
1449 freeware and you can download it for free from
1450 <http://www.fruitchess.com/>. The development on Fruit by Fabien
1451 Letouzey has ceded and it is unlikely to continue.
1453 Fruit was vice world computer chess champion 2005.
1455 If Fruit is installed and can be found in the program search path,
1456 the 'chess-fruit' engine module will automatically detect it.
1458 If Fruit is installed in a non-standard location, variable
1459 'chess-fruit-path' can be set to point to the executable.
1461 If you have multiple engines installed you can explicitly select to
1462 play against Fruit by invoking 'C-u M-x chess <RET> fruit <RET>'.
1465 File: chess.info, Node: Glaurung, Next: GNU Chess, Prev: Fruit, Up: Engines
1470 Glaurung is another freely distributed strong computer chess engine.
1472 If Glaurung is installed and can be found in the program search path,
1473 the 'chess-glaurung' engine module will automatically detect it.
1475 If Glaurung is installed in a non-standard location, variable
1476 'chess-glaurung-path' can be set to point to the executable.
1478 If you have multiple engines installed you can explicitly select to
1479 play against Glaurung by invoking 'C-u M-x chess <RET> glaurung <RET>'.
1482 File: chess.info, Node: GNU Chess, Next: Phalanx, Prev: Glaurung, Up: Engines
1487 GNU Chess is free software, licensed under the terms of the GNU General
1488 Public License version 3 or any later version, and is maintained by
1489 collaborating developers. As one of the earliest computer chess
1490 programs with full source code available, it's one of the oldest for
1491 Unix-based systems and has since been ported to many other platforms.
1493 If GNU Chess is installed and can be found in the program search
1494 path, the 'chess-gnuchess' engine module will automatically detect it.
1496 If GNU Chess is installed in a non-standard location, variable
1497 'chess-gnuchess-path' can be set to point to the executable.
1499 If you have multiple engines installed you can explicitly select to
1500 play against GNU Chess by invoking .
1503 File: chess.info, Node: Phalanx, Next: Sjeng, Prev: GNU Chess, Up: Engines
1508 Phalanx is an old, popular chess engine, with an interesting history.
1510 If Phalanx is installed and can be found in the program search path,
1511 the 'chess-phalanx' engine module will automatically detect it.
1513 If Phalanx is installed in a non-standard location, variable
1514 'chess-phalanx-path' can be set to point to the executable.
1516 If you have multiple engines installed you can explicitly select to
1517 play against Phalanx by invoking 'C-u M-x chess <RET> phalanx <RET>'.
1520 File: chess.info, Node: Sjeng, Next: Stockfish, Prev: Phalanx, Up: Engines
1525 Sjeng (http://sjeng.org/) is a championship-winner automated chess
1526 engine developed by Gian-Carlo Pascutto from Belgium. While its
1527 original version was free, recent developments are for sale.
1529 If Sjeng is installed and can be found in the program search path,
1530 the 'chess-sjeng' engine module will automatically detect it.
1532 If Sjeng is installed in a non-standard location, variable
1533 'chess-sjeng-path' can be set to point to the executable.
1535 If you have multiple engines installed you can explicitly select to
1536 play against Sjeng by invoking 'C-u M-x chess <RET> sjeng <RET>'.
1539 File: chess.info, Node: Stockfish, Prev: Sjeng, Up: Engines
1544 Stockfish (http://www.stockfishchess.org/) is one of the strongest chess
1545 engines in the world, appearing near or at the top of most chess engine
1546 rating lists. Stockfish is also free software, licensed under the terms
1547 of the GNU General Public License.
1549 If Stockfish is installed and can be found in the program search
1550 path, the 'chess-stockfish' engine module will automatically detect it.
1552 If Stockfish is installed in a non-standard location, variable
1553 'chess-stockfish-path' can be set to point to the executable.
1555 If you have multiple engines installed you can explicitly select to
1556 play against Stockfish by invoking 'C-u M-x chess <RET> stockfish
1560 File: chess.info, Node: Internet Chess Servers, Next: Concept Index, Prev: Engines, Up: Top
1562 5 Internet Chess Servers
1563 ************************
1565 Based on the services provided above, there is also a special mode for
1566 communication with Internet Chess Servers.
1568 On an Internet Chess Server you can seek to play against other human
1569 or computer players, observe other games being player or examined, play
1570 tournaments, chat with fellow chess players, participate in team games,
1571 or do various other interesting chess related things.
1573 A default set of well known servers is defined in the following
1576 -- Variable: chess-ics-server-list
1577 A list of servers to connect to. The format of each entry is:
1579 (SERVER PORT [HANDLE] [PASSWORD-OR-FILENAME] [HELPER] [HELPER
1582 Internet Chess Servers based on FICS (Free Internet Chess Server)
1583 (http://www.freechess.org/) and ICC (Internet Chess Club)
1584 (http://www.chessclub.com/) are currently supported.
1588 * Connecting to a server::
1591 * Seeking an opponent for a new game::
1592 * The sought game display::
1595 File: chess.info, Node: Connecting to a server, Next: Chess ICS Mode, Prev: Internet Chess Servers, Up: Internet Chess Servers
1597 5.1 Connecting to a server
1598 ==========================
1600 To open a new connection to an Internet Chess Server, use:
1602 -- Function: chess-ics server port &optional handle
1603 password-or-filename helper &rest helper-args
1604 Connect to an Internet Chess Server.
1607 File: chess.info, Node: Chess ICS Mode, Next: Command History, Prev: Connecting to a server, Up: Internet Chess Servers
1612 The major mode for ICS buffers is Chess ICS mode. Many of its special
1613 commands are bound to the 'C-c' prefix. Here is a list of ICS mode
1617 Send the current line as input to the server ('comint-send-input').
1618 Any prompt at the beginning of the line is omitted. If point is at
1619 the end of buffer, this is like submitting the command line in an
1620 ordinary interactive shell. However, you can also invoke <RET>
1621 elsewhere in the ICS buffer to submit the current line as input.
1624 Either delete a character or send EOF (End Of File)
1625 ('comint-delchar-or-maybe-eof'). Typed at the end of the ICS
1626 buffer, this sends EOF to the server and terminates the connection.
1627 Typed at any other position in the buffer, this deletes a character
1631 Move to the beginning of the line, but after the prompt if any
1632 ('comint-bol-or-process-mark'). If you repeat this command twice
1633 in a row, the second time it moves back to the process mark, which
1634 is the beginning of the input that you have not yet sent to the
1635 server. (Normally that is the same place--the end of the prompt on
1636 this line--but after 'C-c <SPC>' the process mark may be in a
1640 Accumulate multiple lines of input, then send them together
1641 ('comint-accumulate'). This command inserts a newline before
1642 point, but does not send the preceding text as input to the
1643 server--at least, not yet. Both lines, the one before this newline
1644 and the one after, will be sent together (along with the newline
1645 that separates them), when you type <RET>.
1648 Kill all text pending at end of buffer to be sent as input
1649 ('comint-kill-input'). If point is not at end of buffer, this only
1650 kills the part of this text that precedes point.
1653 Kill a word before point ('backward-kill-word').
1656 Delete the last batch of output from an ICS server command
1657 ('comint-delete-output'). This is useful if a server command spews
1658 out lots of output that just gets in the way.
1661 Write the last batch of output from an ICS server command to a file
1662 ('comint-write-output'). With a prefix argument, the file is
1663 appended to instead. Any prompt at the end of the output is not
1668 Scroll to display the beginning of the last batch of output at the
1669 top of the window; also move the cursor there
1670 ('comint-show-output').
1673 Scroll to put the end of the buffer at the bottom of the window
1674 ('comint-show-maximum-output').
1676 'M-x comint-truncate-buffer'
1677 This command truncates the ICS buffer to a certain maximum number
1678 of lines, specified by the variable 'comint-buffer-maximum-size'.
1679 Here's how to do this automatically each time you get output from
1682 (add-hook 'comint-output-filter-functions
1683 'comint-truncate-buffer)
1685 ICS mode is a derivative of Comint mode, a general-purpose mode for
1686 communicating with interactive subprocesses. Most of the features of
1687 ICS mode actually come from Comint mode, as you can see from the command
1691 File: chess.info, Node: Command History, Next: Seeking an opponent for a new game, Prev: Chess ICS Mode, Up: Internet Chess Servers
1693 5.3 ICS Command History
1694 =======================
1696 ICS buffers support two ways of repeating earlier commands. You can use
1697 keys like those used for the minibuffer history; these work much as they
1698 do in the minibuffer, inserting text from prior commands while point
1699 remains always at the end of the buffer. You can move through the
1700 buffer to previous inputs in their original place, then resubmit them or
1701 copy them to the end.
1705 * ICS Command Ring::
1706 * ICS History Copying::
1709 File: chess.info, Node: ICS Command Ring, Next: ICS History Copying, Prev: Command History, Up: Command History
1711 5.3.1 ICS Command History Ring
1712 ------------------------------
1716 Fetch the next earlier old ICS command.
1720 Fetch the next later old ICS command.
1723 Begin an incremental regexp search of old ICS commands.
1726 Fetch the next subsequent command from the history.
1729 Fetch one argument from an old ICS command.
1732 Display the buffer's history of ICS commands in another window
1733 ('comint-dynamic-list-input-ring').
1735 ICS buffers provide a history of previously entered commands. To
1736 reuse commands from the history, use the editing commands 'M-p', 'M-n',
1737 'M-r' and 'M-s'. These work just like the minibuffer history commands
1738 (*note (emacs)Minibuffer History::), except that they operate within the
1739 ICS buffer rather than the minibuffer.
1741 'M-p' fetches an earlier ICS command to the end of the ICS buffer.
1742 Successive use of 'M-p' fetches successively earlier commands, each
1743 replacing any text that was already present as potential input. 'M-n'
1744 does likewise except that it finds successively more recent ICS commands
1745 from the buffer. 'C-<UP>' works like 'M-p', and 'C-<DOWN>' like 'M-n'.
1747 The history search command 'M-r' begins an incremental regular
1748 expression search of previous ICS commands. After typing 'M-r', start
1749 typing the desired string or regular expression; the last matching ICS
1750 command will be displayed in the current line. Incremental search
1751 commands have their usual effects--for instance, 'C-s' and 'C-r' search
1752 forward and backward for the next match (*note (emacs)Incremental
1753 Search::). When you find the desired input, type <RET> to terminate the
1754 search. This puts the input in the command line. Any partial input you
1755 were composing before navigating the history list is restored when you
1756 go to the beginning or end of the history ring.
1758 Often it is useful to reexecute several successive ICS commands that
1759 were previously executed in sequence. To do this, first find and
1760 reexecute the first command of the sequence. Then type 'C-c C-x'; that
1761 will fetch the following command--the one that follows the command you
1762 just repeated. Then type <RET> to reexecute this command. You can
1763 reexecute several successive commands by typing 'C-c C-x <RET>' over and
1766 The command 'C-c .' ('comint-input-previous-argument') copies an
1767 individual argument from a previous command, like '<ESC> .' in Bash.
1768 The simplest use copies the last argument from the previous ICS command.
1769 With a prefix argument N, it copies the Nth argument instead. Repeating
1770 'C-c .' copies from an earlier ICS command instead, always using the
1771 same value of N (don't give a prefix argument when you repeat the 'C-c
1774 These commands get the text of previous ICS commands from a special
1775 history list, not from the ICS buffer itself. Thus, editing the ICS
1776 buffer, or even killing large parts of it, does not affect the history
1777 that these commands access.
1780 File: chess.info, Node: ICS History Copying, Prev: ICS Command Ring, Up: Command History
1782 5.3.2 ICS History Copying
1783 -------------------------
1786 Move point to the previous prompt ('comint-previous-prompt').
1789 Move point to the following prompt ('comint-next-prompt').
1792 Copy the input command at point, inserting the copy at the end of
1793 the buffer ('comint-copy-old-input'). This is useful if you move
1794 point back to a previous command. After you copy the command, you
1795 can submit the copy as input with <RET>. If you wish, you can edit
1796 the copy before resubmitting it. If you use this command on an
1797 output line, it copies that line to the end of the buffer.
1800 If 'comint-use-prompt-regexp' is 'nil' (the default), copy the old
1801 input command that you click on, inserting the copy at the end of
1802 the buffer ('comint-insert-input'). If 'comint-use-prompt-regexp'
1803 is non-'nil', or if the click is not over old input, just yank as
1806 Moving to a previous input and then copying it with 'C-c <RET>' or
1807 'Mouse-2' produces the same results--the same buffer contents--that you
1808 would get by using 'M-p' enough times to fetch that previous input from
1809 the history list. However, 'C-c <RET>' copies the text from the buffer,
1810 which can be different from what is in the history list if you edit the
1811 input text in the buffer after it has been sent.
1814 File: chess.info, Node: Seeking an opponent for a new game, Next: The sought game display, Prev: Command History, Up: Internet Chess Servers
1816 5.4 Seeking an opponent for a new game
1817 ======================================
1819 After you connected to a server, one of the first things you will want
1820 to do is find an oponent for a new game. You can use the ICS command
1821 "seek" to announce your availability for a chess game to interested
1826 fics% seek 10 10 rated
1828 This will announce your availability to play a rated game with 10
1829 minutes initial time-control for each player, and 10 seconds added for
1833 File: chess.info, Node: The sought game display, Prev: Seeking an opponent for a new game, Up: Internet Chess Servers
1835 5.5 The sought game display
1836 ===========================
1838 There is a special mode for displaying games sought by other users on an
1839 Internet Chess Server. Provided you didn't turn off seek advertisments
1840 manually (for instance by setting the seek variable to 0 (off) on the
1841 ICS server by issueing "set seek 0"), the first seek advertisment
1842 automatically pops up a new window which is in 'chess-ics-ads-mode', a
1843 derivative of 'tabulated-list-mode'.
1845 -- Function: chess-ics-ads-mode
1846 A mode for displaying ICS game seek advertisments.
1848 This mode runs the hook 'chess-ics-ads-mode-hook', as the final
1849 step during initialization.
1851 key binding -- -----
1853 ? describe-mode RET chess-ics-sought-accept <mouse-2>
1854 chess-ics-sought-accept
1856 In this buffer, use mouse-2 or '<RET>' on a line to accept that
1857 particular game and play it.
1860 File: chess.info, Node: Concept Index, Next: Function and Variable Index, Prev: Internet Chess Servers, Up: Top