(Re)generate: (find-defun-intro)
Source code:  (find-eev "eev-intro.el" "find-defun-intro")
More intros:  (find-eev-quick-intro)
              (find-eval-intro)
              (find-eepitch-intro)
This buffer is _temporary_ and _editable_.
It is meant as both a tutorial and a sandbox.


Note: this intro needs to be integrated with:
  (find-elisp-intro)
I wrote it for a mini-tutorial on Lisp that I gave.
It complements this:
  (find-eev-quick-intro "2. Evaluating Lisp")
  (find-eval-intro "3. What to execute, and in what order")
  (find-eval-intro "3. What to execute, and in what order" "defun")




Simple examples

  (* 5 5)
  (* 6 6)
  (defun foo (a) (* a a))
  (foo 5)
  (foo 6)

  (+ 5 5)
  (defun foo (a) (+ a a))
  (foo 5)

  (symbol-function 'foo)
  ((lambda (a) (* a a)) 5)
  ((lambda (a) (+ a a)) 5)

See:
  (find-elnode "Function Cells")
  (find-elnode "Defining Functions")



Several arguments

  (defun foo (a b) (+ (* a a) (* b b)))
  (foo 10 2)
  (foo 5)
  (defun foo () (+ (* 2 3) (* 4 5)))
  (foo 10 2)
  (foo 5)
  (foo)



progn and prog1
The body of a "defun" works like a "progn".
See: (find-elnode "Index" "* progn:")

  (defun foo (a b)         (* a b))
  (defun foo (a b) (+ a b) (* a b))
  (defun foo (a b) (* a b) (+ a b))
  (defun foo (a b)         (+ a b))
  (foo 5 6)

  (progn   (* 5 6) (+ 5 6))
  (progn "ignored" (+ 5 6) "result")
  (progn)

  (prog1   (* 5 6) (+ 5 6))
  (prog1 "result" (+ 5 6) "ignored")
  (prog1)



Docstrings
Note that a string in a (progn ...) does nothing - unless it is
the last BODY-FORM.

But see: (find-elnode "Documentation")

Try:

  (defun foo (a b) "IGNORED" (+ a b))
  (defun foo (a b) "This is the description of `foo'" (+ a b))
  (defun foo (a b) "This is the docstring of `foo'" (+ a b))
  (defun foo (a b) "This function returns (* A B). Note the italics!" (+ a b))
  (find-efunctiondescr 'foo)



&optional and &rest
See: (find-elnode "Argument List")
Try:

  (defun foo (a &optional b c) (list "a,b,c:" a b c))
  (foo 11 22 33)
  (foo 11 22)
  (foo 11)
  (foo)
  (foo 11 22 33 44)

  (defun foo (a &optional b c &rest r) (list "a,b,c,r:" a b c r))
  (foo 11 22 33 44 55 66)
  (foo 11 22 33 44 55)
  (foo 11 22 33 44)
  (foo 11 22 33)
  (foo 11 22)
  (foo 11)
  (foo)

  (defun foo (a &rest r) (list "a,r:" a r))
  (foo 11 22 33 44)
  (foo 11 22 33)
  (foo 11 22)
  (foo 11)
  (foo)



A tool: my-insert
See: (find-elnode "Formatting Strings")
Try:

  (format "<%s>" "hello")
  (format "<%s>" "123")
  (format "<%s>" 123)
  (format "<%s>" 'hello)
  (format "<%s>" '(+ 2 3))

  (format "<%S>" "hello")
  (format "<%S>" "123")
  (format "<%S>" 123)
  (format "<%S>" 'hello)
  (format "<%S>" '(+ 2 3))

Now define:

  (defun my-insert (obj)
    "Print (insert) OBJ in the current buffer."
    (insert (format "\n  ;; \\--> %S" obj)))

Try:

  (my-insert 123)
  (my-insert "123")
  (my-insert "hello")
  (my-insert 'hello)
  (my-insert '(+ 2 3))
  (my-insert nil)
  (my-insert '())
  (my-insert ())

See also:
  (find-elnode "Character Type")
  (find-elnode "Basic Char Syntax")
  (find-elnode "Basic Char Syntax" "?\\n")
  (find-elnode "General Escape Syntax")



interactive
Not all Emacs functions are callable with `M-x' - only those that
are "commands" are callable in this way. And only "commands"
can be bound to keys...

See:
  (find-elnode "Defining Functions" "the first two of the BODY-FORMS")
  (find-elnode "Defining Commands")
  (find-elnode "Command Overview")

When you execute an `(interactive ...)' it does nothing - it
simply ignores its arguments (which aren't even evaluated!) and
returns nil. But just as


  (defun my-insert (obj) (insert (format "\n  ;; \\--> %S" obj)))

  (find-efunctiondescr 'interactive)

  (eek "M-x foo")
  (commandp 'foo)

  (defun foo (&rest rest) (interactive) (bar rest))
  (eek "M-x foo")

  (defun foo (&rest rest)                   (bar rest))
  (defun foo (&rest rest) (interactive "P") (bar rest))
  (eek "            M-x foo")
  (eek "M-1         M-x foo")
  (eek "M-1 M-2 M-3 M-x foo")
  (eek "M-- M-2 M-3 M-x foo")

  (defun foo (&rest rest) (interactive "R") (bar rest))
  (eek "M-x foo")