A Ruby port of Clojure's
clojure.spec. This library is largely a copy-and-paste from clojure.spec so all credit goes to Rich Hickey and contributors for their original work.
See clojure.spec - Rationale and Overview for a thorough outline of the problems clojure.spec (and thus Speculation) was built to address and how it addresses them. As a brief summary, Speculation allows you to write predicate specs (nothing to do with RSpec!) which enable:
- declarative data validation and destructuring
- error reporting
- runtime method instrumentation, argument checking and stubbing
- generative testing
The goal of this project is to match clojure.spec as closely as possible, from design to features to API. There aren't, and won't be any, significant departures from clojure.spec.
- sinatra-web-app: A small Sinatra web application demonstrating parameter validation and API error message generation.
- spec_guide.rb: Speculation port of Clojure's spec guide, demonstrating most features.
- codebreaker.rb: Speculation port of the 'codebreaker' game described in Interactive development with clojure.spec
- json_parser.rb: JSON parser using Speculation.
API Documentation is available at RubyDoc and the wiki covers features at a higher level. The API is more-or-less the same as
clojure.spec so if you're already familiar clojure.spec with then you should feel at home with Speculation. Most guides, talks and discussions around clojure.spec should apply equally well to Speculation.
Speculation will mirror any changes made to clojure.spec. clojure.spec is still in alpha so breaking changes should be expected.
While most of features of clojure.spec are implemented in Speculation, a few remain:
Some things I hope to focus on in the near future:
- Explore alternative generator library
- Build up a library of generators around Rantly in the meantime?
- Generate documentation from specs
- perhaps integrating with Pry's documentation browsing?
- Profile and optimise
After checking out the repo, run
bin/setup to install dependencies. Then, run
rake to run rubocop and the tests. You can also run
bin/console for an interactive prompt that will allow you to experiment.
Bug reports and pull requests are welcome on GitHub at https://github.com/english/speculation.
The gem is available as open source under the terms of the MIT License.