diff options
| -rw-r--r-- | README.org | 71 | ||||
| -rw-r--r-- | terrafirma.asd | 6 | ||||
| -rw-r--r-- | terrafirma.lisp | 32 |
3 files changed, 102 insertions, 7 deletions
diff --git a/README.org b/README.org new file mode 100644 index 0000000..ee85650 --- /dev/null +++ b/README.org @@ -0,0 +1,71 @@ +* TERRAFIRMA + +Terrafirma is a small system for defining data type validators with that produce nice error messages on invalid data. + +Terrafirma's main export is the =DEFVALIDATOR= macro. This macro defines a validator function. The body of the validator function evalutes in a special context. Within this context, the symbol =VALIDATE= is a macro that can be used to check predicates and singal a =VALIDATION-ERROR= upon failure: baslically just a wrapper around =ASSERT=. + +The real "magic" happens when validation functions are defined in terms of other validation functions. In that case, error messages are nested to produce high-specific locations for your validation error. + +Here is an example: + +#+begin_src lisp + +(defpackage #:geom + (:use #:cl #:terrafirma)) + +(in-package :geom) + +(defclass point () + ((x :initarg :x) + (y :initarg :y))) + +;; defines a function called VALID-POINT-P. By default the name of the +;; type is used to create the validator function's name. +(defvalidator (pt point) + (validate (and (slot-boundp pt 'x) (slot-boundp pt 'y)) + "Both X and Y must be bound.") + (with-slots (x y) pt + (validate (numberp x) "X = ~s is not a number" x) + (validate (numberp y) "Y = ~s is not a number" y))) + +(defclass polygon () + ((verts :initarg :verts :type (cons point)))) + +;; defines a function called VALID-POLY-P. Here we pass a specific +;; name in. We also define this validator in terms of gthe +;; VALID-POLY-P validator. +(defvalidator (p polygon :name valid-poly-p) + (validate (slot-boundp p 'verts) "VERTS must be bound.") + (let ((verts (slot-value p 'verts))) + (validate (< 2 (length verts)) "VERTS must contain at least three points.") + (validate (every #'valid-point-p verts) "VERTS contains an invalid point."))) + +(defun poly (&rest coords) + (make-instance 'polygon + :verts (loop :for (x y) :on coords :by #'cddr + :collect (make-instance 'point :x x :y y)))) + +#+end_src + +Now, call =VALID-POLY-P= on a couple of bad polygons. + +#+begin_src lisp +(valid-poly-p + (poly 1 2 3 4)) + +;; Error validating POLYGON: VERTS must contain at least three points. +;; [Condition of type VALIDATION-ERROR] + +(valid-poly-p + (poly 1 2 "foo" 10 11 20)) + +;; Error validating POLYGON: VERTS contains an invalid point. +;; More specifically: +;; Error validating POINT: X = "foo" is not a number +;; [Condition of type VALIDATION-ERROR] + +#+end_src + + + +See the docstring on =DEFVALIDATOR= for use details. diff --git a/terrafirma.asd b/terrafirma.asd index 9debdc2..61ed6b5 100644 --- a/terrafirma.asd +++ b/terrafirma.asd @@ -1,9 +1,9 @@ ;;;; terrafirma.asd (asdf:defsystem #:terrafirma - :description "Describe A-OK here" - :author "Your Name <your.name@example.com>" - :license "Specify license here" + :description "Easy informative validation errors in a single macro." + :author "Colin <colin@cicadas.surf>" + :license "Unlicense" :version "0.0.1" :serial t :components ((:file "terrafirma"))) diff --git a/terrafirma.lisp b/terrafirma.lisp index 78d74c9..b5ef90c 100644 --- a/terrafirma.lisp +++ b/terrafirma.lisp @@ -3,8 +3,10 @@ (defpackage #:terrafirma (:use #:cl) (:export - #:validate - #:defvalidator)) + #:validation-error ; Condition + #:validate ; Macrolet Symbol + #:defvalidator ; Macro + )) (in-package #:terrafirma) @@ -47,10 +49,31 @@ (defvar *instance*) (defmacro defvalidator ((var type &key name) &body body) + "Defines a validation function. If TYPE is a symbolic type identifier, +then the defined function will have a name like VALID-<TYPE>-P. +Otherwise a NAME must be provided. + +This means you can define validators for types like (CONS CHAR) if you +want. + +Within the body of DEFVALIDATOR, a special VALIDATE macro is +bound. Its syntax is: + +(VALIDATE CHECK FORMATSTRING &REST FORMATARGS) + +E.G. + + (validate (= 10 foo) \"Foo = ~s is not equal to 10\" foo) + +A VALIDATE form returns T if CHECK evaluates to non-nil. If CHECK +signals an error, or if CHECK returns NIL, then the whole validator +fails. + +If all VALIDATE forms pass, then the function returns T." (assert (and var (symbolp var)) (var) "VAR must be a symbol.") (let ((validator-name (cond ((and name (symbolp name)) name) - ((symbolp type) (intern (format nil "VALIDATED-~a" type))) + ((symbolp type) (intern (format nil "VALID-~a-P" type))) (t (error "Validator Name: Either TYPE must be a symbol or a NAME must be provided."))))) `(macrolet ((validate (check msg &rest args) (let ((suberr (gensym))) @@ -65,4 +88,5 @@ (defun ,validator-name (,var) (let ((terrafirma::*type* ',type) (terrafirma::*instance* ,var)) - ,@body))))) + ,@body + t))))) |