module Validator

Overview

∠(・.-)―〉 →◎ validator is a Crystal data validation module. Very simple and efficient, all validations return true or false.

Also validator/check (not exposed by default) provides error message handling intended for the end user.

There are 2 main ways to use validator:

• As a simple validator to check rules (eg: email, url, min, max, presence, in, ...) which return a boolean.
• As a more advanced validation system which will check a series of rules and returns all validation errors encountered with custom or standard messages.

By default the validator module expose only Validator and Valid (alias) in the scope:

require "validator"

Valid.email? "contact@example.org"                        # => true
Valid.url? "https://github.com/Nicolab/crystal-validator" # => true
Valid.my_validator? "value to validate", "hello", 42      # => true

An (optional) expressive validation flavor, is available as an alternative. \ Not exposed by default, it must be imported:

require "validator/is"

is :email?, "contact@example.org"                        # => true
is :url?, "https://github.com/Nicolab/crystal-validator" # => true
is :my_validator?, "value to validate", "hello", 42      # => true

# raises an error if the email is not valid
is! :email?, "contact@@example..org" # => Validator::Error

is is a macro, no overhead during the runtime 🚀 By the nature of the macros, you can't pass the validator name dynamically with a variable like that is(validator_name, "my value to validate", arg). But of course you can pass arguments with variables is(:validator_name?, arg1, arg2).

Check

Make a series of checks, with a customized error message for each case.

require "validator/check"

check = Check.new

check("email", "The email is required.", is :absence?, "email", user)

Custom validator

Just add your own method to register a custom validator or to overload an existing validator.

module Validator
  # My custom validator
  def self.my_validator?(value, arg : String, another_arg : Int32) : Bool
    # write here the logic of your validator...
    return true
  end
end

# Call it
puts Valid.my_validator?("value to validate", "hello", 42) # => true

# or with the `is` flavor
puts is :my_validator?, "value to validate", "hello", 42 # => true

Check is a simple and lightweight wrapper, let your imagination run wild to add your logic around it.

Using the custom validator with the validation rules:

require "validator/check"

class Article
  # Mixin
  Check.checkable

  property title : String
  property content : String

  Check.rules(
    content: {
      # Now the custom validator is available
      check: {
        my_validator: {"My validator error message"},
        between:      {"The article content must be between 10 and 20 000 characters", 10, 20_000},
        # ...
      },
    },
  )
end

# Triggered with all data
v, article = Article.check(input_data)

# Triggered with one value
v, content = Article.check_content(input_data["content"]?)

Defined in:

Constant Summary

VERSION = {{ (`shards version \"/media/data/lab/dev/work/projects/nicolab/crystal/crystal-validator/src\"`).chomp.stringify.downcase }}

Class Method Summary

• .absence?(key : String | Symbol, list : NamedTuple) : Bool

  Validates the absence of the value.

• .absence?(key : String | Symbol | Number, list : Hash) : Bool

  Validates the absence of the value.

• .accepted?(value : String) : Bool

  Validates that the value String is the representation of an acceptance.

• .accepted?(value) : Bool

  Validates that the value is the representation of an acceptance.

• .ascii_only?(value : String) : Bool

  Validates that the value String is comprised in its entirety by ASCII characters.

• .ascii_only?(values : Array(String)) : Bool

  Validates that all the String in the values Array are comprised in their entirety by ASCII characters.

• .base64?(value : String) : Bool

  Validates that the value has the format base64.

• .between?(value, min, max) : Bool

  Validates that the value is between (inclusive) min and max.

• .between?(value : String | Array, min : Int, max : Int) : Bool

  Validates that the size of the value (String or Array) is between (inclusive) min and max.

• .domain?(value : String) : Bool
• .email?(value : String) : Bool

  Validates that the value is an email.

• .empty?(value) : Bool

  Validates that the value is empty.

• .ends?(value : String, search : String) : Bool

  Validates that the String value ends with search.

• .ends?(value : String, search : Char) : Bool

  Validates that the String value ends with search.

• .ends?(value : String, search : Regex) : Bool

  Validates that the String value ends with search.

• .eq?(value, another_value) : Bool

  Validates that the value is equal to another_value.

• .gt?(value, another_value) : Bool

  Validates that the value is greater than another_value.

• .gt?(value : String | Array, limit : Int) : Bool

  Validates that the size of the value (String or Array) is greater than limit number.

• .gte?(value, another_value) : Bool

  Validates that the value is equal to or greater than another_value.

• .gte?(value : String | Array, min : Int) : Bool

  Validates that the size of the value (String or Array) is greater than min number.

• .hex?(value : String) : Bool

  Validates that the String value does denote a representation of a hexadecimal string.

• .hex?(value : Bytes) : Bool

  Validates that the Bytes value does denote a representation of a hexadecimal slice of Bytes.

• .hex_color?(value : String) : Bool

  Validates that the String value does denote a representation of a hexadecimal color.

• .in?(value, list : Array) : Bool

  Validates that the (list) contains the value.

• .in?(value : String, str : String) : Bool

  Validates that the (str) String contains the value.

• .in?(key : Symbol | String, list : Hash) : Bool

  Validates that the (list) contains the value.

• .in?(key : Symbol | String, list : NamedTuple) : Bool

  Validates that the (list) contains the value.

