Expound printer

CHANGES.md

@@ -1,5 +1,12 @@
 # Changes
 
+## master
+
+## 0.1.2
+
+- Adds support for instrumentation https://github.com/bhb/expound/issues/4
+- Adds support for Spec asserts https://github.com/bhb/expound/issues/5
+
 ## 0.1.1
 
-- Fixes bug https://github.com/bhb/expound/issues/31
+- Fixes bug https://github.com/bhb/expound/issues/3

README.md

@@ -4,10 +4,14 @@ Expound formats `clojure.spec` errors in a way that is optimized for humans to r
 
 Expound is in alpha while `clojure.spec` is in alpha.
 
+Expound is tested with Clojure 1.9.0-alpha17 and Clojurescript 1.9.562. Clojurescript 1.9.542 only supports using `expound` and `expound-str` functions directly.
+
 ## Usage
 
 [![Clojars Project](https://img.shields.io/clojars/v/expound.svg)](https://clojars.org/expound)
 
+### `expound`
+
 Replace calls to `clojure.spec.alpha/explain` with `expound.alpha/expound` and to `clojure.spec.alpha/explain-str` with `expound.alpha/expound-str`.
 
 ```clojure
@@ -71,6 +75,47 @@ Replace calls to `clojure.spec.alpha/explain` with `expound.alpha/expound` and t
 ;; Detected 1 error
 ```
 
+### `*explain-out*`
+
+To use other Spec functions, set `clojure.spec.alpha/*explain-out*` (or `cljs.spec.alpha/*explain-out*` for ClojureScript) to `expound/printer`.
+
+(Setting `*explain-out*` does not work correctly in ClojureScript versions prior to `1.9.562` due to differences in `explain-data`)
+
+```clojure
+(require '[clojure.spec.alpha :as s])
+;; for clojurescript:
+;; (require '[cljs.spec.alpha :as s])
+(require '[expound.alpha :as expound])
+
+(s/def :example.place/city string?)
+(s/def :example.place/state string?)
+
+;;  Use `assert`
+(s/check-asserts true) ; enable asserts
+
+;; Set var in the scope of 'binding'
+(binding [s/*explain-out* expound/printer]
+  (s/assert :example.place/city 1))
+
+;; Or set it globally
+(set! s/*explain-out* expound/printer)
+(s/assert :example.place/city 1)
+
+;; Use `instrument`
+(require '[clojure.spec.test.alpha :as st])
+
+(s/fdef pr-loc :args (s/cat :city :example.place/city
+                            :state :example.place/state))
+(defn pr-loc [city state]
+  (str city ", " state))
+
+(st/instrument `pr-loc)
+(pr-loc "denver" :CO)
+
+;; You can use `explain` without converting to expound
+(s/explain :example.place/city 123)
+```
+
 ## Prior Art
 
 * Error messages in [Elm](http://elm-lang.org/), in particular the [error messages catalog](https://github.com/elm-lang/error-message-catalog)

dev/user.clj

@@ -0,0 +1,11 @@
+(ns user
+  (:require [clojure.spec.alpha :as s]
+            [orchestra.spec.test :as st]
+            [expound.alpha :as expound]))
+
+(defn setup []
+  (set! s/*explain-out* expound/printer)
+  (st/instrument))
+
+(comment
+  (setup))

docs/development.md

@@ -4,7 +4,7 @@
 
 ```
 lein with-profile +test-web,+cljs-repl repl
-````
+```
 
 ```
 M-x cider-connect

project.clj

@@ -1,10 +1,13 @@
-(defproject expound "0.1.1"
+(defproject expound "0.1.2-SNAPSHOT"
   :description "Human-optimized error messages for clojure.spec"
   :url "https://github.com/bhb/expound"
   :license {:name "Eclipse Public License"
             :url "http://www.eclipse.org/legal/epl-v10.html"}
   :dependencies [[org.clojure/clojure "1.9.0-alpha17" :scope "provided"]
-                 [org.clojure/clojurescript "1.9.542" :scope "provided"]
+                 ;; expound launched with this version
+                 ;; and only supported expound and expound-str
+                 ;;[org.clojure/clojurescript "1.9.542" :scope "provided"]
+                 [org.clojure/clojurescript "1.9.562" :scope "provided"]
                  [org.clojure/spec.alpha "0.1.123" :scope "provided"]]
 
   :plugins [[com.jakemccrary/lein-test-refresh "0.20.0"]
@@ -71,7 +74,8 @@
              }
   :profiles {:dev {:dependencies [[binaryage/devtools "0.9.2"]
                                   [figwheel-sidecar "0.5.10"]
-                                  [com.cemerick/piggieback "0.2.1"]]
+                                  [com.cemerick/piggieback "0.2.1"]
+                                  [orchestra "2017.07.04-1"]]
                    ;; need to add dev source path here to get user.clj loaded
                    :source-paths ["src" "dev"]
                    ;; for CIDER

resources/public/index.html

@@ -0,0 +1,8 @@
+<!DOCTYPE html>
+<html>
+  <head></head>
+  <body>
+    <script src="test-web/test.js" type="text/javascript"></script>
+    <p>REPL should be connected...</p>
+  </body>
+</html>