API for clojure.tools.analyzer - Analyzer for Clojure code 0.6.1 (in development)


Full namespace name: clojure.tools.analyzer

Overview

Analyzer for clojure code, host agnostic.

Entry point:
* analyze

Platform implementers must provide dynamic bindings for:
* macroexpand-1
* parse
* create-var
* var?

Setting up the global env is also required, see clojure.tools.analyzer.env

See clojure.tools.analyzer.core-test for an example on how to setup the analyzer.

Public Variables and Functions



-parse

multimethod
No usage documentation available
Takes a form and an env map and dispatches on the head of the form, that is
a special form.
Source


analyze

function
Usage: (analyze form env)
Given a form to analyze and an environment, a map containing:
* :locals     a map from binding symbol to AST of the binding value
* :context    a keyword describing the form's context from the :ctx/* hierarchy.
 ** :ctx/return    the form is in return position
 ** :ctx/statement the return value of the form is not needed
 ** :ctx/expr      the form is an expression, it's value is used
 Derived from :ctx/expr
 ** :ctx.invoke/target  the form is an expression that is invoked as a function
 ** :ctx.invoke/param   the form is an expression used as parameter in a function call
* :ns         a symbol representing the current namespace of the form to be
              analyzed

returns an AST for that form.

Every node in the AST is a map that is *guaranteed* to have the following keys:
* :op   a keyword describing the AST node
* :form the form represented by the AST node
* :env  the environment map of the AST node

Additionaly if the AST node contains sub-nodes, it is guaranteed to have:
* :children a vector of the keys of the AST node mapping to the sub-nodes,
            ordered, when that makes sense

It is considered a node either the top-level node (marked with :top-level true)
or a node that can be reached via :children; if a node contains a node-like
map that is not reachable by :children, there's no guarantee that such a map
will contain the guaranteed keys.
Source


analyze-form

dynamic multimethod
No usage documentation available
Like analyze, but does not mark the form with :top-level true
Source


analyze-in-env

function
Usage: (analyze-in-env env)
Takes an env map and returns a function that analyzes a form in that env
Source


create-var

dynamic function
Usage: (create-var sym env)
Creates a var for sym and returns it
Source


empty-env

function
Usage: (empty-env)
Returns an empty env
Source


macroexpand

function
Usage: (macroexpand form env)
Repeatedly calls macroexpand-1 on form until it no longer
represents a macro form, then returns it.
Source


macroexpand-1

dynamic function
Usage: (macroexpand-1 form env)
If form represents a macro form, returns its expansion,
else returns form.
Source


parse

dynamic function
Usage: (parse [op & args] env)
Multimethod that dispatches on op, should default to -parse
Source


specials

var

    
Set of special forms common to every clojure variant
Source


var?

dynamic function
Usage: (var? obj)
Returns true if obj represent a var form as returned by create-var
Source

clojure.tools.analyzer.ast

Utilities for AST walking/updating

Public Variables and Functions



ast->eav

function
Usage: (ast->eav ast)
Returns an EAV representation of the current AST that can be used by
Datomic's Datalog.
Source


children

function
Usage: (children ast)
Return a vector of the children expression of the AST node, if it has any.
The children expressions are kept in order and flattened so that the returning
vector contains only nodes and not vectors of nodes.
Source


children*

function
Usage: (children* {:keys [children], :as ast})
Return a vector of vectors of the children node key and the children expression
of the AST node, if it has any.
The returned vector returns the childrens in the order as they appear in the
:children field of the AST, and the children expressions may be either a node
or a vector of nodes.
Source


cycling

function
Usage: (cycling & fns*)
Combine the given passes in a single pass that will be applieed repeatedly
to the AST until applying it another time will have no effect
Source


nodes

function
Usage: (nodes ast)
Returns a lazy-seq of all the nodes in the given AST, in depth-first pre-order.
Source


postwalk

function
Usage: (postwalk ast f)
       (postwalk ast f reversed?)
Shorthand for (walk ast identity f reversed?)
Source


prewalk

function
Usage: (prewalk ast f)
Shorthand for (walk ast f identity)
Source


update-children

function
Usage: (update-children ast f)
       (update-children ast f reversed?)
Applies `f` to each AST children node, replacing it with the returned value.
If reversed? is not-nil, `pre` and `post` will be applied starting from the last
children of the AST node to the first one.
Source


walk

function
Usage: (walk ast pre post)
       (walk ast pre post reversed?)
Walk the ast applying `pre` when entering the nodes, and `post` when exiting.
Both functions must return a valid node since the returned value will replace
the node in the AST which was given as input to the function.
If reversed? is not-nil, `pre` and `post` will be applied starting from the last
children of the AST node to the first one.
Source

