What's :eval (colon eval) in defcustom?

Question

I am reading this Elisp library and can't figure out what :eval is.

Answer 1

The doc string tells you this:

"Mode line lighter for Github Notifier."

You couldn't otherwise know for sure what the code is about, or what :eval means in that context. That is, you couldn't know without checking where, and how, that user option (variable) is actually used in the surrounding code.

Normally, you could use i in the Elisp manual, and type :eval, to see where that's indexed in the manual. But there are no index terms that start with : (because of the tools that build the manual), and trying i eval doesn't really help.

However, you can search (C-s, repeating) the manual for :eval, and you will come to nodes in the manual having to do with the mode-line that tell you about this.

In particular, you'll come to node Mode Line Data, where you find this:

(:eval FORM) A list whose first element is the symbol :eval says to evaluate FORM, and use the result as a string to display. Make sure this evaluation cannot load any files, as doing so could cause infinite recursion.

Keep searching for :eval and you'll come to these nodes, which tell you more about the same use of :eval, that is, its use in a mode-line construct:

• Properties in Mode

• Mode Line Top

Another way to find this information would be to use i mode line in the manual. That takes you to node Mode Line Format, which has the other nodes mentioned as subnodes (in the menu you see there).

And after you try i mode line, and visit that node, a message in the echo area tells you that you're visiting the first of four matches for your input mode line, and that you can use , to visit the other matches, in turn. Doing that takes you to the other nodes mentioned above.

All of this is without actually studying the code that uses the variable in question. Of course, searching that Elisp file for the variable name will show you just how it's used, and there you'll see that it's used as a mode-line construct. That will show you the particular use, in context.

In sum:

• Emacs doc strings are a great entry point.

• i in the manuals is your friend.

• But index entries can't start with :, and index entries for just eval unfortunately don't really cover this.

  (Consider filing a bug report: M-x report-emacs-bug, to add an index entry for eval that has to do with the :eval mode-line construct.)

• You can search throughout a manual using C-s.

---

(If you want to get to the web version of the manuals, you can use G (command Info-goto-node-web) when in the manual in Emacs, if you use library Info+. That's how I quickly got the URLS for the above links.)

Answer 2

This has nothing to do with defcustom: if you look at the doc string of defcustom it says:

(defcustom SYMBOL STANDARD DOC &rest ARGS)

In this case, the SYMBOL is github-notifier-mode-line, the DOC is "Mode line lighter for Github Notifier.", the ARGS are :type 'sexp :risky t :group 'github-notifier). The whole quoted expression is the STANDARD value of this variable.

In fact, if you evaluate the defcustom in an emacs session, you can then ask about github-notifier-mode-line with C-h v github-notifier-mode-line: it will tell you its value and its value is exactly that quoted expression.

That's as far as defcustom goes. You have to dig a bit deeper to find out what exactly that value is doing. The hint is that the name of the variable indicates that it has something to do with the mode line. If you look further in the file you linked, that suspicion is confirmed: e.g. the first line of the file says:

Displays your GitHub notifications unread count in mode-line

and the keywords line says:

Keywords: github, mode-line

The clincher however is one of the last lines in the file that says:

(add-to-list 'global-mode-string 'github-notifier-mode-line t)

Now if you ask emacs about global-mode-string with C-h v global-mode-string, it tells you:

String (or mode line construct) included (normally) in ‘mode-line-format’.

In other words, you got to look at the mode-line-format documentation to see what that :eval is doing. C-h v mode-line-format then tells you:

A list of the form ‘(:eval FORM)’ is processed by evaluating FORM and using the result as a mode line construct. Be careful--FORM should not load any files, because that can cause an infinite recursion.

IOW, whenever the mode line is updated, that code is evaluated and its value is plugged into the mode line as part of global-mode-string.

For more details on the mode line, consult the Emacs Lisp manual with C-h i g (elisp) mode line format. In particular, the subsection "Mode line variables" explains how global-mode-string is used.

Answer 3

Run C-h f defcustom RET to show the help information for defcustom. This will tell you what arguments it expects. In particular, is says that this is the expected signature:

(defcustom SYMBOL STANDARD DOC &rest ARGS)

So this :eval thing is in the position of the argument called STANDARD. A few lines down it says:

SYMBOL is the variable name; it should not be quoted.
STANDARD is an expression specifying the variable's standard
value.

So this is just the value that this variable will have by default, unless the user customizes it. But it is a pretty funny–looking value! The hint is in the name of the variable: github-notifier-mode-line. This is a value that will be put into a mode line definition at some point, so we can look in the Elisp manual for information about that. Chapter 23.4.2 The Data Structure of the Mode Line has all the information about what can go into a mode line definition, including what :eval means.

Two other people just answered the question, so I’ll stop there and hope that between the three of us you get the information you need.