API for cljs.core - clojurescript


Full namespace name: cljs.core

Overview





Public Variables and Functions



->

macro
Usage: (-> x & forms)
Threads the expr through the forms. Inserts x as the
second item in the first form, making a list of it if it is not a
list already. If there are more forms, inserts the first form as the
second item in second form, etc.

    
    
    
  


->>

macro
Usage: (->> x & forms)
Threads the expr through the forms. Inserts x as the
last item in the first form, making a list of it if it is not a
list already. If there are more forms, inserts the first form as the
last item in second form, etc.

    
    
    
  


..

macro
Usage: (.. x form)
       (.. x form & more)
form => fieldName-symbol or (instanceMethodName-symbol args*)

Expands into a member access (.) of the first member on the first
argument, followed by the next member on the result, etc. For
instance:

(.. System (getProperties) (get "os.name"))

expands to:

(. (. System (getProperties)) (get "os.name"))

but is easier to write, read, and understand.

    
    
    
  


amap

macro
Usage: (amap a idx ret expr)
Maps an expression across an array a, using an index named idx, and
return value named ret, initialized to a clone of a, then setting
each element of ret to the evaluation of expr, returning the new
array ret.

    
    
    
  


and

macro
Usage: (and)
       (and x)
       (and x & next)
Evaluates exprs one at a time, from left to right. If a form
returns logical false (nil or false), and returns that value and
doesn't evaluate any of the other expressions, otherwise it returns
the value of the last expr. (and) returns true.

    
    
    
  


areduce

macro
Usage: (areduce a idx ret init expr)
Reduces an expression across an array a, using an index named idx,
and return value named ret, initialized to init, setting ret to the
evaluation of expr at each step, returning ret.

    
    
    
  


as->

macro
Usage: (as-> expr name & forms)
Binds name to expr, evaluates the first form in the lexical context
of that binding, then binds name to that result, repeating for each
successive form, returning the result of the last form.

    
    
    
  


assert

macro
Usage: (assert x)
       (assert x message)
Evaluates expr and throws an exception if it does not evaluate to
logical true.

    
    
    
  


binding

macro
Usage: (binding bindings & body)
binding => var-symbol init-expr

Creates new bindings for the (already-existing) vars, with the
supplied initial values, executes the exprs in an implicit do, then
re-establishes the bindings that existed before.  The new bindings
are made in parallel (unlike let); all init-exprs are evaluated
before the vars are bound to their new values.

    
    
    
  


case

macro
Usage: (case e & clauses)
Takes an expression, and a set of clauses.

Each clause can take the form of either:

test-constant result-expr

(test-constant1 ... test-constantN)  result-expr

The test-constants are not evaluated. They must be compile-time
literals, and need not be quoted.  If the expression is equal to a
test-constant, the corresponding result-expr is returned. A single
default expression can follow the clauses, and its value will be
returned if no clause matches. If no default expression is provided
and no clause matches, an Error is thrown.

Unlike cond and condp, case does a constant-time dispatch, the
clauses are not considered sequentially.  All manner of constant
expressions are acceptable in case, including numbers, strings,
symbols, keywords, and (ClojureScript) composites thereof. Note that since
lists are used to group multiple constants that map to the same
expression, a vector can be used to match a list if needed. The
test-constants need not be all of the same type.

    
    
    
  


comment

macro
Usage: (comment & body)
Ignores body, yields nil

    
    
    
  


cond

macro
Usage: (cond & clauses)
Takes a set of test/expr pairs. It evaluates each test one at a
time.  If a test returns logical true, cond evaluates and returns
the value of the corresponding expr and doesn't evaluate any of the
other tests or exprs. (cond) returns nil.

    
    
    
  


cond->

macro
Usage: (cond-> expr & clauses)
Takes an expression and a set of test/form pairs. Threads expr (via ->)
through each form for which the corresponding test
expression is true. Note that, unlike cond branching, cond-> threading does
not short circuit after the first true test expression.

    
    
    
  


cond->>

