speculation 0.4.0 → 0.4.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 7aa989a5796d79c562dc7ade44fe3b9b146b208e
-  data.tar.gz: 4e3249fae769e64f274f040ad59ef012ed4e50f5
+  metadata.gz: 8931f31e4324a18fab4cbc70ba363c072a0fcf78
+  data.tar.gz: 886f8a36b120d8dcebf90a139ec9a0d74817759d
 SHA512:
-  metadata.gz: bf7cb77e9f081fa6605a7676fd733c1ea5a2d3d8da9634bf529bdfd523e37cf54795e96dabdc84e039c920efbd2e1a620f7fcd3d7abbff16c5d8eed90ca0a28d
-  data.tar.gz: b997fa5b070e09ac6c146bb0587278351e03da7bb27ef12d650765484c66045e7f05576bbdea13ccfaf8f4b72e44d53e1ab54e52149eafff7e3b10f48ee78d54
+  metadata.gz: c1cfef5d20928e45e5852a6e25ea04e28fdce96aa36dc3f877e364ba63af52018983bfdfbee523b0221fd29a160a1a0c2dd45c33c3ebe372531fff1e9e6b2dfa
+  data.tar.gz: bb4eb7ded2d8ab2335d9993b2185492d0821e59c65d362b6152af6d06d551867b39dcf6eea23a98eb3e25cbb7dd9d2b3e81485db90b5ff0f46c75a939f25e2d5

data/README.md

