Warning: this is an htmlized version!
The original is across this link,
and the conversion rules are here.
(Re)generate: (find-defun-intro)
Source code:  (find-eev "eev-intro.el" "find-defun-intro")
More intros:  (find-eval-intro)
              (find-eepitch-intro)
This buffer is _temporary_ and _editable_.
Is is meant as both a tutorial and a sandbox.


[At present this is just a _skeleton_ for a tutorial on defining
functions in Lisp...]



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")