Metadata is a map of descriptive properties attached to a Clojure value without putting those properties into the value itself. It suits documentation, debugging information, type hints, and tags that tools can inspect. Different metadata does not make otherwise equal values unequal. section 16.13
Choose the operation according to the object:
- `meta` reads attached metadata, returning `nil` when there is none. `(meta 1)` returns `nil`. section 16.13
- `with-meta` makes a value with a replacement metadata map; `vary-meta` makes one with its map updated by a function. Persistent collections commonly support these operations. section 16.13
- `alter-meta!` and `reset-meta!` change metadata in place on supported objects, including vars, atoms, refs, agents, and namespaces. section 16.13
Annotate a collection
`(def v (with-meta [1 2 3] {:initial-count 3}))` attaches a count without adding a vector element. `(meta (conj v 4))` returns `{:initial-count 3}`, but `(meta (into [] v))` returns `nil`. A second `with-meta` replaces the metadata map rather than merging it. section 16.13
Metadata also participates in function definitions. A `defn` can carry documentation and custom tags; tools can inspect the resulting var with `meta`. Metadata at different positions can serve the var, the compiler, or runtime evaluation, so placement matters. section 2.1.1
(defn ^{:t1 1} foo ; #1
"docstring"
{:t2 2} (^{:t3 3} [a b] {:t4 4} (+ a b)) ; #2
{:t5 5}) ; #3
(meta #'foo) ; #4
;; {:ns #object[clojure.lang.Namespace 0x33f17f86 "user"],
;; :name foo,
;; :t2 2,
;; :file
;; "/private/var/form-init5372276344059831979.clj",
;; :column 1,
;; :line 1,
;; :arglists ([a b]),
;; :doc "docstring",
;; :t1 1,
;; :t5 5}
(meta (first (:arglists (meta #'foo)))) ; #5
;; {:t3 3, :t4 4}
Compare `(meta #'foo)` with metadata on its argument list: annotations at different positions are retrieved from different objects. section 2.1.1
Do not assume every collection operation carries metadata forward. `into` preserves metadata on its destination, not its source; `set` removes input metadata even when given a set. Attach or update metadata on the result when a transformation must retain it. section 8.1.1 section 13.2
