diff --git a/content/reference/metadata.adoc b/content/reference/metadata.adoc index 0d98b373..25b46bb7 100644 --- a/content/reference/metadata.adoc +++ b/content/reference/metadata.adoc @@ -81,19 +81,6 @@ Modify or reset the metadata respectively for a namespace/var/ref/agent/atom. In addition to `with-meta`, there is reader support (<>) for applying metadata to the expression following it at read-time. -For a metadata value of type: +See <> and <> for more information on how metadata is used by the compiler for method overload selection. -* Map: `^{:key value ...}` yields itself -* Keyword: `^:key` yields `^{:key true}` -* Symbol: `^AClass` or `^package.AClass` yields `{:tag package.AClass}` (also see special <>) -* Vector: `^[AClass prim _ ...]` yields `{:param-tags [package.AClass prim _ ...]}` -* *deprecated* String: `^"[Lpackage.AClass;"` yields `{:tag "[Lpackage.AClass;"}` - since 1.12, use array class symbols instead, e.g. `^package.AClass/1` -The `:tag` key is used to hint an objects type to the Clojure compiler. See <> for more information and a complete list of special type hints. - -Since Clojure 1.12, the `:param-tags` key is used on qualified static, instance, and constructor method symbols to specify the arity and parameter types of the desired method overload. The `:param-tags` vector takes any valid `:tag` value or `_` as a placeholder for non-overloaded parameters. - -It is possible to add multiple pieces of metadata by chaining the metadata reader macros together. -For example: `^:dynamic ^ints obj` would apply both the :dynamic flag and ints type-hint to obj. Metadata chains from right to left (left takes precedence). - -Note that metadata reader macros are applied at read-time, not at evaluation-time, and can only be used with values that support metadata, like symbols, vars, collections, sequences, namespaces, refs, atoms, agents, etc. Some important exceptions that *don't* support metadata are strings, numbers, booleans, Java objects, keywords (these are cached and can be shared within the runtime), and deftypes (unless they explicitly implement clojure.lang.IMeta). diff --git a/content/reference/reader.adoc b/content/reference/reader.adoc index f5b4a90d..cdbb8acf 100644 --- a/content/reference/reader.adoc +++ b/content/reference/reader.adoc @@ -141,14 +141,12 @@ Metadata is a map associated with some kinds of objects: Symbols, Lists, Vector, `^{:a 1 :b 2} [1 2 3]` yields the vector `[1 2 3]` with a metadata map of `{:a 1 :b 2}`. + A shorthand version allows the metadata to be a simple symbol or string, in which case it is treated as a single entry map with a key of `:tag` and a value of the (resolved) symbol or string, e.g.: + -`^String x` is the same as `^{:tag java.lang.String} x` + +`^String x` is the same as `^{:tag java.lang.String} x`. -A shorthand version for type signatures allows the metadata to be a vector, in which case it is treated as a single entry map with a key of `:param-tags` and a value of the (resolved) type hints, a vector of `:tag` values or `_`, e.g.: `^[String long _]` is the same as `^{:param-tags [java.lang.String long _]}`. - -Such tags can be used to convey type information to the compiler. + +A shorthand version for type signatures allows the metadata to be a vector, in which case it is treated as a single entry map with a key of `:param-tags` and a value of the (resolved) type hints, a vector of `:tag` values or `_`, e.g.: `^[String long _]` is the same as `^{:param-tags [java.lang.String long _]}`. See <> on how param-tags are used. Another shorthand version allows the metadata to be a keyword, in which case it is treated as a single entry map with a key of the keyword and a value of true, e.g.: + -`^:dynamic x` is the same as `^{:dynamic true} x` + +`^:dynamic x` is the same as `^{:dynamic true} x` Metadata can be chained in which case they are merged from right to left.