;;; poly-lock.el --- Font lock sub-system for polymode -*- lexical-binding: t -*-
;;
;; Copyright (C) 2013-2022 Free Software Foundation, Inc.
;; Author: Vitalie Spinu
;; URL: https://github.com/polymode/polymode
;;
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;;
;; This file is *NOT* part of GNU Emacs.
;;
;; This program is free software; you can redistribute it and/or
;; modify it under the terms of the GNU General Public License as
;; published by the Free Software Foundation; either version 3, or
;; (at your option) any later version.
;;
;; This program is distributed in the hope that it will be useful,
;; but WITHOUT ANY WARRANTY; without even the implied warranty of
;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
;; General Public License for more details.
;;
;; You should have received a copy of the GNU General Public License
;; along with GNU Emacs. If not, see <https://www.gnu.org/licenses/>.
;;
;;
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;;
;;; Commentary:
;;
;;; Code:
;; FONT-LOCK COMPONENTS:
;;
;; All * functions are lazy in poly-lock and jit-lock because they just mark
;; 'fontified nil.
;;
;; fontification-functions -> jit-lock-function / poly-lock-function
;; font-lock-ensure -> font-lock-ensure-function -> jit-lock-fontify-now/poly-lock-fontify-now
;; *font-lock-flush -> font-lock-flush-function -> jit-lock-refontify / poly-lock-flush
;; *font-lock-fontify-buffer -> font-lock-fontify-buffer-function -> jit-lock-refontify / poly-lock-flush
;; font-lock-fontify-region -> font-lock-fontify-region-function -> font-lock-default-fontify-region
;; font-lock-unfontify-region -> font-lock-unfontify-region-function -> font-lock-default-unfontify-region
;; font-lock-unfontify-buffer -> font-lock-unfontify-buffer-function -> font-lock-default-unfontify-buffer
;;
;; Jit-lock components:
;; fontification-functions (called by display engine)
;; --> jit-lock-function
;; --> jit-lock-fontify-now (or deferred through timer/text-properties)
;; --> jit-lock--run-functions
;; --> jit-lock-functions (font-lock-fontify-region bug-reference-fontify etc.)
;;
;;
;; Poly-lock components:
;; fontification-functions
;; --> poly-lock-function
;; --> poly-lock-fontify-now
;; --> jit-lock-fontify-now
;; ...
;;
;; `font-lock-mode' call graph:
;; -> font-lock-function <---- replaced by `poly-lock-mode'
;; -> font-lock-default-function
;; -> font-lock-mode-internal
;; -> font-lock-turn-on-thing-lock
;; -> font-lock-turn-on-thing-lock
;; -> (setq font-lock-flush-function jit-lock-refontify)
;; -> (setq font-lock-ensure-function jit-lock-fontify-now)
;; -> (setq font-lock-fontify-buffer-function jit-lock-refontify)
;; -> (jit-lock-register #'font-lock-fontify-region)
;; -> (add-hook 'jit-lock-functions #'font-lock-fontify-region nil t)
;; -> jit-lock-mode
;; FIXME: Can this hack be avoided if poly-lock is registered in
;; `font-lock-support-mode'?
;; see the comment in pm--mode-setup for these
;; (defun poly-lock--jit-lock-extend-region-span (span old-len)
;; "Call `jit-lock-after-change-extend-region-functions' protected to SPAN.
;; Extend `jit-lock-start' and `jit-lock-end' by side effect.
;; OLD-LEN is passed to the extension function."
;; ;; FIXME: for multi-span regions this function seems to reset
;; ;; jit-lock-start/end to spans limits
;; (let ((beg jit-lock-start)
;; (end jit-lock-end))
;; (let ((sbeg (nth 1 span))
;; (send (nth 2 span)))
;; (when (or (> beg sbeg) (< end send))
;; (pm-with-narrowed-to-span span
;; (setq jit-lock-start (max beg sbeg)
;; jit-lock-end (min end send))
;; (condition-case err
;; (progn
;; ;; set jit-lock-start and jit-lock-end by side effect
;; (run-hook-with-args 'jit-lock-after-change-extend-region-functions
;; jit-lock-start jit-lock-end old-len))
;; (error (message "(after-change-extend-region-functions %s %s %s) -> %s"
;; jit-lock-start jit-lock-end old-len
;; (error-message-string err))))
;; ;; FIXME: this is not in the right buffer, we need to do it in the
;; ;; original buffer.
;; (setq jit-lock-start (min beg (max jit-lock-start sbeg))
;; jit-lock-end (max end (min jit-lock-end send))))
;; (cons jit-lock-start jit-lock-end)))))
;;; poly-lock.el ends here