README.org; defvalidator docstringmaster

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)))))