I bet you use hl-line-mode... Do you know how it works? Overlays, post-command-hook and only 5 functions!!!

What is hl-line-mode?

How does it work?

When you run Emacs, it enters the “editor command loop” almost
immediately.  This loop reads key sequences, executes their definitions,
and displays the results.

(add-hook 'post-command-hook #'hl-line-highlight nil t)

(defun hl-line-highlight ()
  (if hl-line-mode
      (progn
        (unless (overlayp hl-line-overlay)
          (setq hl-line-overlay (hl-line-make-overlay)))
        ;; ...
        (hl-line-move hl-line-overlay)
        ;; ...
        )
    (hl-line-unhighlight)))

(defun hl-line-make-overlay ()
  (let ((ol (make-overlay (point) (point))))
    (overlay-put ol 'priority hl-line-overlay-priority)
    (overlay-put ol 'face hl-line-face)
    ol))

(defun hl-line-move-NO-RANGE-FUNCTION (overlay)
  (let ((beg (line-beginning-position))
        (end (line-beginning-position 2)))
    (move-overlay overlay beg end)))

global-hl-line-mode

In this section everything happens in the buffer *test hooks*.

Let's switch to the new buffer *test hooks* in emacs-lisp-mode by evaluating the following s-exp in the minibuffer (M-x eval-expression):

(progn
  (with-current-buffer (get-buffer-create "*test hooks*")
    (emacs-lisp-mode))
  (switch-to-buffer "*test hooks*"))

We've already seen that by adding functions to the hooks (lists) pre-command-hook and post-command-hook we can trigger actions before or after any command call.

The first things we can do is to inspect the variable post-command-hook by running:

M-x describe-variable RET post-command-hook RET

This will pops up an help buffer that looks like this (the value depends on the packages you are using):

post-command-hook is a variable defined in ‘src/keyboard.c’.

Its value is
(jit-lock--antiblink-post-command yas--post-command-handler
eldoc-schedule-timer company-post-command t)
Local in buffer *test hooks*; global value is
(global-font-lock-mode-check-buffers global-eldoc-mode-check-buffers
smartparens-global-mode-check-buffers
show-smartparens-global-mode-check-buffers
yas-global-mode-check-buffers magit-auto-revert-mode-check-buffers
global-hl-line-highlight insight-check-cursor-color
sp--post-command-hook-handler winner-save-old-configurations)

  This variable may be risky if used as a file-local variable.
  Probably introduced at or before Emacs version 19.20.

Normal hook run after each command is executed.
If an unhandled error happens in running this hook,
the function in which the error occurred is unconditionally removed, since
otherwise the error might happen repeatedly and make Emacs nonfunctional.

It is a bad idea to use this hook for expensive processing.  If
unavoidable, wrap your code in ‘(while-no-input (redisplay) CODE)’ to
avoid making Emacs unresponsive while the user types.

See also ‘pre-command-hook’.

In this help buffer, we see that the local value in the buffer *test hooks* is the list:

(jit-lock--antiblink-post-command yas--post-command-handler eldoc-schedule-timer company-post-command t)

We also see its global value and the last part of the help buffer is the docstring of this variable where we can read:

If an unhandled error happens in running this hook,
the function in which the error occurred is unconditionally removed, since
otherwise the error might happen repeatedly and make Emacs nonfunctional.

This tells us that it is safe to play with post-command-hook because if we add a function to it that raises an error the function will be unconditionally removed.

So let's add to post-command-hook a symbol that has no function definition (ie. raises the error void-function when called as a function). By evaluating the following s-exp (eval-last-sexp bound to C-x C-e):

(add-hook 'post-command-hook 'test-void-function)

we see in the echo area:

Error in post-command-hook (test-void-function): (void-function test-void-function)

And if we inspect the variable post-command-hook (as we did previously), we see that test-void-function symbol isn't in the hook.

What happened?

1. we called eval-last-sexp,

2. then the "editor command loop" ran the hook pre-command-hook,

3. then the expression (add-hook 'post-command-hook 'test-void-function) has been evaluated, which added test-void-function symbol to post-command-hook,

4. then the "editor command loop" ran the hook post-command-hook, and when it try to call the function test-void-function, it raised the error void-function and remove test-void-function from the hook.

Now that we are confident that playing with the hook post-command-hook won't break our running Emacs, let's build the main example of this section.

We write 2 functions test-hook-pre and test-hook-post that print out respectively the name of the command that is about to run and the name of the command that just ran.

To do that we use the emacs variable this-command (that holds the command now being executed) and adds test-hook-pre to pre-command-hook and test-hook-post to post-command-hook.

Note that the info nodes related to this examples are:

• elisp#Command Overview

• elisp#Command Loop Info

Then we call some commands.

And finally we observe what has been printed out in the buffer *Messages*.

In the buffer *test hooks*, we remove everything and add the following expressions:

(defun test-hook-pre ()
  (message "  BEFORE   |   %s" this-command))

(defun test-hook-post ()
  (message "   AFTER   |   %s" this-command))

(add-hook 'pre-command-hook 'test-hook-pre)
(add-hook 'post-command-hook 'test-hook-post)

(message ":::::::: print me ::::::::")

Then, with the point after the last s-exp (last parenthesis), we do in order (without doing anything else, this is important for the messages we want to see printed):

1. M-x eval-buffer (this evaluate all this expressions),

2. C-a (move to the beginning),

3. C-e (move to the end of line),

4. C-x C-e (eval the last expression).

Then, we should see in the buffer (almost at the end) *Messages* the following:

:::::::: print me ::::::::
   AFTER   |   eval-buffer
  BEFORE   |   move-beginning-of-line
   AFTER   |   move-beginning-of-line
  BEFORE   |   move-end-of-line
   AFTER   |   move-end-of-line
  BEFORE   |   eval-last-sexp
:::::::: print me ::::::::
":::::::: print me ::::::::"
   AFTER   |   eval-last-sexp

This gives us an overview of the behavior of the "editor command loop".

Are you annoyed by the noise you have in your echo area?

Me too.

Let's remove the functions test-hook-pre and test-hook-post respectively from the hooks pre-command-hook and post-command-hook by evaluating the following s-exps. This should "clean up" our echo area.

(remove-hook 'pre-command-hook 'test-hook-pre)
(remove-hook 'post-command-hook 'test-hook-post)

We are done with the hooks pre-command-hook and post-command-hook. Let's play with overlays.

In the post Have you ever wondered how org-mode toggles the visibility of headings?, we already played with overlays specifically the invisible property of overlay. We also know that overlays take priority over text properties.

Below we will see:

1. how to move overlays (move-overlay) and,

2. which overlay wins when they overlap (priority property).

Note that all the evaluations of the s-expressions are done in the minibuffer with M-x eval-expression and the point in the buffer we operate on, that we call *overlays*.

Let's switch to the new buffer *overlays* in fundamental-mode by evaluating the following s-exp:

(switch-to-buffer (get-buffer-create "*overlays*"))

Let's insert the characters FOO---BAR---BAZ such that the buffer *overlays* look likes this:

FOO---BAR---BAZ

We make two overlays:

1. ov-x on top of FOO with a background green (#00ff00),

2. ov-y on top of BAZ with a background red (#ff0000).

To do so, we evaluate the following form:

(progn
  (setq ov-x (make-overlay 1 4))
  (overlay-put ov-x 'face '(:background "#00ff00"))
  (setq ov-y (make-overlay 13 16))
  (overlay-put ov-y 'face '(:background "#ff0000")))

Now we have FOO with a background green and BAZ with a background red.

Let's move the overlay ov-x (the green) on top of the characters BAR the same way hl-line-mode does. To do so we use the function move-overlay as follow:

(move-overlay ov-x 7 10)

When more than one overlay overlaps, Emacs decides for each property which overlay "wins" (see elisp#Overlay Properties) over the others by looking up at the overlay property priority which should be a positive integer or nil.

Let's see this in our example.

First, we set the overlay ov-x to have a priority equal to 10 and the overlay ov-y to have a priority equal to 20 by evaluating the following form:

(progn
  (overlay-put ov-x 'priority 10)
  (overlay-put ov-y 'priority 20))

Now we move the overlay ov-y to be on top of the characters BAR (and so overlap with the overlay ov-x) by evaluating this s-exp:

(move-overlay ov-y 7 10)

The buffer *overlays* shows the characters BAR with a background red that corresponds to the overlay ov-y which have a priority 20 superior to the priority 10 of the overlay ov-x.

Now let's make ov-x win by raising its priority to 30:

(overlay-put ov-x 'priority 30)

ISN'T IT SUPER COOL!!!

Something interesting we can do now is to M-x describe-char, with the point between A and R in the word BAR, which pops up the following help buffer:

             position: 9 of 15 (53%), column: 8
            character: R (displayed as R) (codepoint 82, #o122, #x52)
              charset: ascii (ASCII (ISO646 IRV))
code point in charset: 0x52
               script: latin
               syntax: w  which means: word
             category: .:Base, L:Left-to-right (strong), a:ASCII, l:Latin, r:Roman
             to input: type "C-x 8 RET 52" or "C-x 8 RET LATIN CAPITAL LETTER R"
          buffer code: #x52
            file code: #x52 (encoded by coding system utf-8-unix)
              display: by this font (glyph code)
    ftcrhb:-PfEd-DejaVu Sans Mono-normal-normal-normal-*-15-*-*-*-m-0-iso10646-1 (#x35)

Character code properties: customize what to show
  name: LATIN CAPITAL LETTER R
  general-category: Lu (Letter, Uppercase)
  decomposition: (82) ('R')

There are 2 overlays here:
 From 7 to 10
  face                 (:background "#00ff00")
  priority             30
 From 7 to 10
  face                 (:background "#ff0000")
  priority             20

Note that it might differs in your running emacs (different fonts, maybe information about overlays if you are using hl-line-mode, ...).

There are 2 overlays!!!

To finish this post, we remove the overlays like this:

(remove-overlays)

WE ARE DONE!!!