Is there a code example demonstrating a meaningful usage of the built-in function `funcall`?

Question

In order to understand what the symbol funcall means I have checked out its documentation. If I understand it right after reading the docs this symbol represents a function which in my eyes can be always easily removed from the elisp expression without changing the outcome:

(funcall '+ 1 2) ; returns 3
(+ 1 2)          ; returns 3

Also in the code example provided in the funcall function documentation the expression works OK after skipping funcall from it:

(funcall 'cons 'x 'y) ;returns (x . y)
(cons 'x 'y)          ;returns (x . y)

What is the difference between the two code versions giving funcall the right to exist?

Is it just for fun there in order to be able to obfuscate:

(+ 3 2)

expressing it as:

(defun 3+ (x) (+ x 3)) (3+ 2)
(funcall (lambda (x) (+ x 3)) 2)
;; with finally: 
(funcall (setq 3+ (lambda (x) (+ x 3))) 2)

?

Or is it there to fix the problem if someone erroneously misused the value slot of a symbol to store there a function?

In other words: is there a code example able to demonstrate a meaningful usage of funcall?

---

@Drew : elisp is able to distinguish between the value and the function "slots" of a symbol without usage of funcall from the context of symbols usage. Run following piece of code in Emacs 29 to see it yourself:

(setq  f    2)
(defun f () 3)
(message "val: %s  func: %s  symb: %s" f (f) 'f)

which gives:

"val: 2  func: 3  symb: f"

@Drew : to my knowledge in elisp ALL symbols and expressions are ALWAYS evaluated. Also 'f becomes evaluated and it equals to f only because ' is a syntactical sugar for a special form quote returning f as the value of to it passed parameter without evaluating it.

Answer 1

Virtually all of the "real" examples are variations of the following theme: you have a list of functions and you want to call each function in turn (e.g. hooks are lists of functions - when the hook is run, we march down the list and call each function in turn). You cannot march down the list with car and cdr and for each element call it. E.g. this does not work:

;; make a list of a couple of functions
(setq my-hook nil)
(add-hook 'my-hook (lambda () (message "foo")))
(add-hook 'my-hook (lambda () (message "bar")))

;; march down the list, calling each function in turn
(dolist (element my-hook) (element))
==> Debugger entered--Lisp error: (void-function element)
  (element)
  (let ((element (car tail))) (element) (setq tail (cdr tail)))
  (while tail (let ((element (car tail))) (element) (setq tail (cdr tail))))
  (let ((tail my-hook)) (while tail (let ((element (car tail))) (element) (setq tail (cdr tail)))))
  (progn (let ((tail my-hook)) (while tail (let ((element (car tail))) (element) (setq tail (cdr tail))))))
  eval((progn (let ((tail my-hook)) (while tail (let ((element (car tail))) (element) (setq tail (cdr tail)))))) t)

element is bound to each element of the list in turn, but through its value cell, not its function cell, so you cannot call it as a function any more than you can do:

(setq foo (lambda () (message "foobar")))
(foo) ==>  
Debugger entered--Lisp error: (void-function foo)
  (foo)

But you can funcall it:

(funcall foo) ==> nil ;; i.e. no error

Similarly for the my-hook list of functions, you can do:

(dolist (element my-hook) (funcall element))

In both cases, you can check *Messages* to see that the functions were indeed called (and in the correct order in the case of the list).

As I said, this is how hooks are run. There are complications of course, which is why simple examples are used to get the concepts across before you have to worry about all the additional wrinkles that have to be ironed out with real hooks.

Answer 2

Let's consider the case that you have plenty of functions in your Emacs initialization file to which you pass 1 as parameter:

(desktop-save-mode 1)
;; ... many other functions ...
(show-paren-mode   1) 

Now you want to avoid repetition of the parameter value 1 and the calls replacing the above with only one function call to which you pass a list of functions taking this parameter. The code which accomplishes this would be hard to write without using funcall:

;; Run multiple functions with the same passed to them parameter
(mapcar (lambda (f) (funcall f 1)) '(
    desktop-save-mode 
;; ... many other functions ...
    show-paren-mode
))

because in this kind of code design elisp is somehow not able to recognize from the context that f will represent a symbol storing a function and must be instructed with funcall in order not to fail with the message: "Symbol’s function definition is void: f" while running the code.

As explained in the answer by NickD the "somehow not able" is caused by the elisp mechanism of taking items from a list of items in order to provide them as item symbol to the item processing code block.

This mechanism is not capable of recognizing the context and therefore does not differentiate between list symbols representing functions and list symbols representing values. In other words this mechanism provides the list items just always in a value cell instead of the function cell in case the list items are functions. The consequence of this fact is the necessity of using funcall to avoid elisp runtime errors.

Answer 3

Symbols can't just hold a value (as variables). Symbols can also hold a function definition (see Symbol Components). That is, a symbol can act as both a variable and a function.

funcall just calls the function definition stored in a symbol.

A real example from my repo: org-shoplist is a testing-function:

(defun org-shoplist-test-test-in-buffer (func-in-buffer)
  (org-shoplist-test-test
   (lambda ()
     (unwind-protect
         (with-current-buffer (get-buffer-create org-shoplist-test-default-buffer)
           (funcall func-in-buffer)) ;; <--- function called which is stored in the arguemnt
       (kill-buffer org-shoplist-test-default-buffer)))))

This function executes a test in temp-buffer and leaves everything in same state as before. ‘FUNC-IN-BUFFER’ is what should be done in the temp-buffer.

Concrete call of this function would look like this:

(ert-deftest org-shoplist-test/recipe-read-one-ing ()
  (org-shoplist-test-test-in-buffer
   (lambda ()
     (setq org-shoplist-inital-factor nil)
     (insert "* Test
- (200g Nuts) mahlen")
     (goto-char (point-min))
     (should (equal (list "Test" nil 'org-shoplist--recipe-read-ings-current
                          (list (org-shoplist-ing-create "200g" "Nuts")))
            (org-shoplist-recipe-read 'org-shoplist--recipe-read-ings-current))))))

I pass a concrete function (the test-case) into another more general function (which has the funcall-call). funcall helps writing lesser code, because I can extract the general parts and pass in the concrete ones by argument.