This is the clavier Reference Manual, generated automatically by Declt version 4.0 beta 2 "William Riker" on Sun Jun 15 04:54:05 2025 GMT+0.
The main system appears first, followed by any subsystem dependency.
clavierClavier: A Common Lisp validation library
Mariano Montone
MIT
Clavier
———-
[](http://quickdocs.org/clavier/)
[](./LICENSE)
*Clavier* is a general purpose validation library for Common Lisp.
Install
——-
Through Quicklisp:
“‘lisp
(ql:quickload :clavier)
“‘
Getting started
—————
Validators are class instances that validate the arguments passed to the ‘validate‘ function:
“‘lisp
(let ((validator (make-instance ’equal-to-validator :object 22)))
(validate validator 22 :error-p t))
;=> T
“‘
If the validator succeeds, the validate function returns ‘T‘. If it fails, the validate function either signals a validation error, or returns ‘NIL‘ and a validation message depending on the value of the ‘:error-p‘ argument.
“‘lisp
(let ((validator (make-instance ’equal-to-validator :object 22)))
(validate validator 33 :error-p nil))
;=>
;NIL
;"33 is not equal to 22"
“‘
Validators are implemented as funcallable classes. So, alternatively to using the ‘validate‘ function, it is possible to just funcall the validator, like this:
“‘lisp
(let ((validator (make-instance ’equal-to-validator :object 22)))
(funcall validator 22 :error-p t))
;=> T
“‘
## Validation expressions
It is possible to create validators with a more convenient syntax. Each validator provides a builder function. For instance, and equal-to-validator can be built like this:
“‘lisp
(funcall (== 100) 100) ;=> T
(funcall (== 100) 99) ;=> NIL
“‘
## Validators composition
This allows to compose validators, using ‘==‘, ‘~=‘, ‘&&‘, ‘||‘ as the composition operands:
“‘lisp
(let ((validator (|| (&& (greater-than 20)
(less-than 30))
(|| (&& (greater-than 1)
(less-than 10))
(== 100)))))
(funcall validator 5))
“‘
For example, this is how to accept a blank object, but validate it if it isn’t blank:
~~~lisp
(defparameter *validator* (clavier:||
(clavier:blank)
(clavier:&& (clavier:is-a-string)
(clavier:len :min 10)))
"Allow a blank value. When non blank, validate.")
(funcall *validator* "")
;; =>
T
NIL
(funcall *validator* "asdfasdfasdf")
;; =>
T
NIL
(funcall *validator* "asdf")
;; =>
NIL
"Length of \"asdf\" is less than 10"
(funcall *validator* 2)
;; =>
NIL
"2 is not a string"
~~~
## Validators messages
Validators messages to be used when validation fails can be customized passing an ‘:message‘ argument when building the validator
## Catching and collecting validation errors
Validation errors can be controlled globally by setting the dynamic variable ‘*signal-validation-errors*‘, which is ‘NIL‘ by default (no validation errors are signaled by default).
There’s also the ‘with-signal-validation-errors‘ macro to specify whether validation errors should be signaled or not in a dynamic extent. For instance, this code signals a validation error:
“‘lisp
(let ((validator (make-instance ’equal-to-validator :object 22)))
(with-signal-validation-errors (t)
(validate validator 33)))
“‘
Use the ‘collecting-validation-errors‘ macro to collect validation errors happening in a dynamic extent:
“‘lisp
(let ((validator (make-instance ’equal-to-validator :object 22)))
(collecting-validation-errors (errors found-p)
(progn
(funcall validator 33 :error-p t)
(funcall validator 44 :error-p t))
(print errors)
(print found-p)))
;=>
;(#<VALIDATION-ERROR 44: 44 is not equal to 22 {1008A48673}>
; #<VALIDATION-ERROR 33: 33 is not equal to 22 {1008A47EA3}>)
;T
“‘
## Validators list:
This is the list of available validator classes and their shortcut function:
* equal-to-validator ‘(==)‘
* not-equal-to-validator ‘(~=)‘
* blank-validator ‘(blank)‘
* not-blank-validator ‘(not-blank)‘
* true-validator ‘(is-true)‘
* false-validator ‘(is-false)‘
* type-validator ‘(is-a type)‘
* string-validator ‘(is-a-string)‘
* boolean-validator ‘(is-a-boolean)‘
* integer-validator ‘(is-an-integer)‘
* symbol-validator ‘(is-a-symbol)‘
* keyword-validator ‘(is-a-keyword)‘
* list-validator ‘(is-a-list)‘
* function-validator ‘(fn function message)‘
* email-validator ‘(valid-email)‘
* regex-validator ‘(matches-regex regex-pattern)‘
* url-validator ‘(valid-url)‘
* datetime-validator ‘(valid-datetime)‘
* pathname-validator ‘(valid-pathname)‘
* not-validator ‘(~ validator)‘
* and-validator ‘(&& validator1 validator2)‘
* or-validator ‘(|| validator1 validator2)‘
* one-of-validator ‘(one-of options)‘
* less-than-validator ‘(less-than number)‘
* greater-than-validator ‘(greater-than number)‘
* length-validator ‘(len)‘
alexandria (system).
cl-ppcre (system).
closer-mop (system).
chronicity (system).
cl-fad (system).
package.lisp (file).
clavier.lisp (file).
Files are sorted by type and then listed depth-first from the systems components trees.
clavier/clavier.lisppackage.lisp (file).
clavier (system).
∅ (function).
&& (function).
*signal-validation-errors* (special variable).
== (function).
and-validator (class).
blank (function).
blank-validator (class).
boolean-validator (class).
call-with-signal-validation-errors (function).
collecting-validation-errors (macro).
datetime-validator (class).
email-validator (class).
equal-to-validator (class).
false-validator (class).
fn (function).
function-validator (class).
greater-than (function).
greater-than-validator (class).
initialize-instance (method).
integer-validator (class).
is-a (function).
is-a-boolean (function).
is-a-keyword (function).
is-a-list (function).
is-a-string (function).
is-a-symbol (function).
is-an-integer (function).
is-false (function).
is-true (function).
keyword-validator (class).
len (function).
length-validator (class).
less-than (function).
less-than-validator (class).
list-validator (class).
matches-regex (function).
message (method).
message (reader method).
(setf message) (writer method).
not-blank (function).
not-blank-validator (class).
not-equal-to-validator (class).
not-validator (class).
one-of (function).
one-of-validator (class).
or-validator (class).
pathname-validator (class).
print-object (method).
regex-validator (class).
string-validator (class).
symbol-validator (class).
true-validator (class).
type-validator (class).
url-validator (class).
valid-datetime (function).
valid-email (function).
valid-pathname (function).
valid-url (function).
validate (function).
validation-error (function).
validation-error (condition).
validation-error-message (reader method).
validation-error-target (reader method).
validator (reader method).
(setf validator) (writer method).
validator (class).
validator-collection (class).
validator-message (function).
with-signal-validation-errors (macro).
~ (function).
~= (function).
%collecting-validation-errors (function).
%validate (generic function).
absolute-p (reader method).
(setf absolute-p) (writer method).
object (reader method).
object (reader method).
(setf object) (writer method).
(setf object) (writer method).
options (reader method).
(setf options) (writer method).
pathname-type* (reader method).
(setf pathname-type*) (writer method).
probe-p (reader method).
(setf probe-p) (writer method).
valid-email-address-p (function).
valid-url-p (function).
validator-function (reader method).
(setf validator-function) (writer method).
validator-length (reader method).
(setf validator-length) (writer method).
validator-max (reader method).
(setf validator-max) (writer method).
validator-max-message (reader method).
(setf validator-max-message) (writer method).
validator-min (reader method).
(setf validator-min) (writer method).
validator-min-message (reader method).
(setf validator-min-message) (writer method).
validator-number (reader method).
validator-number (reader method).
(setf validator-number) (writer method).
(setf validator-number) (writer method).
validator-regex (reader method).
(setf validator-regex) (writer method).
validator-type (reader method).
(setf validator-type) (writer method).
validators (reader method).
(setf validators) (writer method).
x (reader method).
x (reader method).
(setf x) (writer method).
(setf x) (writer method).
y (reader method).
y (reader method).
(setf y) (writer method).
(setf y) (writer method).
Packages are listed by definition order.
claviercommon-lisp.
∅ (function).
&& (function).
*signal-validation-errors* (special variable).
== (function).
and-validator (class).
blank (function).
blank-validator (class).
boolean-validator (class).
call-with-signal-validation-errors (function).
collecting-validation-errors (macro).
datetime-validator (class).
email-validator (class).
equal-to-validator (class).
false-validator (class).
fn (function).
function-validator (class).
greater-than (function).
greater-than-validator (class).
integer-validator (class).
is-a (function).
is-a-boolean (function).
is-a-keyword (function).
is-a-list (function).
is-a-string (function).
is-a-symbol (function).
is-an-integer (function).
is-false (function).
is-true (function).
keyword-validator (class).
len (function).
length-validator (class).
less-than (function).
less-than-validator (class).
list-validator (class).
matches-regex (function).
message (generic function).
(setf message) (generic writer).
not-blank (function).
not-blank-validator (class).
not-equal-to-validator (class).
not-validator (class).
one-of (function).
one-of-validator (class).
or-validator (class).
pathname-validator (class).
regex-validator (class).
string-validator (class).
symbol-validator (class).
true-validator (class).
type-validator (class).
url-validator (class).
valid-datetime (function).
valid-email (function).
valid-pathname (function).
valid-url (function).
validate (function).
validation-error (function).
validation-error (condition).
validation-error-message (generic reader).
validation-error-target (generic reader).
validator (generic reader).
(setf validator) (generic writer).
validator (class).
validator-collection (class).
validator-message (function).
with-signal-validation-errors (macro).
~ (function).
~= (function).
%collecting-validation-errors (function).
%validate (generic function).
absolute-p (generic reader).
(setf absolute-p) (generic writer).
object (generic reader).
(setf object) (generic writer).
options (generic reader).
(setf options) (generic writer).
pathname-type* (generic reader).
(setf pathname-type*) (generic writer).
probe-p (generic reader).
(setf probe-p) (generic writer).
valid-email-address-p (function).
valid-url-p (function).
validator-function (generic reader).
(setf validator-function) (generic writer).
validator-length (generic reader).
(setf validator-length) (generic writer).
validator-max (generic reader).
(setf validator-max) (generic writer).
validator-max-message (generic reader).
(setf validator-max-message) (generic writer).
validator-min (generic reader).
(setf validator-min) (generic writer).
validator-min-message (generic reader).
(setf validator-min-message) (generic writer).
validator-number (generic reader).
(setf validator-number) (generic writer).
validator-regex (generic reader).
(setf validator-regex) (generic writer).
validator-type (generic reader).
(setf validator-type) (generic writer).
validators (generic reader).
(setf validators) (generic writer).
x (generic reader).
(setf x) (generic writer).
y (generic reader).
(setf y) (generic writer).
Definitions are sorted by export status, category, package, and then by lexicographic order.
Enables/disables validation errors in body
Args: - signal(boolean) : If **T**, errors are signaled. If **NIL**, they are not.
Returns the validator message for the given object
length-validator)) ¶validation-error)) ¶validation-error)) ¶not-validator)) ¶automatically generated reader method
not-validator)) ¶automatically generated writer method
validation-error) stream) ¶error.
(quote (error "set up the target"))
:target
This slot is read-only.
(quote (error "provide the error message"))
:error-msg
This slot is read-only.
| Initarg | Value |
|---|---|
:message | (lambda (validator object) (if (not (validate (x validator) object error-p nil)) (validator-message (x validator) object) (validator-message (y validator) object))) |
| Initarg | Value |
|---|---|
:message | (lambda (validator object) (declare (ignorable validator object)) (format nil should be blank)) |
| Initarg | Value |
|---|---|
:type | (quote boolean) |
:message | (lambda (validator object) (declare (ignorable validator)) (format nil ~a is not a boolean object)) |
| Initarg | Value |
|---|---|
:message | (lambda (validator object) (declare (ignorable validator object)) (format nil ~a is not a valid timestamp object)) |
| Initarg | Value |
|---|---|
:message | (lambda (validator object) (declare (ignorable validator)) (format nil the email is invalid: ~a object)) |
| Initarg | Value |
|---|---|
:message | (lambda (validator object) (format nil ~a is not equal to ~a object (object validator))) |
(error "provide the object")
:object
| Initarg | Value |
|---|---|
:message | (lambda (validator object) (declare (ignorable validator object)) (format nil is not false)) |
common-lisp.
(error "provide the function")
:function
| Initarg | Value |
|---|---|
:message | (lambda (validator object) (declare (ignorable validator object)) (format nil ~a is not greater than ~a object (validator-number validator))) |
common-lisp.
(error "provide the number")
:number
| Initarg | Value |
|---|---|
:type | (quote integer) |
:message | (lambda (validator object) (declare (ignorable validator)) (format nil ~a is not an integer object)) |
| Initarg | Value |
|---|---|
:type | (quote keyword) |
:message | (lambda (validator object) (declare (ignorable validator)) (format nil ~a is not a keyword object)) |
| Initarg | Value |
|---|---|
:message | nil |
Minimum length
common-lisp.
:min
Maximum length
common-lisp.
:max
The expected length
common-lisp.
:length
Message for when length is below minimum
:min-message
Message for when length is above maximum
:max-message
| Initarg | Value |
|---|---|
:message | (lambda (validator object) (declare (ignorable validator object)) (format nil ~a is not lower than ~a object (validator-number validator))) |
common-lisp.
(error "provide the number")
:number
| Initarg | Value |
|---|---|
:type | (quote list) |
:message | (lambda (validator object) (declare (ignorable validator)) (format nil ~a is not a list object)) |
| Initarg | Value |
|---|---|
:message | (lambda (validator object) (declare (ignorable validator object)) (format nil should not be blank)) |
| Initarg | Value |
|---|---|
:message | (lambda (validator object) (format nil ~a is equal to ~a object (object validator))) |
(error "provide the object")
:object
| Initarg | Value |
|---|---|
:message | (lambda (validator object) (format nil not ~a (validator-message (validator validator) object))) |
(error "provide the validator")
:validator
| Initarg | Value |
|---|---|
:message | (lambda (validator object) (declare (ignorable validator object)) (format nil should be one of ~{~a~} (options validator))) |
(error "provide the options")
:options
| Initarg | Value |
|---|---|
:message | (lambda (validator object) (if (validate (x validator) object error-p nil) (validator-message (x validator) object) (validator-message (y validator) object))) |
| Initarg | Value |
|---|---|
:message | (lambda (validator object) (declare (ignorable validator object)) (format nil ~a is not a valid pathname object)) |
If the pathname should be absolute
:absolute-p
Probe existance of pathname
:probe-p
The pathname type
common-lisp.
:pathname-type
| Initarg | Value |
|---|---|
:message | (lambda (validator object) (declare (ignorable validator object)) (format nil ~a does not match the regex ~s object (validator-regex validator))) |
(error "provide the regex")
:regex
| Initarg | Value |
|---|---|
:type | (quote string) |
:message | (lambda (validator object) (declare (ignore validator)) (format nil ~s is not a string object)) |
| Initarg | Value |
|---|---|
:type | (quote symbol) |
:message | (lambda (validator object) (declare (ignorable validator)) (format nil ~a is not a symbol object)) |
| Initarg | Value |
|---|---|
:message | (lambda (validator object) (declare (ignorable validator object)) (format nil is not true)) |
| Initarg | Value |
|---|---|
:message | (lambda (validator object) (format nil ~a is not of type ~a object (validator-type validator))) |
common-lisp.
(error "provide the type")
:type
| Initarg | Value |
|---|---|
:message | (lambda (validator object) (declare (ignorable validator object)) (format nil ~a is not a valid url object)) |
funcallable-standard-object.
and-validator.
blank-validator.
datetime-validator.
email-validator.
equal-to-validator.
false-validator.
function-validator.
greater-than-validator.
length-validator.
less-than-validator.
not-blank-validator.
not-equal-to-validator.
not-validator.
one-of-validator.
or-validator.
pathname-validator.
regex-validator.
true-validator.
type-validator.
url-validator.
validator-collection.
(or null string function)
(error "provide the validation error message")
:message
| Initarg | Value |
|---|---|
:message | (lambda (&rest args) (declare (ignorable args)) ) |
:validators
greater-than-validator) object &rest args) ¶less-than-validator) object &rest args) ¶one-of-validator) object &rest args) ¶or-validator) object &rest args) ¶and-validator) object &rest args) ¶not-validator) object &rest args) ¶pathname-validator) object &rest args) ¶datetime-validator) object &rest args) ¶regex-validator) object &rest args) ¶url-validator) object &rest args) ¶email-validator) object &rest args) ¶length-validator) object &rest args) ¶false-validator) object &rest args) ¶true-validator) object &rest args) ¶not-blank-validator) object &rest args) ¶blank-validator) object &rest args) ¶function-validator) object &rest args) ¶type-validator) object &rest args) ¶not-equal-to-validator) object &rest args) ¶equal-to-validator) object &rest args) ¶validator-collection) object &rest args) ¶pathname-validator)) ¶pathname-validator)) ¶If the pathname should be absolute
not-equal-to-validator)) ¶automatically generated reader method
equal-to-validator)) ¶automatically generated reader method
not-equal-to-validator)) ¶automatically generated writer method
equal-to-validator)) ¶automatically generated writer method
one-of-validator)) ¶automatically generated reader method
one-of-validator)) ¶automatically generated writer method
pathname-validator)) ¶pathname-validator)) ¶The pathname type
pathname-validator)) ¶pathname-validator)) ¶Probe existance of pathname
function-validator)) ¶automatically generated reader method
function-validator)) ¶automatically generated writer method
length-validator)) ¶length-validator)) ¶The expected length
length-validator)) ¶length-validator)) ¶Maximum length
max.
length-validator)) ¶length-validator)) ¶Message for when length is above maximum
length-validator)) ¶length-validator)) ¶Minimum length
min.
length-validator)) ¶length-validator)) ¶Message for when length is below minimum
greater-than-validator)) ¶automatically generated reader method
less-than-validator)) ¶automatically generated reader method
greater-than-validator)) ¶automatically generated writer method
less-than-validator)) ¶automatically generated writer method
regex-validator)) ¶automatically generated reader method
regex-validator)) ¶automatically generated writer method
type-validator)) ¶automatically generated reader method
type.
type-validator)) ¶automatically generated writer method
type.
validator-collection)) ¶automatically generated reader method
validator-collection)) ¶automatically generated writer method
or-validator)) ¶automatically generated reader method
x.
and-validator)) ¶automatically generated reader method
x.
or-validator)) ¶automatically generated writer method
x.
and-validator)) ¶automatically generated writer method
x.
or-validator)) ¶automatically generated reader method
y.
and-validator)) ¶automatically generated reader method
y.
or-validator)) ¶automatically generated writer method
y.
and-validator)) ¶automatically generated writer method
y.
| Jump to: | %
&
(
=
~
∅
A B C F G I L M N O P V W X Y |
|---|
| Jump to: | %
&
(
=
~
∅
A B C F G I L M N O P V W X Y |
|---|
| Jump to: | *
A E F L M N O P R S T V X Y |
|---|
| Jump to: | *
A E F L M N O P R S T V X Y |
|---|
| Jump to: | A B C D E F G I K L N O P R S T U V |
|---|
| Jump to: | A B C D E F G I K L N O P R S T U V |
|---|