Skip to content

clojure.spec (spec.alpha) library aiming to be a fundamental tool for analyzing spec errors

License

Notifications You must be signed in to change notification settings

athos/spectrace

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

spectrace

Clojars Project CircleCI codecov

spectrace is a clojure.spec (spec.alpha) library aiming to be a fundamental tool for analyzing spec errors.

Installation

Add the following to your :dependencies:

Clojars Project

Why and how to use it

In clojure.spec (spec.alpha), s/explain-data reports how spec conformance eventually failed, as follows:

user=> (require '[clojure.spec.alpha :as s])
nil
user=> (s/def ::x integer?)
:user/x
user=> (s/def ::y string?)
:user/y
user=> (s/def ::m (s/merge (s/keys :req-un [::x]) (s/keys :req-un [::y])))
:user/m
user=> (def ed (s/explain-data ::m {:x :a}))
#'user/ed
user=> ed
#:clojure.spec.alpha{:problems
                     ({:path [:x], :pred clojure.core/integer?,
                       :val :a, :via [:user/m :user/x], :in [:x]}
                      {:path [], :pred (clojure.core/fn [%] (clojure.core/contains? % :y)),
                       :val {:x :a}, :via [:user/m], :in []}), :spec :user/m, :value {:x :a}}

Although this might be useful enough as it is to make simple error messages, it's not sufficient in some cases due to the difficulty of extracting more useful information from it.

spectrace will help us in such a situation:

user=> (require '[spectrace.core :as strace])
nil
user=> (strace/traces ed)
[[{:spec
   (clojure.spec.alpha/merge
     (clojure.spec.alpha/keys :req-un [:user/x])
     (clojure.spec.alpha/keys :req-un [:user/y])),
   :path [:x],
   :val {:x :a},
   :in [:x]
   :trail [],
   :spec-name :user/m}
  {:spec (clojure.spec.alpha/keys :req-un [:user/x]),
   :path [:x],
   :val {:x :a},
   :in [:x],
   :trail [0]}
  {:spec clojure.core/integer?, :path [], :val :a, :in [], :trail [0 :x], :spec-name :user/x}]
 [{:spec
   (clojure.spec.alpha/merge
     (clojure.spec.alpha/keys :req-un [:user/x])
     (clojure.spec.alpha/keys :req-un [:user/y])),
   :path [],
   :val {:x :a},
   :in [],
   :trail [],
   :spec-name :user/m}
  {:spec (clojure.spec.alpha/keys :req-un [:user/y]),
   :path [],
   :val {:x :a},
   :in [],
   :trail [1]}
  {:spec (clojure.core/fn [%] (clojure.core/contains? % :y)),
   :path [],
   :val {:x :a},
   :in [],
   :trail [1]}]]
user=> 

It traces and enumerates all the specs involved in the spec error and makes it easy to build more structured error messages. For example, Pinpointer, a pretty-printing reporter for spec errors, is using spectrace to achieve its high quality error reporting.

Issues to be addressed

The following is a list of spec.alpha issues that I'm aware are to be addressed before a final release of spectrace:

License

Copyright © 2017 Shogo Ohta

Distributed under the Eclipse Public License either version 1.0 or (at your option) any later version.

About

clojure.spec (spec.alpha) library aiming to be a fundamental tool for analyzing spec errors

Topics

Resources

License

Stars

Watchers

Forks

Packages

No packages published