API for cljs.spec - clojurescript


Full namespace name: cljs.spec

Overview





Public Variables and Functions



&

macro
Usage: (& re & preds)
takes a regex op re, and predicates. Returns a regex-op that consumes
input as per re but subjects the resulting value to the
conjunction of the predicates, and any conforming they might perform.

    
    
    
  


*

macro
Usage: (* pred-form)
Returns a regex op that matches zero or more values matching
pred. Produces a vector of matches iff there is at least one match

    
    
    
  


+

macro
Usage: (+ pred-form)
Returns a regex op that matches one or more values matching
pred. Produces a vector of matches

    
    
    
  


?

macro
Usage: (? pred-form)
Returns a regex op that matches zero or one value matching
pred. Produces a single value (not a collection) if matched.

    
    
    
  


alt

macro
Usage: (alt & key-pred-forms)
Takes key+pred pairs, e.g.

(s/alt :even even? :small #(< % 42))

Returns a regex op that returns a map entry containing the key of the
first matching pred and the corresponding value. Thus the
'key' and 'val' functions can be used to refer generically to the
components of the tagged return.

    
    
    
  


and

macro
Usage: (and & pred-forms)
Takes predicate/spec-forms, e.g.

(s/and even? #(< % 42))

Returns a spec that returns the conformed value. Successive
conformed values propagate through rest of predicates.

    
    
    
  


cat

macro
Usage: (cat & key-pred-forms)
Takes key+pred pairs, e.g.

(s/cat :e even? :o odd?)

Returns a regex op that matches (all) values in sequence, returning a map
containing the keys of each pred and the corresponding value.

    
    
    
  


coll-of

macro
Usage: (coll-of pred & opts)
Returns a spec for a collection of items satisfying pred. Unlike
generator will fill an empty init-coll.

Same options as 'every'. conform will produce a collection
corresponding to :into if supplied, else will match the input collection,
avoiding rebuilding when possible.

Same options as 'every'.

See also - every, map-of

    
    
    
  


conformer

macro
Usage: (conformer f)
       (conformer f unf)
takes a predicate function with the semantics of conform i.e. it should return either a
(possibly converted) value or :cljs.spec/invalid, and returns a
spec that uses it as a predicate/conformer. Optionally takes a
second fn that does unform of result of first

    
    
    
  


def

macro
Usage: (def k spec-form)
Given a namespace-qualified keyword or resolveable symbol k, and a spec,
spec-name, predicate or regex-op makes an entry in the registry mapping k to
the spec

    
    
    
  


every

macro
Usage: (every pred & {:keys [into kind count max-count min-count distinct gen-max gen-into gen], :as opts})
takes a pred and validates collection elements against that pred.

Note that 'every' does not do exhaustive checking, rather it samples
*coll-check-limit* elements. Nor (as a result) does it do any
conforming of elements. 'explain' will report at most *coll-error-limit*
problems.  Thus 'every' should be suitable for potentially large
collections.

Takes several kwargs options that further constrain the collection:

:kind - a pred/spec that the collection type must satisfy, e.g. vector?
        (default nil) Note that if :kind is specified and :into is
        not, this pred must generate in order for every to generate.
:count - specifies coll has exactly this count (default nil)
:min-count, :max-count - coll has count (<= min-count count max-count) (defaults nil)
:distinct - all the elements are distinct (default nil)

And additional args that control gen

:gen-max - the maximum coll size to generate (default 20)
:into - one of [], (), {}, #{} - the default collection to generate into
    (default same as :kind if supplied, else []

Optionally takes :gen generator-fn, which must be a fn of no args that
returns a test.check generator

See also - coll-of, every-kv

    
    
    
  


every-kv

macro
Usage: (every-kv kpred vpred & opts)
like 'every' but takes separate key and val preds and works on associative collections.

Same options as 'every', :into defaults to {}

See also - map-of

    
    
    
  


exercise-fn

macro
Usage: (exercise-fn sym)
       (exercise-fn sym n)
       (exercise-fn sym n fspec)
exercises the fn named by sym (a symbol) by applying it to
n (default 10) generated samples of its args spec. When fspec is
supplied its arg spec is used, and sym-or-f can be a fn.  Returns a
sequence of tuples of [args ret]. 

    
    
    
  


fdef

macro
Usage: (fdef fn-sym & specs)
Takes a symbol naming a function, and one or more of the following:

:args A regex spec for the function arguments as they were a list to be
  passed to apply - in this way, a single spec can handle functions with
  multiple arities
:ret A spec for the function's return value
:fn A spec of the relationship between args and ret - the
  value passed is {:args conformed-args :ret conformed-ret} and is
  expected to contain predicates that relate those values

Qualifies fn-sym with resolve, or using *ns* if no resolution found.
Registers an fspec in the global registry, where it can be retrieved
by calling get-spec with the var or full-qualified symbol.

Once registered, function specs are included in doc, checked by
instrument, tested by the runner clojure.spec.test/run-tests, and (if
a macro) used to explain errors during macroexpansion.

Note that :fn specs require the presence of :args and :ret specs to
conform values, and so :fn specs will be ignored if :args or :ret
are missing.

Returns the qualified fn-sym.

For example, to register function specs for the symbol function:

(s/fdef clojure.core/symbol
  :args (s/alt :separate (s/cat :ns string? :n string?)
               :str string?
               :sym symbol?)
  :ret symbol?)

    
    
    
  


fspec

macro
Usage: (fspec & {:keys [args ret fn gen]})
takes :args :ret and (optional) :fn kwargs whose values are preds
and returns a spec whose conform/explain take a fn and validates it
using generative testing. The conformed value is always the fn itself.

See 'fdef' for a single operation that creates an fspec and
registers it, as well as a full description of :args, :ret and :fn

fspecs can generate functions that validate the arguments and
fabricate a return value compliant with the :ret spec, ignoring
the :fn spec if present.

Optionally takes :gen generator-fn, which must be a fn of no args
that returns a test.check generator.

    
    
    
  


inst-in

macro
Usage: (inst-in start end)
Returns a spec that validates insts in the range from start
(inclusive) to end (exclusive).

    
    
    
  


instrument

macro
Usage: (instrument v)
Instruments the var at v, a var or symbol, to check specs
registered with fdef. Wraps the fn at v to check :args
spec, if it exist, throwing an ex-info with explain-data if a
check fails. Idempotent.

    
    
    
  


instrument-all

macro
Usage: (instrument-all)
Call instrument for all speced-vars. Idempotent.

    
    
    
  


instrument-ns

macro
Usage: (instrument-ns & ns-syms)
Call instrument for all speced-vars in namespaces named
by ns-syms. Idempotent.

    
    
    
  


int-in

macro
Usage: (int-in start end)
Returns a spec that validates longs in the range from start
(inclusive) to end (exclusive).

    
    
    
  


keys

macro
Usage: (keys & {:keys [req req-un opt opt-un gen]})
Creates and returns a map validating spec. :req and :opt are both
vectors of namespaced-qualified keywords. The validator will ensure
the :req keys are present. The :opt keys serve as documentation and
may be used by the generator.

The :req key vector supports 'and' and 'or' for key groups:

(s/keys :req [::x ::y (or ::secret (and ::user ::pwd))] :opt [::z])

There are also -un versions of :req and :opt. These allow
you to connect unqualified keys to specs.  In each case, fully
qualfied keywords are passed, which name the specs, but unqualified
keys (with the same name component) are expected and checked at
conform-time, and generated during gen:

(s/keys :req-un [:my.ns/x :my.ns/y])

The above says keys :x and :y are required, and will be validated
and generated by specs (if they exist) named :my.ns/x :my.ns/y
respectively.

In addition, the values of *all* namespace-qualified keys will be validated
(and possibly destructured) by any registered specs. Note: there is
no support for inline value specification, by design.

Optionally takes :gen generator-fn, which must be a fn of no args that
returns a test.check generator.

    
    
    
  


keys*

macro
Usage: (keys* & kspecs)
takes the same arguments as spec/keys and returns a regex op that matches sequences of key/values,
converts them into a map, and conforms that map with a corresponding
spec/keys call:

user=> (s/conform (s/keys :req-un [::a ::c]) {:a 1 :c 2})
{:a 1, :c 2}
user=> (s/conform (s/keys* :req-un [::a ::c]) [:a 1 :c 2])
{:a 1, :c 2}

the resulting regex op can be composed into a larger regex:

user=> (s/conform (s/cat :i1 integer? :m (s/keys* :req-un [::a ::c]) :i2 integer?) [42 :a 1 :c 2 :d 4 99])
{:i1 42, :m {:a 1, :c 2, :d 4}, :i2 99}

    
    
    
  


map-of

macro
Usage: (map-of kpred vpred & opts)
Returns a spec for a map whose keys satisfy kpred and vals satisfy
vpred. Unlike 'every-kv', map-of will exhaustively conform every
value.

Same options as 'every', :kind defaults to map?, with the addition of:

:conform-keys - conform keys as well as values (default false)

See also - every-kv

    
    
    
  


merge

macro
Usage: (merge & pred-forms)
Takes map-validating specs (e.g. 'keys' specs) and
returns a spec that returns a conformed map satisfying all of the
specs.  Successive conformed values propagate through rest of
predicates. Unlike 'and', merge can generate maps satisfying the
union of the predicates.

    
    
    
  


multi-spec

macro
Usage: (multi-spec mm retag)
Takes the name of a spec/predicate-returning multimethod and a
tag-restoring keyword or fn (retag).  Returns a spec that when
conforming or explaining data will pass it to the multimethod to get
an appropriate spec. You can e.g. use multi-spec to dynamically and
extensibly associate specs with 'tagged' data (i.e. data where one
of the fields indicates the shape of the rest of the structure).

(defmulti mspec :tag)

The methods should ignore their argument and return a predicate/spec:
(defmethod mspec :int [_] (s/keys :req-un [::tag ::i]))

retag is used during generation to retag generated values with
matching tags. retag can either be a keyword, at which key the
dispatch-tag will be assoc'ed, or a fn of generated value and
dispatch-tag that should return an appropriately retagged value.

Note that because the tags themselves comprise an open set,
the tag key spec cannot enumerate the values, but can e.g.
test for keyword?.

Note also that the dispatch values of the multimethod will be
included in the path, i.e. in reporting and gen overrides, even
though those values are not evident in the spec.

    
    
    
  


nilable

macro
Usage: (nilable pred)
returns a spec that accepts nil and values satisfiying pred

    
    
    
  


or

macro
Usage: (or & key-pred-forms)
Takes key+pred pairs, e.g.

(s/or :even even? :small #(< % 42))

Returns a destructuring spec that returns a map entry containing the
key of the first matching pred and the corresponding value. Thus the
'key' and 'val' functions can be used to refer generically to the
components of the tagged return.

    
    
    
  


spec

macro
Usage: (spec form & {:keys [gen]})
Takes a single predicate form, e.g. can be the name of a predicate,
like even?, or a fn literal like #(< % 42). Note that it is not
generally necessary to wrap predicates in spec when using the rest
of the spec macros, only to attach a unique generator

Can also be passed the result of one of the regex ops -
cat, alt, *, +, ?, in which case it will return a regex-conforming
spec, useful when nesting an independent regex.
---

Optionally takes :gen generator-fn, which must be a fn of no args that
returns a test.check generator.

Returns a spec.

    
    
    
  


speced-vars

macro
Usage: (speced-vars & ns-syms)
Returns the set of vars whose namespace is in ns-syms AND
whose vars have been speced with fdef. If no ns-syms are
specified, return speced vars from all namespaces.

    
    
    
  


tuple

macro
Usage: (tuple & preds)
takes one or more preds and returns a spec for a tuple, a vector
where each element conforms to the corresponding pred. Each element
will be referred to in paths using its ordinal.

    
    
    
  


unstrument

macro
Usage: (unstrument v)
Undoes instrument on the var at v, a var or symbol. Idempotent.

    
    
    
  


unstrument-all

macro
Usage: (unstrument-all)
Call unstrument for all speced-vars. Idempotent

    
    
    
  


unstrument-ns

macro
Usage: (unstrument-ns & ns-syms)
Call unstrument for all speced-vars in namespaces named
by ns-syms. Idempotent.

    
    
    
  


with-instrument-disabled

macro
Usage: (with-instrument-disabled & body)
Disables instrument's checking of calls, within a scope.

    
    
    
  

cljs.spec.impl.gen





Public Variables and Functions



delay

macro
Usage: (delay & body)
given body that returns a generator, returns a
generator that delegates to that, but delays
creation until used.

    
    
    
  

cljs.spec.test





Public Variables and Functions



run-all-tests

macro
Usage: (run-all-tests)
Like clojure.test/run-all-tests, but runs test.check tests
for all speced vars. Prints per-test results to *out*, and
returns a map with :test,:pass,:fail, and :error counts.

    
    
    
  


run-tests

macro
Usage: (run-tests)
       (run-tests & ns-syms)
Like run-all-tests, but scoped to specific namespaces, or to
*ns* if no ns-sym are specified.

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