clojure.tools.analyzer.ast.query

Utilities for querying tools.analyzer ASTs with Datomic

Public Variables and Functions



db

function
Usage: (db asts)
Given a list of ASTs, returns a representation of those
that can be used as a database in a Datomic Datalog query
Source


q

function
Usage: (q query asts & inputs)
Execute a Datomic Datalog query against the ASTs.
The first input is always assumed to be an AST database, if more
are required, it's required to call `db` on them.
`unfold-expression-clauses` is automatically applied to the
query.
Source


query-map

function
Usage: (query-map query)
Transoforms a Datomic query from its vector representation to its map one.
If the given query is already in its map representation, the original query
is returned.
Source


resolve-calls

function
Usage: (resolve-calls query)
Automatically replace fn name symbols in expression clauses with
their namespace qualified one if the symbol can be resolved in the
current namespace.
Source


unfold-expression-clauses

function
Usage: (unfold-expression-clauses query)
Given a Datomic query, walk the :where clauses searching for
expression clauses with nested calls, unnesting those calls.

E.g {:where [[(inc (dec ?foo)) ?bar] ..] ..} will be transformed in
{:where [[(dec ?foo) ?1234] [(inc ?1234) ?bar] ..] ..}
Source

clojure.tools.analyzer.env





Public Variables and Functions



*env*

dynamic var

    
Global env atom
Required options:
 * :namespaces an atom containing a map from namespace symbol to namespace map,
   the namespace map contains at least the following keys:
  ** :mappings a map of mappings of the namespace, symbol to var/class
  ** :aliases a map of the aliases of the namespace, symbol to symbol
  ** :ns a symbol representing the namespace
Source


deref-env

function
Usage: (deref-env)
Returns the value of the current global env if bound, otherwise
throws an exception.
Source


ensure

macro
Usage: (ensure env & body)
If *env* is not bound it binds it to env before executing the body
Source


with-env

macro
Usage: (with-env env & body)
Binds the global env to env, then executes the body
Source

clojure.tools.analyzer.passes





Public Variables and Functions



schedule

function
Usage: (schedule passes & [opts])
Takes a set of Vars that represent tools.analyzer passes and returns a function
that takes an AST and applies all the passes and their dependencies to the AST,
trying to compose together as many passes as possible to reduce the number of
full tree traversals.

Each pass must have a :pass-info element in its Var's metadata and it must point
to a map with the following parameters (:before, :after, :affects and :state are
optional):
* :after    a set of Vars, the passes that must be run before this pass
* :before   a set of Vars, the passes that must be run after this pass
* :depends  a set of Vars, the passes this pass depends on, implies :after
* :walk     a keyword, one of:
              - :none if the pass does its own tree walking and cannot be composed
                      with other passes
              - :post if the pass requires a postwalk and can be composed with other
                      passes
              - :pre  if the pass requires a prewalk and can be composed with other
                      passes
              - :any  if the pass can be composed with other passes in both a prewalk
                      or a postwalk
* :affects  a set of Vars, this pass must be the last in the same tree traversal that all
            the specified passes must partecipate in
            This pass must take a function as argument and return the actual pass, the
            argument represents the reified tree traversal which the pass can use to
            control a recursive traversal
* :state    a no-arg function that should return the init value of an atom that will be
            passed as the first argument to the pass (the pass will thus take the ast
            as the second parameter), the atom will be the same for the whole tree traversal
            and thus can be used to preserve state across the traversal
An opts map might be provided, valid parameters:
* :debug?   if true, returns a vector of the scheduled passes rather than the concrete
            function
Source

clojure.tools.analyzer.passes.add-binding-atom





Public Variables and Functions



add-binding-atom

function
Usage: (add-binding-atom ast)
       (add-binding-atom state ast)
Adds an atom-backed-map to every local binding,the same
atom will be shared between all occurences of that local.

The atom is put in the :atom field of the node.
Source

clojure.tools.analyzer.passes.collect-closed-overs





Public Variables and Functions



collect-closed-overs

function
Usage: (collect-closed-overs ast)
Attach closed-overs info to the AST as specified by the passes opts:
* :where       set of :op nodes where to attach the closed-overs
* :top-level?  if true attach closed-overs info to the top-level node
Source

clojure.tools.analyzer.passes.constant-lifter





Public Variables and Functions



constant-lift

multimethod
No usage documentation available
If the node represents a collection with no metadata, and every item of that
collection is a literal, transform the node to an equivalent :const node.
Source

clojure.tools.analyzer.passes.elide-meta





Public Variables and Functions



elide-meta

function
Usage: (elide-meta ast)
If elides is not empty and the AST node contains metadata,
dissoc all the keys in elides from the metadata.
Source


