When is the first element in the argument list regarded as a function symbol and when not?

Question

I'm learning elisp, and I just learned that the first element of a list is interpreted as a function symbol. I then learned how to define a function with defun. Here's the example from An Introduction to Programming in Emacs Lisp

(defun multiply-by-seven (number)
  "Multiply NUMBER by seven."
  (* 7 number))

https://www.gnu.org/software/emacs/manual/html_node/eintr/defun.html

Now it looks the first element of the argument list [(number) in the example above] is not regarded as a function symbol.

Given a list in an elisp code, how do I know if its first element is a function or not?

---

Addendum after seeing answer and comments by whitetrillium

I got the idea that there's distinction between symbol (i.e., variable) and value.

My question is the following: when I read an elisp code, how can I judge if the code fragment (e.g., number, 7, multiply-by-seven, defun in the example above) refers to the symbol itself or the value to be obtained by evaluating the symbol.

Somewhat relevant is the distinction between set and setq functions. Please see these examples:

(set 'flowers '(rose violet daisy buttercup))
(setq carnivores '(lion tiger leopard))

https://www.gnu.org/software/emacs/manual/html_node/eintr/Using-set.html https://www.gnu.org/software/emacs/manual/html_node/eintr/Using-setq.html

In set function, the first argument is not treated as a symbol, but it is evaluated to its value. To avoid the evaluation, it needs to be quoted. In contrast, in setq function, the first argument is treated as a symbol, and it is not evaluated.

I can guess that it doesn't make sense for (number) to be evaluated in the particular example of defun because it's a placeholder. I also know that the first argument to setq is treated as a symbol because I learned it from the tutorial. However, if I see the following code,

(hoge (foo bar))

how do I know whether (foo bar) is evaluated by passing argument bar to function foo or it is treated as a list of two elements, (foo bar)? I guess I might need to look into the source code which defines hoge. Then, how can I write function hoge in these two ways, and where does the difference appear?

Answer 1

the first element of a list is interpreted as a function symbol

That's the most common case, but it isn't an absolute rule.

First, you need to know that every symbol can have both a function meaning ((symbol-function 'foo)) and a value meaning ((symbol-value 'foo)).

The general rule is that a top-level expression in a Lisp program is evaluated according to the following rules:

• If the expression is a list whose first element is a symbol, then Emacs looks up the symbol's meaning as a function. Then:
  • If that meaning is a function, then:
    1. All the other elements of the list are evaluated, by applying this procedure recursively.
    2. The function is called, with the list of evaluated elements passed as its argument list.
  • If that meaning is a macro or a special form (like a macro, but built into Emacs), then:
    1. The macro is called, with the rest of the list passed as its argument list, unevaluated.
    2. The result of the macro is evaluated, by applying this procedure recursively.
• The empty list () evaluates to the symbol nil, which is how Emacs represents an empty list.
• If the expression is a symbol, it evaluates to the meaning of this symbol as a value.
• Otherwise the expression evaluates as itself.

I've omitted a few uncommon cases. See the Emacs Lisp manual for details.

Here are a few examples concerning built-in functions and macros.

• set, symbol-value and symbol-function are ordinary functions. To pass a symbol to them which is typed directly into the source code, you need to quote it. For example, (set a 3) requires the value of a to be a symbol, and sets that symbol to 3.
• setq is a special form. It wants its first argument to be a symbol, and does not evaluate it. It evaluates its second argument. So for example (setq a (+ 2 1)) calls the implementation of setq with two arguments, the symbol a and the list (+ 2 1). This implementation evaluates (+ 2 1) and assigns the resulting value to the symbol a.
• if is a special form. It first evaluates its first argument. If the resulting value is nil, it evaluates its third argument and the following ones, ignoring the second argument. If the resulting value is non-nil, it evaluates its second argument and ignores the following ones.
• defun is a special form. It wants its first argument to be a symbol and its second argument to be a list of symbols (possibly empty). It sets the symbol's function meaning to be a function whose argument list is the second argument passed to defun and whose body is the list of arguments starting with the third. It so happens that evaluating (defun …) does not evaluate any of the elements inside the parentheses.
• quote is a special form. It wants one argument, and just returns that argument without evaluating it. 'FOO is an abbreviation for (quote FOO).

if I see the following code,

(hoge (foo bar))

how do I know [how (foo bar) is evaluated]

You have to look up the function meaning of the symbol hoge. If you find that it's a function (including built-in functions), then (foo bar) is evaluated as a call to foo with the one argument bar. If you find that hoge is a macro or a special form, there is no general rule: you have to consult the documentation or the source code of hoge.

Answer 2

If I see the following code,

    (hoge (foo bar))

how do I know whether (foo bar) is evaluated by passing argument bar to function foo or it is treated as a list of two elements, (foo bar)? I guess I might need to look into the source code which defines hoge. Then, how can I write function hoge in these two ways, and where does the difference appear?

You are thinking along the right lines ...

 (hoge (foo bar))

When the runtime is evaluating hoge, it will see how hoge is defined. Is it a defmacro, defun, defvar, defface` etc.

When the runtime evaluates foo it will look up how foo is defined, Is it a defmacro. defun, defvar, defface etc.

A symbol can have two values ... and which value is picked depends on where the symbol occurs.

• if it occurs as the first element of a list, the symbol-s function slot is consulted for its value.

• if the symbol occurs as NON-first element of a list, its value slot is a consulted for its value.

Consider this example,

(set 'a 10)
(fset 'a '+)

(+ a 10)

(a 10 20)

In (+ a 10), a occurs as a second symbol in the list, + is a defun, so the value slot of a gives its value. And the value of a is 10.

In the expression (a 10 20), a occurs as the first symbol, so its function slot is considered. So, the value of in this case is +.

So, set and fset are the two fundamental setters---one sets the value of value slot and the other sets the value of function slot.

setq is a special form, set is a function.

Try doingC-h f set, C-h f setq and C-h f fset.

If you did

(set a 10)

instead of

(set 'a 10)

the runtime will try to find the value of a by evaluating a, and it will fail. This is like finding "John" in a house that doesn't exist.

In real life ...

• You build a house, and define it as church, a restaurant, a house etc.

• Once you know how the house is defined, you can put the right person there.

• If it is a hotel, put a chef. If it is a church, put a priest etc.

• It is Ok to put a priest in a hotel. But the priest will not be a priest but a client (who is having food).

---

defun is a defmacro. The arguments of defmacro are NOT eval-lled. The def "functions" are SPECIAL forms.

So, the first arg (= multiply-by-seven) and second arg (=number) are NOT eval-led in the caller; note that defun is a caller of defmacro.

+ is a defun, and when you are calling a symbol which is a defun it is arguments are always EVAL-led.. So, if a symbol (or an expression) occurs in a eval-led contex,t and you want the expression to be NOT eval-led you signal it by putting a quote around it.

defmacro is a special-form. And its arguments are NOT evalled.

That is why you don't do

(defun 'multiply-by-seven (number)
  "Multiply NUMBER by seven."
  (* 7 number))

(Note the single quote before multiply-by-seven)

We know that in a defmacro all arguments are NOT evalled. So, the runtime is NOT going to go ahead and fetch the value of multiply-by-seven. So, it is OK to NOT quote the symbol.

As a general rule, any symbol that starts with def is a special-form, and its args are NOT evalled.

When you are def-ining, you are in the proces of building a house, it goes without saying---and it is expected that---that there are NO people there.

You put a quote, when you expect that an expression will be evalled, and you know for sure that the expression has NO value at all.

For example, if you do

(a b c)

and you have NOT define-d a, then it will fail. Because a doesn't have a function definition in the function slot. So, you do

'(a b c)

You say, please don't go ahead an fetch the value of a there is nothing in its function slot; don't go ahead fetch the value of b from it's value slot, because there is nothing there. So, eval nothing.

---

But if you have

(defun a () )

you can do

(a)

because the a will have a value in its function slot. Why? Because *defun (and fset) does exactly that---put a value in a function slot*

Similarly defvar and set put a value in the value slot of a name.

My description may not be clear. But my examples, will drive home the point.

So, you need to ask "Is this position eval-lled?, and the answer is is "Yes" (in some contexts) and "No" (in some other contexts).

Answer 3

Lisp code and some Lisp data structures (lists, symbols, strings, vectors, etc.) can be the same thing. Lisp code is a Lisp data structure that's ready to be evaluated, that is, "run".

Both code and some data structures are Lisp S-expressions, also called sexps.

In particular, IF Lisp evaluates a nonempty list THEN it interprets the first list element (the car) as a function and any other elements, in order, as arguments to be passed to the function. The entire list is considered a function application.

Typically, the first element of a function application is a function symbol, but it could also be a lambda expression.

Evaluating some lists doesn't treat them in this standard function-application way. Such lists are Lisp macros or special forms. Their evaluation follows a different approach, which depends on the definition of the specific macro or special form. An example of a macro is defun. An example of a special form is an if expression.

Macros and special forms need not evaluate any of their arguments (the list elements other than the first). Typically they evaluate some or all of their arguments, but they don't necessarily evaluate them all together, or from left to right.

defun, for example, doesn't evaluate its arguments, and if evaluates its first argument, and then based on the resulting value, either its second argument or the third and subsequent arguments (in order).

So when you see this:

(defun multiply-by-seven (number)
  "Multiply NUMBER by seven."
  (* 7 number))

None of the elements of that list, whose car is the symbol defun, is evaluated when the list is evaluated as a macro expression. Instead, the definition of the macro is used to macroexpand the list to a definition of a function named multiply-by-seven, and then that definition is evaluated to define that function.

So in particular, the list (number), as the third element of that defun macro expression, is not evaluated. Nor is the next element (the string "Multiply..."). Nor is the next element, the list (* 7 number).

If the list (number) were evaluated then evaluation would, as you say, try to apply the function number to an empty list of arguments. If there is no defined function named number (which is the case by default) then such an evaluation attempt would raise an error, saying that there's no function number.

Evaluating a Lisp macro is always a two-step process: (1) macroexpand the list, to get a new sexp, then (2) evaluate that resulting sexp.

---

You shouldn't include multiple questions in the same post. But the general answer to your follow-up question of how to tell whether a sexp will be evaluated (used as code) or not (used as data) is this: a sexp gets evaluated.

That general rule doesn't preclude a subexpression from not being evaluated. I gave the example of sexp (defun...) being evaluated but its subexpressions not being evaluated. And evaluating the sexp (if t aaa bbb) does not evaluate one of the subexpressions aaa or bbb -- if is a control structure, a conditional.

Consider also the sexp 'foo. That's syntactic sugar for the sexp (quote foo). A quote sexp is a special form. Its argument (foo, here) isn't evaluated, but it is returned as the value -- the result of evaluation -- of (quote foo).

Except when the first element of a function application, a symbol is generally evaluated as a variable, the evaluation returning the variable value. (You can obtain the variable value of a symbol using function symbol-value.)

When a symbol is the car of a function application its evaluation returns its function value (its definition, but not necessarily in source-code form). You can obtain the function value of a symbol using function symbol-function.

Finally, some sexps are self-evaluating. t and nil (which is the same as ()) evaluate to themselves, as do numbers, strings, and vectors.

Answer 4

Specifically responding to

if I see the following code,

(hoge (foo bar))

how do I know whether (foo bar) is evaluated by passing argument bar to function foo or it is treated as a list of two elements, (foo bar)?

which doesn't seem to have a good answer yet.

As you guessed, the answer to this question is that it depends on the definition of hoge. There are four different things that hoge could be:

1. An ordinary function, defined by defun or one of its siblings (defalias, defsubst, etc). In this case (foo bar) will be evaluated; it's not quite right to say "by passing argument bar to function foo", the exact treatment of bar will depend on which of these four different possibilities foo is (and so on, recursing down the tree).

2. A macro, defined by defmacro (as far as I know, this one doesn't have any siblings, although if you look at the definition of defmacro itself in byte-run.el you'll see that there's at least one other way to define a macro from Lisp, and there may also be "built-in macros" defined by the C part of Emacs). In this case (foo bar) will not be evaluated; hoge will be called on the literal list (foo bar), as if you had written (hoge '(foo bar)). Furthermore, whatever hoge returns will be evaluated again.

3. A special form. These have special rules for how they handle their arguments, and every one is different. They're all defined by the C part of Emacs. The Elisp manual includes a comprehensive list. You have to memorize these, but the list is short enough that you don't have to worry about it; you will naturally memorize the behavior of the special forms as part of becoming fluent in Lisp. (I say "Lisp", not "Emacs Lisp", because most of the special forms are common to all dialects of Lisp.)

   Note that macros often expand into uses of special forms, meaning that they can also appear to be evaluating some but not all of their arguments. For instance, letrec expands into a let form.

4. Void, which is the manual's jargon for "this symbol isn't defined as any sort of function". In this case an error will be thrown before any of the arguments are processed at all. That shouldn't ever matter but I'm mentioning it just in case it does for some reason.

Answer 5

I appreciate that you are making an effort at understanding the material in your hand.

---

Let us take a real world example ...

Every person has a name.

When you mention the name "John"--this name is so common--I ask you "Which John", and you say "John, son of so and so".

In a sense, when something is so common, you have to use some form of dis-ambiguation.

In the previous example, the parent name is a good way of dis-ambiguating "John".

---

Now in lisp everything is a symbol. A function is a symbol, a variable is a symbol etc.

When everything is a symbol, you need to ask what type of symbol is that. And for that you need to look at his parent.

Now it looks the first element of the argument list [(number) in the example above] is not regarded as a function symbol.

In your case, parent of (number) is defun.

Now ask Emacs what defun is; and you do that with C-h f defun.

If you do C-h f defun, you will see the following ... and (number) is interpreted as a ARGLIST. And in a ARGLIST first symbol is not a function.

To confirm that number is not a function, do C-h f number and it won't work.

**defun is a Lisp macro in ‘byte-run.el’.**

(defun NAME ARGLIST [DOCSTRING] [DECL] [INTERACTIVE] BODY...)

Define NAME as a function.
The definition is (lambda ARGLIST [DOCSTRING] [INTERACTIVE] BODY...).
DECL is a declaration, optional, of the form (declare DECLS...) where
DECLS is a list of elements of the form (PROP . VALUES).  These are
interpreted according to ‘defun-declarations-alist’.
INTERACTIVE is an optional ‘interactive’ specification.
The return value is undefined.

  Probably introduced at or before Emacs version 17.

---

There are two types of symbols

• symbols which have a value
• symbols that don't have a value (like a "John" who is dead, or the argument number in your example which doesn't have any value; number takes its value from the caller; it is meaningless to ask what is the value of number in your example)

A symbol can have two types of values (a function, and a value)

• a value, like number 10, a string like "John"
• a function, like +, - etc.

In any programming language, a symbol is interpreted according as it occurs in the RHS (Right Hand Side) or LHS (Left Hand Side) of an equation.

When a symbol occurs on a LHS, it denotes a variable, a "box" in which a "value" is stored.

When a symbol occurs on RHS, it denotes the value contained in it.

So, in

(defun multiply-by-seven (number)
  "Multiply NUMBER by seven."
  (* 7 number))

the symbol number is LHS

and if you call the above function with

(setq n 7)
(multiply-by-seven n)

In setq, n is LHS, and 7 is RHS.

In (multiply-by-seven n), the variable number is LHS, and the variable n is RHS.

It is also confusing, but the key to thing understand is that meaning of a symbol is not fixed, it depends on context in which it is defined.

---

Here is some experiment for you

do

(multiply-by-seven "10")

and see if you can explain what happens.

You will see that number takes the value "10", and when you do (* 7 number), it will fail. Because the meaning of number is defined by the * function, * expects that number be of type numeric value.

So, a value can have different type-s

• "10" is a string type
• 7 is a numeric type

Re-read the section on what a DATA TYPE is in the elisp manual

---

The key thing to understand is "The context defines the meaning".

Answer 6

I'm not sure you have your answer already, but here's my take on it.

For your example:

(defun multiply-by-seven (number)
  "Multiply NUMBER by seven."
  (* 7 number))

... the first thing it sees in the list is 'defun'. So, first it checks whether it's a function, macro or special-form, to see what it's going to do with your arguments. If you look it up in Help, you can see it says "defun is a Lisp macro".

For this specific case, you can also do:

(symbol-function 'defun) 

I get:

(macro . #[lots of stuff]) 

So 'defun' is a macro, but what does a 'macro' entail then?

From my understanding of a macro, it doesn't evaluate any of its arguments; and that gives you a chance to re-arrange its arguments, add or detach parts of the code, or otherwise modify them. And then, whatever_comes_out_of_that is the thing it evaluates.

In other words, it doesn't evaluate the arguments which it receives; it evaluates whatever comes out after modifying it.

For your example, the 'defun' macro receives four not-evaluated arguments:

o  the symbol 'multiply-by-seven' 
o  the list (number)
o  the string "Multiply NUMBER by seven."
o  another list (* 7 number)

You can do this yourself to see the result of the modifications:

(macroexpand-all
  '(defun multiply-by-seven (number)
     "Multiply NUMBER by seven."
     (* 7 number)))

I get:

(defalias 'multiply-by-seven 
  #'(lambda (number) "Multiply NUMBER by seven." (* 7 number)))

And this is the thing it evaluates. 'defalias' here puts your code into 'multiply-by-seven'.

You can look at the source code for 'defun' in the file "byte-run.el" (find it online or download the source files) to see the specifics of those modifications, but it's quite messy.

Anyway, that's why in your example, it sees the second argument (number) and fourth argument (* 7 number) as lists and not treat them as function calls - the macro doesn't evaluate them.

It does however evaluate the list (* 7 number) when you call 'multiply-by-seven'.

This next bit is about what happens when you evaluate a function like (* 7 number).

Starting from the top, it first checks what kind of thing * is. Help says it's a built-in function.

And so, because it's a function, it evaluates all of its arguments.

o  7 is an integer, which evaluates to itself, the integer 7. 
o  it evaluates 'number' by getting its symbol-value, say 3. 

And then, it passes these two arguments into the function to do the multiplication steps. You can see it in the source code "data.c", which is in C language.

Likewise, if you call (multiply-by-seven 3):

It checks what 'multiply-by-seven' is. Help says it's a Lisp function.

And so, it'll evaluate all of its arguments.

o  3 evaluates to 3, and then locally binds it to 'number'. 

Then it passes its arguments into the function 'multiply-by-seven' to do the next steps. (See above.)

For your other mentions, 'set' is a function and behaves like in the steps above. But what about 'setq'?

Help says 'setq' is a special-form. Special-forms are only defined in C, and exist so that they can evaluate some arguments and not others.

You can check out how it handles 'setq' in "eval.c". There's a 'for' loop which gets every sym-val pair passed in, and evaluates just the val from each pair.

There's no need for a lisp equivalent to define special-forms - you have macros, which don't evaluate any argument, and can use it to ultimately evaluate some arguments and not others.

Finally, for the other example:

(hoge (foo bar))

How do you know whether it evaluates (foo bar) or reads it in as a list?

If 'hoge' is a special-form, it's specific to that special-form whether or not to evaluate it. You can look it up the source code, or just test the code and see. There is a limited number of these special-forms.

Otherwise, it evaluates (foo bar) when 'hoge' is a function, and reads it in as a list when 'hoge' is a macro. You can use 'functionp' and 'macrop' to check. Both of the following give me 't':

(macrop 'defun)
(functionp 'multiply-by-seven)

And how do you write it in these two ways?

(defmacro hoge (arg)
  "this doesn't evaluate arg, but does evaluate the result of calling (hoge arg)." 
  ...)

(defun hoge (arg) 
  "this evaluates arg, and gives you the result of calling (hoge arg)." 
  ...)