speculation 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: b293a72669d39d6366f5c1f42a3112fdfa03e6c5
-  data.tar.gz: a90bc4265285e116cb93978928546a0f9f18256e
+  metadata.gz: 19dd9abfde4552ea62d19dda2714f9dd0e6f33a8
+  data.tar.gz: 112bed767778c508470b5d3303937580158bd649
 SHA512:
-  metadata.gz: 7c0f3352a89d81340eaf8ddd583b8d5f2dcaeb68a1da4d025f4af680a0edc5aba522cfeb997152484753ee072217efd3bb64877e297937e03af16852779f751e
-  data.tar.gz: d4a90effba95011da873b7aa3c03d496a59379dd7d890c0aaf5e3101a0ec2a1e8ef9840710c13e257f10ecbef7144457679b47e7a14acafd8bb92a8835f6e572
+  metadata.gz: 1e0d5b36cb7c3e868004e4e62b408bc1a80c144759791c2ae138fefcef90a345106fde0780c7ac8b1fee36c0049c3e8f922af8a72e9ceeed9c133337d494514f
+  data.tar.gz: fb3eb18c1a8a4e1be72a0223f30c11dd05170a1b9225bfd73bebb6a2f27bda4255d51ae952597bf5bf3dd8301ce6990cac1fbe481d3897caf9f54e5b531cc7ef

data/.rubocop.yml

@@ -3,6 +3,7 @@ AllCops:
     - 'bin/*'
     - '*.*'
     - 'vendor/**/*'
+    - 'examples/**/*'
   TargetRubyVersion: 2.4
 
 Metrics/ClassLength:
@@ -85,3 +86,15 @@ Style/NumericLiterals:
 
 Style/NumericPredicate:
   Enabled: false
+
+Style/SpecialGlobalVars:
+  Enabled: false
+
+Style/RescueModifier:
+  Enabled: false
+
+Performance/RedundantBlockCall:
+  Enabled: false
+
+Style/MethodName:
+  Enabled: false

data/.travis.yml

@@ -2,6 +2,8 @@ sudo: false
 language: ruby
 cache: bundler
 rvm:
+  - 2.0.0
+  - 2.1.10
   - 2.2.6
   - 2.3.3
   - 2.4.0
@@ -10,7 +12,3 @@ rvm:
 before_install:
   - gem update --system
   - gem install bundler
-matrix:
-  allow_failures:
-    - rvm: 2.2.6
-    - rvm: jruby-9.0.5.0

data/README.md

@@ -1,6 +1,6 @@
-# Speculation
+# Speculation [![Build Status](https://travis-ci.org/english/speculation.svg?branch=master)](https://travis-ci.org/english/speculation)
 
-A Ruby port of Clojure's `clojure.spec`. See [clojure.spec - Rationale and Overview](https://clojure.org/about/spec). The `Speculation` library is largely a copy-and-paste from `clojure.spec`. All credit goes to the clojure.spec authors.
+A Ruby port of Clojure's `clojure.spec`. See [clojure.spec - Rationale and Overview](https://clojure.org/about/spec). All advantages/disadvantages for clojure.spec should apply to Speculation too. This library is largely a copy-and-paste from clojure.spec so all credit goes to the clojure.spec authors.
 
 ## Installation
 
@@ -18,9 +18,18 @@ Or install it yourself as:
 
     $ gem install speculation
 
+## Project Goals
+
+The goal of this project is to match clojure.spec as closely as possible, from design to features to API. This decision comes with the trade-off that the library may not necessarily be idiomatic Ruby, however there's nothing stopping other libraries from being built atop Speculation to bring a more Ruby-like feel. This library won't introduce features that do not exist in clojure.spec.
+
+## Examples
+
+- [spec_guide.rb](examples/spec_guide.rb): Speculation port of Clojure's [spec guide](https://clojure.org/guides/spec)
+- [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)
+
 ## 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:
+The API is more-or-less the same as `clojure.spec`. If you're already familiar with 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
 
@@ -35,25 +44,25 @@ S.valid?(/^\d+$/, "123")
 S.valid?(Set[:foo, :bar, :baz], :foo)
 ```
 
-### Namespaced keywords
+### Namespaced keywords/symbols
 
 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:
+In order keep the global spec registry architecture in Speculation, we utilise a helper method `ns` achieve similar behaviour:
 
 ```rb
-using Speculation::NamespacedSymbols.refine(MyModule)
+extend Speculation::NamespacedSymbols
 
-p :foo.ns
+p ns(:foo)
 # => :"MyModule/foo"
 
-p :foo.ns(AnotherModule)
+p ns(AnotherModule, :foo)
 # => :"AnotherModule/foo"
 ```
 
 ### FSpecs
 
-#### Symbols
+#### Symbols/Methods
 
 Clojure uses Symbols to refer to functions. To refer to a method in Ruby, we must use the `method` method.
 
@@ -96,8 +105,6 @@ Bug reports and pull requests are welcome on GitHub at https://github.com/englis
 ## TODO
 
 - tidy up tests
-- write up comparison with clojure.spec
-- write guide
 
 ### clojure.spec features
 
@@ -108,7 +115,10 @@ Bug reports and pull requests are welcome on GitHub at https://github.com/englis
 
 ### Improvements
 
-- Find/build an alternative to Rantly
+- 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](https://github.com/pry/pry/wiki/Documentation-browsing)?
 - Profile and optimise
 
 ## License

data/Rakefile

@@ -9,17 +9,13 @@ task :rubocop do
 end
 
 task :test do
-  if RUBY_PLATFORM == "java"
-    $LOAD_PATH.unshift(File.expand_path("../test", __FILE__))
+  $LOAD_PATH.unshift(File.expand_path("../test", __FILE__))
 
-    FileList["test/**/*.rb"].each do |test_file|
-      require "./#{test_file}"
-    end
-
-    raise unless Minitest.run
-  else
-    sh "TEST_QUEUE_SPLIT_GROUPS=1 bundle exec ruby -r minitest/autorun -I test -S minitest-queue $(find test -name *_test.rb)"
+  FileList["test/**/*.rb"].each do |test_file|
+    require "./#{test_file}"
   end
+
+  raise unless Minitest.run
 end
 
 task :doc do

data/bin/console

@@ -3,11 +3,11 @@
 $LOAD_PATH.unshift File.expand_path("../../test", __FILE__)
 
 require "bundler/setup"
+require "pry"
 require 'rubocop'
 require "speculation"
 require "speculation/test"
 require "speculation/gen"
-require "speculation/utils_specs"
 
 def reload!
   Minitest::Test.reset
@@ -18,7 +18,6 @@ def reload!
   end
 
   load "./lib/speculation/namespaced_symbols.rb"
-  load "./lib/speculation/conj.rb"
   load "./lib/speculation/pmap.rb"
   load "./lib/speculation/identifier.rb"
   load "./lib/speculation/utils.rb"
@@ -33,7 +32,6 @@ def reload!
   load "./lib/speculation.rb"
   load "./lib/speculation/gen.rb"
   load "./lib/speculation/test.rb"
-  load "./lib/speculation/utils_specs.rb"
 
   Dir["test/**/*.rb"].each do |f|
     load f
@@ -44,7 +42,7 @@ def reload!
   Object.const_set(:Gen, Speculation::Gen)
   Object.const_set(:U, Speculation::Utils)
 
-  # STest.instrument
+  STest.instrument
 end
 
 def t
@@ -61,10 +59,59 @@ require "minitest"
 include Minitest::Assertions
 def self.assertions; 1; end
 def self.assertions=(_x); end
-using Speculation::NamespacedSymbols.refine(self)
+
+extend Speculation::NamespacedSymbols
+
+def self.test_check_utils
+  S.fdef(U.method(:hash?),
+         :args => S.tuple(ns(S, :any)),
+         :ret  => ns(S, :boolean))
+
+  S.fdef(U.method(:array?),
+         :args => S.tuple(ns(S, :any)),
+         :ret  => ns(S, :boolean))
+
+  S.fdef(U.method(:collection?),
+         :args => S.tuple(ns(S, :any)),
+         :ret  => ns(S, :boolean))
+
+  S.fdef(U.method(:itself),
+         :args => S.cat(:x => ns(S, :any)),
+         :ret  => ns(S, :any),
+         :fn   => ->(x) { x[:args][:x].equal?(x[:ret]) })
+
+  # S.fdef(U.method(:complement),
+  #        :args  => ns(S, :empty),
+  #        :block => S.fspec(:args => S.zero_or_more(ns(S, :any)),
+  #                          :ret  => ns(S, :any)),
+  #        :ret   => S.fspec(:args => S.zero_or_more(ns(S, :any)),
+  #                          :ret  => ns(S, :boolean)))
+
+  S.fdef(U.method(:constantly),
+         :args => S.cat(:x => ns(S, :any)),
+         :ret  => Proc,
+         :fn   => ->(x) { x[:args][:x].equal?(x[:ret].call) })
+
+  S.fdef(U.method(:distinct?),
+         :args => S.cat(:coll => Enumerable),
+         :ret  => ns(S, :boolean))
+
+  S.fdef(U.method(:ident?),
+         :args => S.cat(:x => ns(S, :any)),
+         :ret  => ns(S, :boolean))
+
+  S.fdef(U.method(:method?),
+         :args => S.cat(:x => ns(S, :any)),
+         :ret  => ns(S, :boolean))
+
+  S.fdef(U.method(:empty),
+         :args => S.cat(:coll => Enumerable),
+         :ret  => S.and(Enumerable, ->(coll) { coll.empty? }),
+         :fn   => ->(x) { x[:args][:coll].class == x[:ret].class })
+
+  STest.summarize_results(STest.check(STest.enumerate_methods(Speculation::Utils), :num_tests => 50))
+end
 
 reload!
 
-# (If you use this, don't forget to add pry to your Gemfile!)
-require "pry"
 Pry.start

data/examples/codebreaker.rb

@@ -0,0 +1,246 @@
+# frozen_string_literal: true
+# See http://blog.cognitect.com/blog/2016/10/5/interactive-development-with-clojurespec
+
+require "bundler/inline"
+require "set"
+
+gemfile true do
+  gem "speculation",
+      :git     => "https://github.com/english/speculation.git",
+      :require => ["speculation", "speculation/test", "speculation/gen"]
+end
+
+S = Speculation
+Gen = S::Gen
+STest = S::Test
+
+extend Speculation::NamespacedSymbols
+
+peg = Set[:y, :g, :r, :c, :w, :b]
+
+S.def ns(:code), S.coll_of(peg, :min_count => 4, :max_count => 6)
+
+def score; end
+
+S.fdef method(:score),
+       :args => S.cat(:secret => ns(:code), :guess => ns(:code))
+
+S.exercise S.get_spec(method(:score)).args
+
+# [[[[:c, :g, :y, :w, :g, :y], [:y, :y, :c, :r, :y, :y]], {:secret=>[:c, :g, :y, :w, :g, :y], :guess=>[:y, :y, :c, :r, :y, :y]}],
+#  [[[:b, :b, :y, :y], [:b, :r, :y, :y, :y]], {:secret=>[:b, :b, :y, :y], :guess=>[:b, :r, :y, :y, :y]}],
+#  [[[:y, :y, :w, :g, :r, :w], [:r, :w, :c, :b, :r, :y]], {:secret=>[:y, :y, :w, :g, :r, :w], :guess=>[:r, :w, :c, :b, :r, :y]}],
+#  ...
+
+S.fdef method(:score),
+       :args => S.and(S.cat(:secret => ns(:code), :guess => ns(:code)),
+                      ->(args) { args[:secret].count == args[:guess].count })
+
+S.exercise S.get_spec(method(:score)).args
+
+# [[[[:b, :w, :b, :c, :b], [:y, :r, :y, :y, :b]], {:secret=>[:b, :w, :b, :c, :b], :guess=>[:y, :r, :y, :y, :b]}],
+#  [[[:c, :y, :w, :c], [:c, :r, :c, :c]], {:secret=>[:c, :y, :w, :c], :guess=>[:c, :r, :c, :c]}],
+#  [[[:g, :g, :y, :g], [:b, :y, :w, :b]], {:secret=>[:g, :g, :y, :g], :guess=>[:b, :y, :w, :b]}],
+#  ...
+
+S.def ns(:exact_matches), ns(S, :natural_integer)
+S.def ns(:loose_matches), ns(S, :natural_integer)
+
+S.fdef method(:score),
+       :args => S.and(S.cat(:secret => ns(:code), :guess => ns(:code)),
+                      ->(args) { args[:secret].count == args[:guess].count }),
+       :ret  => S.keys(:req => [ns(:exact_matches), ns(:loose_matches)])
+
+S.exercise S.get_spec(method(:score)).ret
+# [[{:"main/exact_matches"=>301501626008109845, :"main/loose_matches"=>1592567845535536138},
+#   {:"main/exact_matches"=>301501626008109845, :"main/loose_matches"=>1592567845535536138}],
+#  [{:"main/exact_matches"=>705260057025726755, :"main/loose_matches"=>4979282811122408}, {:"main/exact_matches"=>705260057025726755, :"main/loose_matches"=>4979282811122408}],
+#  [{:"main/exact_matches"=>905565787875512744, :"main/loose_matches"=>965211463791348650},
+# ...
+
+S.fdef method(:score),
+       :args => S.and(S.cat(:secret => ns(:code), :guess => ns(:code)),
+                      ->(args) { args[:secret].count == args[:guess].count }),
+       :ret  => S.keys(:req => [ns(:exact_matches), ns(:loose_matches)]),
+       :fn   => ->(fn) {
+         sum_matches = fn[:ret].values.reduce(&:+)
+         sum_matches.between?(0, fn[:args][:secret].count)
+       }
+
+def self.score(secret, guess)
+  { ns(:exact_matches) => 0,
+    ns(:loose_matches) => 0 }
+end
+
+STest.check method(:score)
+# [{:spec=>Speculation::FSpec(main.score), :"Speculation::Test/ret"=>{:num_tests=>1000, :result=>true}, :method=>#<Method: main.score>}]
+
+def self.score(secret, guess)
+  { ns(:exact_matches) => 4,
+    ns(:loose_matches) => 3 }
+end
+
+# STest.check method(:score)
+
+# [{:spec=>Speculation::FSpec(main.score),
+#   :"Speculation::Test/ret"=>
+#    {:fail=>[[:y, :b, :r, :r, :b], [:y, :w, :g, :r, :g]],
+#     :block=>nil,
+#     :num_tests=>1,
+#     :result=>
+#      #<Speculation::Error: {:"Speculation/problems"=>
+#   [{:path=>[:fn],
+#     :val=>
+#      {:args=>{:secret=>[:y, :b, :r, :r, :b], :guess=>[:y, :w, :g, :r, :g]},
+#       :block=>nil,
+#       :ret=>{:"main/exact_matches"=>4, :"main/loose_matches"=>3}},
+#     :via=>[],
+
+def self.score(secret, guess)
+  { ns(:exact_matches) => secret.zip(guess).count { |(a, b)| a.equal?(b) },
+    ns(:loose_matches) => 0 }
+end
+
+S.exercise_fn method(:score)
+
+# [[[[:c, :w, :r, :c, :c, :b], [:c, :y, :y, :r, :c, :b]], {:"main/exact_matches"=>3, :"main/loose_matches"=>0}],
+#  [[[:r, :g, :w, :c, :y], [:y, :w, :r, :w, :r]], {:"main/exact_matches"=>0, :"main/loose_matches"=>0}],
+#  [[[:b, :b, :r, :b, :r], [:b, :g, :c, :c, :g]], {:"main/exact_matches"=>1, :"main/loose_matches"=>0}],
+#  [[[:g, :r, :b, :y], [:g, :c, :r, :w]], {:"main/exact_matches"=>1, :"main/loose_matches"=>0}],
+
+STest.check method(:score)
+
+# [{:spec=>Speculation::FSpec(main.score), :"Speculation::Test/ret"=>{:num_tests=>1000, :result=>true}, :method=>#<Method: main.score>}]
+
+def self.score(secret, guess)
+  { ns(:exact_matches) => exact_matches(secret, guess),
+    ns(:loose_matches) => 0 }
+end
+
+def self.exact_matches(secret, guess)
+  secret.zip(guess).count { |(a, b)| a.equal?(b) }
+end
+
+S.def ns(:secret_and_guess), S.and(S.cat(:secret => ns(:code), :guess => ns(:code)),
+                                   ->(args) { args[:secret].count == args[:guess].count })
+
+S.fdef method(:score),
+       :args => ns(:secret_and_guess),
+       :ret  => S.keys(:req => [ns(:exact_matches), ns(:loose_matches)]),
+       :fn   => ->(fn) {
+         sum_matches = fn[:ret].values.reduce(&:+)
+         sum_matches.between?(0, fn[:args][:secret].count)
+       }
+
+S.fdef method(:exact_matches),
+       :args => ns(:secret_and_guess),
+       :ret  => ns(S, :natural_integer),
+       :fn   => ->(fn) { fn[:ret].between?(0, fn[:args][:secret].count) }
+
+S.exercise_fn method(:exact_matches)
+
+# [[[[:g, :b, :b, :b, :c], [:w, :y, :c, :y, :b]], 0],
+#  [[[:c, :w, :r, :c], [:y, :r, :y, :g]], 0],
+#  [[[:g, :c, :g, :g, :y], [:g, :g, :c, :c, :r]], 1],
+#  [[[:g, :r, :y, :g, :g], [:g, :y, :y, :r, :w]], 2],
+
+STest.check method(:exact_matches)
+# [{:spec=>Speculation::FSpec(main.exact_matches), :"Speculation::Test/ret"=>{:num_tests=>1000, :result=>true}, :method=>#<Method: main.exact_matches>}]
+
+STest.instrument method(:exact_matches)
+S.exercise_fn method(:score)
+
+# [[[[:y, :r, :y, :r], [:g, :w, :b, :g]], {:"main/exact_matches"=>0, :"main/loose_matches"=>0}],
+#  [[[:c, :g, :g, :y, :b, :c], [:w, :y, :g, :b, :y, :c]], {:"main/exact_matches"=>2, :"main/loose_matches"=>0}],
+#  [[[:r, :b, :r, :g, :w, :r], [:c, :w, :y, :g, :g, :y]], {:"main/exact_matches"=>1, :"main/loose_matches"=>0}],
+#  [[[:r, :y, :c, :y, :y, :b], [:g, :r, :b, :c, :r, :y]], {:"main/exact_matches"=>0, :"main/loose_matches"=>0}],
+
+def self.score(secret, guess)
+  { ns(:exact_matches) => exact_matches(secret, guess.take(3)),
+    ns(:loose_matches) => 0 }
+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]]
+# Speculation/args [[:r, :b, :c, :y, :b, :r], [:w, :y, :c]]
+# Speculation/failure :instrument
+# Speculation::Test/caller "(pry):69:in `score'"
+
+def self.score(secret, guess)
+  { ns(:exact_matches) => exact_matches(secret, guess),
+    ns(:loose_matches) => 0 }
+end
+
+def match_count; end
+
+S.fdef method(:match_count),
+       :args => ns(:secret_and_guess),
+       :ret  => ns(S, :natural_integer),
+       :fn   => ->(fn) { fn[:ret].between?(0, fn[:args][:secret].count) }
+
+S.exercise_fn method(:exact_matches), :n => 10, :fspec => S.get_spec(method(:match_count))
+
+# [[[[:r, :b, :g, :w, :b], [:b, :c, :c, :r, :w]], 0],
+#  [[[:c, :r, :c, :g, :g, :y], [:y, :c, :b, :y, :y, :r]], 0],
+#  [[[:c, :g, :r, :y, :y], [:w, :y, :y, :c, :w]], 0],
+
+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>}
+
+STest.instrument method(:exact_matches), :spec => { method(:exact_matches) => S.get_spec(method(:match_count)) }
+
+S.exercise_fn method(:score)
+
+# [[[[:y, :r, :y, :c, :y], [:b, :w, :c, :g, :b]], {:"main/exact_matches"=>0, :"main/loose_matches"=>0}],
+#  [[[:r, :b, :w, :c, :w, :y], [:w, :r, :w, :g, :b, :r]], {:"main/exact_matches"=>1, :"main/loose_matches"=>0}],
+#  [[[:c, :w, :r, :w, :g, :c], [:g, :g, :c, :c, :c, :b]], {:"main/exact_matches"=>0, :"main/loose_matches"=>0}],
+
+STest.check method(:score)
+
+# [{:spec=>Speculation::FSpec(main.score), :"Speculation::Test/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) }
+  select_keys = ->(h, ks) { Hash[ks.zip(h.values_at(*ks))].compact }
+
+  select_keys.call(frequencies.call(secret), guess).
+    merge(select_keys.call(frequencies.call(guess), secret)) { |k, a, b| [a, b].min }.
+    values.
+    reduce(0, &:+)
+end
+
+S.exercise_fn method(:all_matches), :n => 10, :fspec => S.get_spec(method(:match_count))
+
+# [[[[:c, :b, :w, :w], [:b, :c, :g, :y]], 2],
+#  [[[:y, :r, :g, :r, :b], [:r, :g, :w, :b, :r]], 4],
+#  [[[:r, :g, :r, :g, :g], [:r, :g, :g, :b, :c]], 3],
+
+def self.score(secret, guess)
+  exact = exact_matches(secret, guess)
+  all = all_matches(secret, guess)
+
+  { ns(:exact_matches) => exact,
+    ns(:loose_matches) => all - exact }
+end
+
+STest.instrument [method(:exact_matches), method(:all_matches)],
+                 :spec => { method(:exact_matches) => S.get_spec(method(:exact_matches)),
+                            method(:all_matches)   => S.get_spec(method(:exact_matches)) }
+
+S.exercise_fn method(:score)
+# [[[[:w, :r, :w, :c, :c, :c], [:r, :y, :r, :w, :c, :b]], {:"main/exact_matches"=>1, :"main/loose_matches"=>2}],
+#  [[[:r, :c, :w, :y, :c], [:g, :c, :y, :y, :y]], {:"main/exact_matches"=>2, :"main/loose_matches"=>0}],
+#  [[[:y, :y, :b, :g, :b], [:g, :w, :b, :c, :g]], {:"main/exact_matches"=>1, :"main/loose_matches"=>1}],
+#  [[[:c, :b, :r, :y, :g], [:g, :w, :r, :y, :y]], {:"main/exact_matches"=>2, :"main/loose_matches"=>1}],
+
+STest.summarize_results STest.check method(:score)
+
+# {:total=>1, :check_passed=>1}
+
+result = STest.summarize_results STest.check(method(:score))
+result[:total] == result[:check_passed] && !result.key?(:check_failed)
+
+# true