clojure.alpha.spec - spec-alpha2 0.2.177-SNAPSHOT API documentation (original) (raw)
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
*coll-check-limit*
dynamic var
The number of elements validated in a collection spec'ed with 'every'
*coll-error-limit*
dynamic var
The number of errors reported by explain in a collection spec'ed with 'every'
*compile-asserts*
dynamic var
If true, compiler will enable spec asserts, which are then subject to runtime control via check-asserts? If false, compiler will eliminate all spec assert overhead. See 'assert'.
Initially set to boolean value of clojure.spec.compile-asserts system property. Defaults to true.
*fspec-iterations*
dynamic var
The number of times an anonymous fn specified by fspec will be (generatively) tested during conform
*recursion-limit*
dynamic var
A soft limit on how many times a branching spec (or/alt/*/opt-keys/multi-spec) can be recursed through during generation. After this a non-recursive branch will be chosen.
+
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 int? even? #(< % 42))
Returns a spec that returns the conformed value. Successive conformed values propagate through rest of predicates.
and-
macro
Usage: (and- & pred-forms)
Takes predicate/spec-forms, e.g.
(s/and- (s/cat :i int?) #(pos? (first %)))
Returns a spec that validates all preds on and returns the conformed value of the first pred. Conformed values are NOT propagated through rest of predicates.
assert
macro
Usage: (assert spec x)
spec-checking assert expression. Returns x if x is valid? according to spec, else throws an ex-info with explain-data plus ::failure of :assertion-failed.
Can be disabled at either compile time or runtime:
If compile-asserts is false at compile time, compiles to x. Defaults to value of 'clojure.spec.compile-asserts' system property, or true if not set.
If (check-asserts?) is false at runtime, always returns x. Defaults to value of 'clojure.spec.check-asserts' system property, or false if not set. You can toggle check-asserts? with (check-asserts bool).
assert*
function
Usage: (assert* spec x)
Do not call this directly, use 'assert'.
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.
cats
macro
Usage: (cats & key-pred-forms)
Like s/cat, but constrain to only seqs
catv
macro
Usage: (catv & key-pred-forms)
Like s/cat, but constrain to only vectors
check-asserts
function
Usage: (check-asserts flag)
Enable or disable spec asserts that have been compiled with 'compile-asserts' true. See 'assert'.
Initially set to boolean value of clojure.spec.check-asserts system property. Defaults to false.
check-asserts?
function
Usage: (check-asserts?)
Returns the value set by check-asserts.
coll-of
macro
Usage: (coll-of pred & opts)
Returns a spec for a collection of items satisfying pred. Unlike 'every', coll-of will exhaustively conform every value.
Same options as 'every'. conform will produce a collection corresponding to :into if supplied, else will match the input collection, avoiding rebuilding when possible.
See also - every, map-of
conform
function
Usage: (conform spec x) (conform spec x settings)
Given a spec and a value, returns :clojure.alpha.spec/invalid if value does not match spec, else the (possibly destructured) value.
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 :clojure.alpha.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
create-spec
multimethod
No usage documentation available
Create a spec object from an explicated spec map. This is an extension
point for adding new spec ops. Generally, consumers should instead call
resolve-spec.
def
macro
Usage: (def k spec-form)
Given a namespace-qualified keyword or resolvable symbol k, and a spec-name or symbolic spec, makes an entry in the registry mapping k to the spec. Use nil to remove an entry in the registry for k.
defcompop
macro
Usage: (defcompop op-name doc-string? spec-op preds+)
Defines a new composite spec with op-name and args same as spec-op. The new spec takes the same args as spec-op, and also ensures the preds are satisfied.
defop
macro
Usage: (defop op-name doc-string? opts? [params*] form)
Defines a new spec op with op-name defined by the form. Defines a macro for op-name with docstring that expands to a call to resolve-spec with the explicated form. args are replaced in the form. Creates a create-spec method implementation for op-name that creates a spec whose body is form.
Opts allowed: :gen - takes a no-arg function returning a generator to use
describe
function
Usage: (describe spec)
returns an abbreviated description of the spec as data
double-in
macro
Usage: (double-in & {:keys [infinite? NaN? min max :as m]})
Specs a 64-bit floating point number. Options:
:infinite? - whether +/- infinity allowed (default true) :NaN? - whether NaN allowed (default true) :min - minimum value (inclusive, default none) :max - maximum value (inclusive, default none)
every
macro
Usage: (every pred & {:keys [:clojure.alpha.spec/describe], :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 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: empty coll as generated by :kind pred 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
function
Usage: (exercise spec) (exercise spec n) (exercise spec n overrides)
generates a number (default 10) of values compatible with spec and maps conform over them, returning a sequence of [val conformed-val] tuples. Optionally takes a generator overrides map as per gen
exercise-fn
function
Usage: (exercise-fn sym) (exercise-fn sym n) (exercise-fn sym-or-f 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].
expand-spec
multimethod
No usage documentation available
Create a symbolic spec map from an explicated spec form. This is an
extension point for adding new spec ops. Generally, consumers should
instead call resolve-spec. For anything other than symbolic spec maps,
return the same object unchanged.
explain
function
Usage: (explain spec x) (explain spec x settings)
Given a spec and a value that fails to conform, prints an explanation to out.
explain-data
function
Usage: (explain-data spec x) (explain-data spec x settings)
Given a spec and a value x which ought to conform, returns nil if x conforms, else a map with at least the key ::problems whose value is a collection of problem-maps, where problem-map has at least :path :pred and :val keys describing the predicate and the value that failed at that path.
explain-out
function
Usage: (explain-out ed)
Prints explanation data (per 'explain-data') to out using the printer in explain-out, by default explain-printer.
explain-printer
function
Usage: (explain-printer ed)
Default printer for explain-data. nil indicates a successful validation.
explain-str
function
Usage: (explain-str spec x) (explain-str spec x settings)
Given a spec and a value that fails to conform, returns an explanation as a string.
explicate
function
Usage: (explicate ns-name form)
Return a fully-qualified form given a namespace name context and a form
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 fully-qualified symbol.
Once registered, function specs are included in doc, checked by instrument, tested by the runner clojure.alpha.spec.test/check, 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?)
form
function
Usage: (form spec)
returns the spec as data
fspec
macro
Usage: (fspec & opts)
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.
gen
function
Usage: (gen spec) (gen spec overrides)
Given a spec, returns the generator for it, or throws if none can be constructed. Optionally an overrides map can be provided which should map spec names or paths (vectors of keywords) to no-arg generator-creating fns. These will be used instead of the generators at those names/paths. Note that parent generator (in the spec or overrides map) will supersede those of any subtrees. A generator for a regex op must always return a sequential collection (i.e. a generator for s/? should return either an empty sequence/vector or a sequence/vector with one item in it)
get-spec
function
Usage: (get-spec k)
Returns spec registered for keyword/symbol/var k, or nil.
inst-in
macro
Usage: (inst-in start end)
Returns a spec that validates insts in the range from start (inclusive) to end (exclusive).
inst-in-range?
function
Usage: (inst-in-range? start end inst)
Return true if inst at or after start and before end
int-in
macro
Usage: (int-in start end)
Returns a spec that validates fixed precision integers in the range from start (inclusive) to end (exclusive).
int-in-range?
function
Usage: (int-in-range? start end val)
Return true if start <= val, val < end and val is a fixed precision integer.
invalid?
function
Usage: (invalid? ret)
tests the validity of a conform return value
keys
macro
Usage: (keys & ks)
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 qualified 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. 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.
nest
macro
Usage: (nest re)
takes a regex op and returns a non-regex op that describes a nested sequential collection.
nilable
macro
Usage: (nilable pred)
returns a spec that accepts nil and values satisfying pred
nonconforming
macro
Usage: (nonconforming spec)
takes a spec and returns a spec that has the same properties except 'conform' returns the original (not the conformed) value.
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.
regex?
function
Usage: (regex? x)
returns x if x is a (clojure.spec) regex op, else logical false
register
function
Usage: (register k s)
Given a namespace-qualified keyword or resolvable symbol k, and a spec-name or spec object, makes an entry in the registry mapping k to the spec. Use nil to remove an entry in the registry for k.
registry
function
Usage: (registry)
Returns the registry map, prefer 'get-spec' to lookup a spec by name
resolve-fn
function
Usage: (resolve-fn fn-form)
Resolves a symbolic function to a function object (predicate).
resolve-spec
function
Usage: (resolve-spec qform)
Returns a spec object given a fully-qualified spec op form, symbol, set, or registry identifier. If needed, use 'explicate' to qualify forms.
schema
macro
Usage: (schema & coll)
Given a literal vector or map schema, expand to a proper explicated spec form, which when evaluated yields a schema object.
schema*
function
Usage: (schema* sform)
Returns a schema object given a fully-qualified schema definition. If needed use 'explicate' to qualify forms.
schema?
function
Usage: (schema? x)
Returns x if x is a schema object, else logical false
select
macro
Usage: (select keyset selection)
Takes a keyset and a selection pattern and returns a spec that validates a map. The keyset specifies what keys may be in the map and the specs to use if the keys are unqualified. The selection pattern indicates what keys must be in the map, and any nested maps.
macro
Usage: (spec s)
Given a function symbol, set of constants, or anonymous function, returns a spec object.
spec?
function
Usage: (spec? x)
returns x if x is a spec object, else logical false
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.
unform
function
Usage: (unform spec x)
Given a spec and a value created by or compliant with a call to 'conform' with the same spec, returns a value with all conform destructuring undone.
union
macro
Usage: (union & schemas)
Takes schemas and unions them, returning a schema object
valid?
function
Usage: (valid? spec x) (valid? spec x settings)
Helper function that returns true when x is valid for spec.
with-gen
macro
Usage: (with-gen spec gen-fn)
Takes a spec and a no-arg, generator-returning fn and returns a version of that spec that uses that generator
Public Variables and Functions
any
function
Usage: (any & args)
Fn returning clojure.test.check.generators/any
any-printable
function
Usage: (any-printable & args)
Fn returning clojure.test.check.generators/any-printable
bind
function
Usage: (bind & args)
Lazy loaded version of clojure.test.check.generators/bind
boolean
function
Usage: (boolean & args)
Fn returning clojure.test.check.generators/boolean
bytes
function
Usage: (bytes & args)
Fn returning clojure.test.check.generators/bytes
cat
function
Usage: (cat & gens)
Returns a generator of a sequence catenated from results of gens, each of which should generate something sequential.
char
function
Usage: (char & args)
Fn returning clojure.test.check.generators/char
char-alpha
function
Usage: (char-alpha & args)
Fn returning clojure.test.check.generators/char-alpha
char-alphanumeric
function
Usage: (char-alphanumeric & args)
Fn returning clojure.test.check.generators/char-alphanumeric
char-ascii
function
Usage: (char-ascii & args)
Fn returning clojure.test.check.generators/char-ascii
choose
function
Usage: (choose & args)
Lazy loaded version of clojure.test.check.generators/choose
delay
macro
Usage: (delay & body)
given body that returns a generator, returns a generator that delegates to that, but delays creation until used.
double
function
Usage: (double & args)
Fn returning clojure.test.check.generators/double
double*
function
Usage: (double* & args)
Lazy loaded version of clojure.test.check.generators/double*
elements
function
Usage: (elements & args)
Lazy loaded version of clojure.test.check.generators/elements
fmap
function
Usage: (fmap & args)
Lazy loaded version of clojure.test.check.generators/fmap
for-all*
function
Usage: (for-all* & args)
Dynamically loaded clojure.test.check.properties/for-all*.
frequency
function
Usage: (frequency & args)
Lazy loaded version of clojure.test.check.generators/frequency
gen-for-name
function
Usage: (gen-for-name s)
Dynamically loads test.check generator named s.
gen-for-pred
function
Usage: (gen-for-pred pred)
Given a predicate, returns a built-in generator if one exists.
generate
function
Usage: (generate generator)
Generate a single value using generator.
hash-map
function
Usage: (hash-map & args)
Lazy loaded version of clojure.test.check.generators/hash-map
int
function
Usage: (int & args)
Fn returning clojure.test.check.generators/int
keyword
function
Usage: (keyword & args)
Fn returning clojure.test.check.generators/keyword
keyword-ns
function
Usage: (keyword-ns & args)
Fn returning clojure.test.check.generators/keyword-ns
large-integer
function
Usage: (large-integer & args)
Fn returning clojure.test.check.generators/large-integer
large-integer*
function
Usage: (large-integer* & args)
Lazy loaded version of clojure.test.check.generators/large-integer*
list
function
Usage: (list & args)
Lazy loaded version of clojure.test.check.generators/list
map
function
Usage: (map & args)
Lazy loaded version of clojure.test.check.generators/map
not-empty
function
Usage: (not-empty & args)
Lazy loaded version of clojure.test.check.generators/not-empty
one-of
function
Usage: (one-of & args)
Lazy loaded version of clojure.test.check.generators/one-of
ratio
function
Usage: (ratio & args)
Fn returning clojure.test.check.generators/ratio
return
function
Usage: (return & args)
Lazy loaded version of clojure.test.check.generators/return
sample
function
Usage: (sample & args)
Lazy loaded version of clojure.test.check.generators/sample
scale
function
Usage: (scale & args)
Lazy loaded version of clojure.test.check.generators/scale
set
function
Usage: (set & args)
Lazy loaded version of clojure.test.check.generators/set
shuffle
function
Usage: (shuffle & args)
Lazy loaded version of clojure.test.check.generators/shuffle
simple-type
function
Usage: (simple-type & args)
Fn returning clojure.test.check.generators/simple-type
simple-type-printable
function
Usage: (simple-type-printable & args)
Fn returning clojure.test.check.generators/simple-type-printable
string
function
Usage: (string & args)
Fn returning clojure.test.check.generators/string
string-alphanumeric
function
Usage: (string-alphanumeric & args)
Fn returning clojure.test.check.generators/string-alphanumeric
string-ascii
function
Usage: (string-ascii & args)
Fn returning clojure.test.check.generators/string-ascii
such-that
function
Usage: (such-that & args)
Lazy loaded version of clojure.test.check.generators/such-that
symbol
function
Usage: (symbol & args)
Fn returning clojure.test.check.generators/symbol
symbol-ns
function
Usage: (symbol-ns & args)
Fn returning clojure.test.check.generators/symbol-ns
tuple
function
Usage: (tuple & args)
Lazy loaded version of clojure.test.check.generators/tuple
uuid
function
Usage: (uuid & args)
Fn returning clojure.test.check.generators/uuid
vector
function
Usage: (vector & args)
Lazy loaded version of clojure.test.check.generators/vector
vector-distinct
function
Usage: (vector-distinct & args)
Lazy loaded version of clojure.test.check.generators/vector-distinct
vector-distinct-by
function
Usage: (vector-distinct-by & args)
Lazy loaded version of clojure.test.check.generators/vector-distinct-by