Ruby port of clojure.spec
Ruby Shell
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
bin Monkey patch ns in dev on jruby Feb 23, 2017
examples finished guide Feb 22, 2017
lib refactor date/time gen Feb 27, 2017
test Handle block pred. Feb 22, 2017
.gitignore Initial commit Dec 13, 2016
.rubocop.yml rubocop Feb 23, 2017
.travis.yml Cache bundle on travis Feb 11, 2017
.yardopts Add a bunch of docs Feb 12, 2017
Gemfile Split tests by example Feb 4, 2017
LICENSE.txt Initial commit Dec 13, 2016
README.md update readme Feb 23, 2017
Rakefile Add a bunch of docs Feb 12, 2017
speculation.gemspec update gemspec Feb 12, 2017

README.md

Speculation

A Ruby port of Clojure's clojure.spec. See clojure.spec - Rationale and Overview. The Speculation library is largely a copy-and-paste from clojure.spec. All credit goes to the clojure.spec authors.

Installation

Add this line to your application's Gemfile:

gem 'speculation'

And then execute:

$ bundle

Or install it yourself as:

$ gem install speculation

Usage

The API is more-or-less the same as clojure.spec. If you're already familiar with clojure.spec then you should be write at home with Speculation. Clojure and Ruby and quite different languages, so naturally there are some differences:

Built in predicates

clojure.spec leans on its macro system and rich standard library of predicate functions when writing specs. Ruby has neither of those, so we must be creative with what we define as a 'predicate' in Speculation. Each of the following are valid Speculation predicates:

S.valid?(->(x) { x > 0 }, 2)
S.valid?(:even?.to_proc, 2)
S.valid?(String, "foo")
S.valid?(Enumerable, [1, 2, 3])
S.valid?(/^\d+$/, "123")
S.valid?(Set[:foo, :bar, :baz], :foo)

Namespaced keywords

Namespaced keywords are at the core of clojure.spec. Since spec utilises a global spec registry, namespaced keywords allow libraries to register specs with the same names but under different namespaces, thus removing accidental collisions. Ruby's equivalent to Clojure's keywords are Symbols. Ruby Symbol's don't have namespaces.

In order keep the global spec registry architecture in Speculation, we utilise refinements achieve similar behaviour:

using Speculation::NamespacedSymbols.refine(MyModule)

p :foo.ns
# => :"MyModule/foo"

p :foo.ns(AnotherModule)
# => :"AnotherModule/foo"

FSpecs

Symbols

Clojure uses Symbols to refer to functions. To refer to a method in Ruby, we must use the method method.

def self.hello(name)
  "Hello #{name}"
end

S.fdef(method(:hello), :args => S.cat(:name => String), :ret => String)

Block args

In addition to regular arguments which can easily be described as a list, Ruby methods can take blocks. In Speculation, we spec a method's block separately to its args:

def self.hello(name, &block)
  "Hello #{block.call(name)}"
end

S.fdef(method(:hello), :args => S.cat(:name => String),
                       :block => S.fspec(:args => S.cat(:s => String), :ret => String),
                       :ret => String)

Generators and quick check

Speculation uses Rantly for random data generation. Generator functions in Speculation are Procs that take one argument (Rantly instance) and return random value. While clojure's test.check generators generate values that start small and continue to grow and get more complex as a property holds true, Rantly always generates random values.

Rantly gives Speculation the ability to shrink a failing test case down to a its smallest failing case, however in Speculation we limit this to Integers and Strings. This is an area where Speculation may currently be significantly weaker than clojure.spec.

Development

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.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/english/speculation.

TODO

  • tidy up tests

clojure.spec features

Improvements

  • Explore alternative generator library
    • Build up a library of generators around Rantly in the meantime?
  • Generate documentation from specs
  • Profile and optimise

License

The gem is available as open source under the terms of the MIT License.