/usr/share/doc/libtools-analyzer-clojure/README.html

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html>
<head>
<title>tools.analyzer</title>
</head>
<body>
<h1>tools.analyzer</h1>

<p>An analyzer for host agnostic Clojure code, written in Clojure and producing AST in EDN.</p>

<p>Timothy Baldridge gave a talk on tools.analyzer[.jvm] at Clojure/West in
March 2014. Video
<a href="https://www.youtube.com/watch?v=KhRQmT22SSg&amp;list=PLZdCLR02grLp__wRg5OTavVj4wefg69hM&amp;index=11">here</a>.</p>

<p>Note that the analyzer in this library should not to be used directly as it lacks any knowledge about host-specific special forms and it should only be considered as a building platform for host-specific analyzers.
Currently the following platform specific analyzers written on top of tools.analyzer exist: <a href="https://github.com/clojure/tools.analyzer.jvm">tools.analyzer.jvm</a>, <a href="https://github.com/clojure/tools.analyzer.js">tools.analyzer.js</a></p>

<ul>
<li><a href="#example-usage">Example Usage</a></li>
<li><a href="#quickref">Quickref</a></li>
<li><a href="#releases-and-dependency-information">Releases and Dependency Information</a></li>
<li><a href="#changelog">Changelog</a></li>
<li><a href="#api-index">API Index</a></li>
<li><a href="#developer-information">Developer Information</a></li>
<li><a href="#license">License</a></li>
</ul>

<h1><a href="http://clojure.github.io/tools.analyzer/spec/quickref.html">Quickref</a></h1>

<h2>Example Usage</h2>

