Overview

An Emacs major-mode for chess PGN files, powered by Python.

• Quickstart
• pygn-mode
• Interactive Commands
• Minor Mode
• Prior Art
• License
• Compatibility and Requirements

Quickstart

;; maybe
;; (eval-after-load "pygn-mode"
;;   (define-key pygn-mode-map (kbd "C-c C-n") 'pygn-mode-next-game)
;;   (define-key pygn-mode-map (kbd "C-c C-p") 'pygn-mode-previous-game)
;;   (define-key pygn-mode-map (kbd "M-f")     'pygn-mode-next-move)
;;   (define-key pygn-mode-map (kbd "M-b")     'pygn-mode-previous-move)
;;   (define-key pygn-mode-map (kbd "C-c SPC") 'pygn-mode-display-gui-board-at-pos)
;;   (define-key pygn-mode-map (kbd "C-h $")   'pygn-mode-describe-annotation-at-pos))

;; or maybe
;; (eval-after-load "pygn-mode"
;;   (define-key pygn-mode-map (kbd "C-c C-n") 'pygn-mode-next-game)
;;   (define-key pygn-mode-map (kbd "C-c C-p") 'pygn-mode-previous-game)
;;   (define-key pygn-mode-map (kbd "M-f")     'pygn-mode-next-move-follow-board)
;;   (define-key pygn-mode-map (kbd "M-b")     'pygn-mode-previous-move-follow-board)
;;   (define-key pygn-mode-map (kbd "C-c SPC") 'pygn-mode-display-gui-board-at-pos)
;;   (define-key pygn-mode-map (kbd "C-h $")   'pygn-mode-describe-annotation-at-pos))

(require 'pygn-mode)

M-x pygn-mode-run-diagnostic

pygn-mode

Provides

• syntax highlighting via tree-sitter, including highlighting of bracketed {comments} and parenthesized (variations).
• customizable faces
• navigation and selection commands
• computation of FEN at point (using the chess library)
• computation and display of board at point (using chess)
• evaluation of board at point (requires uci-mode)

Interactive Commands

No keys are bound by default. Consider binding keys in an eval-after-load form.

Default mouse bindings are provided:

• mouse-2 — pygn-mode-mouse-display-variation-board

In English, clicking the middle mouse button on a move in Emacs displays a board image computed after that move was made.

In addition, the mouse wheel (buttons 4/5) is bound to pygn-mode-next-move and pygn-mode-previous-move when hovering over the PyGN lighter in the modeline.

Game Navigation Commands

A PGN file may contain multiple concatenated games. Navigation commands depend on the convention of each game starting with an [Event "?"] tagpair. (The value is ignored).

Next-game and previous-game commands accept a positive numeric prefix argument.

• pygn-mode-next-game
• pygn-mode-previous-game
• pygn-mode-ivy-jump-to-game-by-any-header
• pygn-mode-ivy-jump-to-game-by-fen

Move Navigation Commands

Move navigation commands navigate only among the actual played moves of the chess game. If the point is within a bracketed comment or a parenthesized variation, the point will leave the comment or variation in search of a player move. This will happen even if the point is looking at a notional move within the comment or variation. Similarly, the point will advance over intervening comments and variations when advancing moves.

Move navigation commands treat move numbers as whitespace. If the point is on the move number for a move, it is considered to be on that move. Move numbers will be skipped over whenever possible by move navigation.

• pygn-mode-next-move — suggested binding M-f
• pygn-mode-previous-move — suggested binding M-b

Selection Commands

Like game navigation commands, game selection commands depend on the convention of each game starting with an [Event "?"] tagpair.

• pygn-mode-select-game

FEN Commands

• pygn-mode-echo-fen-at-pos — echo FEN, optionally copying to clipboard
• pygn-mode-display-fen-at-pos — display FEN in another buffer
• pygn-mode-display-variation-fen-at-pos — display FEN, respecting variations

Annotation Symbol Commands

• pygn-mode-describe-annotation-at-pos — echo description of annotation symbol, optionally copying to clipboard
• pygn-mode-ivy-insert-annotation — insert an annotation interactively

Game Commands

• pygn-mode-insert-game — insert a new, empty game

Board Commands

• pygn-mode-display-board-at-pos — display board image in another buffer (format automatic)
• pygn-mode-display-gui-board-at-pos — display graphical board image in another buffer
• pygn-mode-display-text-board-at-pos — display text board image in another buffer
• pygn-mode-display-variation-board-at-pos — display board image, respecting variations
• pygn-mode-previous-move-follow-board — advance to next move and display board image
• pygn-mode-next-move-follow-board — move point to previous move and display board image

Line Commands

• pygn-mode-display-line-at-pos — display SAN line in another buffer
• pygn-mode-display-variation-line-at-pos — display SAN line, respecting variations

Engine Commands

• pygn-mode-engine-go-depth — display depth-limited engine evaluation in another buffer
• pygn-mode-engine-go-time — display time-limited engine evaluation in another buffer
• pygn-mode-engine-go-searchmoves — display engine evaluation on the current move in another buffer

Window-management Commands

• pygn-mode-triple-window-layout-bottom — arrange windows for engine evaluation
• pygn-mode-triple-window-layout-right — arrange windows for engine evaluation

Minor Mode

Enabling pygn-mode-follow-minor-mode causes a board rendering to be displayed and updated after any changes to the cursor position.

Prior Art

emacs-chess
https://github.com/jwiegley/emacs-chess
Comparison to emacs-chess

License

• pygn-mode: BSD 2-Clause
• bundled chess library: GPL-3+

Compatibility and Requirements

GNU Emacs 26.1+, compiled with dynamic module support

tree-sitter.el and tree-sitter-langs.el

Python 3.8+

Needed for board images and FENs: chess (bundled version 1.11.1)

Needed for engine evaluations: uci-mode

Needed for jump commands: ivy-mode.el

Uses if present: nav-flash.el

Requirements Diagnostic

The diagnostic command will check dependencies: Python, chess library, and optional Emacs libraries.

Interactively: M-x pygn-mode-run-diagnostic

Programmatically:

(pygn-mode-run-diagnostic) ; truthy iff diagnostic completed successfully.

Upgrading the chess library

To use a non-bundled version of the Python chess library:

$ pip install chess

;; can also use customize
;; can also use set a system path
(setq pygn-mode-pythonpath nil)