macro
Usage: (cond->> expr & clauses)
Takes an expression and a set of test/form pairs. Threads expr (via ->>)
through each form for which the corresponding test expression
is true.  Note that, unlike cond branching, cond->> threading does not short circuit
after the first true test expression.

    
    
    
  


condp

macro
Usage: (condp pred expr & clauses)
Takes a binary predicate, an expression, and a set of clauses.
Each clause can take the form of either:

test-expr result-expr

test-expr :>> result-fn

Note :>> is an ordinary keyword.

For each clause, (pred test-expr expr) is evaluated. If it returns
logical true, the clause is a match. If a binary clause matches, the
result-expr is returned, if a ternary clause matches, its result-fn,
which must be a unary function, is called with the result of the
predicate as its argument, the result of that call being the return
value of condp. A single default expression can follow the clauses,
and its value will be returned if no clause matches. If no default
expression is provided and no clause matches, an
IllegalArgumentException is thrown.

    Added in clojurescript version 1.0


declare

macro
Usage: (declare & names)
defs the supplied var names with no bindings, useful for making forward declarations.

    
    
    
  


defmacro

macro
Usage: (defmacro name doc-string? attr-map? [params*] body)
       (defmacro name doc-string? attr-map? ([params*] body) + attr-map?)
Like defn, but the resulting function name is declared as a
macro and will be used as a macro by the compiler when it is
called.

    
    
    
  


defmethod

macro
Usage: (defmethod multifn dispatch-val & fn-tail)
Creates and installs a new method of multimethod associated with dispatch-value. 

    
    
    
  


defmulti

macro
Usage: (defmulti mm-name & options)
Creates a new multimethod with the associated dispatch function.
The docstring and attribute-map are optional.

Options are key-value pairs and may be one of:
  :default    the default dispatch value, defaults to :default
  :hierarchy  the isa? hierarchy to use for dispatching
              defaults to the global hierarchy

    
    
    
  


defn

macro
Usage: (defn name doc-string? attr-map? [params*] prepost-map? body)
       (defn name doc-string? attr-map? ([params*] prepost-map? body) + attr-map?)
Same as (def name (core/fn [params* ] exprs*)) or (def
name (core/fn ([params* ] exprs*)+)) with any doc-string or attrs added
to the var metadata. prepost-map defines a map with optional keys
:pre and :post that contain collections of pre or post conditions.

    
    
    
  


defn-

macro
Usage: (defn- name & decls)
same as defn, yielding non-public def

    
    
    
  


defonce

macro
Usage: (defonce x init)
defs name to have the root value of init iff the named var has no root value,
else init is unevaluated

    
    
    
  


defprotocol

macro
Usage: (defprotocol psym & doc+methods)
A protocol is a named set of named methods and their signatures:

(defprotocol AProtocolName
  ;optional doc string
  "A doc string for AProtocol abstraction"

;method signatures
  (bar [this a b] "bar docs")
  (baz [this a] [this a b] [this a b c] "baz docs"))

No implementations are provided. Docs can be specified for the
protocol overall and for each method. The above yields a set of
polymorphic functions and a protocol object. All are
namespace-qualified by the ns enclosing the definition The resulting
functions dispatch on the type of their first argument, which is
required and corresponds to the implicit target object ('this' in
JavaScript parlance). defprotocol is dynamic, has no special compile-time
effect, and defines no new types.

(defprotocol P
  (foo [this])
  (bar-me [this] [this y]))

(deftype Foo [a b c]
  P
  (foo [this] a)
  (bar-me [this] b)
  (bar-me [this y] (+ c y)))

(bar-me (Foo. 1 2 3) 42)
=> 45

(foo
  (let [x 42]
    (reify P
      (foo [this] 17)
      (bar-me [this] x)
      (bar-me [this y] x))))
=> 17

    
    
    
  


defrecord

macro
Usage: (defrecord rsym fields & impls)
(defrecord name [fields*]  options* specs*)

Currently there are no options.

Each spec consists of a protocol or interface name followed by zero
or more method bodies:

protocol-or-Object
(methodName [args*] body)*

The record will have the (immutable) fields named by
fields, which can have type hints. Protocols and methods
are optional. The only methods that can be supplied are those
declared in the protocols.  Note that method bodies are
not closures, the local environment includes only the named fields,
and those fields can be accessed directly.

Method definitions take the form:

(methodname [args*] body)

The argument and return types can be hinted on the arg and
methodname symbols. If not supplied, they will be inferred, so type
hints should be reserved for disambiguation.

Methods should be supplied for all methods of the desired
protocol(s). You can also define overrides for
methods of Object. Note that a parameter must be supplied to
correspond to the target object ('this' in JavaScript parlance). Note also
that recur calls to the method head should *not* pass the target object, it
will be supplied automatically and can not be substituted.

In the method bodies, the (unqualified) name can be used to name the
class (for calls to new, instance? etc).

The type will have implementations of several ClojureScript
protocol generated automatically: IMeta/IWithMeta (metadata support) and
IMap, etc.

In addition, defrecord will define type-and-value-based =,
and will define ClojureScript IHash and IEquiv.

Two constructors will be defined, one taking the designated fields
followed by a metadata map (nil for none) and an extension field
map (nil for none), and one taking only the fields (using nil for
meta and extension fields). Note that the field names __meta
and __extmap are currently reserved and should not be used when
defining your own records.

Given (defrecord TypeName ...), two factory functions will be
defined: ->TypeName, taking positional parameters for the fields,
and map->TypeName, taking a map of keywords to field values.

    
    
    
  


deftype

macro
Usage: (deftype t fields & impls)
(deftype name [fields*]  options* specs*)

Currently there are no options.

Each spec consists of a protocol or interface name followed by zero
or more method bodies:

protocol-or-Object
(methodName [args*] body)*

The type will have the (by default, immutable) fields named by
fields, which can have type hints. Protocols and methods
are optional. The only methods that can be supplied are those
declared in the protocols/interfaces.  Note that method bodies are
not closures, the local environment includes only the named fields,
and those fields can be accessed directly. Fields can be qualified
with the metadata :mutable true at which point (set! afield aval) will be
supported in method bodies. Note well that mutable fields are extremely
difficult to use correctly, and are present only to facilitate the building
of higherlevel constructs, such as ClojureScript's reference types, in
ClojureScript itself. They are for experts only - if the semantics and
implications of :mutable are not immediately apparent to you, you should not
be using them.

Method definitions take the form:

(methodname [args*] body)

The argument and return types can be hinted on the arg and
methodname symbols. If not supplied, they will be inferred, so type
hints should be reserved for disambiguation.

Methods should be supplied for all methods of the desired
protocol(s). You can also define overrides for methods of Object. Note that
a parameter must be supplied to correspond to the target object
('this' in JavaScript parlance). Note also that recur calls to the method
head should *not* pass the target object, it will be supplied
automatically and can not be substituted.

In the method bodies, the (unqualified) name can be used to name the
class (for calls to new, instance? etc).

One constructor will be defined, taking the designated fields.  Note
that the field names __meta and __extmap are currently reserved and
should not be used when defining your own types.

Given (deftype TypeName ...), a factory function called ->TypeName
will be defined, taking positional parameters for the fields

    
    
    
  


delay

macro
Usage: (delay & body)
Takes a body of expressions and yields a Delay object that will
invoke the body only the first time it is forced (with force or deref/@), and
will cache the result and return it on all subsequent force
calls.

    
    
    
  


doseq

macro
Usage: (doseq seq-exprs & body)
Repeatedly executes body (presumably for side-effects) with
bindings and filtering as provided by "for".  Does not retain
the head of the sequence. Returns nil.

    
    
    
  


dotimes

macro
Usage: (dotimes bindings & body)
bindings => name n

Repeatedly executes body (presumably for side-effects) with name
bound to integers from 0 through n-1.

    
    
    
  


doto

macro
Usage: (doto x & forms)
Evaluates x then calls all of the methods and functions with the
value of x supplied at the front of the given arguments.  The forms
are evaluated in order.  Returns x.