<p><code>clojure.tools.analyzer/analyze</code> will not work out of the box, as it requires a number of entry-points to be set.
Here's what could happen trying to use <code>clojure.tools.analyzer/analyze</code> directly:
<code>clojure
clojure.tools.analyzer&gt; (analyze 'a {})
Attempting to call unbound fn: #'clojure.tools.analyzer/macroexpand-1
  [Thrown class java.lang.IllegalStateException]
</code></p>

<p>At the moment there exist two official analyzers written on top of <a href="https://github.com/clojure/tools.analyzer">tools.analyzer</a>: <a href="https://github.com/clojure/tools.analyzer.jvm">tools.analyzer.jvm</a> for clojure on the JVM and <a href="https://github.com/clojure/tools.analyzer.js">tools.analyzer.js</a> for clojurescript.
We will use <a href="https://github.com/clojure/tools.analyzer.jvm">tools.analyzer.jvm</a> for those examples.</p>

<p>Here's a simplified version of how <code>clojure.tools.analyzer.jvm/analyze</code> is defined:
<code>clojure
(require '[clojure.tools.analyzer :as ana])
(require '[clojure.tools.analyzer.env :as env])
(defn analyze [form env]
  (binding [ana/macroexpand-1 macroexpand-1
            ana/create-var    create-var
            ana/parse         parse
            ana/var?          var?]
       (env/ensure (global-env)
         (run-passes (-analyze form env))))))
</code></p>

<p>Here, <code>-analyze</code> is a multimethod that defaults to <code>ana/analyze</code> and defines analysis methods for the JVM specific special forms, <code>global-env</code> is a function that returns a global environment for the JVM analyzer and <code>run-passes</code> is a function that takes an AST and applies a number of passes to it.</p>

<p>The <code>tools.analyzer.jvm</code> <a href="https://github.com/clojure/tools.analyzer.jvm#example-usage">README</a> contains more examples on how the <code>analyze</code> function works as well as a reference for all the nodes it can return.</p>

<p>One of the most important features of <code>tools.analyzer</code> is the ability to walk generically through the AST nodes, this has been immensely useful to write most of the passes used by the various analyzers.
The <code>tools.analyzer.ast</code> namespace provides a number of functions that implement various generic AST walking strategies.</p>

<p>The <code>children</code> function returns a vector of the children nodes of the current node (the output has been elided and pretty-printed for clarity):
<code>clojure
clojure.tools.analyzer.jvm&gt; (require '[clojure.tools.analyzer.ast :as ast])
nil
clojure.tools.analyzer.jvm&gt; (ast/children (analyze '(do 1 2 :foo)))
[{:op   :const,
  :id   0,
  :type :number,
  :val  1,
  :form 1,
  ...}
 {:op   :const,
  :id   1,
  :type :number,
  :val  2,
  :form 2,
  ...}
 {:op   :const,
  :id   3,
  :type :keyword,
  :val  :foo,
  :form :foo,
  ...}]
</code></p>

<p>If we want to access a flattened view of all the nodes of an AST, we can use the <code>nodes</code> function:
<code>clojure
clojure.tools.analyzer.jvm&gt; (ast/nodes (analyze '[1 (+ 1 2)]))
({:op        :vector,
  :top-level true,
  :items
  [{:op   :const,
    :type :number,
    :val  1,
    ...}
   {:op     :static-call,
    :class  clojure.lang.Numbers,
    :method add,
    :form   (. clojure.lang.Numbers (add 1 2)),
    :args   [{:op  :const,
              :val 1,
              ...}
             {:op  :const,
              :val 2,
              ...}],
   ...}]
  :form [1 (+ 1 2)],
  ...}
 {:op   :const,
  :type :number,
  :val  1,
  ...}
 {:op    :static-call,
  :class  clojure.lang.Numbers,
  :method add,
  :form   (. clojure.lang.Numbers (add 1 2)),
  :args [{:op  :const,
          :val 1,
          ...}
         {:op  :const,
          :val 2,
          ...}],
  ...}
  ..)
</code></p>

<p>The <code>update-children</code> function takes an AST node and a function and replaces the children nodes of the given node with the result of applying the function to each children node.
<code>clojure
clojure.tools.analyzer.jvm&gt; (ast/update-children (analyze '(do 1 (+ 1 2) :foo))
                               #(assoc % :visited true))
{:op :do
 :statements
 [{:op      :const,
   :val     1,
   :visited true,
   ...}
  {:op      :static-call,
   :class   clojure.lang.Numbers,
   :method  add,
   :visited true,
   :args   [{:op  :const
             :val 1,
             ...}
            {:op  :const,
             :val 2,
             ...}],
   ...}]
 :ret
 {:op      :const,
  :val     :foo,
  :visited true,
  ...},
 ...}
</code>
If it's desiderable to walk all the AST applying a function to all the nodes and the children nodes, one of <code>walk</code>, <code>prewalk</code> or <code>postwalk</code> should be used, read the docstrings of the three functions to understand the differences.
Here's the previous example using <code>prewalk</code> instead of <code>update-children</code>:
<code>clojure
clojure.tools.analyzer.jvm&gt; (ast/prewalk (analyze '(do 1 (+ 1 2) :foo))
                               #(assoc % :visited true))
{:op      :do
 :visited true,
 :statements
 [{:op      :const,
   :val     1,
   :visited true,
   ...}
  {:op      :static-call,
   :class   clojure.lang.Numbers,
   :method  add,
   :visited true,
   :args   [{:op      :const
             :val     1,
             :visited true,
             ...}
            {:op     :const,
             :val     2,
             :visited true,
             ...}],
   ...}]
 :ret
 {:op      :const,
  :val     :foo,
  :visited true,
  ...},
 ...}
</code>
As you can see, this time all the nodes have been marked <code>:visited</code>.</p>

<p>Since version <code>0.6.0</code>, passes can be scheduled automatically using <code>clojure.tools.analyzer.passes/schedule</code> rather than having to compose them and sort out pass dependencies manually, refer to its docstrings and examples from <code>tools.analyzer.jvm</code> for more info.</p>

<h2>SPONSORSHIP</h2>

<ul>
<li>Cognitect (http://cognitect.com/) has sponsored tools.analyzer development (https://groups.google.com/d/msg/clojure/iaP16MHpX0E/EMtnGmOz-rgJ)</li>
<li>Ambrose BS (https://twitter.com/ambrosebs) has sponsored tools.analyzer development in his typed clojure campaign (http://www.indiegogo.com/projects/typed-clojure).</li>
</ul>

<h2>YourKit</h2>

<p>YourKit has given an open source license for their profiler, greatly simplifying the profiling of tools.analyzer performance.</p>

<p>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:</p>

<ul>
<li><a href="http://www.yourkit.com/java/profiler/index.jsp">YourKit Java Profiler</a> and</li>
<li><a href="http://www.yourkit.com/.net/profiler/index.jsp">YourKit .NET Profiler</a>.</li>
</ul>

<h1>Releases and Dependency Information</h1>

<p>Latest stable release: 0.6.7</p>

<ul>
<li><p><a href="http://search.maven.org/#search%7Cgav%7C1%7Cg%3A%22org.clojure%22%20AND%20a%3A%22tools.analyzer%22">All Released Versions</a></p></li>
<li><p><a href="https://oss.sonatype.org/index.html#nexus-search;gav%7Eorg.clojure%7Etools.analyzer%7E%7E%7E">Development Snapshot Versions</a></p></li>
</ul>

<p><a href="https://github.com/technomancy/leiningen">Leiningen</a> dependency information:</p>

<p><code>clojure
[org.clojure/tools.analyzer "0.6.7"]
</code>
<a href="http://maven.apache.org/">Maven</a> dependency information:</p>

<p><code>xml
&lt;dependency&gt;
  &lt;groupId&gt;org.clojure&lt;/groupId&gt;
  &lt;artifactId&gt;tools.analyzer&lt;/artifactId&gt;
  &lt;version&gt;0.6.7&lt;/version&gt;
&lt;/dependency&gt;
</code></p>

<h1><a href="CHANGELOG.md">Changelog</a></h1>

<h1>API Index</h1>

<ul>
<li><a href="http://crossclj.info/doc/org.clojure/tools.analyzer/lastest/index.html">CrossClj Documentation</a></li>
<li><a href="http://clojure.github.io/tools.analyzer">API index</a></li>
</ul>

<h1>Developer Information</h1>

<ul>
<li><p><a href="https://github.com/clojure/tools.analyzer">GitHub project</a></p></li>
<li><p><a href="http://dev.clojure.org/jira/browse/TANAL">Bug Tracker</a></p></li>
<li><p><a href="http://build.clojure.org/job/tools.analyzer/">Continuous Integration</a></p></li>
<li><p><a href="http://build.clojure.org/job/tools.analyzer-test-matrix/">Compatibility Test Matrix</a></p></li>
</ul>

<h2>License</h2>

<p>Copyright © 2013-2015 Nicola Mometto, Rich Hickey &amp; contributors.</p>

<p>Distributed under the Eclipse Public License, the same as Clojure.</p>
</body>
</html>
libtools-analyzer-clojure 0.6.9-1 / usr / share / doc / libtools-analyzer-clojure / README.html