elides

dynamic var

    
A map of op keywords to predicate IFns.
The predicate will be used to indicate what map keys should be elided on
metadata of nodes for that op.
:all can be used to indicate what should be elided for every node with
metadata.
Defaults to {:all (set (:elide-meta *compiler-options*))}
Source

clojure.tools.analyzer.passes.emit-form





Public Variables and Functions



-emit-form*

dynamic function
Usage: (-emit-form* {:keys [form], :as ast} opts)
Extension point for custom emit-form implementations, should be rebound
to a multimethod with custom emit-form :opts.
Source


emit-form

function
Usage: (emit-form ast)
       (emit-form ast opts)
Return the form represented by the given AST.
Opts is a set of options, valid options are:
 * :hygienic
Source


emit-hygienic-form

function
Usage: (emit-hygienic-form ast)
Return an hygienic form represented by the given AST
Source

clojure.tools.analyzer.passes.index-vector-nodes





Public Variables and Functions



index-vector-nodes

function
Usage: (index-vector-nodes ast)
Adds an :idx attribute to nodes in a vector children, representing the position
of the node vector.
Source

clojure.tools.analyzer.passes.source-info





Public Variables and Functions



source-info

function
Usage: (source-info ast)
Adds (when avaliable) :line, :column, :end-line, :end-column and :file info to the AST :env
Source

clojure.tools.analyzer.passes.uniquify





Public Variables and Functions



uniquify-locals

function
Usage: (uniquify-locals ast)
Walks the AST performing alpha-conversion on the :name field
of :local/:binding nodes, invalidates :local map in :env field
Source

clojure.tools.analyzer.passes.warn-earmuff





Public Variables and Functions



warn-earmuff

function
Usage: (warn-earmuff ast)
Prints a warning to *err* if the AST node is a :def node and the
var name contains earmuffs but the var is not marked dynamic
Source

clojure.tools.analyzer.utils





Public Variables and Functions



-source-info

function
Usage: (-source-info x env)
Returns the source-info of x
Source


arglist-for-arity

function
Usage: (arglist-for-arity fn argc)
Takes a fn node and an argc and returns the matching arglist
Source


boolean?

function
Usage: (boolean? x)
Returns true if x is a boolean
Source


butlast+last

function
Usage: (butlast+last s)
Returns same value as (juxt butlast last), but slightly more
efficient since it only traverses the input sequence s once, not
twice.
Source


classify

function
Usage: (classify form)
Returns a keyword describing the form type
Source


const-val

function
Usage: (const-val {:keys [op form val expr]})
Returns the value of a constant node (either :quote or :const)
Source


constant?

function
Usage: (constant? var)
Returns true if the var is a const
Source


ctx

function
Usage: (ctx env ctx)
Returns a copy of the passed environment with :context set to ctx
Source


dissoc-env

function
Usage: (dissoc-env ast)
Dissocs :env from the ast
Source


dynamic?

function
Usage: (dynamic? var)
Returns true if the var is dynamic
Source


into!

function
Usage: (into! to from)
Like into, but for transients
Source


macro?

function
Usage: (macro? var)
Returns true if the var maps to a macro
Source


mmerge

var

    
Same as (fn [m1 m2] (merge-with merge m2 m1))
Source


obj?

function
Usage: (obj? x)
Returns true if x implements IObj
Source


private?

function
Usage: (private? var)
Returns true if the var is private
Source


protocol-node?

function
Usage: (protocol-node? var)
Returns true if the var maps to a protocol function
Source


record?

function
Usage: (record? x)
Returns true if x is a record
Source


reference?

function
Usage: (reference? x)
Returns true if x implements IReference
Source


regex?

function
Usage: (regex? x)
Returns true if x is a regex
Source


resolve-ns

function
Usage: (resolve-ns ns-sym {:keys [ns]})
Resolves the ns mapped by the given sym in the env
Source


resolve-var

function
Usage: (resolve-var sym {:keys [ns], :as env})
Resolves the var mapped by the given sym in the env
Source


rseqv

function
Usage: (rseqv v)
Same as (comp vec rseq)
Source


source-info

function
Usage: (source-info m)
Returns the available source-info keys from a map
Source


type?

function
Usage: (type? x)
Returns true if x is a type
Source


update-keys

function
Usage: (update-keys m f)
Applies f to all the keys in the map
Source


update-kv

function
Usage: (update-kv m f)
Applies f to all the keys and vals in the map
Source


update-vals

function
Usage: (update-vals m f)
Applies f to all the vals in the map
Source
Logo & site design by Tom Hickey.
Clojure auto-documentation system by Tom Faulhaber.