Skip to content

Latest commit

 

History

History
162 lines (129 loc) · 6.42 KB

README.md

File metadata and controls

162 lines (129 loc) · 6.42 KB
Raw

tools.analyzer.jvm

An analyzer for Clojure code, written on top of tools.analyzer, providing additional jvm-specific passes.

Note for REPL usage

The AST tools.analyzer.jvm produces contains a lot of redundant information and while having this structure in memory will not require an excessive amount of memory thanks to structural sharing, attempting to print the AST of even a relatively small clojure expression can easily produce a several thousand lines output which might make your REPL irresponsive for several seconds or even crash it. For this reason, when exploring tools.analyzer.jvm ASTs on the REPL, I encourage you to:

  • set *print-length* and *print-level* to a small value, like 10
  • interactively explore the AST structure, inspecting the :children and :op fields of a node and the keys function rather than printing it to see its content

Example Usage

Calling analyze on the form is all it takes to get its AST (the output has been pretty printed for clarity):

user> (require '[clojure.tools.analyzer.jvm :as ana.jvm])
nil
user> (ana.jvm/analyze 1)
{:op        :const,
 :env       {:context :ctx/expr, :locals {}, :ns user},
 :form      1,
 :top-level true,
 :val       1,
 :type      :number,
 :literal?  true,
 :id        0,
 :tag       long,
 :o-tag     long}

To get a clojure form out of an AST, use the emit-form pass:

user> (require '[clojure.tools.analyzer.passes.jvm.emit-form :as e])
nil
user> (e/emit-form (ana.jvm/analyze '(let [a 1] a)))
(let* [a 1] a)

Note that the output will be fully macroexpanded. You can also get an hygienic form back, using the emit-hygienic-form pass:

user> (e/emit-hygienic-form (ana.jvm/analyze '(let [a 1 a a] a)))
(let* [a__#0 1 a__#1 a__#0] a__#1)

As you can see the local names are renamed to resolve shadowing.

The analyze function can take an environment arg (when not provided it uses the default empty-env) which allows for more advanced usages, like injecting locals from an outer scope:

user> (-> '(let [a a] a)
        (ana.jvm/analyze (assoc (ana.jvm/empty-env)
                           :locals '{a {:op    :binding
                                        :name  a
                                        :form  a
                                        :local :let}}))
        e/emit-hygienic-form)
(let* [a__#0 a] a__#0)

There's also an analyze+eval function that, as the name suggests, evaluates the form after its analysis and stores the resulting value in the :result field of the AST, this function should be used when analyzing multiple forms, as the analysis of a clojure form might require the evaluation of a previous one to make sense.

This would not work using analyze but works fine when using analyze+eval:

user> (ana.jvm/analyze+eval '(defmacro x []))
{:op        :do,
 :top-level true,
 :form      (do (clojure.core/defn x ([&form &env])) (. (var x) (setMacro)) (var x)),
 ... ,
 :result    #'user/x}
user> (ana.jvm/analyze+eval '(x))
{:op        :const,
 :env       {:context :ctx/expr, :locals {}, :ns user},
 :form      nil,
 :top-level true,
 :val       nil,
 :type      :nil,
 :literal?  true,
 :tag       java.lang.Object,
 :o-tag     java.lang.Object,
 :result    nil}

To analyze a whole namespace, use analyze-ns which behaves like analyze+eval and puts the ASTs for each analyzed form in a vector, in order.

user> (ana.jvm/analyze-ns 'clojure.string)
[{:op        :do,
  :result    nil,
  :top-level true,
  :form      (do (clojure.core/in-ns (quote clojure.string)) ..),
  ...}
..]

AST Quickref

Note that the quickref refers to the last stable release of t.a.jvm and might not be valid for the current SNAPSHOT version or for previous ones. Note also that the documented node fields refer to the output of t.a.jvm/analyze running the default passes and using the default configuration.

SPONSORSHIP

YourKit

YourKit has given an open source license for their profiler, greatly simplifying the profiling of tools.analyzer.jvm 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.0

Leiningen dependency information:

[org.clojure/tools.analyzer.jvm "1.3.0"]

Maven dependency information:

<dependency>
  <groupId>org.clojure</groupId>
  <artifactId>tools.analyzer.jvm</artifactId>
  <version>1.3.0</version>
</dependency>

Changelog

API Index

Developer Information

License

Copyright © Nicola Mometto, Rich Hickey & contributors.

Distributed under the Eclipse Public License, the same as Clojure.