Git Product home page Git Product logo

pygn-mode's Introduction

Build Status

Overview

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

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

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)

pygn-mode's People

Contributors

dwcoates avatar qnix avatar qnix-databricks avatar rolandwalker avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar  avatar

pygn-mode's Issues

Commands fail on long PGNs

I noted this in a code comment in #114, but it deserves an issue since it blocks this mode from being fully useful.

Commands that depend on the server (eg pygn-mode-display-board-at-pos) stop working after a certain distance into a long PGN. The docstring for process-send-string says

If STRING is more than 500 characters long, it is sent in several bunches

This is probably the reason for the bug. We may need to use a process sentinel to detect whether the server is in the right state before accepting a response. Or we may need to use a tempfile to hand off request payloads, which would probably entail a regrettable performance penalty.

follow-minor-mode stops working after free motion

From #174 :

After this PR, pygn-mode-follow-minor-mode works correctly, IFF pygn-mode-next-move and pygn-mode-previous-move are used to navigate. But if I move the cursor freely through variations and comments, the "follow" board window eventually stops being updated at all, and the follow mode stops working.

We need to

  • find out if this is an old bug, or whether it was introduced by the tree-sitter port
  • check whether the recent #177 happened to affect it
  • track down the problem and fix

Error in server response

I get this error when i call pygn functions to display a board, any idea why?

pygn-mode--parse-response: Bad response from ‘pygn-mode’ server -- no :version. Attempted restat

Black pawns are painted white

Black pawns, that should be black, are faced white, as shown in the screenshot below. (Also tested by loading Emacs with no init and a new fresh installation of pygn-mode.)
2023-03-20-204825_563x563_scrot

PGN example:

[Event "Testing PyGN"]
[Site "localhost"]
[Date "2023.03.20"]
[Round "?"]
[White "Player1"]
[Black "Player2"]
[Result "*"]

1. e4
*

I saw that pygn-mode-pgn-to-board is already returning the missing fill=#000 information for the "black-pawn" in SVG... Inside that function, we find a call to pygn-mode--server-query and, from that one, a call to pygn-mode--server-send. From inside the last one, when process-send-string is called and writes out the Python server response on *pygn-mode-server* buffer, the fill=#000 is already missing...

Strangely, when the same string that is given as STRING argument to process-send-string is input on the server running on the terminal (with the same command python -u /home/username/.emacs.d/elpa/pygn-mode-20220531.1422/pygn_server.py -), it has some extra information before the SVG and does not lack the fill=#000 information for the "black-pawn"...

Any hints for the difference on server response when it is running form terminal compared to Emacs' one?

Why just fill=#000 for black pawn is missing among that cumbersome SVG information when server on Emacs is in play? (Remember, by running the PyGN server on terminal, it DOES return the information correctly.)

Error: "bad or does not contain working server script (pygn_server.py)"

I'm getting this error [ ] Bad. The pygn-mode-script-directory ('c:/Users/Alejandro/AppData/Roaming/.emacs.d/elpa/pygn-mode-20211021.2325/') is bad or does not contain working server script (pygn_server.py). after running pygn-mode-run-diagnostic. Any idea why?

pygn_server.py is in the directory. I'm using Windows 10. I don't know what the problem is.

the complete diagnostic is as follows:

[x] Good. We can execute the pygn-mode-python-executable at 'python'

[x] Good. The pygn-mode-python-executable at 'python' is a Python 3 interpreter.

[x] Good. The pygn-mode-python-executable at 'python' is better than or equal to Python version 3.7.

[x] Good. The pygn-mode-python-executable at 'python' can import the Python chess library.

[ ] Bad. The pygn-mode-script-directory ('c:/Users/Alejandro/AppData/Roaming/.emacs.d/elpa/pygn-mode-20211021.2325/') is bad or does not contain working server script (pygn_server.py).

PyGN Board not working

  • Python 3.7+
  • Chess lib version 1.6.1
  • pygn-mode-run-diagnostic = good

Output:
pygn-mode--python-chess-guard: The Python interpreter at ‘pygn-mode-python-path’ must have the Python chess library available

Syntax highlighting does not work

The pygn-mode works in my setup but does not provide any syntax highlighting when I edit PGN files. This is not a regression, I have been using pygn-mode for three years, and the syntax highlighting has never worked for me.

Emacs version:

  • GNU Emacs 28.2 (build 1, x86_64-redhat-linux-gnu, GTK+ Version 3.24.38, cairo version 1.17.8)

Package versions (MELPA):

  • pygn-mode-20230606.42
  • tree-sitter-20220212.1632
  • tree-sitter-langs-20230705.525
  • uci-mode-20210626.1956
  • nav-flash-20220726.1117
  • ivy-20230410.1815

The configuration provided by ~/.emacs.d/init.el

;; PyGN mode
(use-package pygn-mode
  :ensure t
  :bind (:map pygn-mode-map
              ("C-c C-n" . pygn-mode-next-game)
              ("C-c C-p" . pygn-mode-previous-game)
              ("M-f" . pygn-mode-next-move-follow-board)
              ("M-b" . pygn-mode-previous-move-follow-board)
              ("C-c SPC". pygn-mode-display-gui-board-at-pos)
              ("C-h $" . pygn-mode-describe-annotation-at-pos))
  :hook (pygn-mode . visual-line-mode)
  :custom
  ;; pygn-mode-pythonpath is not automatically updated after pygn-mode
  ;; package update.  To workaround this issue I set the variable
  ;; here.
  (pygn-mode-pythonpath
   (concat (getenv "HOME")
           "/.emacs.d/elpa/pygn-mode-"
           (mapconcat 'number-to-string
                      (pkg-info-package-version 'pygn-mode) ".")
           "/lib/python/site-packages/")))

Output of the pygn-mode-run-diagnostic command:

[x] Good. We can execute the pygn-mode-python-executable at 'python'

[x] Good. The pygn-mode-python-executable at 'python' is a Python 3 interpreter.

[x] Good. The pygn-mode-python-executable at 'python' is better than or equal to Python version 3.7.

[x] Good. The pygn-mode-python-executable at 'python' can import the Python chess library.

[x] Good. The pygn-mode-script-directory ('/home/gszasz/.emacs.d/elpa/pygn-mode-20230606.42/') is found and the server script is callable.

[x] Good.  The `uci-mode' library is available.

[x] Good.  The `nav-flash' library is available.

[x] Good.  The `ivy' library is available.

------------------------------------

All pygn-mode required diagnostics completed successfully.

Commands may throw exceptions when outside a game

Example

(goto-char (point-max))

M-x pygn-mode-echo-fen-at-pos
; Wrong type argument: integer-or-marker-p, nil

Tree-sitter brought a deeper understanding of the structure of the file, and is naturally more strict. But this does not match the previous behavior. In addition, if an exception is to be thrown, it must be meaningful. This needs testing, and thinking through.

Intuitively, I think some of the defuns could reman strict in their understanding of placement in the buffer, but the commands made more lenient.

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.