Repository files navigation

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
• Releases and Dependency Information
• Changelog
• API Index
• Developer Information
• Example Usage
• Differences from LispReader.java
• License

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

For a list of additional features of the reader, readDifferences from LispReader.java

Moreover, by using reader types fromclojure.tools.reader.reader-types, 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:

• YourKit Java Profiler and
• YourKit .NET Profiler.

Latest stable release: 1.5.2

• All Released Versions

• Development Snapshot Versions

clj dependency information:

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

Leiningen dependency information:

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

Maven dependency information:

<dependency>  <groupId>org.clojure</groupId>  <artifactId>tools.reader</artifactId>  <version>1.5.2</version></dependency>

• API index

• GitHub project
• Bug Tracker
• Continuous Integration

To read data structures, functions fromclojure.tools.reader.edn should be used, since those aresafe and don't allow any code execution at all.

Remember that when usingread youneed to use a reader that implementsIPushbackReader such asstring-push-back-reader.

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

(require '[clojure.tools.reader.edn: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 (constantly1)}}"#foo bar");=> 1

To switch from usingclojure.core/read-string toclojure.tools.reader.edn/read-string in your projects, put this in your namespace declaration:

(:refer-clojure:exclude [read read-string])(:use [clojure.tools.reader.edn:only [read read-string]])

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

(require '[clojure.tools.reader:as r]);=> nil(r/read-string"1");=> 1;; WARNING!(r/read-string"#=(+ 1 2)");=> 3(binding [r/*read-eval*false]  (r/read-string"#=(+ 1 2)"))=> ExceptionInfo #= not allowedwhen *read-eval* isfalse

To switch from usingclojure.core/read-string toclojure.tools.reader/read-string in your projects, put this in your namespace declaration:

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

Reader types example usage:

(require '[clojure.tools.reader.reader-types:as t]);=> nil(defreader (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 tounread more chars than the pushback buffer dimension.

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

(defreader (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

There are small differences from clojure.lang.LispReader:

• read throws anex-info for almost every exception, whereasclojure.lang.LispReader/read throws aReaderException wrapping the causing exception.
• read is capable of reading literal tags containing periods, fixing#CLJ-1100
• clojure.tools.reader/read checks ifclojure.tools.reader/*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
• clojure.tools.reader/read adds additional line/column info to symbols, vectors and maps when possible
• clojure.tools.reader.reader-types/read-line has an additional arity with which is possible to specify the reader to read from

Copyright © Nicola Mometto, Rich Hickey & contributors.

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