speculative

speculative is a collection of specs for the functions in clojure.core. While its ultimate goal is to be rendered obsolete by these or similar specs being added to clojure.core proper, speculative hopefully provides some value while we're waiting for that to happen.

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.

Without specs on clojure.core/map the error looks like:

Clojure 1.10.0-RC1
user=> (map 'lol 'lol)
Error printing return value (IllegalArgumentException) at clojure.lang.RT.seqFrom (RT.java:551).
Don't know how to create ISeq from: clojure.lang.Symbol
user=>

With speculative, we get

user=> (map 1 'lol)
Evaluation error - invalid arguments to clojure.core/map at (NO_SOURCE_FILE:4).
1 - failed: ifn? at: [:f]
user=>

Installation

Add the relevant coordinates to your favourite build tool:

deps.edn

speculative {:mvn/version "0.0.2"}

lein

[speculative "0.0.2"]

Usage

user=> (require 'speculative.core)
nil
user=> (require '[clojure.spec.test.alpha :as stest])
nil
user=> (stest/instrument `map)
[clojure.core/map]
user=> (map 1 'lol)
Evaluation error - invalid arguments to clojure.core/map at (NO_SOURCE_FILE:4).
1 - failed: ifn? at: [:f]
user=>

Test tools

Namespace speculative.test provides various tools around clojure.spec.test.alpha. More info here.

Tests

Clojure

clj -A:test:clj-tests

ClojureScript

script/cljs-tests

Self-Hosted ClojureScript

plk -A:test:plk-tests

Try online

KLIPSE REPL with speculative and expound.

Origins

The project started based on two tweets. First @mfikes tweeted

I still hold the view that Clojure’s core fns should have specs.

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

— Mike Fikes (@mfikes) October 19, 2018

Then @borkdude tweeted a couple of days later:

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

Issues found

These issues were found while developing and using speculative.

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 for Clojure so that any code in speculative can be used in either Clojure or Clojurescript.

Please have look at the style guide before submiting a PR.

License

Copyright © 2018 Erik Assum

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