- -Then @borkdude tweeted a couple of days later: -I still hold the view that Clojure’s core fns should have specs.
— Mike Fikes (@mfikes) October 19, 2018
Ex: While
(merge-with + [0 3] {0 7 1 2} {0 3 2 32})
produces a reasonable result, it is not even a map. A spec would reject 2nd arg.
What if I conclude dot products are possible via
(merge-with + [0 3] [1 2])
?
+Or maybe have a development version with guards and a production version without guards (I think Stu said something like this)
— (λ. borkdude) (@borkdude) October 19, 2018
+ +Then @borkdude tweeted a couple of days later:I still +hold the view that Clojure’s core fns should have specs.
— Mike +Fikes (@mfikes) October +19, 2018
Ex: While
+(merge-with + [0 3] {0 7 1 2} {0 3 2 32})
produces a reasonable result, it is +not even a map. A spec would reject 2nd arg.
What if I conclude dot +products are possible via
(merge-with + [0 3] [1 2])
?
## Rationale -With the new error-messages that are coming with Clojure 1.10, adding specs to the `clojure.core` functions give much better error messages. +With the new error-messages that are coming with Clojure 1.10, adding specs to +the `clojure.core` functions give much better error messages. Without specs on `clojure.core/map` the error looks like: @@ -42,7 +57,7 @@ Add the relevant coordinates to your favourite build tool: deps.edn ``` -speculative {:mvn/version "RELEASE"} +speculative {:mvn/version "0.0.2"} ``` lein @@ -70,59 +85,8 @@ user=> ## Test tools Namespace `speculative.test` provides macros and functions that are used in the -tests for speculative, but may also come in handy in other projects. - -``` clojure -$ clj -Sdeps '{:deps {net.cgrand/macrovich {:mvn/version "0.2.1"}}}' -Clojure 1.10.0-RC1 - -user=> (require '[speculative.test :refer [check - with-instrumentation - gentest - success?]]) -nil - -user=> (require '[clojure.spec.alpha :as s]) -nil - -user=> (s/fdef foo - :args (s/cat :n number?) - :ret number?) -user/foo - -user=> (defn foo [n] - "ret") -#'user/foo - -user=> (check `foo [1]) -Evaluation error - invalid arguments to null at clojure.spec.test.alpha/explain-check (alpha.clj:278). -"ret" - failed: number? at: [:ret] - -user=> (s/fdef foo - :args (s/cat :n number?) - :ret string?) -user/foo - -user=> (check `foo [1]) -"ret" - -user=> (with-instrumentation `foo - (foo "a")) -Evaluation error - invalid arguments to user/foo at (NO_SOURCE_FILE:15). -"a" - failed: number? at: [:n] - -user=> (foo "a") -"ret" - -user=> (gentest `foo nil {:num-tests 1}) -generatively testing user/foo -({:spec #object[clojure.spec.alpha$fspec_impl$reify__2524 0x72bd06ca "clojure.spec.alpha$fspec_impl$reify__2524@72bd06ca"], :clojure.spec.test.check/ret {:result true, :pass? true, :num-tests 1, :time-elapsed-ms 1, :seed 1541249961647}, :sym user/foo}) - -user=> (success? *1) -true - -user=> -``` +tests for speculative, but may also come in handy in other projects. Read about +it [here](doc/test.md). ## Issues found @@ -144,8 +108,10 @@ user=> ## Contributing -In the hope that the code in this project would be useful for `clojure.core`, any contributer to this repo needs to have a -[Contributor Agreement](https://clojure.org/community/contributing) for Clojure so that any code in speculative can be used in either Clojure or Clojurescript. +In the hope that the code in this project would be useful for `clojure.core`, +any contributer to this repo needs to have a [Contributor +Agreement](https://clojure.org/community/contributing) for Clojure so that any +code in speculative can be used in either Clojure or Clojurescript. Take a look at the [style guide](doc/style.md). diff --git a/doc/test.md b/doc/test.md new file mode 100644 index 0000000..f4e5244 --- /dev/null +++ b/doc/test.md @@ -0,0 +1,56 @@ +## Test tools + +Namespace `speculative.test` provides macros and functions that are used in the +tests for speculative, but may also come in handy in other projects. + +``` clojure +$ clj -Sdeps '{:deps {net.cgrand/macrovich {:mvn/version "0.2.1"}}}' +Clojure 1.10.0-RC1 + +user=> (require '[speculative.test :refer [check + with-instrumentation + gentest + successful?]]) +nil + +user=> (require '[clojure.spec.alpha :as s]) +nil + +user=> (s/fdef foo + :args (s/cat :n number?) + :ret number?) +user/foo + +user=> (defn foo [n] + "ret") +#'user/foo + +user=> (check `foo [1]) +Evaluation error - invalid arguments to null at clojure.spec.test.alpha/explain-check (alpha.clj:278). +"ret" - failed: number? at: [:ret] + +user=> (s/fdef foo + :args (s/cat :n number?) + :ret string?) +user/foo + +user=> (check `foo [1]) +"ret" + +user=> (with-instrumentation `foo + (foo "a")) +Evaluation error - invalid arguments to user/foo at (NO_SOURCE_FILE:15). +"a" - failed: number? at: [:n] + +user=> (foo "a") +"ret" + +user=> (gentest `foo nil {:num-tests 1}) +generatively testing user/foo +({:spec #object[clojure.spec.alpha$fspec_impl$reify__2524 0x72bd06ca "clojure.spec.alpha$fspec_impl$reify__2524@72bd06ca"], :clojure.spec.test.check/ret {:result true, :pass? true, :num-tests 1, :time-elapsed-ms 1, :seed 1541249961647}, :sym user/foo}) + +user=> (successful? *1) +true + +user=> +``` diff --git a/project.clj b/project.clj index d529f96..6fcec35 100644 --- a/project.clj +++ b/project.clj @@ -1,4 +1,4 @@ -(defproject speculative "0.0.2-SNAPSHOT" +(defproject speculative "0.0.2" :description "A collection of specs for clojure.core functions" :url "https://github.com/slipset/speculative" :license {:name "Eclipse Public License"Or maybe have a +development version with guards and a production version without guards (I think +Stu said something like this)
— (λ. borkdude) (@borkdude) October +19, 2018