Difference between symbol and variable name in emacs lisp

Question

I'm wondering what the difference is between

(add-to-list 'flymake-allowed-file-name-masks
         '("\\.py\\'" flymake-pylint-init))

and

(add-to-list flymake-allowed-file-name-masks
         '("\\.py\\'" flymake-pylint-init))

What is the clear meaning of the apostrophe here?

Answer 1

The apostrophe is a quote, which tells the interpreter to not parse the following expression (the symbol name). Thus, 'add-to-list gets the symbol which contains the list value that is intended to be evaluated.

To learn more about symbols, read the Symbol documentation (specifically, Symbol Components symbols have names, values, function definitions and property lists).

Without reading the documentation, this is how I explain it: Emacs lisp's evaluation strategy is to pass by value (as opposed to by name or reference or something else). If the quote were not there, flymake-allowed-file-name-masks would be evaluated to a value, and add-to-list would have to work directly on the list. This would work, with the following exceptions. If the list were empty, there would be no way to change what the original variable pointed to. For the same reason, you would not be able to add elements to the front of the list.

To make those two cases work, you actually need the variable name so that you can modify what it points to.

It'd probably be useful to read the following: Introduction to Evaluation, Modifying List Variables, and Modifying Existing List Structures.

If you're familiar with box diagrams, perhaps this will help.

Imagine that some-var points to a list:

somevar
  |
  |
  v
 --- ---      --- ---      --- ---        
|   |   |--> |   |   |--> |   |   |--> nil
 --- ---      --- ---      --- ---        
  |            |            |             
  |            |            |             
   --> rose     --> violet   --> buttercup

And you wanted to put something on the front of that list.

If all you have to work with is the value of the pointer in somevar, then the best you can do is put a new element on the front of the list, but you cannot actually modify what somevar points to (because you don't have somevar, you have it's value). Like so:

             somevar
               |
               |
               v
 --- ---      --- ---      --- ---      --- ---        
|   |   |--> |   |   |--> |   |   |--> |   |   |--> nil
 --- ---      --- ---      --- ---      --- ---        
  |            |            |            |             
  |            |            |            |             
   --> tulip     --> rose     --> violet   --> buttercup

So, to write your own 'add-to-list function, you need the variable name.

Of course, if you wrote 'add-to-list as a macro, you wouldn't have that restriction.