From 3cface95937c61b36398742a89ef44c9981c8225 Mon Sep 17 00:00:00 2001
From: colin <colin@cicadas.surf>
Date: Thu, 30 Nov 2023 08:07:44 -0800
Subject: README.org; defvalidator docstring

---
 README.org | 71 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 71 insertions(+)
 create mode 100644 README.org

(limited to 'README.org')

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.
-- 
cgit v1.2.3