This ancient article has been superseded by a much better and up to date article on the Clojure website
A reference collection of characters used in Clojure that are difficult to "google". Descriptions sourced from various blogs, StackOverflow, Learning Clojure and the official Clojure docs - sources attributed where necessary. Type the symbols into the box below to search (or use
CTRL-F). Sections not in any particular order but related items are grouped for ease. If I'm wrong or missing anything worthy of inclusion tweet me @kouphax or mail me at [email protected].
# - Dispatch macro
You'll see this macro character beside another e.g. #( or #". This topic will act as a bit preamble before looking at your specific case.
# is the dispatch macro, a reader macro that tells the Clojure reader (the thing that takes a file of Clojure text and parses it for consumption in the compiler) to go and look at another read table for the definition of the next character - in essence this allows extending default reader behaviour.
Clojure doesn't provide support for creating reader macros but it is possible through a bit of hackery.
If you see # at the end of a symbol then this is used to automatically generate a new symbol. This is useful inside macros to keep macro specifics from leaking into the userspace. A regular let will fail in a macro definition
user=> (defmacro m [] `(let [x 1] x))
#'user/m
user=> (m)
CompilerException java.lang.RuntimeException: Can't let qualified name: user/x, compiling:(NO_SOURCE_PATH:1)
Instead you need to append # to the end of the variable name and let Clojure generate a unique symbol for it.
user=> (defmacro m [] `(let [x# 1] x#))
#'user/m
user=> (m)
1
user=>
If we expand this macro we can see the gensym'd name
user=> (macroexpand '(m))
(let* [x__681__auto__ 1] x__681__auto__)
Another place you'll see the # is in tagged literals. Most commonly you'll see this use in EDN (extensible data notation - a rich data format that can be used in Clojure) and in ClojureScript (#js). Search for #inst, #uuid or #js for some more info.
#{ - Set macro
See the dispatch (#) macro for additional details.
#{ defines a set (a collection of unique values) specifically a hash-set. The following are equivalent,
user=> #{1 2 3 4}
#{1 2 3 4}
user=> (hash-set 1 2 3 4)
#{1 2 3 4}
Attempting to create a set using this literal form will throw if there are duplicates. Instead the hash-set function should be used on a vector
user=> #{1 2 3 4 1}
IllegalArgumentException Duplicate key: 1 clojure.lang.PersistentHashSet.createWithCheck (PersistentHashSet.java:68)
user=> (set [1 2 3 4 1]) ; convert vector to set, removing duplicates
#{1 2 3 4}
#_ - Discard macro
See the dispatch (#) macro for additional details.
#_ tells the reader to ignore the next form completely.
user=> [1 2 3 #_ 4 5]
[1 2 3 5]
The docs suggest that "The form following #_ is completely skipped by the reader. (This is a more complete removal than the comment macro which yields nil).". This can prove useful for debugging situations or for multline comments. I've never used it.
#" - Regular Expression macro
See the dispatch (#) macro for additional details.
#" indicates the start of a regular expression pattern.
user=> (re-matches #"^test$" "test")
"test"
This form is compiled at read time into a java.util.regex.Pattern.
#( - Function macro
See the dispatch (#) macro for additional details.
#( begins the short hand syntax for an inline function definition. The following 2 bits of code are similar,
; anonymous function takin a single argument and printing it
(fn [line] (println line)) ;
; anonymous function takin a single argument and printing it - shorthand
#(println %)
The macro expands the shorthand syntax into a function definition whose arity (the number of arguments it takes) is defined by how the % placeholders are declared. See the % character for discussion around arity.
user=> (macroexpand `#(println %))
(fn* [arg] (clojure.core/println arg)) ; argument names shortened for clarity
#' - Var macro
#' is the var quote. It is the same a the var method,
user=> (def nine 9)
#'user/nine
user=> nine
9
user=> (var nine)
#'user/nine
user=> #'nine
#'user/nine
When used it will attempt to return the referenced var. This is useful when you want to talk about the reference/declaration instead of the value it represents. See the use of meta in the metadata (^) discussion.
#inst, #uuid & #js etc. - tagged literals
Commonly found in EDN and ClojureScript this use of # is called the tagged literal. Look at this example,
user=> (java.util.Date.)
#inst "2014-05-19T19:12:37.925-00:00"
When we create a new date it is represented as a tagged literal, or in this case a tagged string. We can use Clojures read-string to read this back (or use it directly)
user=> (type #inst "2014-05-19T19:12:37.925-00:00")
java.util.Date
(read-string "#inst \"2014-05-19T19:12:37.925-00:00\"")
#inst "2014-05-19T19:12:37.925-00:00"
user=> (type (read-string "#inst \"2014-05-19T19:12:37.925-00:00\""))
java.util.Date
A tagged literal tells the reader how to parse the literal value. Other common uses include #uuid for generating UUIDs and in the ClojureScript world an extremely common use of tagged literals is #js which can be used to convert ClojureScript data structures into JavaScript structures directly.
% - Argument placeholder
% is not a macro but a placeholder for use in the #( macro. It represents an argument that will be passed into the function when it is expanded.
user=> (macroexpand `#(println %))
(fn* [arg] (clojure.core/println arg)) ; takes a single arg, uses it once
user=> (macroexpand `#(println % %))
(fn* [arg] (clojure.core/println arg arg)) ; takes a single arg, uses it twice
Numbers can be placed directly after the % to indicate the arguments position. Numbers are also used by the #( macro to determine the number of arguments to pass in.
user=> (macroexpand `#(println %1 %2))
(fn* [arg1 arg2] (clojure.core/println arg1 arg2)) ; takes 2 args
user=> (macroexpand `#(println %4))
(fn* [arg1 arg2 arg3 arg4] (clojure.core/println arg4)) ; takes 4 args doesn't use 3
So you don't have to use the arguments but you do need to declare them in the order you'd expect an external caller to pass them in.
% and %1 can be used interchangably,
user=> (macroexpand `#(println % %1)) ; use both % and %1
(fn* [arg1] (clojure.core/println arg1 arg1)) ; still only takes 1 argument
@ - Deref macro
@ is the deref macro, it is the shorthand equivalent of the deref function so these 2 forms are the same,
user=> (def x (atom 1))
#'user/x
user=> @x
1
user=> (deref x)
1
user=>
@ is used to get the current value of a reference. The above example uses @ to get the current value of an atom but @ can be applied to other things such as futures, delays, promises etc. to force computation and potentially block.
^ - Metadata
^ is the metadata marker. Metadata is a map of values (with shorthand option) that can be attached to various forms in Clojure. This provides extra information for these forms and can be used for documentation, compilation warnings, typehints and other features.
user=> (def ^{ :debug true } five 5) ; meta map with single boolean value
#'user/five
We can access the metadata by the meta method which should be executed against the declaration itself (rather than the returned value).
user=> (def ^{ :debug true } five 5)
#'user/five
user=> (meta #'five)
{:ns #<Namespace user>, :name five, :column 1, :debug true, :line 1, :file "NO_SOURCE_PATH"}
As we have a single value here we can use a shorthand notation for declaring the metadata ^:name which is useful for flags as the value will be set to true.
user=> (def ^:debug five 5)
#'user/five
user=> (meta #'five)
{:ns #<Namespace user>, :name five, :column 1, :debug true, :line 1, :file "NO_SOURCE_PATH"}
Another use of ^ is for type hints. These are used to tell the compiler what type the value will be and allow it to perform type specific optimisations thus potentially making resultant code a bit faster.
user=> (def ^Integer five 5)
#'user/five
user=> (meta #'five)
{:ns #<Namespace user>, :name five, :column 1, :line 1, :file "NO_SOURCE_PATH", :tag java.lang.Integer}
We can see in that example the :tag property is set.
You can also stack the shorthand notations,
user=> (def ^Integer ^:debug ^:private five 5)
#'user/five
user=> (meta #'five)
{:ns #<Namespace user>, :name five, :column 1, :private true, :debug true, :line 1, :file "NO_SOURCE_PATH", :tag java.lang.Integer}
' - Quote macro
Can be used against symbols as part of a dispatch macro (see #'). Also used to quote forms and prevent their evaluation as with the quote function.
user=> (1 3 4) ; fails as it tries to evaluate 1 as a function
ClassCastException java.lang.Long cannot be cast to clojure.lang.IFn user/eval925 (NO_SOURCE_FILE:1)
user=> '(1 3 4) ; quote
(1 3 4)
user=> (quote (1 2 3)) ; using the longer quote method
(1 2 3)
user=>
; - Comment
; is a comment. In fact its a comment macro that takes all input from its starting point to the end of the line and ensures the reader ignore it.
user=> (def x "x") ; this is a comment
#'user/x
user=> ; this is a comment too
<returns nothing>
: - Keyword
: is the indicator for a Keyword which is an interned string that provides fast comparison and lower memory overhead.
user=> (type :test)
clojure.lang.Keyword
Alternativley you can use keyword to create a keyword from a string
user=> (keyword "test")
:test
A neat thing about keywords is they also implement IFn and can act as functions for extracting values from maps which is very nice.
user=> (def my-map { :one 1 :two 2 })
#'user/my-map
user=> (:one my-map) ; get the value for :one by invoking it as function
1
user=> (:three my-map) ; it can safely access non-keys
nil
user=> (:three my-map 3) ; it can return a default if specified
3
:: - Qualified keyword
:: is used to fully qualify a keyword with the current namespace.
user=> :my-keyword
:my-keyword
user=> ::my-keyword
:user/my-keyword
user=> (= ::my-keyword :my-keyword)
false
I have found this useful when creating macros. If I want to ensure a macro, that calls another method in the macro namespace, correctly expands to call the method I have used ::my-method to refer to the fully qualified name.
/ - Namespace separator
Can be the division function / but can also act as a separator in a symbol name to break apart the symbol name and the namespace it resides in my-namepace/utils. This allows symbols to be fully qualified to prevent collisions or spread.
$ - Inner class reference
Used to reference inner classes and interfaces in Java. Seperates the container class name and the inner class name,
(:import (basex.core BaseXClient$EventNotifier)
(defn- build-notifier [notifier-action]
(reify BaseXClient$EventNotifier
(notify [this value]
(notifier-action value))))
EventNotifier is an inner interface of the BaseXClient class which is an imported Java class.
-> ->> some-> cond-> as-> etc. - Threading macros
These are threading macros. Almost all of them take an initial value and thread this value through a number of forms. Lets imagine (for reasons unknown) we wanted to take a number, find the square root, cast it to an int, then a string then back to an integer again. We could write it like this,
user=> (Integer. (str (int (Math/sqrt 25))))
5
The threading macro allows us to unravel this deep nesting,
user=> (-> 25 (Math/sqrt) int str Integer.)
5
Or if you prefer multiline and consistent brackettering
(-> 25
(Math/sqrt)
(int)
(str)
(Integer.))
What the macro does is take the value returned from each expression and push it in as the first argument to the next one.
->> is the same but different. Rather than push the last value in as the first argument it passes it in as the last argument.
The "etc." in the title refers to the fact there are a whole host of threading macros that perform variations on the same theme (cond->, some->, as-> and their ->> equivalents). There is also an entire library, swiss-arrows, dedicated to the threading macros.
~ - Unquote macro
See ` (syntax quote) for additional information.
~ is unquote. That is within as syntax quoted (`) block ~ will unquote the associated symbol i.e. resolve it in the current context.
user=> (def five 5) ; create a named ref representing the number 5
#'user/five
user=> five ; five will yeild its internal value
5
user=> `five ; syntax quoting five will fully resolve the SYMBOL
user/five
user=> `~five ; within a syntax quoted block ~ wil resolve the value in the current context
5
This forms the meat and potatoes of creating macros which are, to be highly reductionist, functions that return blocks of syntax with parts evaluated in varying contexts.
- Clojure for the Brave and True - Writing Macros
- Clojure from the ground up: macros
- Clojure Official Documentation
~@ - Unquote splicing macro
See ` (syntax quote) and ~ (unquote) for additional information.
~@ is unquote-splicing. Where unquote (~) deals with single values (or treats its attached item as a single item) ~@ works on lists and expands them out into multiple statements. Think JavaScripts .apply method that takes an array and expands it out as arguments to the applied function.
user=> (def three-and-four (list 3 4))
#'user/three-and-four
user=> `(1 ~three-and-four) ; treates as a single statement produces a nested list
(1 (3 4))
user=> `(1 ~@three-and-four) ; expand out as seperate statements
(1 3 4)
Again this gives us a lot of power in macros.
- Clojure for the Brave and True - Writing Macros
- Clojure from the ground up: macros
- Clojure Official Documentation
` - Syntax quote
See ~@ (unquote splicing) and ~ (unquote) for additional information.
` is the syntax quote. When used on a symbol it resolves the symbol in the current context,
user=> (def five 5)
#'user/five
user=> `five
user/five
When used with lists (remember every thing in Clojure is data) it forms a template for the data structure and won't immediately resolve it.
user=> (1 2 3)
ClassCastException java.lang.Long cannot be cast to clojure.lang.IFn user/eval832 (NO_SOURCE_FILE:1)
user=> `(1 2 3)
(1 2 3)
You'll see this most often in the context of macros. We can write one now,
user=> (defmacro debug [body]
#_=> `(let [val# ~body]
#_=> (println "DEBUG: " val#)
#_=> val#))
#'user/debug
user=> (debug (+ 2 2))
DEBUG: 4
4
Code updated based on recommendations from Leif Foged
The macro takes a single statement wraps it in a quoted let block, evaluates and prints the result and then evaluates the body. In effect this defmacro call returns a quoted data structure representing the program we are writing with it. The ` allows this to happen.
- Clojure for the Brave and True - Writing Macros
- Clojure from the ground up: macros
- Clojure Official Documentation
*var-name* - Earmuffs
Earmuffs (a pair of asterisk bookending var names) is a naming convention in many LISPs used to denote special vars. Most commonly in Clojure this seems to be used to denote dynamic vars i.e. ones that can change depending on where you are in the program. The earmuffs act as a warning that "here be dragons" and to never assume the state of the var. Remember this is a convention not a rule.
Core Clojure examples are *out* and *in* which represent the standard in and out Writers for Clojure.
>!!, <!!, >! & <! - core.async channel macros
These symbols are channel operations in core.async - a Clojure/ClojureScript library for channel based asynchronous programming (specifically CSP - Communicating Sequential Processes).
If you imagine, for the sake of argument, a channel is a bit like a queue that things can put stuff on and take stuff off then these symbols support that simple API.
>!!&<!!are blocking put and take respectively>!&<!are, simply, put and take
The difference being the blocking versions operate outside go blocks and block the thread they operate on.
user=> (def my-channel (chan 10)) ; create a channel
user=> (>!! my-channel "hello") ; put stuff on the channel
user=> (println (<!! my-channel)) ; take stuff off the channel
hello
The non-blocking versions need to be executed within a go block otherwise they'll throw an exception
user=> (def c (chan))
#'user/c
user=> (>! c "nope")
AssertionError Assert failed: >! used not in (go ...) block
nil clojure.core.async/>! (async.clj:123)
While the difference between these is well outside the scope of this article fundamentally the go blocks operate and manage their own resources pausing execution of code without blocking threads. This makes asynchronously executed code appear to be synchronous and removing the pain of managing asynchronous code from the code base.
<symbol>? - Predicate Marker
Putting ? at the end of a symbol is a naming convention common across many languages that support special characters in their symbol names It is used to indicate the thing is a predicate i.e. that it poses a question. For example imagine using an API that dealt with buffer manipulation
(def my-buffer (buffers/create-buffer [1 2 3]))
(buffers/empty my-buffer)
At a glance how would you know if the method empty in this case,
- Returned true if the passed in buffer was empty, or,
- Cleared the buffer
While the author could have renamed empty to is-empty the richness of symbol naming in Clojure allows us to express intent more symbolically.
(def my-buffer (buffers/create-buffer [1 2 3]))
(buffers/empty? my-buffer)
false
This is simply a recommended convention not a requirement
<symbol>! - Unsafe Operations
The Clojure style guide has this to say
The names of functions/macros that are not safe in STM transactions should end with an exclamation mark (e.g.
reset!).
You'll most commonly see this appended to function names whose purpose is to mutate state e.g connecting to a data store, updating an atom or closing a file stream.
user=> (def my-stateful-thing (atom 0))
#'user/my-stateful-thing
user=> (swap! my-stateful-thing inc)
1
user=> @my-stateful-thing
1
This is simply a recommended convention not a requirement
_ - Irrelevant var
When you see this used as function arguments or similar it is a common naming convention for vars or arguments you are not interested in using. That is you don't intend to use them so you aren't really interested in thinking of a useful name for them.
This is an example using the add-watch function that can be used to add callback style behavior when atoms change value. Imagine, given an atom, we want to print the new value everytime it changes,
(def value (atom 0))
(add-watch value nil (fn [_ _ _ new-value]
(println new-value))
(reset! value 6)
; prints 6
(reset! value 9)
; prints 9
add-watch takes 4 arguments but in our case we only really care about the last argument - the new value of the atom. I don't really want to spend time thinking of names for these arguments I'll never use, nor do I want to generate a long line of text unnecessarily (of course I could have used the shorthand #(println %4) but that defeats the purpose of this example).
Many thanks to everyone who has contributed ideas and [the copious amounts of] spelling corrections (crikey I'm bad at speelingz - so thanks Michael R. Mayne, lobsang_ludd). I've tried to call out people who have specifically asked for things. Sorry if I've missed you.