CrossClj

1.1.9 docs

SourceDocs



RECENT
    VARS
    ->AnythingSchema
    ->Atomic
    ->Both
    ->ConditionalSchema
    ->CondPre
    ->Constrained
    ->Either
    ->EnumSchema
    ->EqSchema
    ->FnSchema
    ->Isa
    ->MapEntry
    ->Maybe
    ->NamedSchema
    ->One
    ->OptionalKey
    ->Predicate
    ->Protocol
    ->Queue
    ->Record
    ->Recursive
    ->RequiredKey
    Any
    AnythingSchema
    arity
    as-queue
    atom
    atom?
    Atomic
    Bool
    Both
    both
    check
    checker
    cond-pre
    conditional
    ConditionalSchema
    CondPre
    Constrained
    constrained
    Either
    either
    enum
    EnumSchema
    eq
    EqSchema
    explain-input-schema
    explain-kspec
    explicit-schema-key
    find-extra-keys-schema
    fn-schema
    fn-validation?
    fn-validator
    FnSchema
    HasPrecondition
    if
    Inst
    instance-precondition
    Int
    isa
    Isa
    Keyword
    make-fn-schema
    map->AnythingSchema
    map->Atomic
    map->Both
    map->ConditionalSchema
    map->CondPre
    map->Constrained
    map->Either
    map->EnumSchema
    map->EqSchema
    map->FnSchema
    map->Isa
    map->MapEntry
    map->Maybe
    map->NamedSchema
    map->One
    map->OptionalKey
    map->Predicate
    map->Protocol
    map->Queue
    map->Record
    map->Recursive
    map->RequiredKey
    map-elements
    map-entry
    map-entry-ctor
    map-error
    map-explain
    map-spec
    MapEntry
    Maybe
    maybe
    named
    NamedSchema
    Num
    One
    one
    optional
    optional-key
    optional-key?
    OptionalKey
    pair
    parse-sequence-schema
    pred
    Predicate
    Protocol
    protocol-name
    queue
    Queue
    queue?
    Record
    record*
    recursive
    Recursive
    Regex
    required-key
    required-key?
    RequiredKey
    Schema
    schema-name
    schema-ns
    schema-with-name
    schematize-fn
    set-fn-validation!
    set-max-value-length!
    specific-key?
    Str
    Symbol
    Uuid
    validate
    validator
    var-name

    « Index of all namespaces of this project

    A library for data shape definition and validation. A Schema is just Clojure data,
    which can be used to document and validate Clojure functions and data.
    
    For example,
    
    (def FooBar {:foo Keyword :bar [Number]}) ;; a schema
    
    (check FooBar {:foo :k :bar [1.0 2.0 3.0]})
    ==> nil
    
    representing successful validation, but the following all return helpful errors
    describing how the provided data fails to measure up to schema FooBar's standards.
    
    (check FooBar {:bar [1.0 2.0 3.0]})
    ==> {:foo missing-required-key}
    
    (check FooBar {:foo 1 :bar [1.0 2.0 3.0]})
    ==> {:foo (not (keyword? 1))}
    
    (check FooBar {:foo :k :bar [1.0 2.0 3.0] :baz 1})
    ==> {:baz disallowed-key}
    
    Schema lets you describe your leaf values using the Any, Keyword, Symbol, Number,
    String, and Int definitions below, or (in Clojure) you can use arbitrary Java
    classes or primitive casts to describe simple values.
    
    From there, you can build up schemas for complex types using Clojure syntax
    (map literals for maps, set literals for sets, vector literals for sequences,
    with details described below), plus helpers below that provide optional values,
    enumerations, arbitrary predicates, and more.
    
    Assuming you (:require [schema.core :as s :include-macros true]),
    Schema also provides macros for defining records with schematized elements
    (s/defrecord), and named or anonymous functions (s/fn and s/defn) with
    schematized inputs and return values.  In addition to producing better-documented
    records and functions, these macros allow you to retrieve the schema associated
    with the defined record or function.  Moreover, functions include optional
    *validation*, which will throw an error if the inputs or outputs do not
    match the provided schemas:
    
    (s/defrecord FooBar
     [foo :- Int
      bar :- String])
    
    (s/defn quux :- Int
     [foobar :- Foobar
      mogrifier :- Number]
     (* mogrifier (+ (:foo foobar) (Long/parseLong (:bar foobar)))))
    
    (quux (FooBar. 10 "5") 2)
    ==> 30
    
    (fn-schema quux)
    ==> (=> Int (record user.FooBar {:foo Int, :bar java.lang.String}) java.lang.Number)
    
    (s/with-fn-validation (quux (FooBar. 10.2 "5") 2))
    ==> Input to quux does not match schema: [(named {:foo (not (integer? 10.2))} foobar) nil]
    
    As you can see, the preferred syntax for providing type hints to schema's defrecord,
    fn, and defn macros is to follow each element, argument, or function name with a
    :- schema.  Symbols without schemas default to a schema of Any.  In Clojure,
    class (e.g., clojure.lang.String) and primitive schemas (long, double) are also
    propagated to tag metadata to ensure you get the type hinting and primitive
    behavior you ask for.
    
    If you don't like this style, standard Clojure-style typehints are also supported:
    
    (fn-schema (s/fn [^String x]))
    ==> (=> Any java.lang.String)
    
    You can directly type hint a symbol as a class, primitive, or simple
    schema.
    
    See the docstrings of defrecord, fn, and defn for more details about how
    to use these macros.
    (->AnythingSchema _)
    (->Atomic schema)
    (->Both schemas)
    (->ConditionalSchema preds-and-schemas error-symbol)
    (->CondPre schemas)
    (->Constrained schema postcondition post-name)
    (->Either schemas)
    (->EnumSchema vs)
    (->FnSchema output-schema input-schemas)
    (->Isa h parent)
    (->MapEntry key-schema val-schema)
    (->Maybe schema)
    (->NamedSchema schema name)
    (->One schema optional? name)
    (->OptionalKey k)
    (->Predicate p? pred-name)
    (->Queue schema)
    (->Record klass schema)
    (->Recursive derefable)
    (->RequiredKey k)
    Any value, including nil.
    
    Private
    (arity input-schema)
    (as-queue col)
    (atom schema)
    An atom containing a value matching 'schema'.
    
    Private
    (atom? x)
    Boolean true or false
    
    Deprecated
    (both & schemas)
    A value that must satisfy every schema in schemas.
    
    DEPRECATED: prefer 'conditional' with a single condition
    instead, or constrained.
    
    When used with coercion, coerces each schema in sequence.
    (check schema x)
    Return nil if x matches schema; otherwise, returns a value that looks like the
    'bad' parts of x with ValidationErrors at the leaves describing the failures.
    
    If you will be checking many datums, it is much more efficient to create
    a 'checker' once and call it on each of them.
    (checker schema)
    Compile an efficient checker for schema, which returns nil for valid values and
    error descriptions otherwise.
    (cond-pre & schemas)
    A replacement for either that constructs a conditional schema
    based on the schema spec preconditions of the component schemas.
    
    Given a datum, the preconditions for each schema (which typically
    check just the outermost class) are tested against the datum in turn.
    The first schema whose precondition matches is greedily selected,
    and the datum is validated against that schema.  Unlike either,
    a validation failure is final (and there is no backtracking to try
    other schemas that might match).
    
    Thus, cond-pre is only suitable for schemas with mutually exclusive
    preconditions (e.g., s/Int and s/Str).  If this doesn't hold
    (e.g. {:a s/Int} and {:b s/Str}), you must use conditional instead
    and provide an explicit condition for distinguishing the cases.
    
    EXPERIMENTAL
    (conditional & preds-and-schemas)
    Define a conditional schema.  Takes args like cond,
    (conditional pred1 schema1 pred2 schema2 ...),
    and checks the first schemaX where predX (an ordinary Clojure function
    that returns true or false) returns true on the value.
    Unlike cond, throws if the value does not match any condition.
    :else may be used as a final condition in the place of (constantly true).
    More efficient than either, since only one schema must be checked.
    An optional final argument can be passed, a symbol to appear in
    error messages when none of the conditions match.
    (constrained ???)(constrained ???)(constrained ???)
    A schema with an additional post-condition.  Differs from conditional
    with a single schema, in that the predicate checked *after* the main
    schema.  This can lead to better error messages, and is often better
    suited for coercion.
    Deprecated
    (either & schemas)
    A value that must satisfy at least one schema in schemas.
    Note that either does not work properly with coercion
    
    DEPRECATED: prefer conditional or cond-pre
    
    WARNING: either does not work with coercion.  It is also slow and gives
    bad error messages.  Please consider using conditional and friends
    instead; they are more efficient, provide better error messages,
    and work with coercion.
    (enum & vs)
    A value that must be = to some element of vs.
    
    (eq v)
    A value that must be (= v).
    
    (explain-input-schema input-schema)
    Private
    (explain-kspec kspec)
    (explicit-schema-key ks)
    (find-extra-keys-schema map-schema)
    (fn-schema f)
    Produce the schema for a function defined with s/fn or s/defn.
    
    (fn-validation?)
    Get the current global schema validation setting.
    
    A var that can be rebound to a function to customize the behavior
    of fn validation. When fn validation is on and fn-validator is
    bound to a function, normal argument and return value checks will
    be substituted with a call to this function with five arguments:
    
      direction   - :input or :output
      fn-name     - a symbol, the function's name
      schema      - the schema for the arglist or the return value
      checker     - a precompiled checker to check a value against
                    the schema
      value       - the actual arglist or return value
    
    The function's return value will be ignored.
    protocol
    (precondition this)
    Return a predicate representing the Precondition for this schema:
    the predicate returns true if the precondition is satisfied.
    (See spec.core for more details)
    (if pred if-schema else-schema)
    if the predicate returns truthy, use the if-schema, otherwise use the else-schema
    
    The local representation of #inst ...
    
    (instance-precondition s klass)
    Any integral number
    
    (isa ???)(isa ???)
    A value that must be a child of parent.
    
    (make-fn-schema output-schema input-schemas)
    A function outputting a value in output schema, whose argument vector must match one of
    input-schemas, each of which should be a sequence schema.
    Currently function schemas are purely descriptive; they validate against any function,
    regardless of actual input and output types.
    (map->AnythingSchema G__20288)
    (map->Atomic G__20491)
    (map->Both G__20468)
    (map->ConditionalSchema G__20398)
    (map->CondPre G__20441)
    (map->Constrained G__20456)
    (map->Either G__20383)
    (map->EnumSchema G__20323)
    (map->EqSchema G__20299)
    (map->FnSchema G__20626)
    (map->Isa G__20310)
    (map->MapEntry G__20522)
    (map->Maybe G__20363)
    (map->NamedSchema G__20373)
    (map->One G__20580)
    (map->OptionalKey G__20509)
    (map->Predicate G__20334)
    (map->Protocol G__20347)
    (map->Queue G__20571)
    (map->Record G__20612)
    (map->Recursive G__20480)
    (map->RequiredKey G__20500)
    Private
    (map-elements this)
    (map-entry key-schema val-schema)
    (map-entry-ctor [k v :as coll])
    Private
    (map-error)
    Private
    (map-explain this)
    Private
    (map-spec this)
    (maybe schema)
    A value that must either be nil or satisfy schema
    
    (named schema name)
    A value that must satisfy schema, and has a name for documentation purposes.
    
    Any number
    
    (one schema name)
    A single required element of a sequence (not repeated, the implicit default)
    
    (optional schema name)
    A single optional element of a sequence (not repeated, the implicit default)
    
    (optional-key k)
    An optional key in a map
    
    (optional-key? ks)
    (pair first-schema first-name second-schema second-name)
    A schema for a pair of schemas and their names
    
    (parse-sequence-schema s)
    (pred ???)(pred ???)
    A value for which p? returns true (and does not throw).
    Optional pred-name can be passed for nicer validation errors.
    (protocol-name protocol)
    (queue x)
    Defines a schema satisfied by instances of clojure.lang.PersistentQueue
    (clj.core/PersistentQueue in ClojureScript) whose values satisfy x.
    (record* klass schema map-constructor)
    (recursive schema)
    Support for (mutually) recursive schemas by passing a var that points to a schema,
    e.g (recursive #'ExampleRecursiveSchema).
    A regular expression
    
    (required-key k)
    A required key in a map
    
    (required-key? ks)
    protocol
    (explain this)
    Expand this schema to a human-readable format suitable for pprinting,
    also expanding class schematas at the leaves.  Example:
    
    user> (s/explain {:a s/Keyword :b [s/Int]} )
    {:a Keyword, :b [Int]}
    (spec this)
    A spec is a record of some type that expresses the structure of this schema
    in a declarative and/or imperative way.  See schema.spec.* for examples.
    (schema-name schema)
    Returns the name of a schema attached via schema-with-name (or defschema).
    
    (schema-ns schema)
    Returns the namespace of a schema attached via defschema.
    
    (schema-with-name schema name)
    Records name in schema's metadata.
    
    (schematize-fn f schema)
    Attach the schema to fn f at runtime, extractable by fn-schema.
    
    (set-fn-validation! on?)
    Globally turn on (or off) schema validation for all s/fn and s/defn instances.
    
    (set-max-value-length! max-length)
    Sets the maximum length of value to be output before it is contracted to a prettier name.
    
    (specific-key? ks)
    Satisfied only by String.
    Is (pred string?) and not js/String in cljs because of keywords.
    The local representation of #uuid ...
    
    (validate schema value)
    Throw an exception if value does not satisfy schema; otherwise, return value.
    If you will be validating many datums, it is much more efficient to create
    a 'validator' once and call it on each of them.
    (validator schema)
    Compile an efficient validator for schema.