Reader Conditionals Guide

Reader conditionals are a feature added in Clojure 1.7. They are designed to allow different dialects of Clojure to share common code that is mostly platform independent, but contains some platform dependent code. If you are writing code across multiple platforms that is mostly independent you should separate .clj and .cljs files instead.

Reader conditionals are integrated into the Clojure reader, and don’t require any extra tooling beyond Clojure 1.7 or greater. To use reader conditionals, all you need is for your file to have a .cljc extension and to use Clojure 1.7 or ClojureScript 0.0-3196 or higher. Reader conditionals are expressions, and can be manipulated like ordinary Clojure expressions. For more technical details, see the reference page on the reader.

There are two types of reader conditionals, standard and splicing. The standard reader conditional behaves similarly to a traditional cond. The syntax for usage is #? and looks like:

The platform tags :clj, etc are a fixed set of tags hard-coded into each platform. The :default tag is a well-known tag to catch and provide an expression if no platform tag matches. If no tags match and :default is not provided, the reader conditional will read nothing (not nil, but as if nothing was read from the stream at all).

The syntax for a splicing reader conditional is #?@. It is used to splice lists into the containing form. So the Clojure reader would read this:

as this:

One important thing to note is that in Clojure 1.7 a splicing conditional reader cannot be used to splice in multiple top level forms. In concrete terms, this means you can’t do this:

Instead you’d need to do wrap each function individually:

or use a do to wrap all of the top level functions:

Let’s go through some examples of places you might want to use these new reader conditionals.

Host interop is one of the biggest pain points solved by reader conditionals. You may have a Clojure file that is almost pure Clojure, but needs to call out to the host environment for one function. This is a classic example:

Namespaces are the other big pain point for sharing code between Clojure and ClojureScript. ClojureScript has different syntax for requiring macros than Clojure. To use macros that work in both Clojure and ClojureScript in a .cljc file, you’ll need reader conditionals in the namespace declaration.

Here is an example from a test in route-ccrs

Here is another example, we want to be able to use the rethinkdb.query namespace in Clojure and ClojureScript. However we can’t load the required rethinkdb.net in ClojureScript as it uses Java sockets to communicate with the database. Instead we use a reader conditional so the namespace is only required when read by Clojure programs.

Exception handling is another area that benefits from reader conditionals. ClojureScript supports (catch :default) to catch everything, however you will often still want to handle host specific exceptions. Here’s an example from lemon-disc.

The splicing reader conditional is not as widely used as the standard one. For an example on its usage, let’s look at the tests for reader conditionals in the ClojureCLR reader. What might not be obvious at first glance is that the vectors inside the splicing reader conditional are being wrapped by a surrounding vector.

There isn’t a clear community consensus yet around where to put .cljc files. Two options are to have a single src directory with .clj, .cljs, and .cljc files, or to have separate src/clj, src/cljc, and src/cljs directories.

Before reader conditionals were introduced, the same goal of sharing code between platforms was solved by a Leiningen plugin called cljx. cljx processes files with the .cljx extension and outputs multiple platform specific files to a generated sources directory. These were then read as normal Clojure or ClojureScript files by the Clojure reader. This worked well, but required another piece of tooling to run. cljx was deprecated on June 13 2015 in favour of reader conditionals.

Sente previously used cljx for sharing code between Clojure and ClojureScript. I’ve rewritten the main namespace to use reader conditionals. Notice that we’ve used the splicing reader conditional to splice the vector into the parent :require. Notice also that some of the requires are duplicated between :clj and :cljs.

At the time of writing, there is no way to use .cljc files in versions of Clojure less than 1.7, nor is there any porting mechanism to preprocess .cljc files to output .clj and .cljs files like cljx does. For that reason library maintainers may need to wait for a while until they can safely drop support for older versions of Clojure and adopt reader conditionals.