(doto (new java.util.HashMap) (.put "a" 1) (.put "b" 2))

    
    
    
  


exists?

macro
Usage: (exists? x)
Return true if argument exists, analogous to usage of typeof operator
in JavaScript.

    
    
    
  


extend-protocol

macro
Usage: (extend-protocol p & specs)
Useful when you want to provide several implementations of the same
protocol all at once. Takes a single protocol and the implementation
of that protocol for one or more types. Expands into calls to
extend-type:

(extend-protocol Protocol
  AType
    (foo [x] ...)
    (bar [x y] ...)
  BType
    (foo [x] ...)
    (bar [x y] ...)
  AClass
    (foo [x] ...)
    (bar [x y] ...)
  nil
    (foo [x] ...)
    (bar [x y] ...))

expands into:

(do
 (clojure.core/extend-type AType Protocol 
   (foo [x] ...) 
   (bar [x y] ...))
 (clojure.core/extend-type BType Protocol 
   (foo [x] ...) 
   (bar [x y] ...))
 (clojure.core/extend-type AClass Protocol 
   (foo [x] ...) 
   (bar [x y] ...))
 (clojure.core/extend-type nil Protocol 
   (foo [x] ...) 
   (bar [x y] ...)))

    
    
    
  


extend-type

macro
Usage: (extend-type type-sym & impls)
Extend a type to a series of protocols. Useful when you are
supplying the definitions explicitly inline. Propagates the
type as a type hint on the first argument of all fns.

type-sym may be

 * default, meaning the definitions will apply for any value,
   unless an extend-type exists for one of the more specific
   cases below.
 * nil, meaning the definitions will apply for the nil value.
 * any of object, boolean, number, string, array, or function,
   indicating the definitions will apply for values of the
   associated base JavaScript types. Note that, for example,
   string should be used instead of js/String.
 * a JavaScript type not covered by the previous list, such
   as js/RegExp.
 * a type defined by deftype or defrecord.

