validateur.validation

Validateur is a validation library inspired by Ruby's ActiveModel.
Validateur is functional: validators are functions, validation sets are higher-order
functions, validation results are returned as values.

acceptance-of

(acceptance-of attribute & {:keys [allow-nil accept message blank-message message-fn], :or {allow-nil false, accept #{true "true" "1"}, message "must be accepted", blank-message "can't be blank"}})
Returns a function that, when given a map, will validate that the value of the attribute in that map is accepted.
By default, values that are considered accepted: true, "true", "1". Primarily used for validation of data that comes from
Web forms.

Accepted options:

:message (default:"must be accepted"): returned error message
:blank-message (default:"can't be blank"): returned error message if value is not present
:message-fn function to retrieve message with signature (fn [type map attribute & args]).
            type will be :blank or :acceptance, args will be the set of accepted values

:allow-nil (default: false): should nil values be allowed?
:accept (default: #{true, "true", "1"}): pass to use a custom list of values that will be considered accepted

Used in conjunction with validation-set:

(require '[validateur.validation :refer :all])

(validation-set
  (presence-of :name)
  (presence-of :age)
  (acceptance-of :terms))

all-keys-in

(all-keys-in allowed-keys & {:keys [unknown-message], :or {unknown-message "unknown key"}})
Returns a function that, when given a map, will validate that all keys in the map are drawn from a set of allowed keys.

Accepted options:

:unknown-message (default:"unknown key"): returned error message if key is not in allowed set

Used in conjunction with validation-set:

(validation-set
  (all-keys-in #{:church :turing :gödel}))

as-vec

(as-vec arg)

compose-sets

(compose-sets & fns)
Takes a collection of validation-sets and returns a validaton-set function which applies
all given validation-set and merges the results.

Example:

(let [user (validation-set (presence-of :user))
      pass (validation-set (presence-of :pass))
      signup-form (compose-sets user pass)]
  (valid? signup-form {:user "rich" :pass "secret"}))

errors

(errors k m)
Takes in a key (either a single keyword or a nested key) and
returns any errors present in the validation error map for that key,
or nil if none are present.

errors?

exclusion-of

(exclusion-of attribute & {:keys [allow-nil in message blank-message message-fn], :or {allow-nil false, message "must not be one of: ", blank-message "can't be blank"}})
Returns a function that, when given a map, will validate that the value of the attribute in that map is not one of the given.

Accepted options:

:blank-message (default:"can't be blank"): returned error message if value is not present
:message-fn (default nil): function to retrieve message with signature (fn [type map attribute & args]).
                           type will be :blank or :exclusion, args will be the set of invalid values
:message (default: "must not be one of: "): returned error message
                                              (with comma separated list of invalid values appended)
:allow-nil (default: false): should nil values be allowed?
:in (default: nil): a collection of invalid values for the attribute

Used in conjunction with validation-set:

(require '[validateur.validation :refer :all])

(validation-set
  (presence-of :name)
  (presence-of :age)
  (exclusion-of :status :in #{"banned" "non-activated"}))

format-of

(format-of attribute & {:keys [allow-nil allow-blank format message blank-message message-fn], :or {allow-nil false, allow-blank false, message "has incorrect format", blank-message "can't be blank"}})
Returns a function that, when given a map, will validate that the value of the attribute in that map is in the given format.

Accepted options:

:allow-nil (default: false): should nil values be allowed?
:allow-blank (default: false): should blank string values be allowed?
:format (default: nil): a regular expression of the format
:message (default: "has incorrect format"): an error message for invalid values
:blank-message (default:"can't be blank"): returned error message if value is not present
:message-fn (default nil): function to retrieve message with signature (fn [type map attribute & args]).
                           type will be :format or :blank, args will be the applied format

Used in conjunction with validation-set:

(require '[validateur.validation :refer :all])

(validation-set
  (presence-of :username)
  (presence-of :age)
  (format-of :username :format #"[a-zA-Z0-9_]")

inclusion-of

(inclusion-of attribute & {:keys [allow-nil in message blank-message message-fn], :or {allow-nil false, message "must be one of: ", blank-message "can't be blank"}})
Returns a function that, when given a map, will validate that the value of the attribute in that map is one of the given.

Accepted options:

:blank-message (default:"can't be blank"): returned error message if value is not present
:message (default: "must be one of: "): returned error message
                                          (with comma-separated valid values appended)
:message-fn (default:nil): function to retrieve message with signature (fn [type map attribute & args]).
                           type will be :blank or :inclusion, args will be the set of valid values

:allow-nil (default: false): should nil values be allowed?
:in (default: nil): a collection of valid values for the attribute

Used in conjunction with validation-set:

(require '[validateur.validation :refer :all])

(validation-set
  (presence-of :name)
  (presence-of :age)
  (inclusion-of :team :in #{"red" "blue"}))

invalid?

length-of

(length-of attribute & {:keys [allow-nil is within allow-blank blank-message message-fn], :or {allow-nil false, allow-blank false, blank-message "can't be blank"}})
Returns a function that, when given a map, will validate that the value of the attribute in that map is of the given length.

Accepted options:

:allow-nil (default: false): should nil values be allowed?
:allow-blank (default: false): should blank string values be allowed?
:is (default: nil): an exact length, as long
:within (default: nil): a range of lengths
:blank-message (default:"can't be blank"): returned error message if value is not present
:message-fn (default nil): function to retrieve message with signature (fn [type m attribute & args]).
                           type will be :length:is or :length:within, args will be the applied number or range

Used in conjunction with validation-set:

(require '[validateur.validation :refer :all])

(validation-set
  (presence-of :name)
  (presence-of :age)
  (length-of :password :within (range 6 100))

(validation-set
  (presence-of :name)
  (presence-of :age)
  (length-of :zip :is 5)

nest

(nest attr m)
Takes an attribute (either a single key or a vector of keys) and a
validation set and prefixes the keys in the validation set's
error map with that attribute.

nested

(nested attr vset)
Takes an attribute (either a single key or a vector of keys) and a
validation set, and returns a function that will apply the supplied
validation set to the inner value located at `attr`.

numericality-of

(numericality-of attribute & {:keys [allow-nil only-integer gt gte lt lte equal-to odd even messages message-fn], :or {allow-nil false, only-integer false, odd false, even false}})
Returns a function that, when given a map, will validate that the value of the attribute in that map is numerical.

Accepted options:

:messages : a map of type->message to be merge with defaults
:message-fn (default:nil):
            function to retrieve message with signature (fn [type map attribute & args])
            type will be one of [:blank :number :integer  :odd  :even
                                 :equal-to :gt  :gte :lt :lte]
            args will be the numeric constraint if any

:allow-nil (default: false): should nil values be allowed?
:only-integer (default: false): should only integer values be allowed?
:even (default: false): should even values be allowed?
:odd (default: false): should odd values be allowed?
:equal-to: accept only values equal to the given
:gt: accept only values greater than the given
:gte: accept only values greater than or equal to the given
:lt: accept only values less than the given
:lte: accept only values less than or equal to the given

Used in conjunction with validation-set:

(require '[validateur.validation :refer :all])

(validation-set
  (presence-of :name)
  (presence-of :age)
  (numericality-of :age :only-integer true :gte 18))

presence-of

(presence-of attributes & {:keys [message message-fn any], :or {message "can't be blank"}})
Returns a function that, when given a map, will validate presence of the attribute(s) in that map.

Attributes can be given as a set or as a single attribute.
Individual attributes can be vectors and they are treated as arguments to get-in (nested attributes).

Accepted options:
:message (default:"can't be blank"): returned error message
:message-fn (default:nil): function to retrieve message with signature (fn [type map attribute & args])
                           type will be :blank, args will be nil
:any (default:nil): if true, validation succeeds when any attribute from the set is present
                    the default is to require all attributes from the set to be present

Used in conjunction with validation-set:

(require '[validateur.validation :refer :all])

(validation-set
  (presence-of :name)
  (presence-of :age))

Or on its own:

(presence-of #{:name :age})

unnest

(unnest attr m)
Takes an attribute (either a single key or a vector of keys) and a
validation set and returns a new validation set with that
attribute removed from the beginning of any matching internal
attributes. Entries in the validation set that aren't prefixed
with the supplied attribute will be filtered.

valid?

(valid? vsm)(valid? vs m)
Takes a validation set and a map.

Returns true if validation returned no errors, false otherwise

validate-by

(validate-by attr pred & {:keys [message], :or {message "Failed predicate validation."}})
Returns a function that, when given a map, will validate that the
value of the attribute in that map is one of the given.


 Accepted options:

 :message (default: "Failed predicate validation.")

 Used in conjunction with validation-set:

 (require '[validateur.validation :refer :all])

 (validation-set
   (presence-of :name)
   (presence-of :age)
   (validate-by [:user :name] not-empty :message "Username can't be empty!"))

validate-some

(validate-some & validators)
Takes a sequence of validators and returns a validator that returns
the result of the FIRST failing validator, short-circuiting
after. This is helpful when downstream validations call functions
that can't have nil inputs, for example.

Example:

(require '[validateur.validation :refer :all])

(validate-some
  (presence-of :name)
  (validate-by :name not-empty))

validate-when

(validate-when predicate validator)
Returns a function that, when given a map, will run the validator against that map if and
only if the predicate function returns true.  The predicate function will be given the same
map on which the validator may run.

Example:

(require '[validateur.validation :refer :all])

(validate-when #(contains? % :name) (presence-of :name))

validate-with-predicate

(validate-with-predicate attribute predicate & {:keys [message message-fn], :or {message "is invalid"}})
Returns a function that, when given a map, will validate that the predicate returns
true when given the map.

Accepted options:

:message (default: "is invalid"): an error message for invalid values
:message-fn (default:nil): function to retrieve message with signature (fn [map])

Example:

(require '[validateur.validation :refer :all])

(validate-with-predicate :name #(contains? % :name))

validation-set

(validation-set & validators)
Takes a collection of validators and returns a function that, when given a map, will run all
the validators against that map and collect all the error messages that are then returned
as a set.

Example:

(require '[validateur.validation :refer :all])

(validation-set
  (presence-of :name)
  (presence-of :age)
  (length-of :password :within (range 6 100))