`defmacro` defines a macro and binds it to a var in the current namespace. Use it when ordinary functions cannot express the desired behavior because arguments must be handled before evaluation, or when repeated code is better expressed as a new form. A macro receives forms as data during compilation and returns a Clojure expression for later evaluation. section 4.0 section 4.1
Its shape is `(defmacro name & fdecl)`, much like `defn`:
- `name` must be a valid Clojure symbol; `fdecl` supplies arguments and a body. Multiple arities, destructuring, and `:pre` and `:post` conditions are supported. section 4.1
- The macro body can access two implicit arguments: `&form`, the original call form, and `&env`, the local compilation environment. They reduce the limit on fixed arguments from 20 to 18. section 4.1
- Defining a macro returns the `clojure.lang.Var` that refers to it. section 4.1
Build and inspect a conditional form
`(defmacro when [test & body] (list 'if test (cons 'do body)))` builds an `if` expression rather than evaluating `test` or `body` while expanding. `(macroexpand-1 '(when (= 1 2) (println "foo")))` produces `(if (= 1 2) (do (println "foo")))`. Evaluating the original `when` call prints nothing and returns `nil`. `macroexpand-1` shows the first expansion without expanding it further. section 4.1
(macroexpand '(defmacro simple [a] (str a))) ; #1 ;; (do ;; (clojure.core/defn simple ([&form &env a] (str a))) ; #2 ;; (. (var simple) (setMacro)) ; #3 ;; (var simple)) ; #4
Expanding a `defmacro` definition reveals a function definition with implicit `&form` and `&env` parameters, followed by marking its var as a macro and returning that var. section 4.1
Reach for `macroexpand` when generated code is surprising; it prints an expansion for inspection without executing it. For generated symbols or quoted code, `gensym` and quoting facilities are related tools. The essential contract remains simple: accept unevaluated forms, produce an expression. section 4.0 section 4.9