@@ -2,7 +2,7 @@
 
 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](https://clojure.org/about/spec) 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:
+See [clojure.spec - Rationale and Overview](https://clojure.org/about/spec) 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 describe the structure of datastructures and methods, enabling:
 
 * declarative data validation and destructuring
 * error reporting
@@ -11,85 +11,178 @@ See [clojure.spec - Rationale and Overview](https://clojure.org/about/spec) for
 
 ## Project Goals
 
-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.
+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.
 
-## Examples
+## Usage
 
-* [sinatra-web-app](examples/sinatra-web-app): A small Sinatra web application demonstrating parameter validation and API error message generation.
-* [spec_guide.rb](examples/spec_guide.rb): Speculation port of Clojure's [spec guide](https://clojure.org/guides/spec), demonstrating most features.
-* [codebreaker.rb](examples/codebreaker.rb): Speculation port of the 'codebreaker' game described in [Interactive development with clojure.spec](http://blog.cognitect.com/blog/2016/10/5/interactive-development-with-clojurespec)
-* [json_parser.rb](examples/json_parser.rb): JSON parser using Speculation.
+API Documentation is available at [RubyDoc](http://www.rubydoc.info/github/english/speculation) and [the wiki](https://github.com/english/speculation/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.
 
-## Usage
+To demonstrate most of the features of Speculation we can explore an implementation of [Conway's Game of Life](https://en.wikipedia.org/wiki/Conway%27s_Game_of_Life):
+
+### Game of Life demonstration
+
+First, we'll require the [speculation][speculation] library along with the [generator][gen] and [test][test] modules. We'll be referring to `Speculation` a lot, so we'll add a shorthand to save us some typing:
 
-Documentation is available at [RubyDoc](http://www.rubydoc.info/github/english/speculation). The API is more-or-less the same as `clojure.spec`. If you're already familiar clojure.spec with then you should feel at home with Speculation. Most guides, talks and discussion around clojure.spec should apply equally well to Speculation. Clojure and Ruby and quite different languages, so naturally there are some differences:
+```ruby
+require 'speculation'
+require 'speculation/test'
+require 'speculation/gen'
 
-## Differences with clojure.spec
+S = Speculation
+```
+
+The Game of Life can be modelled with just a few simple entities. Let's describe them up front:
 
-### Built in predicates
+```ruby
+# Our 'world' is a set of 'cells'.
+S.def :"gol/world", S.coll_of(:"gol/cell", kind: Set)
 
-clojure.spec utilises its rich standard library of predicate functions and data structures 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:
+# A cell is a tuple of coordinates.
+S.def :"gol/cell", S.tuple(:"gol/coordinate", :"gol/coordinate")
 
-```rb
-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)
+# A coordinate is just an integer.
+S.def :"gol/coordinate", S.with_gen(Integer) { S.gen(S.int_in(-5..5)) }
 ```
 
-### Namespaced keywords/symbols
+Let's unpick what we've done so far:
 
-Namespaced keywords are at the core of `clojure.spec`. Since clojure.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.
+- We've registered 'specs' (via [`S.def`][s-def]) to a global registry of specs, naming then with [namespaced Symbols][ns-symbols].
+- We've created both complex ([`S.coll_of`][coll_of] and [`S.tuple`][tuple]) and simple (`Integer`) specs.
+- We've also leveraged the built-in generators for `S.coll_of` and `S.tuple` but swapped out the `Integer` `:"gol/coordinate"` generator for another built-in: [`S.int_in`][int_in]. While we don't have an upper or lower bound on a valid coordinate, using a more restrictive generator allows us to experiment with smaller worlds.
 
-In order keep the global spec registry architecture in Speculation, we utilise a helper method `ns` to achieve similar behaviour:
+Before we move on to implementing the logic of the Game of Life, let's get an idea of the kind of data we'll be working with.
+
+```ruby
+S::Gen.generate(S.gen(:"gol/world"))
+# => #<Set: {[2, -3], [-3, 5], [1, 1], [0, -3], [-5, 2], [-2, -3]}>
+S::Gen.generate(S.gen(:"gol/world"))
+# => #<Set: {}>
+```
 
-```rb
-module MyModule
-  extend Speculation::NamespacedSymbols
+Our up front definition of specs is already paying off. We can generate random, valid examples of our expected domain entities and play around with them, either in tests or in a REPL (e.g. Pry, IRB). Without this kind of exploration we may not have initially considered the case where the world is empty!
 
-  p ns(:foo)
-  # => :"MyModule/foo"
+Now to the logic of the game. Before we can implement [the rules](https://en.wikipedia.org/wiki/Conway%27s_Game_of_Life#Rules), we must be able to find the neighbouring cells for a given cell.
 
-  p ns(AnotherModule, :foo)
-  # => :"AnotherModule/foo"
+```ruby
+def self.neighbours(cell)
+  cell_x, cell_y = cell
+  (-1..1).to_a.repeated_permutation(2).map { |(x, y)| [cell_x - x, cell_y - y] }
 end
 ```
 
-### FSpecs
+Now I think that should work... But I'm not so confident. Let's write a spec for the method. Its argument should be a cell, which we already have a spec for. We'll assume our world has no boundaries, so any cell should have a set of 8 neighbours.
 
-#### Symbols/Methods
+```ruby
+S.fdef method(:neighbours),
+  args: S.cat(cell: :"gol/cell"),
+  ret: S.coll_of(:"gol/cell", count: 8, kind: Set)
+```
+
+Now that we've described the inputs and outputs of the method, we can generatively test it:
+
+```ruby
+S::Test.summarize_results S::Test.check(method(:neighbours))
+# {:spec=>"Speculation::FSpec(main.neighbours)",
+#  :method=>#<Method: main.neighbours>,
+#  :failure=>
+#   {:problems=>
+#     [{:path=>[:ret],
+#       :val=>[[-1, 6], [-1, 5], [-1, 4], [-2, 6], [-2, 5], [-2, 4], [-3, 6], [-3, 5], [-3, 4]],
+#       :via=>[],
+#       :in=>[],
+#       :pred=>[Set,[[[-1, 6], [-1, 5], [-1, 4], [-2, 6], [-2, 5], [-2, 4], [-3, 6], [-3, 5], [-3, 4]]]]}],
+#    :spec=>Speculation::EverySpec(),
+#    :value=>[[-1, 6], [-1, 5], [-1, 4], [-2, 6], [-2, 5], [-2, 4], [-3, 6], [-3, 5], [-3, 4]],
+#    :args=>[[-2, 5]],
+#    :val=> [[-1, 6], [-1, 5], [-1, 4], [-2, 6], [-2, 5], [-2, 4], [-3, 6], [-3, 5], [-3, 4]],
+#    :failure=>:check_failed}}
+# => {:total=>1, :check_failed=>1}
+```
 
-Clojure uses Symbols to refer to functions. To refer to a method in Ruby, we must use the `method` method.
+Great, it's found a problem! This is saying that an input case was generated that failed our spec. The `:problems` values let's us know exactly what it found wrong. It's saying that the `:ret` part of our `neighbours` spec failed the 'Set' predicate. We can see that the value at `:val` is an Array, not a Set! There's our problem! Let's fix it by calling `to_set` before we return the collection of cells:
 
-```rb
-def self.hello(name)
-  "Hello #{name}"
+```ruby
+def self.neighbours(cell)
+  cell_x, cell_y = cell
+  (-1..1).to_a.repeated_permutation(2).map { |(x, y)| [cell_x - x, cell_y - y] }.to_set
 end
 
-S.fdef(method(:hello), :args => S.cat(:name => String), :ret => String)
+S::Test.summarize_results S::Test.check(method(:neighbours))
+# {:spec=>"Speculation::FSpec(main.neighbours)",
+#  :method=>#<Method: main.neighbours>,
+#  :failure=>
+#   {:problems=>
+#     [{:path=>[:ret],
+#       :pred=>
+#        [#<Method: Speculation::Predicates.count_eq?>,
+#         [8, #<Set: {[-4, -1], [-4, -2], [-4, -3], [-5, -1], [-5, -2], [-5, -3], [-6, -1], [-6, -2], [-6, -3]}>]],
+#       :val=>
+#        #<Set: {[-4, -1], [-4, -2], [-4, -3], [-5, -1], [-5, -2], [-5, -3], [-6, -1], [-6, -2], [-6, -3]}>,
+#       :via=>[],
+#       :in=>[]}],
+#    :spec=>Speculation::EverySpec(),
+#    :value=>
+#     #<Set: {[-4, -1], [-4, -2], [-4, -3], [-5, -1], [-5, -2], [-5, -3], [-6, -1], [-6, -2], [-6, -3]}>,
+#    :args=>[[-5, -2]],
+#    :val=>
+#     #<Set: {[-4, -1], [-4, -2], [-4, -3], [-5, -1], [-5, -2], [-5, -3], [-6, -1], [-6, -2], [-6, -3]}>,
+#    :failure=>:check_failed}}
+# => {:total=>1, :check_failed=>1}
 ```
 
-#### Block args
+So we've fixed our Set problem, but now we have another. The `:ret` spec has failed once again, but this time the `:pred` is `Speculation::Predicates.count_eq?`, with an argument of 8 and then a set of 9 cells. Aha! We're including the given cell in this set of neighbours, therefore getting one too neighbouring cells back! That's an easy fix:
 
-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:
-
-```rb
-def self.hello(name, &block)
-  "Hello #{block.call(name)}"
+```ruby
+def self.neighbours(cell)
+  cell_x, cell_y = cell
+  block = (-1..1).to_a.repeated_permutation(2).map { |(x, y)| [cell_x - x, cell_y - y] }.to_set
+  block - Set[cell]
 end
 
-S.fdef(method(:hello), :args => S.cat(:name => String),
-                       :block => S.fspec(:args => S.cat(:s => String), :ret => String),
-                       :ret => String)
+S::Test.summarize_results S::Test.check(method(:neighbours))
+# => {:total=>1, :check_passed=>1}
 ```
 
-#### Generators and quick check
+Great, we've managed to verify that, after generating many random inputs (1,000 by default), our method's return value satisfies the properties we defined in its spec. That gives me more confidence than a small handful of hand-written example tests would!
+
+We can gain additional leverage from our spec: we can [`instrument`][instrument] the `neighbours` method so that it lets us know when it's been invoked with arguments that do not conform to its `:args` spec.
+
+Before we do that, let's observe the method's current behavior when we provide deceptively invalid arguments:
+
+```ruby
+neighbours([1.0, 2.0])
+# => #<Set: {[2.0, 3.0], [2.0, 2.0], [2.0, 1.0], [1.0, 3.0], [1.0, 1.0], [0.0, 3.0], [0.0, 2.0], [0.0, 1.0]}>
+```
+
+Here, we've provided a tuple of floats as a coordinate. This didn't raise any errors with our current implementation; it has dutifully gone to work and returned a value. However, the return value doesn't make sense: our program deals with integer pair coordinates. This situation would most likely lead to either invalid data or an exception at a later stage in our program, far away from the root cause of the problem (calling a method with incorrect types).
+
+Let's address that by instrumenting our method so that it verifies its arguments at invocation time:
+
+```ruby
+S::Test.instrument method(:neighbours)
+neighbours([1.0, 2.0])
+# Speculation::Error: Call to 'main.neighbours' did not conform to spec:
+# In: [0, 1] val: 2.0 fails spec: :"gol/coordinate" at: [:args, :cell, 1] predicate: [Integer, [2.0]]
+# In: [0, 0] val: 1.0 fails spec: :"gol/coordinate" at: [:args, :cell, 0] predicate: [Integer, [1.0]]
+# :spec Speculation::RegexSpec()
+# :value [[1.0, 2.0]]
+# :args [[1.0, 2.0]]
+# :failure :instrument
+# :caller "(pry):44:in `<main>'"
+# from /Users/jamie/Projects/speculation/lib/speculation/test.rb:237:in `block in spec_checking_fn'
+```
 
-Speculation uses [`Rantly`](https://github.com/abargnesi/rantly) for random data generation. Generator functions in Speculation are Procs that take one argument (Rantly instance) and return a 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.
+We can see from the error message that our argument has two problems: both elements of our array argument have failed the Integer predicate for the `:"gol/coordinate"` spec.  This is arguably much better feedback than if we hadn't instrumented this method.
 
-Rantly gives Speculation the ability to shrink a failing test case down to 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.
+We've demonstrated several Speculation features, so we'll leave this demo here. See the full [Game of Life example](examples/game_of_life.rb) where we take this idea further.
+
+## Examples
+
+* [sinatra-web-app](examples/sinatra-web-app): A small Sinatra web application demonstrating parameter validation and API error message generation.
+* [spec_guide.rb](examples/spec_guide.rb): Speculation port of Clojure's [spec guide](https://clojure.org/guides/spec), demonstrating most features.
+* [codebreaker.rb](examples/codebreaker.rb): Speculation port of the 'codebreaker' game described in [Interactive development with clojure.spec](http://blog.cognitect.com/blog/2016/10/5/interactive-development-with-clojurespec).
+* [game_of_life.rb](examples/game_of_life.rb): [Conway's Game of Life](https://en.wikipedia.org/wiki/Conway%27s_Game_of_Life) implementation.
+* [json_parser.rb](examples/json_parser.rb): (toy) JSON parser using Speculation.
 
 ## Project status
 
@@ -97,10 +190,8 @@ Speculation will mirror any changes made to clojure.spec. clojure.spec is still
 
 While most of features of clojure.spec are implemented in Speculation, a few remain:
 
-- [`unform`](https://clojuredocs.org/clojure.spec/unform)
-- [`form`](https://clojuredocs.org/clojure.spec/form)
-- [`abbrev`](https://clojuredocs.org/clojure.spec/abbrev)
-- [`describe`](https://clojuredocs.org/clojure.spec/describe)
+- [`multi-spec`](https://clojure.github.io/clojure/branch-master/clojure.spec-api.html#clojure.spec/multi-spec) - Ruby doesn't have an equivalent of multimethods...
+- [`describe`](https://clojuredocs.org/clojure.spec/describe) - Since we can't capture the source code of a Ruby method/proc, we won't be able to match Clojure's `s/describe` but we may be able to come up with something close.
 
 ## Improvements
 
@@ -114,7 +205,7 @@ Some things I hope to focus on in the near future:
 
 ## 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.
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake` to run Rubocop and the test suite. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
 
 ## Contributing
 
@@ -123,3 +214,13 @@ Bug reports and pull requests are welcome on GitHub at https://github.com/englis
 ## License
 
 The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
+
+[def]: http://www.rubydoc.info/github/english/speculation/master/Speculation#def-class_method
+[coll_of]: http://www.rubydoc.info/github/english/speculation/master/Speculation#coll_of-class_method
+[tuple]: http://www.rubydoc.info/github/english/speculation/master/Speculation#tuple-class_method
+[int_in]: http://www.rubydoc.info/github/english/speculation/master/Speculation#int_in-class_method
+[ns-symbols]: https://github.com/english/speculation/wiki/Namespaced-Symbols
+[speculation]: http://www.rubydoc.info/github/english/speculation/master/Speculation
+[gen]: http://www.rubydoc.info/github/english/speculation/master/Speculation/Gen
+[test]: http://www.rubydoc.info/github/english/speculation/master/Speculation/Test
+[instrument]: http://www.rubydoc.info/github/english/speculation/master/Speculation/Test#instrument-class_method

data/examples/codebreaker.rb

@@ -72,7 +72,7 @@ def self.score(secret, guess)
 end
 
 STest.check method(:score)
-# [{:spec=>Speculation::FSpec(main.score), :"Speculation::Test/ret"=>{:num_tests=>1000, :result=>true}, :method=>#<Method: main.score>}]
+# [{:spec=>Speculation::FSpec(main.score), :ret=>{:num_tests=>1000, :result=>true}, :method=>#<Method: main.score>}]
 
 def self.score(secret, guess)
   { ns(:exact_matches) => 4,
@@ -82,12 +82,12 @@ end
 # STest.check method(:score)
 
 # [{:spec=>Speculation::FSpec(main.score),
-#   :"Speculation::Test/ret"=>
+#   :ret=>
 #    {:fail=>[[:y, :b, :r, :r, :b], [:y, :w, :g, :r, :g]],
 #     :block=>nil,
 #     :num_tests=>1,
 #     :result=>
-#      #<Speculation::Error: {:"Speculation/problems"=>
+#      #<Speculation::Error: {:problems=>
 #   [{:path=>[:fn],
 #     :val=>
 #      {:args=>{:secret=>[:y, :b, :r, :r, :b], :guess=>[:y, :w, :g, :r, :g]},
@@ -109,7 +109,7 @@ S.exercise_fn method(:score)
 
 STest.check method(:score)
 
-# [{:spec=>Speculation::FSpec(main.score), :"Speculation::Test/ret"=>{:num_tests=>1000, :result=>true}, :method=>#<Method: main.score>}]
+# [{:spec=>Speculation::FSpec(main.score), :ret=>{:num_tests=>1000, :result=>true}, :method=>#<Method: main.score>}]
 
 def self.score(secret, guess)
   { ns(:exact_matches) => exact_matches(secret, guess),
@@ -144,7 +144,7 @@ S.exercise_fn method(:exact_matches)
 #  [[[:r, :b, :r, :c], [:y, :r, :g, :b]], nil, 0],
 
 STest.check method(:exact_matches)
-# [{:spec=>Speculation::FSpec(main.exact_matches), :"Speculation::Test/ret"=>{:num_tests=>1000, :result=>true}, :method=>#<Method: main.exact_matches>}]
+# [{:spec=>Speculation::FSpec(main.exact_matches), :ret=>{:num_tests=>1000, :result=>true}, :method=>#<Method: main.exact_matches>}]
 
 STest.instrument method(:exact_matches)
 S.exercise_fn method(:score)
@@ -163,7 +163,7 @@ end
 # S.exercise_fn method(:score)
 
 # Speculation::Error: Call to 'main.exact_matches' did not conform to spec:
-#  In: [1] val: [:w, :y, :c] fails spec: :"Object/code" at: [:args, :guess] predicate: [#<Method: Speculation::Utils.count_between?>, [[:w, :y, :c], 4, 6]]
+#  In: [1] val: [:w, :y, :c] fails spec: :"Object/code" at: [:args, :guess] predicate: [#<Method: Speculation::Predicates.count_between?>, [4, 6, [:w, :y, :c]]]
 # Speculation/args [[:r, :b, :c, :y, :b, :r], [:w, :y, :c]]
 # Speculation/failure :instrument
 # Speculation::Test/caller "(pry):69:in `score'"
@@ -189,7 +189,7 @@ S.exercise_fn method(:exact_matches), 10, S.get_spec(method(:match_count))
 
 STest.check_method method(:exact_matches), S.get_spec(method(:match_count))
 
-# {:spec=>Speculation::FSpec(main.match_count), :"Speculation::Test/ret"=>{:num_tests=>1000, :result=>true}, :method=>#<Method: main.exact_matches>}
+# {:spec=>Speculation::FSpec(main.match_count), :ret=>{:num_tests=>1000, :result=>true}, :method=>#<Method: main.exact_matches>}
 
 STest.instrument method(:exact_matches), :spec => { method(:exact_matches) => S.get_spec(method(:match_count)) }
 
@@ -202,7 +202,7 @@ S.exercise_fn method(:score)
 
 STest.check method(:score)
 
-# [{:spec=>Speculation::FSpec(main.score), :"Speculation::Test/ret"=>{:num_tests=>1000, :result=>true}, :method=>#<Method: main.score>}]
+# [{:spec=>Speculation::FSpec(main.score), :ret=>{:num_tests=>1000, :result=>true}, :method=>#<Method: main.score>}]
 
 def self.all_matches(secret, guess)
   frequencies = ->(xs) { xs.group_by(&:itself).transform_values(&:count) }

data/examples/game_of_life.rb

@@ -0,0 +1,120 @@
+require "bundler/setup"
+require "speculation"
+require "speculation/gen"
+require "speculation/test"
+
+S = Speculation
+STest = S::Test
+Gen = S::Gen
+
+S.def :"gol/coordinate", S.with_gen(Integer) { S.gen(S.int_in(-5..5)) }
+S.def :"gol/cell", S.tuple(:"gol/coordinate", :"gol/coordinate")
+S.def :"gol/world", S.coll_of(:"gol/cell", :kind => Set)
+
+def self.neighbours(cell)
+  cell_x, cell_y = cell
+  (-1..1).repeated_permutation(2).map { |(x, y)| [cell_x - x, cell_y - y] }.to_set
+  block - Set[cell]
+end
+
+def self.cell_distance(cell_a, cell_b)
+  [
+    (cell_a[0] - cell_b[0]).abs,
+    (cell_a[1] - cell_b[1]).abs
+  ]
+end
+
+S.fdef method(:neighbours),
+  :args => S.cat(:cell => :"gol/cell"),
+  :ret  => S.coll_of(:"gol/cell", :count => 8, :kind => Set),
+  :fn   => ->(fn) {
+    cell = fn[:args][:cell]
+    neighbours = fn[:ret]
+    neighbours.all? { |neighbour| [[1, 0], [0, 1], [1, 1]].include?(cell_distance(cell, neighbour)) }
+  }
+
+S.exercise_fn(method(:neighbours))
+STest.instrument(method(:neighbours))
+# STest.summarize_results STest.check(method(:neighbours))
+
+def self.alive_neighbours(world, cell)
+  neighbours(cell).intersection(world)
+end
+
+def self.alive?(world, cell)
+  world.include?(cell)
+end
+
+def self.tick(world)
+  world.
+    flat_map { |cell| neighbours(cell).to_a }.
+    select { |cell|
+      alive_neighbour_count = alive_neighbours(world, cell).count
+
+      if alive?(world, cell)
+        (2..3).cover?(alive_neighbour_count)
+      else
+        alive_neighbour_count == 3
+      end
+    }.
+    to_set
+end
+
+S.fdef method(:tick),
+  :args => S.cat(:world => :"gol/world"),
+  :ret  => :"gol/world"
+
+S.exercise_fn(method(:tick))
+STest.instrument(method(:tick))
+# STest.check(method(:tick))
+
+def self.simulation(world)
+  Enumerator.new do |yielder|
+    loop do
+      yielder << world
+      world = tick(world)
+    end
+  end
+end
+
+def self.serialize_world(world)
+  return [[]] if world.empty?
+
+  min_y, max_y = world.minmax_by(&:last).map(&:last)
+  min_x, max_x = world.minmax_by(&:first).map(&:first)
+
+  (min_y.pred..max_y.next).map { |y| (min_x.pred..max_x.next).map { |x| world.include?([x, y]) } }
+end
+
+S.fdef method(:serialize_world),
+  :args => S.cat(:world => :"gol/world"),
+  :ret  => S.coll_of(S.coll_of(:"Speculation/boolean")),
+  :fn   => ->(fn) { fn[:ret].flatten.count(&:itself) == fn[:args][:world].count }
+
+def self.print_world(world, out)
+  world.each do |line|
+    line.each do |cell|
+      if cell
+        out << "\u2588"
+      else
+        out << "\u2591"
+      end
+    end
+
+    out << "\n"
+  end
+
+  nil
+end
+
+init = Gen.generate(S.gen(:"gol/world"))
+worlds = simulation(init).lazy.take_while { |world| !world.empty? }
+
+worlds.first(10).each do |world|
+  print "\033[2J"
+  puts world.sort.to_s
+  print_world(serialize_world(world), STDOUT)
+  sleep 0.5
+end
+
+# STest.summarize_results STest.check