Skip to content
Clojure reader in Clojure
Clojure HTML
Branch: master
Clone or download
Latest commit 97d5dac Jul 11, 2019
Type Name Latest commit message Commit time
Failed to load latest commit information.
.gitignore project: move to contrib Feb 3, 2013 Correct 1.3.2 release date Jun 20, 2019 Update links in Apr 28, 2019 update Readme Oct 28, 2018
epl.html fix corrupt license file Oct 1, 2013
pom.xml [maven-release-plugin] prepare for next development iteration Oct 26, 2018
project.clj exclude read+string Feb 25, 2018

A complete Clojure reader and an EDN-only reader, works with Clojure versions >= 1.4.0 and Clojurescript >=0.5308 and since version 0.10.0-alpha1

Rationale offers all functionality of the reader from clojure-1.9.0, and more.

For a list of additional features of the reader, read Differences from

Moreover, by using reader types from, if using an IndexingReader, column info is available and both line and column metadata is attached not only to lists, but to symbols, vectors and maps too, when additional debugging info is needed (note that the edn reader doesn't add any line/column metadata at all).


YourKit has given an open source license for their profiler, greatly simplifying the profiling of tools.reader performance.

YourKit is kindly supporting open source projects with its full-featured Java Profiler. YourKit, LLC is the creator of innovative and intelligent tools for profiling Java and .NET applications. Take a look at YourKit's leading software products:

Releases and Dependency Information

Latest stable release: 1.3.2

clj dependency information:

org.clojure/tools.reader {:mvn/version "1.3.2"}

Leiningen dependency information:

[org.clojure/tools.reader "1.3.2"]

Maven dependency information:



API Index

Developer Information

Example Usage

To read data structures, functions from should be used, since those are safe and don't allow any code execution at all.

Remember that when using read you need to use a reader that implements IPushbackReader such as string-push-back-reader.

Note that since no code-execution is permitted, reader literals are also disabled.

(require '[ :as edn])
;=> nil
(edn/read-string "1")
;=> 1
(edn/read-string "#inst \"2010-11-12T13:14:15.666\"")
;=> #inst "2010-11-12T13:14:15.666-00:00"
(let [my-unknown (fn [tag val] {:unknown-tag tag :value val})]
   (edn/read-string {:default my-unknown} "#foo bar"))
;=> {:unknown-tag foo, :value bar}
(edn/read-string {:readers {'foo (constantly 1)}} "#foo bar")
;=> 1

To switch from using clojure.core/read-string to in your projects, put this in your namespace declaration:

(:refer-clojure :exclude [read read-string])
(:use [ :only [read read-string]])

If (and only if) reading from a trusted source, and advanced features that need some level of code-execution during read are needed, functions from should be used.

(require '[ :as r])
;=> nil
(r/read-string "1")
;=> 1
(r/read-string "#=(+ 1 2)")
;=> 3
(binding [r/*read-eval* false]
  (r/read-string "#=(+ 1 2)"))
=> ExceptionInfo #= not allowed when *read-eval* is false

To switch from using clojure.core/read-string to in your projects, put this in your namespace declaration:

(:refer-clojure :exclude [read read-string *default-data-reader-fn* *read-eval* *data-readers*])
(:use [ :only [read read-string *default-data-reader-fn* *read-eval* *data-readers*]])

Reader types example usage:

(require '[ :as t])
;=> nil
(def reader (t/string-push-back-reader "1"))
;=> #'user/reader
(t/read-char reader)
;=> \1
(t/unread reader \a)
;=> \a
(t/peek-char reader)
;=> \a
(t/read-char reader)
;=> \a
(t/read-char reader)
;=> nil

Note that the pushback buffer is of dimension 1 by default, and an exception will be thrown if trying to unread more chars than the pushback buffer dimension.

Every predefined reader type has an additional arity that allows to specify the pushback buffer dimension.

(def reader (t/string-push-back-reader "" 2))
;=> nil
(t/unread reader \a)
;=> \a
(t/unread reader \b)
;=> \b
(t/read-char reader)
;=> \b
(t/read-char reader)
;=> \a
(t/read-char reader)
;=> nil

Differences from

There are small differences from clojure.lang.LispReader:

  • read throws an ex-info for almost every exception, whereas clojure.lang.LispReader/read throws a ReaderException wrapping the causing exception.
  • read is capable of reading literal tags containing periods, fixing #CLJ-1100
  • checks if*alias-map* is bound, if that's the case, aliases will be resolved by querying it (must be a map), otherwhise (ns-aliases *ns*) will be used
  • adds additional line/column info to symbols, vectors and maps when possible
  • has an additional arity with which is possible to specify the reader to read from


Copyright © 2013-2018 Nicola Mometto, Rich Hickey & contributors.

Licensed under the EPL. (See the file epl.html.)

You can’t perform that action at this time.