(extend-type MyType
  ICounted
  (-count [c] ...)
  Foo
  (bar [x y] ...)
  (baz ([x] ...) ([x y & zs] ...))

    
    
    
  


fast-path-protocol-partitions-count

var

    
total number of partitions

    
    
    
  


fast-path-protocols

var

    
protocol fqn -> [partition number, bit]

    
    
    
  


fn

macro
Usage: (fn & sigs)
params => positional-params* , or positional-params* & next-param
positional-param => binding-form
next-param => binding-form
name => symbol

Defines a function

    
    
    
  


for

macro
Usage: (for seq-exprs body-expr)
List comprehension. Takes a vector of one or more
 binding-form/collection-expr pairs, each followed by zero or more
 modifiers, and yields a lazy sequence of evaluations of expr.
 Collections are iterated in a nested fashion, rightmost fastest,
 and nested coll-exprs can refer to bindings created in prior
 binding-forms.  Supported modifiers are: :let [binding-form expr ...],
 :while test, :when test.

(take 100 (for [x (range 100000000) y (range 1000000) :while (< y x)]  [x y]))

    
    
    
  


goog-define

macro
Usage: (goog-define sym default)
Defines a var using `goog.define`. Passed default value must be
string, number or boolean.

Default value can be overridden at compile time using the
compiler option `:closure-defines`.

Example:
  (ns your-app.core)
  (goog-define DEBUG! false)
  ;; can be overridden with
  :closure-defines {"your_app.core.DEBUG_BANG_" true}
  or
  :closure-defines {'your-app.core/DEBUG! true}

    
    
    
  


if-let

macro
Usage: (if-let bindings then)
       (if-let bindings then else & oldform)
bindings => binding-form test

If test is true, evaluates then with binding-form bound to the value of 
test, if not, yields else

    
    
    
  


if-not

macro
Usage: (if-not test then)
       (if-not test then else)
Evaluates test. If logical false, evaluates and returns then expr, 
otherwise else expr, if supplied, else nil.

    
    
    
  


if-some

macro
Usage: (if-some bindings then)
       (if-some bindings then else & oldform)
bindings => binding-form test

If test is not nil, evaluates then with binding-form bound to the
value of test, if not, yields else

    
    
    
  


implements?

macro
Usage: (implements? psym x)
EXPERIMENTAL

    
    
    
  


js-comment

macro
Usage: (js-comment comment)
Emit a top-level JavaScript multi-line comment. New lines will create a
new comment line. Comment block will be preceded and followed by a newline

    
    
    
  


js-debugger

macro
Usage: (js-debugger)
Emit JavaScript "debugger;" statement

    
    
    
  


js-inline-comment

macro
Usage: (js-inline-comment comment)
Emit an inline JavaScript comment.

    
    
    
  


lazy-cat

macro
Usage: (lazy-cat & colls)
Expands to code which yields a lazy sequence of the concatenation
of the supplied colls.  Each coll expr is not evaluated until it is
needed.

(lazy-cat xs ys zs) === (concat (lazy-seq xs) (lazy-seq ys) (lazy-seq zs))

    
    
    
  


lazy-seq

macro
Usage: (lazy-seq & body)
Takes a body of expressions that returns an ISeq or nil, and yields
a ISeqable object that will invoke the body only the first time seq
is called, and will cache the result and return it on all subsequent
seq calls.

    
    
    
  


let

macro
Usage: (let bindings & body)
binding => binding-form init-expr

Evaluates the exprs in a lexical context in which the symbols in
the binding-forms are bound to their respective init-exprs or parts
therein.

    
    
    
  


letfn

macro
Usage: (letfn fnspecs & body)
fnspec ==> (fname [params*] exprs) or (fname ([params*] exprs)+)

Takes a vector of function specs and a body, and generates a set of
bindings of functions to their names. All of the names are available
in all of the definitions of the functions, as well as the body.

    
    
    
  


loop

macro
Usage: (loop bindings & body)
Evaluates the exprs in a lexical context in which the symbols in
the binding-forms are bound to their respective init-exprs or parts
therein. Acts as a recur target.

    
    
    
  


macroexpand

macro
Usage: (macroexpand quoted)
Repeatedly calls macroexpand-1 on form until it no longer
represents a macro form, then returns it.  Note neither
macroexpand-1 nor macroexpand expand macros in subforms.

    
    
    
  


macroexpand-1

macro
Usage: (macroexpand-1 quoted)
If form represents a macro form, returns its expansion,
else returns form.

    
    
    
  


memfn

macro
Usage: (memfn name & args)
Expands into code that creates a fn that expects to be passed an
object and any args and calls the named instance method on the
object passing the args. Use when you want to treat a Java method as
a first-class fn. name may be type-hinted with the method receiver's
type in order to avoid reflective calls.

    
    
    
  


ns-interns

macro
Usage: (ns-interns [quote ns])
Returns a map of the intern mappings for the namespace.

    
    
    
  


ns-unmap

macro
Usage: (ns-unmap [quote0 ns] [quote1 sym])
Removes the mappings for the symbol from the namespace.

    
    
    
  


or

macro
Usage: (or)
       (or x)
       (or x & next)
Evaluates exprs one at a time, from left to right. If a form
returns a logical true value, or returns that value and doesn't
evaluate any of the other expressions, otherwise it returns the
value of the last expression. (or) returns nil.

    
    
    
  


reify

macro
Usage: (reify & impls)
reify is a macro with the following structure:

(reify options* specs*)

 Currently there are no options.

 Each spec consists of the protocol name followed by zero
 or more method bodies:

 protocol
 (methodName [args+] body)*

 Methods should be supplied for all methods of the desired
 protocol(s). You can also define overrides for Object methods. Note that
 the first parameter must be supplied to correspond to the target object
 ('this' in JavaScript parlance). Note also that recur calls
 to the method head should *not* pass the target object, it will be supplied
 automatically and can not be substituted.

 recur works to method heads The method bodies of reify are lexical
 closures, and can refer to the surrounding local scope:

 (str (let [f "foo"]
      (reify Object
        (toString [this] f))))
 == "foo"

 (seq (let [f "foo"]
      (reify ISeqable
        (-seq [this] (-seq f)))))
 == (\f \o \o))

 reify always implements IMeta and IWithMeta and transfers meta
 data of the form to the created object.

 (meta ^{:k :v} (reify Object (toString [this] "foo")))
 == {:k :v}

    
    
    
  


satisfies?

macro
Usage: (satisfies? psym x)
Returns true if x satisfies the protocol

    
    
    
  


simple-benchmark

macro
Usage: (simple-benchmark bindings expr iterations & {:keys [print-fn], :or {print-fn (quote println)}})
Runs expr iterations times in the context of a let expression with
the given bindings, then prints out the bindings and the expr
followed by number of iterations and total time. The optional
argument print-fn, defaulting to println, sets function used to
print the result. expr's string representation will be produced
using pr-str in any case.

    
    
    
  


some->

macro
Usage: (some-> expr & forms)
When expr is not nil, threads it into the first form (via ->),
and when that result is not nil, through the next etc

    
    
    
  


some->>

macro
Usage: (some->> expr & forms)
When expr is not nil, threads it into the first form (via ->>),
and when that result is not nil, through the next etc

    
    
    
  


specify

macro
Usage: (specify expr & impls)
Identical to specify! but does not mutate its first argument. The first
argument must be an ICloneable instance.

    
    
    
  


specify!

macro
Usage: (specify! expr & impls)
Identical to reify but mutates its first argument.

    
    
    
  


this-as

macro
Usage: (this-as name & body)
Defines a scope where JavaScript's implicit "this" is bound to the name provided.

    
    
    
  


time

macro
Usage: (time expr)
Evaluates expr and prints the time it took. Returns the value of expr.

    
    
    
  


undefined?

macro
Usage: (undefined? x)
Return true if argument is identical to the JavaScript undefined value.

    
    
    
  


unsafe-cast

macro
Usage: (unsafe-cast t x)
EXPERIMENTAL: Subject to change. Unsafely cast a value to a different type.

    
    
    
  


vswap!

macro
Usage: (vswap! vol f & args)
Non-atomically swaps the value of the volatile as if:
(apply f current-value-of-vol args). Returns the value that
was swapped in.

    
    
    
  


when

macro
Usage: (when test & body)
Evaluates test. If logical true, evaluates body in an implicit do.

    
    
    
  


when-first

macro
Usage: (when-first bindings & body)
bindings => x xs

Roughly the same as (when (seq xs) (let [x (first xs)] body)) but xs is evaluated only once

    
    
    
  


when-let

macro
Usage: (when-let bindings & body)
bindings => binding-form test

When test is true, evaluates body with binding-form bound to the value of test

    
    
    
  


when-not

macro
Usage: (when-not test & body)
Evaluates test. If logical false, evaluates body in an implicit do.

    
    
    
  


when-some

macro
Usage: (when-some bindings & body)
bindings => binding-form test

When test is not nil, evaluates body with binding-form bound to the
value of test

    
    
    
  


while

macro
Usage: (while test & body)
Repeatedly executes body while test expression is true. Presumes
some side-effect will cause test to become false/nil. Returns nil

    
    
    
  


with-out-str

macro
Usage: (with-out-str & body)
Evaluates exprs in a context in which *print-fn* is bound to .append
on a fresh StringBuffer.  Returns the string created by any nested
printing calls.

    
    
    
  


with-redefs

macro
Usage: (with-redefs bindings & body)
binding => var-symbol temp-value-expr

Temporarily redefines vars while executing the body.  The
temp-value-exprs will be evaluated and each resulting value will
replace in parallel the root value of its var.  After the body is
executed, the root values of all the vars will be set back to their
old values. Useful for mocking out functions during testing.

    
    
    
  
Logo & site design by Tom Hickey.
Clojure auto-documentation system by Tom Faulhaber.