From 4a084a83e45b5aabb44791bba13fa84db1c8b217 Mon Sep 17 00:00:00 2001 From: Alex Miller Date: Thu, 11 Nov 2021 14:44:21 -0600 Subject: [PATCH] add section on var metadata tags in vars page, #534 --- content/reference/vars.adoc | 23 ++++++++++++++++++++++- 1 file changed, 22 insertions(+), 1 deletion(-) diff --git a/content/reference/vars.adoc b/content/reference/vars.adoc index 59492abf..f7f376a3 100644 --- a/content/reference/vars.adoc +++ b/content/reference/vars.adoc @@ -93,6 +93,27 @@ The <> special form or the `pass:[#']` reader macro _(see It is possible to create vars that are not interned by using https://clojure.github.io/clojure/clojure.core-api.html#clojure.core/with-local-vars[with-local-vars]. These vars will not be found during free symbol resolution, and their values have to be accessed manually. But they can serve as useful thread-local mutable cells. +[[metadata]] +== Var metadata + +The forms that create vars `def`, `defn`, `defmacro`, etc use a standard set of var <> to describe vars. Some of these forms provide explicit places in the syntax to provide values stored in the metadata, but generally you can also supply that metadata as a map on the var symbol. + +Common var metadata keys (all optional at var definition): + +* `:doc` - a string documenting the var, usually set by the docstring parameter +* `:added` - a string documenting the version when this var was added +* `:private` a boolean flag, often set by `defn-`, used by the author to state the intent that this var is an implementation detail. Private vars are globally accessible but will not be referred or listed in `ns-`... functions which filter to non-private vars. +* `:arglists` - a coll of arglists, will be generated automatically if not supplied, most often used to document macro syntax +* `:macro` - a boolean flag added by `defmacro` automatically (not typically used directly) +* `:tag` - a type identifier (usually a class) for the type of the value in the var or the return type of a function held in the var. Note that var metadata is evaluated, so type hints like `^long` on the var will evaluate to the `long` function, not a `long` primitive type hint. Generally, it is preferred to use a type hint on the arglist for defn vars instead. +* `:test` - the `clojure.test` framework attaches unit tests to vars using this key (not typically used directly) +* `:dynamic` - indicates a var may be dynamically rebound in a thread context (see above). Dynamic vars will not be direct linked when compiling with direct linking. +* `:redef` - indicates that a var should not be direct linked when compiling with direct linking (thus allowing it to be redefined) +* `:static` - no longer used (originally vars were dynamic by default, now they are static by default) +* `:const` - indicates that a var is a compile-time constant and the compiler can inline the value into code that uses it. Note: this is rarely needed and only works with constants at compile time (read, but not evaluated), such as numbers, strings, etc (NOT classes, functions, ref types, etc). Redefining or dynamically binding a const var will not affect code that consumes the var that has already been compiled and loaded in the runtime. + +Also see <> for more information about direct linking and metadata elision during compilation. + [[related]] == Related functions @@ -101,4 +122,4 @@ Variants of `def`: https://clojure.github.io/clojure/clojure.core-api.html#cloju Working with interned Vars: https://clojure.github.io/clojure/clojure.core-api.html#clojure.core/declare[declare] https://clojure.github.io/clojure/clojure.core-api.html#clojure.core/intern[intern] https://clojure.github.io/clojure/clojure.core-api.html#clojure.core/binding[binding] https://clojure.github.io/clojure/clojure.core-api.html#clojure.core/find-var[find-var] <> Working with Var objects: https://clojure.github.io/clojure/clojure.core-api.html#clojure.core/with-local-vars[with-local-vars] https://clojure.github.io/clojure/clojure.core-api.html#clojure.core/var-get[var-get] https://clojure.github.io/clojure/clojure.core-api.html#clojure.core/var-set[var-set] https://clojure.github.io/clojure/clojure.core-api.html#clojure.core/alter-var-root[alter-var-root] https://clojure.github.io/clojure/clojure.core-api.html#clojure.core/var?[var?] https://clojure.github.io/clojure/clojure.core-api.html#clojure.core/with-redefs[with-redefs] https://clojure.github.io/clojure/clojure.core-api.html#clojure.core/with-redefs-fn[with-redefs-fn] Var validators: https://clojure.github.io/clojure/clojure.core-api.html#clojure.core/set-validator![set-validator!] https://clojure.github.io/clojure/clojure.core-api.html#clojure.core/get-validator[get-validator] -Common Var metadata: https://clojure.github.io/clojure/clojure.repl-api.html#clojure.repl/doc[doc] https://clojure.github.io/clojure/clojure.repl-api.html#clojure.repl/find-doc[find-doc] https://clojure.github.io/clojure/clojure.core-api.html#clojure.core/test[test] +Using Var metadata: https://clojure.github.io/clojure/clojure.repl-api.html#clojure.repl/doc[doc] https://clojure.github.io/clojure/clojure.repl-api.html#clojure.repl/find-doc[find-doc] https://clojure.github.io/clojure/clojure.core-api.html#clojure.core/test[test]