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

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

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

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)

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.

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

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

• pygn-mode-select-game

• 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

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

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

• 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

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

• 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

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

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

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

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

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

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.

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)