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

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

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)

dwcoates/pygn-mode