• .in?(value, list : Range) : Bool

  Validates that the (list) contains the value.

• .in?(value, list : Tuple) : Bool

  Validates that the (list) contains the value.

• .ip?(value : String) : Bool

  Validates that the value is an IP (IPv4 or IPv6).

• .ipv4?(value : String) : Bool

  Validates that the value is an IPv4.

• .ipv6?(value : String) : Bool

  Validates that the value is an IPv6.

• .json?(value : String, strict : Bool = true) : Bool

  Validates that the value represents a JSON string.

• .jwt?(value : String) : Bool

  Validates that the value is a JSON Web Token.

• .lat?(value : String | Float) : Bool

  Validates that the value is a valid format representation of a geographical latitude.

• .lat_lng?(value : String) : Bool

  Validates that the value is a valid format representation of a geographical position (given in latitude and longitude).

• .lng?(value : String | Float) : Bool

  Validates that the value is a valid format representation of a geographical longitude.

• .lower?(value : String) : Bool

  Validates that the value is in lower case.

• .lt?(value : String | Array, limit : Int) : Bool

  Validates that the size of the value (String or Array) is lesser than limit number.

• .lt?(value, another_value) : Bool

  Validates that the value is lesser than another_value.

• .lte?(value : String | Array, max : Int) : Bool

  Validates that the size of the value (String or Array) is equal or lesser than max number.

• .lte?(value, another_value) : Bool

  Validates that the value is equal to or lesser than another_value.

• .mac_addr?(value : String, no_colons : Bool = false) : Bool

  Validates that the value is a MAC address.

• .magnet_uri?(value : String) : Bool

  Validates that the value is a Magnet URI.

• .match?(value : Number, pattern : Regex) : Bool

  Validates that the value matches the pattern.

• .match?(value : String, pattern : Regex) : Bool

  Validates that the value matches the pattern.

• .max?(value, max) : Bool

  Validates that the value is equal to or lesser than max (inclusive).

• .max?(value : String | Array, max : Int) : Bool

  :ditto: > Based on the size of the String.

• .md5?(value : String) : Bool

  Validates that the value has the format md5.

• .min?(value, min) : Bool

  Validates that the value is equal to or greater than min (inclusive).

• .min?(value : String | Array, min : Int) : Bool

  :ditto: > Based on the size of the String.

• .mongo_id?(value : Bytes) : Bool

  Validates that the Bytes value does denote a representation of a MongoID slice of Bytes.

• .mongo_id?(value : String) : Bool

  Validates that the String value does denote a representation of a MongoID string.

• .not_empty?(value) : Bool

  Validates that the value is not empty.

• .not_in?(value : String, str : String) : Bool

  Validates that the (str) String does not contain the value.

• .not_in?(value, list : Array) : Bool

  Validates that the (list) does not contain the value.

• .not_in?(value, list : Tuple) : Bool

  Validates that the (list) does not contain the value.

• .not_in?(value, list : Range) : Bool

  Validates that the (list) does not contain the value.

• .not_in?(key : Symbol | String, list : NamedTuple) : Bool

  Validates that the (list) does not contain the value.

• .not_in?(key : Symbol | String, list : Hash) : Bool

  Validates that the (list) does not contain the value.

• .not_null?(value) : Bool

  Validates that the value is not null (nil).

• .null?(value) : Bool

  Validates that the value is null (nil).

• .number?(value : String) : Bool

  Validates that the value is a numeric String representation.

• .port?(value : String = "0", min : String = "1", max : String = "65535") : Bool

  Validates that the value is in a valid port range, between (inclusive) 1 / min and 65535 / max.

• .port?(value = 0, min = 1, max = 65535) : Bool

  Validates that the value is in a valid port range, between (inclusive) 1 / min and 65535 / max.

• .presence?(key : String | Symbol, list : NamedTuple) : Bool

  Validates the presence of the value.

• .presence?(key : String | Symbol | Number, list : Hash) : Bool

  Validates the presence of the value.

• .refused?(value) : Bool

  Returns true if the value is the representation of a refusal.

• .refused?(value : String) : Bool

  Validates that the value String is the representation of a refusal.

• .size?(value, size : Array(String))

  Validates that the value is in the size array.

• .size?(value, size : Array(Int))

  Validates that the value is in the size array.

• .size?(value, size : Range)

  Validates that the value is in the size range.

• .size?(value, size : String)

  Validates that the value is equal to the size.

• .size?(value, size : Int)

  Validates that the value is equal to the size.

• .slug?(value : String, min = 1, max = 100) : Bool

  Validates that the value is a slug.

• .starts?(value : String, search : Char) : Bool

  Validates that the String value starts with search.

• .starts?(value : String, search : Regex) : Bool

  Validates that the String value starts with search.

• .starts?(value : String, search : String) : Bool

  Validates that the String value starts with search.

• .time?(value : String) : Bool

  Validates that the value is a time String representation.

• .upper?(value : String) : Bool

  Validates that the value is in upper case.

• .url?(value : String) : Bool

  Validates that the value is a URL.

• .uuid?(value : String, version = 0) : Bool

  Validates that the value is a UUID Versions: 0 (all), 3, 4 and 5.

Class Method Detail

Valid.hex_color? "#fff" => true
Valid.hex_color? "#ffffff" => true