10

Just to clarify... For example, in this doc:

A hook is a Lisp variable which holds a list of functions, to be called on some well-defined occasion. (This is called running the hook.) The individual functions in the list are called the hook functions of the hook. For example, the hook kill-emacs-hook runs just before exiting Emacs...

I think it's saying there is a variable (symbol) named kill-emacs-hookthat represents a list of a set of "hook functions" that will run when the kill-emacs-hook is evaluated, thereby performing those functions. Correct? Then

(add-hook 'text-mode-hook 'auto-fill-mode)

is adding auto-fill-mode to that list identified by text-mode-hook in addition to what's already there. Good. Now this

(defcustom text-mode-hook nil
  "Normal hook run when entering Text mode and many related modes."
  :type 'hook
  :options '(turn-on-auto-fill flyspell-mode)
  :group 'wp)

where it seems we are either creating or altering the text-mode-hook. I'm now confused as to the nature of hooks and their relationship with defcustom. My logical choice is that this code is creating a variable text-mode-hook which is of "type" (don't know what is meant by types in elisp) hook. Is this, indeed, supposed to be the initial creation of the hook text-mode-hook? If so, what's up with the "options?" Are those the supposed hook functions, or something else?

147pm
  • 2,907
  • 1
  • 18
  • 39
  • 1
    From your link: «The :options keyword specifies a suggested list of values for the variable. Usually, :options applies to a hook. The list is only a suggestion; it is not exclusive; a person who sets the variable may set it to other values; the list shown following the :options keyword is intended to offer convenient choices to a user.» – The Sidhekin Aug 30 '15 at 17:38

1 Answers1

7

Your understanding of Emacs Lisp notion of hook is absolutely correct. Indeed, “normal” hooks are just lists of functions (every function doesn't take arguments, otherwise it's not usually called “hook” or “normal hook” in Emacs Lisp).

Most of these variables have names ending with -hook. They are normal hooks, run by means of run-hooks. The value of such a hook is a list of functions; the functions are called with no arguments and their values are completely ignored. The recommended way to put a new function on such a hook is to call add-hook.

The variables whose names end in -functions are usually abnormal hooks (some old code may also use the deprecated -hooks suffix); their values are lists of functions, but these functions are called in a special way (they are passed arguments, or their return values are used). The variables whose names end in -function have single functions as their values.

Customization interface is a different thing. All the difference between defvar and defcustom is that the latter allows user to edit the variable via “customize” interface. This interface can facilitate editing of certain types of data, so for example if you're saying that :type of text-mode-hook is hook, then customization interface makes sure that text-mode-hook is always a list of functions. Furthermore, you can specify which options are recommended with :options argument.

So, your understanding is correct and defcustom and its options are just a way to instruct Emacs, so it can better assist user when he/she uses “customize” interface.

Mark Karpov
  • 4,893
  • 1
  • 24
  • 53
  • But this example of a `defcustom` is not great because `text-mode-hook` already exists; it's included already. Right? Now, if I wrote my own mode and then wanted customization, I'd do this. My confusion is this example is really creating `text-mode-hook`, not altering it. Is that a correct understanding? And if this is indeed creating a new `text-mode-hook`, the `:options` is offering those two functions as options to do an `add-hook` to the list, right? – 147pm Aug 30 '15 at 18:46
  • @147pm, this example just shows you how some part of Emacs' existing code defines customizable variable that represents hook. In nutshell `defcustom` just defines new variables. In this particular example `text-mode-hook` is created and its initial value is `nil`. Customization interface is also told that recommended values to have in this list are `turn-on-auto-fill` and `flyspell-mode`. You however can set `text-mode-hook` to anything you like programmatically, it's normal variable. You can use `add-hook` with any other functions too. – Mark Karpov Aug 30 '15 at 19:06
  • @147, in other words, all the keyword arguments are just hints for customization system, they don't make any difference outside of it. Without the hints that code amounts to `(defvar text-mode-hook nil)`. – Mark Karpov Aug 30 '15 at 19:12
  • But is this `defcustom` how the hook is initially being created? That what it looks like. In other words this example is taken from deep in the bowels of Emacs code somewhere. – 147pm Aug 30 '15 at 19:43
  • @147pm, yes, correct. – Mark Karpov Aug 30 '15 at 20:10
  • FWIW, hooks are rarely user options. And even `text-mode-hook`, a commonly used hook, was not a user option until Emacs 22. Why this was done is not obvious (typically it is not done). Presumably this was only in order to provide the proposed choices (`:options` values) that are there. (A non-option variable can provide no such choices; it can provide only a default value.) – Drew Aug 30 '15 at 20:17