CrossClj

0.2.168 docs

SourceDocs



RECENT
    VARS
    &
    *
    *coll-check-limit*
    *coll-error-limit*
    *compile-asserts*
    *explain-out*
    *fspec-iterations*
    *recursion-limit*
    +
    ->sym
    ?
    abbrev
    accept
    accept-nil?
    accept?
    add-ret
    alt
    alt*
    alt-impl
    alt2
    alts
    amp-impl
    and
    and-preds
    and-spec-impl
    assert
    assert*
    call-valid?
    cat
    cat-impl
    check-asserts
    check-asserts?
    coll-of
    coll-prob
    conform
    conformer
    deep-resolve
    def
    def-impl
    deriv
    describe
    double-in
    dt
    empty-coll
    every
    every-impl
    every-kv
    exercise
    exercise-fn
    explain
    explain-1
    explain-data
    explain-data*
    explain-out
    explain-pred-list
    explain-printer
    explain-str
    fdef
    filter-alt
    form
    fspec
    fspec-impl
    gen
    gensub
    get-spec
    inck
    inst-in
    inst-in-range?
    int-in
    int-in-range?
    invalid?
    keys
    keys*
    macroexpand-check
    map-of
    map-spec-impl
    maybe-impl
    maybe-spec
    merge
    merge-spec-impl
    multi-spec
    multi-spec-impl
    nilable
    nilable-impl
    nonconforming
    noret?
    ns-qualify
    op-describe
    op-explain
    op-unform
    or
    or-spec-impl
    pcat
    pcat*
    preturn
    pvalid?
    re-conform
    re-explain
    re-gen
    recur-limit?
    reg-resolve
    reg-resolve!
    regex-spec-impl
    regex?
    registry
    registry-ref
    rep*
    rep+impl
    rep-impl
    res
    res-kind
    Spec
    spec
    spec-impl
    spec-name
    spec?
    Specize
    specize
    tagged-ret
    the-spec
    tuple
    tuple-impl
    unfn
    unform
    valid?
    validate-fn
    with-gen
    with-name

    « Index of all namespaces of this project

    macro
    (& 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
    (* 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
    Dynamic
    The number of elements validated in a collection spec'ed with 'every'
    
    Dynamic
    The number of errors reported by explain in a collection spec'ed with 'every'
    
    Dynamic
    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.
    Dynamic
    The number of times an anonymous fn specified by fspec will be (generatively) tested during conform
    
    Dynamic
    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
    (+ pred-form)
    Returns a regex op that matches one or more values matching
    pred. Produces a vector of matches
    Private
    (->sym x)
    Returns a symbol from a symbol or var
    
    macro
    (? pred-form)
    Returns a regex op that matches zero or one value matching
    pred. Produces a single value (not a collection) if matched.
    (abbrev form)
    Private
    (accept x)
    Private
    (accept-nil? p)
    Private
    (accept? {:keys [:clojure.spec.alpha/op]})
    Private
    (add-ret p r k)
    macro
    (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
    Private
    (alt* ps ks forms)
    (alt-impl ks ps forms)
    Do not call this directly, use 'alt'
    
    Private
    (alt2 p1 p2)
    Private
    (alts & ps)
    (amp-impl re preds pred-forms)
    Do not call this directly, use '&'
    
    macro
    (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.
    Private
    (and-preds x preds forms)
    (and-spec-impl forms preds gfn)
    Do not call this directly, use 'and'
    
    macro
    (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* spec x)
    Do not call this directly, use 'assert'.
    
    Private
    (call-valid? f specs args)
    macro
    (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.
    (cat-impl ks ps forms)
    Do not call this directly, use 'cat'
    
    (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?)
    Returns the value set by check-asserts.
    
    macro
    (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
    Private
    (coll-prob x kfn kform distinct count min-count max-count path via in)
    (conform spec x)
    Given a spec and a value, returns :clojure.spec.alpha/invalid 
    if value does not match spec, else the (possibly destructured) value.
    macro
    (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.spec.alpha/invalid, and returns a
    spec that uses it as a predicate/conformer. Optionally takes a
    second fn that does unform of result of first
    Private
    (deep-resolve reg k)
    macro
    (def k spec-form)
    Given a namespace-qualified keyword or resolvable symbol k, and a
    spec, spec-name, predicate or regex-op makes an entry in the
    registry mapping k to the spec
    (def-impl k form spec)
    Do not call this directly, use 'def'
    
    Private
    (deriv p x)
    (describe spec)
    returns an abbreviated description of the spec as data
    
    macro
    (double-in & {:keys [infinite? NaN? min max], :or {infinite? true, NaN? true}, :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)
    Private
    (dt pred x form)(dt pred x form cpred?)
    macro
    (every pred & {:keys [into kind count max-count min-count distinct gen-max 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: 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-impl form pred opts)(every-impl form pred {conform-into :into, describe-form :clojure.spec.alpha/describe, :keys [kind :clojure.spec.alpha/kind-form count max-count min-count distinct gen-max :clojure.spec.alpha/kfn :clojure.spec.alpha/cpred conform-keys :clojure.spec.alpha/conform-all], :or {gen-max 20}, :as opts} gfn)
    Do not call this directly, use 'every', 'every-kv', 'coll-of' or 'map-of'
    
    macro
    (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 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 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]. 
    (explain spec x)
    Given a spec and a value that fails to conform, prints an explanation to *out*.
    
    Private
    (explain-1 form pred path via in v)
    (explain-data spec x)
    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-data* spec path via in x)
    (explain-out ed)
    Prints explanation data (per 'explain-data') to *out* using the printer in *explain-out*,
    by default explain-printer.
    Private
    (explain-pred-list forms preds path via in x)
    (explain-printer ed)
    Default printer for explain-data. nil indicates a successful validation.
    
    (explain-str spec x)
    Given a spec and a value that fails to conform, returns an explanation as a string.
    
    macro
    (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.spec.test.alpha/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?)
    Private
    (filter-alt ps ks forms f)
    (form spec)
    returns the spec as data
    
    macro
    (fspec & {:keys [args ret fn gen], :or {ret (quote clojure.core/any?)}})
    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.
    (fspec-impl argspec aform retspec rform fnspec fform gfn)
    Do not call this directly, use 'fspec'
    
    (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)
    Private
    (gensub spec overrides path rmap form)
    (get-spec k)
    Returns spec registered for keyword/symbol/var k, or nil.
    
    Private
    (inck m k)
    macro
    (inst-in start end)
    Returns a spec that validates insts in the range from start
    (inclusive) to end (exclusive).
    (inst-in-range? start end inst)
    Return true if inst at or after start and before end
    
    macro
    (int-in start end)
    Returns a spec that validates fixed precision integers in the
    range from start (inclusive) to end (exclusive).
    (int-in-range? start end val)
    Return true if start <= val, val < end and val is a fixed
    precision integer.
    (invalid? ret)
    tests the validity of a conform return value
    
    macro
    (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.
    macro
    (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}
    Private
    (macroexpand-check v args)
    macro
    (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
    (map-spec-impl {:keys [req-un opt-un keys-pred pred-exprs opt-keys req-specs req req-keys opt-specs pred-forms opt gfn], :as argm})
    Do not call this directly, use 'spec' with a map argument
    
    (maybe-impl p form)
    Do not call this directly, use '?'
    
    Private
    (maybe-spec spec-or-k)
    spec-or-k must be a spec, regex or resolvable kw/sym, else returns nil.
    
    macro
    (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.
    (merge-spec-impl forms preds gfn)
    Do not call this directly, use 'merge'
    
    macro
    (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.
    (multi-spec-impl form mmvar retag)(multi-spec-impl form mmvar retag gfn)
    Do not call this directly, use 'multi-spec'
    
    macro
    (nilable pred)
    returns a spec that accepts nil and values satisfying pred
    
    (nilable-impl form pred gfn)
    Do not call this directly, use 'nilable'
    
    (nonconforming spec)
    takes a spec and returns a spec that has the same properties except
    'conform' returns the original (not the conformed) value. Note, will specize regex ops.
    Private
    (noret? p1 pret)
    Private
    (ns-qualify s)
    Qualify symbol s by resolving it or using the current *ns*.
    
    Private
    (op-describe p)
    Private
    (op-explain form p path via in input)
    Private
    (op-unform p x)
    macro
    (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.
    (or-spec-impl keys forms preds gfn)
    Do not call this directly, use 'or'
    
    Private
    (pcat & ps)
    Private
    (pcat* {[p1 & pr :as ps] :ps, [k1 & kr :as ks] :ks, [f1 & fr :as forms] :forms, ret :ret, rep+ :rep+})
    Private
    (preturn p)
    Private
    (pvalid? pred x)(pvalid? pred x form)
    internal helper function that returns true when x is valid for spec.
    
    Private
    (re-conform p [x & xs :as data])
    Private
    (re-explain path via in re input)
    Private
    (re-gen p overrides path rmap f)
    Private
    (recur-limit? rmap id path k)
    Private
    (reg-resolve k)
    returns the spec/regex at end of alias chain starting with k, nil if not found, k if k not ident
    
    Private
    (reg-resolve! k)
    returns the spec/regex at end of alias chain starting with k, throws if not found, k if k not ident
    
    (regex-spec-impl re gfn)
    Do not call this directly, use 'spec' with a regex op argument
    
    (regex? x)
    returns x if x is a (clojure.spec) regex op, else logical false
    
    (registry)
    returns the registry map, prefer 'get-spec' to lookup a spec by name
    
    Private
    (rep* p1 p2 ret splice form)
    (rep+impl form p)
    Do not call this directly, use '+'
    
    (rep-impl form p)
    Do not call this directly, use '*'
    
    Private
    (res form)
    Private
    (res-kind opts)
    protocol
    (conform* spec x)
    (describe* spec)
    (explain* spec path via in x)
    (gen* spec overrides path rmap)
    (unform* spec y)
    (with-gen* spec gfn)
    macro
    (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.
    (spec-impl form pred gfn cpred?)(spec-impl form pred gfn cpred? unc)
    Do not call this directly, use 'spec'
    
    Private
    (spec-name spec)
    (spec? x)
    returns x if x is a spec object, else logical false
    
    protocol
    (specize* _)(specize* _ form)
    Private
    (specize s)(specize s form)
    Private
    (tagged-ret tag ret)
    Private
    (the-spec spec-or-k)
    spec-or-k must be a spec, regex or kw/sym, else returns nil. Throws if unresolvable kw/sym
    
    macro
    (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.
    (tuple-impl forms preds)(tuple-impl forms preds gfn)
    Do not call this directly, use 'tuple'
    
    Private
    (unfn expr)
    (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.
    (valid? spec x)(valid? spec x form)
    Helper function that returns true when x is valid for spec.
    
    Private
    (validate-fn f specs iters)
    returns f if valid, else smallest
    
    (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
    
    Private
    (with-name spec name)