speculation 0.4.0 → 0.4.2

data/examples/sinatra-web-app/Gemfile

@@ -3,5 +3,5 @@ gem 'sinatra'
 gem 'sequel'
 gem 'bcrypt'
 gem 'sqlite3'
-gem 'speculation', :git => "https://github.com/english/speculation.git", :ref => "ae3ee09"
+gem 'speculation', :path => File.expand_path('../../..', __FILE__)
 gem 'pry'

data/examples/sinatra-web-app/Gemfile.lock

@@ -1,9 +1,7 @@
-GIT
-  remote: https://github.com/english/speculation.git
-  revision: ae3ee095765816a8d5bfa5b29c808439f04633b0
-  ref: ae3ee09
+PATH
+  remote: /Users/jamie/Projects/speculation
   specs:
-    speculation (0.2.0)
+    speculation (0.4.1)
       concurrent-ruby (~> 1.0)
       rantly (~> 1.0)
 

data/examples/sinatra-web-app/app.rb

@@ -64,7 +64,7 @@ module User
 
   def self.serialize_validation_errors(user)
     data = S.explain_data(ns(:user), user)
-    data[ns(S, :problems)].map { |problem| Validation.serialize_problem(problem) }
+    data[:problems].map { |problem| Validation.serialize_problem(problem) }
   end
 
   def self.fake
@@ -121,7 +121,7 @@ module User
 
     USER_ERROR_MESSAGE_MAP = {
       [] => {
-        S::Utils.method(:key?) => ->(args) {
+        S::Predicates.method(:key?) => ->(args) {
           key = args.first
           if key == S.or_keys(:email, :username)
             "email or username is required"
@@ -146,8 +146,8 @@ module User
     }
   end
 
-  S.def ns(:email), S.with_gen(S.and(String, Validation::EMAIL_REGEX), Generators.method(:email))
-  S.def ns(:username), S.with_gen(S.and(String, Validation.method(:validate_username_length)), Generators.method(:username))
-  S.def ns(:password), S.with_gen(S.and(String, Validation.method(:validate_password_length), Validation.method(:validate_password_complexity)), Generators.method(:password))
+  S.def ns(:email), S.with_gen(S.and(String, Validation::EMAIL_REGEX)) { Generators.method(:email) }
+  S.def ns(:username), S.with_gen(S.and(String, Validation.method(:validate_username_length))) { Generators.method(:username) }
+  S.def ns(:password), S.with_gen(S.and(String, Validation.method(:validate_password_length), Validation.method(:validate_password_complexity))) { Generators.method(:password) }
   S.def ns(:user), S.keys(:req_un => [S.or_keys(ns(:email), ns(:username)), ns(:password)])
 end

data/examples/spec_guide.rb

@@ -155,7 +155,7 @@ S.explain ns(:name_or_id), :foo
 # as a string or explain_data to receive the errors as data.
 
 S.explain_data ns(:name_or_id), :foo
-# => {:"Speculation/problems"=>
+# => {:problems=>
 #      [{:path=>[:name],
 #        :val=>:foo,
 #        :via=>[:"Object/name_or_id"],
@@ -214,8 +214,8 @@ S.valid? ns(:person), ns(:first_name) => "Elon", ns(:last_name) => "Musk", ns(:e
 
 # Fails required key check
 S.explain ns(:person), ns(:first_name) => "Elon"
-# >> val: {:"Object/first_name"=>"Elon"} fails spec: :"Object/person" predicate: [#<Method: Speculation::Utils.key?>, [:"Object/last_name"]]
-# >> val: {:"Object/first_name"=>"Elon"} fails spec: :"Object/person" predicate: [#<Method: Speculation::Utils.key?>, [:"Object/email"]]
+# >> val: {:"Object/first_name"=>"Elon"} fails spec: :"Object/person" predicate: [#<Method: Speculation::Predicates.key?>, [:"Object/last_name"]]
+# >> val: {:"Object/first_name"=>"Elon"} fails spec: :"Object/person" predicate: [#<Method: Speculation::Predicates.key?>, [:"Object/email"]]
 
 # Fails attribute conformance
 S.explain ns(:person), ns(:first_name) => "Elon", ns(:last_name) => "Musk", ns(:email) => "n/a"
@@ -248,8 +248,8 @@ S.explain :"unq/person", :first_name => "Elon", :last_name => "Musk", :email =>
 # >> In: [:email] val: "n/a" fails spec: :"Object/email_type" at: [:email] predicate: [/^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,63}$/, ["n/a"]]
 
 S.explain :"unq/person", :first_name => "Elon"
-# >> val: {:first_name=>"Elon"} fails spec: :"unq/person" predicate: [#<Method: Speculation::Utils.key?>, [:"Object/last_name"]]
-# >> val: {:first_name=>"Elon"} fails spec: :"unq/person" predicate: [#<Method: Speculation::Utils.key?>, [:"Object/email"]]
+# >> val: {:first_name=>"Elon"} fails spec: :"unq/person" predicate: [#<Method: Speculation::Predicates.key?>, [:"Object/last_name"]]
+# >> val: {:first_name=>"Elon"} fails spec: :"unq/person" predicate: [#<Method: Speculation::Predicates.key?>, [:"Object/email"]]
 
 # Unqualified keys can also be used to validate record attributes - don't support
 # Keyword args keys* - don't support
@@ -301,7 +301,7 @@ S.conform ns(:vnum3), [1, 2, 3] # => #<Set: {1, 2, 3}>
 S.explain ns(:vnum3), Set[1, 2, 3] # not an array
 # >> val: #<Set: {1, 2, 3}> fails spec: :"Object/vnum3" predicate: [Array, [#<Set: {1, 2, 3}>]]
 S.explain ns(:vnum3), [1, 1, 1] # not distinct
-# >> val: [1, 1, 1] fails spec: :"Object/vnum3" predicate: [#<Method: Speculation::Utils.distinct?>, [[1, 1, 1]]]
+# >> val: [1, 1, 1] fails spec: :"Object/vnum3" predicate: [#<Method: Speculation::Predicates.distinct?>, [[1, 1, 1]]]
 S.explain ns(:vnum3), [1, 2, :a] # not a number
 # >> In: [2] val: :a fails spec: :"Object/vnum3" predicate: [Numeric, [:a]]
 
@@ -499,15 +499,15 @@ end
 S.check_asserts = true
 person_name 100 rescue $!
 # => #<Speculation::Error: Spec assertion failed
-#    val: 100 fails predicate: [#<Method: Speculation::Utils.hash?>, [100]]
+#    val: 100 fails predicate: [#<Method: Speculation::Predicates.hash?>, [100]]
 #    Speculation/failure :assertion_failed
-#     {:"Speculation/problems"=>
+#     {:problems=>
 #      [{:path=>[],
-#        :pred=>[#<Method: Speculation::Utils.hash?>, [100]],
+#        :pred=>[#<Method: Speculation::Predicates.hash?>, [100]],
 #        :val=>100,
 #        :via=>[],
 #        :in=>[]}],
-#     :"Speculation/failure"=>:assertion_failed}
+#     :failure=>:assertion_failed}
 #    >
 
 # A deeper level of integration is to call conform and use the return value to
@@ -925,7 +925,7 @@ S.exercise_fn(method(:ranged_rand))
 # predicate implicitly presumes values of a particular type but the spec does
 # not specify them:
 
-Gen.generate S.gen(:even?.to_proc) rescue $! # => #<Speculation::Error: unable to construct gen at: [] for: Speculation::Spec(#<Proc:0x007fb69b1908f8(&:even?)>) {:"Speculation/failure"=>:no_gen, :"Speculation/path"=>[]}\n>
+Gen.generate S.gen(:even?.to_proc) rescue $! # => #<Speculation::Error: unable to construct gen at: [] for: Speculation::Spec(#<Proc:0x007fb69b1908f8(&:even?)>) {:failure=>:no_gen, :"Speculation/path"=>[]}\n>
 
 # In this case spec was not able to find a generator for the even? predicate.
 # Most of the primitive generators in spec are mapped to the common type
@@ -1013,8 +1013,10 @@ Gen.sample sym_gen, 5
 # To redefine our spec using this custom generator, use with_gen which takes a
 # spec and a replacement generator as a block:
 
-gen = S.gen(Set[:"my.domain/name", :"my.domain/occupation", :"my.domain/id"])
-S.def(ns(:syms), S.with_gen(S.and(Symbol, ->(s) { S::NamespacedSymbols.namespace(s) == "my.domain" }), gen))
+syms_spec = S.with_gen(S.and(Symbol, ->(s) { S::NamespacedSymbols.namespace(s) == "my.domain" })) do
+  S.gen(Set[:"my.domain/name", :"my.domain/occupation", :"my.domain/id"])
+end
+S.def ns(:syms), syms_spec
 
 S.valid? ns(:syms), :"my.domain/name"
 Gen.sample S.gen(ns(:syms)), 5
@@ -1025,7 +1027,7 @@ Gen.sample S.gen(ns(:syms)), 5
 #     :"my.domain/id"]
 
 # Note that with_gen (and other places that take a custom generator) take a
-# one-arg function that returns the generator, allowing it to be lazily
+# no-arg block that returns the generator, allowing it to be lazily
 # realized.
 
 # One downside to this approach is we are missing what property testing is
@@ -1048,11 +1050,14 @@ Gen.sample sym_gen_2, 5 # => [:"my.domain/hLZnEpj", :"my.domain/kvy", :"my.domai
 # Returning to our "hello" example, we now have the tools to make that
 # generator:
 
-S.def ns(:hello), S.with_gen(->(s) { s.include?("hello") }, ->(rantly) {
-  s1 = rantly.sized(rantly.range(0, 10)) { rantly.string(:alpha) }
-  s2 = rantly.sized(rantly.range(0, 10)) { rantly.string(:alpha) }
-  "#{s1}hello#{s2}"
-})
+hello_spec = S.with_gen(->(s) { s.include?("hello") }) do
+  ->(rantly) {
+    s1 = rantly.sized(rantly.range(0, 10)) { rantly.string(:alpha) }
+    s2 = rantly.sized(rantly.range(0, 10)) { rantly.string(:alpha) }
+    "#{s1}hello#{s2}"
+  }
+end
+S.def ns(:hello), hello_spec
 
 Gen.sample S.gen(ns(:hello))
 # => ["XRLhtLshelloaY",
@@ -1136,7 +1141,7 @@ ranged_rand 8, 5 rescue $!
 #    Speculation/args [8, 5]
 #    Speculation/failure :instrument
 #    Speculation::Test/caller "/var/folders/4l/j2mycv0j4rx7z47sp01r93vc3kfxzs/T/seeing_is_believing_temp_dir20170304-91770-1jtmc1y/program.rb:901:in `<main>'"
-#     {:"Speculation/problems"=>
+#     {:problems=>
 #      [{:path=>[:args],
 #        :val=>{:start=>8, :end=>5},
 #        :via=>[],
@@ -1144,9 +1149,9 @@ ranged_rand 8, 5 rescue $!
 #        :pred=>
 #         [#<Proc:0x007fb69a8a0fb8@/var/folders/4l/j2mycv0j4rx7z47sp01r93vc3kfxzs/T/seeing_is_believing_temp_dir20170304-91770-1jtmc1y/program.rb:548 (lambda)>,
 #          [{:start=>8, :end=>5}]]}],
-#     :"Speculation/args"=>[8, 5],
-#     :"Speculation/failure"=>:instrument,
-#     :"Speculation::Test/caller"=>
+#     :args=>[8, 5],
+#     :failure=>:instrument,
+#     :caller=>
 #      "/var/folders/4l/j2mycv0j4rx7z47sp01r93vc3kfxzs/T/seeing_is_believing_temp_dir20170304-91770-1jtmc1y/program.rb:901:in `<main>'"}
 #    >
 
@@ -1172,7 +1177,7 @@ ranged_rand 8, 5 rescue $!
 
 STest.check method(:ranged_rand)
 # => [{:spec=>Speculation::FSpec(main.ranged_rand),
-#      :"Speculation::Test/ret"=>{:num_tests=>1000, :result=>true},
+#      :ret=>{:num_tests=>1000, :result=>true},
 #      :method=>#<Method: main.ranged_rand>}]
 
 # check also takes a number of options ~~that can be passed to test.check to
@@ -1193,7 +1198,7 @@ STest.abbrev_result STest.check(method(:ranged_rand)).first
 # >> {:spec=>"Speculation::FSpec(main.ranged_rand)",
 # >>  :method=>#<Method: main.ranged_rand>,
 # >>  :failure=>
-# >>   {:"Speculation/problems"=>
+# >>   {:problems=>
 # >>     [{:path=>[:fn],
 # >>       :val=>{:args=>{:start=>-1, :end=>0}, :block=>nil, :ret=>0},
 # >>       :via=>[],
@@ -1201,10 +1206,10 @@ STest.abbrev_result STest.check(method(:ranged_rand)).first
 # >>       :pred=>
 # >>        [#<Proc:0x007fb69a8a0c98@/var/folders/4l/j2mycv0j4rx7z47sp01r93vc3kfxzs/T/seeing_is_believing_temp_dir20170304-91770-1jtmc1y/program.rb:551 (lambda)>,
 # >>         [{:args=>{:start=>-1, :end=>0}, :block=>nil, :ret=>0}]]}],
-# >>    :"Speculation::Test/args"=>[-1, 0],
-# >>    :"Speculation::Test/val"=>
+# >>    :args=>[-1, 0],
+# >>    :val=>
 # >>     {:args=>{:start=>-1, :end=>0}, :block=>nil, :ret=>0},
-# >>    :"Speculation/failure"=>:check_failed}}
+# >>    :failure=>:check_failed}}
 
 # check has reported an error in the :fn spec. We can see the arguments passed
 # were -1 and 0 and the return value was -0, which is out of the expected

data/lib/speculation.rb

@@ -12,6 +12,7 @@ require "speculation/version"
 require "speculation/namespaced_symbols"
 require "speculation/method_identifier"
 require "speculation/utils"
+require "speculation/predicates"
 require "speculation/spec"
 require "speculation/error"
 
@@ -22,9 +23,8 @@ module Speculation
     # Enables or disables spec asserts. Defaults to false.
     attr_accessor :check_asserts
 
-    # A soft limit on how many times a branching spec (or/alt/zero_or_more) can
-    # be recursed through during generation.  After this a non-recursive branch
-    # will be chosen.
+    # A soft limit on how many times a branching spec (or/alt/zero_or_more/opt keys) can be recursed
+    # through during generation. After this a non-recursive branch will be chosen.
     attr_accessor :recursion_limit
 
     # The number of times an anonymous fn specified by fspec will be
@@ -47,29 +47,6 @@ module Speculation
 
   @registry_ref = Concurrent::Atom.new({})
 
-  INVALID = ns(:invalid)
-
-  # @private
-  OP = ns(:op)
-  # @private
-  ALT = ns(:alt)
-  # @private
-  AMP = ns(:amp)
-  # @private
-  PCAT = ns(:pcat)
-  # @private
-  REP = ns(:rep)
-  # @private
-  ACCEPT = ns(:accept)
-  # @private
-  NIL = ns(:nil)
-  # @private
-  RECURSION_LIMIT = ns(:recursion_limit)
-  # @private
-  GEN = ns(:gen)
-  # @private
-  NAME = ns(:name)
-
   # Can be enabled or disabled at runtime:
   # - enabled/disabled by setting `check_asserts`.
   # - enabled by setting environment variable SPECULATION_CHECK_ASSERTS to the
@@ -83,7 +60,7 @@ module Speculation
     return x unless check_asserts
     return x if valid?(spec, x)
 
-    ed = _explain_data(spec, [], [], [], x).merge(ns(:failure) => :assertion_failed)
+    ed = _explain_data(spec, [], [], [], x).merge(:failure => :assertion_failed)
     out = StringIO.new
     explain_out(ed, out)
 
@@ -110,28 +87,28 @@ module Speculation
     gens << [1, ->(r) { r.choose(Float::INFINITY, -Float::INFINITY) }] if infinite
     gens << [1, ->(_) { Float::NAN }] if nan
 
-    spec(self.and(*preds), :gen => ->(rantly) { rantly.freq(*gens) })
+    spec(self.and(*preds), :gen => ->() { ->(rantly) { rantly.freq(*gens) } })
   end
 
   # @param range [Range<Integer>]
   # @return Spec that validates ints in the given range
   def self.int_in(range)
     spec(self.and(Integer, ->(x) { range.include?(x) }),
-         :gen => ->(_) { rand(range) })
+         :gen => ->() { ->(_) { rand(range) } })
   end
 
   # @param time_range [Range<Time>]
   # @return Spec that validates times in the given range
   def self.time_in(time_range)
     spec(self.and(Time, ->(x) { time_range.cover?(x) }),
-         :gen => ->(_) { rand(time_range) })
+         :gen => ->() { ->(_) { rand(time_range) } })
   end
 
   # @param date_range [Range<Date>]
   # @return Spec that validates dates in the given range
   def self.date_in(date_range)
     spec(self.and(Date, ->(x) { date_range.cover?(x) }),
-         :gen => ->(_) { rand(date_range) })
+         :gen => ->() { ->(_) { rand(date_range) } })
   end
 
   # @param x [Spec, Object]
@@ -143,30 +120,43 @@ module Speculation
   # @param x [Hash, Object]
   # @return [Hash, false] x if x is a (Speculation) regex op, else logical false
   def self.regex?(x)
-    Utils.hash?(x) && x[OP] && x
+    x.is_a?(Hash) && x[:op] && x
   end
 
   # @param value return value of a `conform` call
   # @return [Boolean] true if value is the result of an unsuccessful conform
   def self.invalid?(value)
-    value.equal?(INVALID)
+    value.equal?(:"Speculation/invalid")
   end
 
   # @param spec [Spec]
   # @param value value to conform
-  # @return [Symbol, Object] :Speculation/invalid if value does not match spec, else the (possibly destructured) value
+  # @return [Symbol, Object] :Speculation/invalid if value does not match spec, else the (possibly
+  #   destructured) value
   def self.conform(spec, value)
     spec = MethodIdentifier(spec)
     specize(spec).conform(value)
   end
 
-  # Takes a spec and a one-arg generator function and returns a version of the spec that uses that generator
   # @param spec [Spec]
-  # @param gen [Proc] generator proc that receives a Rantly instance
+  # @value value [Object] value created by `conform` call and given `spec`
+  # @return value with conform destructuring undone
+  def self.unform(spec, value)
+    specize(spec).unform(value)
+  end
+
+  # Takes a spec and a no-arg generator returning block and returns a version of the spec that uses
+  #   that generator
+  # @param spec [Spec]
+  # @yieldreturn Rantly generator
   # @return [Spec]
-  def self.with_gen(spec, gen)
+  def self.with_gen(spec, &gen)
+    if gen && !gen.arity.zero?
+      raise ArgumentError, "gen must be a no-arg block that returns a generator"
+    end
+
     if regex?(spec)
-      spec.merge(ns(:gfn) => gen)
+      spec.merge(:gfn => gen)
     else
       specize(spec).with_gen(gen)
     end
@@ -177,19 +167,21 @@ module Speculation
     probs = specize(spec).explain(path, via, inn, value)
 
     if probs && probs.any?
-      { ns(:problems) => probs }
+      { :problems => probs,
+        :spec     => spec,
+        :value    => value }
     end
   end
 
   # Given a spec and a value x which ought to conform, returns nil if x
-  # conforms, else a hash with at least the key :"Speculation/problems" whose
+  # conforms, else a hash with at least the key :problems whose
   # value is a collection of problem-hashes, where problem-hash has at least
   # :path :pred and :val keys describing the predicate and the value that failed
   # at that path.
   # @param spec [Spec]
   # @param x value which ought to conform
   # @return [nil, Hash] nil if x conforms, else a hash with at least the key
-  #   :Speculation/problems whose value is a collection of problem-hashes,
+  #   :problems whose value is a collection of problem-hashes,
   #   where problem-hash has at least :path :pred and :val keys describing the
   #   predicate and the value that failed at that path.
   def self.explain_data(spec, x)
@@ -203,7 +195,9 @@ module Speculation
   def self.explain_out(ed, out = STDOUT)
     return out.puts("Success!") unless ed
 
-    ed.fetch(ns(:problems)).each do |prob|
+    problems = Utils.sort_descending(ed.fetch(:problems)) { |prob| prob[:path] }
+
+    problems.each do |prob|
       path, pred, val, reason, via, inn = prob.values_at(:path, :pred, :val, :reason, :via, :in)
 
       out.print("In: ", inn.to_a.inspect, " ") unless inn.empty?
@@ -223,7 +217,7 @@ module Speculation
     end
 
     ed.each do |k, v|
-      out.puts("#{k} #{PP.pp(v, String.new)}") unless k == ns(:problems)
+      out.puts("#{k.inspect} #{PP.pp(v, String.new)}") unless k == :problems
     end
 
     nil
@@ -251,13 +245,14 @@ module Speculation
 
     spec = specize(spec)
     gfn = overrides[spec_name(spec) || spec] || overrides[path]
+    gfn = gfn.call if gfn
     g = gfn || spec.gen(overrides, path, rmap)
 
     if g
       Gen.such_that(g) { |x| valid?(spec, x) }
     else
       raise Speculation::Error.new("unable to construct gen at: #{path.inspect} for: #{spec.inspect}",
-                                   ns(:failure) => :no_gen, ns(:path) => path)
+                                   :failure => :no_gen, :path => path)
     end
   end
 
@@ -277,7 +272,7 @@ module Speculation
   # @return [Proc]
   def self.gen(spec, overrides = nil)
     spec = MethodIdentifier(spec)
-    gensub(spec, overrides, [], RECURSION_LIMIT => recursion_limit)
+    gensub(spec, overrides, [], :recursion_limit => recursion_limit)
   end
 
   # @private
@@ -329,8 +324,8 @@ module Speculation
   # NOTE: it is not generally necessary to wrap predicates in spec when using
   # `S.def` etc., only to attach a unique generator.
   #
-  # Optionally takes :gen generator function, which must be a proc of one arg
-  # (Rantly instance) that generates a valid value.
+  # Optionally takes :gen generator function, which must be a no-arg proc that returns a generator
+  # (proc that receives a Rantly instance) that generates a valid value.
   #
   # @param pred [Proc, Method, Set, Class, Regexp, Hash] Takes a single predicate. A
   #   predicate can be one of:
@@ -346,8 +341,8 @@ module Speculation
   #   zero_or_more, one_or_more, zero_or_one, in which case it will return a
   #   regex-conforming spec, useful when nesting an independent regex.
   #
-  # @param gen [Proc] generator function, which must be a proc of one
-  #   arg (Rantly instance) that generates a valid value.
+  # @param gen [Proc] generator returning function, which must be a zero arg proc that returns a
+  #   proc of one arg (Rantly instance) that generates a valid value.
   # @return [Spec]
   def self.spec(pred, gen: nil)
     spec_impl(pred, gen, false) if pred
@@ -381,20 +376,20 @@ module Speculation
   # @param opt [Array<Symbol>]
   # @param req_un [Array<Symbol>]
   # @param opt_un [Array<Symbol>]
-  # @param gen [Proc] generator function, which must be a proc of one arg
-  #   (Rantly instance) that generates a valid value
+  # @param gen [Proc] generator returning function, which must be a zero arg proc that
+  #   returns a proc of one arg (Rantly instance) that generates a valid value.
   def self.keys(req: [], opt: [], req_un: [], opt_un: [], gen: nil)
     HashSpec.new(req, opt, req_un, opt_un, gen)
   end
 
   # @see keys
   def self.or_keys(*ks)
-    [ns(:or), *ks]
+    [:"Speculation/or", *ks]
   end
 
   # @see keys
   def self.and_keys(*ks)
-    [ns(:and), *ks]
+    [:"Speculation/and", *ks]
   end
 
   # @param key_preds [Hash] Takes key+pred hash
@@ -440,8 +435,8 @@ module Speculation
   # @option opts :into [Array, Hash, Set] (Array) one of [], {}, Set[], the
   #   default collection to generate into (default: empty coll as generated by
   #   :kind pred if supplied, else [])
-  # @option opts :gen [Proc] generator proc, which must be a proc of one arg
-  #   (Rantly instance) that generates a valid value.
+  # @option opts :gen [Proc] generator returning function, which must be a zero arg proc that
+  #   returns a proc of one arg (Rantly instance) that generates a valid value.
   # @see coll_of
   # @see every_kv
   # @return [Spec] spec that validates collection elements against pred
@@ -461,9 +456,9 @@ module Speculation
   # @param vpred val pred
   # @param options [Hash]
   # @return [Spec] spec that validates associative collections
-  def self.every_kv(kpred, vpred, options)
-    every(tuple(kpred, vpred), ns(:kfn) => ->(_i, v) { v.first },
-                               :into    => {},
+  def self.every_kv(kpred, vpred, options = {})
+    every(tuple(kpred, vpred), :kfn  => ->(_i, v) { v.first },
+                               :into => {},
                                **options)
   end
 
@@ -479,13 +474,13 @@ module Speculation
   # @param opts [Hash]
   # @return [Spec]
   def self.coll_of(pred, opts = {})
-    every(pred, ns(:conform_all) => true, **opts)
+    every(pred, :conform_all => true, **opts)
   end
 
   # Returns a spec for a hash whose keys satisfy kpred and vals satisfy vpred.
   # Unlike 'every_kv', hash_of will exhaustively conform every value.
   #
-  # Same options as 'every', :kind defaults to `Speculation::Utils.hash?`, with
+  # Same options as 'every', :kind defaults to `Speculation::Predicates.hash?`, with
   # the addition of:
   #
   # :conform_keys - conform keys as well as values (default false)
@@ -496,8 +491,8 @@ module Speculation
   # @param options [Hash]
   # @return [Spec]
   def self.hash_of(kpred, vpred, options = {})
-    every_kv(kpred, vpred, :kind            => Utils.method(:hash?),
-                           ns(:conform_all) => true,
+    every_kv(kpred, vpred, :kind        => Predicates.method(:hash?),
+                           :conform_all => true,
                            **options)
   end
 
@@ -519,7 +514,7 @@ module Speculation
   # @return [Hash] regex op that matches zero or one value matching pred. Produces a
   # single value (not a collection) if matched.
   def self.zero_or_one(pred)
-    _alt([pred, accept(NIL)], nil)
+    _alt([pred, accept(:nil)], nil)
   end
 
   # @param kv_specs [Hash] key+pred pairs
@@ -550,14 +545,15 @@ module Speculation
   #   resulting value to the conjunction of the predicates, and any conforming
   #   they might perform.
   def self.constrained(re, *preds)
-    { OP => AMP, :p1 => re, :predicates => preds }
+    { :op => :amp, :p1 => re, :predicates => preds }
   end
 
-  # @param f predicate function with the semantics of conform i.e. it should
+  # @param f [#call] function with the semantics of conform i.e. it should
   #   return either a (possibly converted) value or :"Speculation/invalid"
+  # @param unformer [#call] function that does the unform of the result of `f`
   # @return [Spec] a spec that uses pred as a predicate/conformer.
-  def self.conformer(f)
-    spec_impl(f, nil, true)
+  def self.conformer(f, unformer = nil)
+    spec_impl(f, nil, true, unformer)
   end
 
   # Takes :args :ret and (optional) :block and :fn kwargs whose values are preds and returns a spec
@@ -571,8 +567,8 @@ module Speculation
   # @param ret predicate
   # @param fn predicate
   # @param block predicate
-  # @param gen [Proc] generator proc, which must be a proc of one arg (Rantly
-  #   instance) that generates a valid value.
+  # @param gen [Proc] generator returning function, which must be a zero arg proc that
+  #   returns a proc of one arg (Rantly instance) that generates a valid value.
   # @return [Spec]
   # @see fdef See 'fdef' for a single operation that creates an fspec and registers it, as well as a
   #   full description of :args, :block, :ret and :fn
@@ -662,7 +658,7 @@ module Speculation
   # @return [Array] an array of triples of [args, block, ret].
   def self.exercise_fn(method, n = 10, fspec = nil)
     fspec ||= get_spec(method)
-    raise ArgumentError, "No fspec found for #{method}" unless fspec
+    raise ArgumentError, "No :args spec found for #{method}" unless fspec && fspec.args
 
     block_gen = fspec.block ? gen(fspec.block) : Utils.constantly(nil)
     gen = Gen.tuple(gen(fspec.args), block_gen)
@@ -674,7 +670,7 @@ module Speculation
 
   # @private
   def self.recur_limit?(rmap, id, path, k)
-    rmap[id] > rmap[RECURSION_LIMIT] &&
+    rmap[id] > rmap[:recursion_limit] &&
       path.include?(k)
   end
 
@@ -692,11 +688,11 @@ module Speculation
     if spec
       conform(spec, x)
     elsif pred.is_a?(Module) || pred.is_a?(::Regexp)
-      pred === x ? x : INVALID
+      pred === x ? x : :"Speculation/invalid"
     elsif pred.is_a?(Set)
-      pred.include?(x) ? x : INVALID
+      pred.include?(x) ? x : :"Speculation/invalid"
     elsif pred.respond_to?(:call)
-      pred.call(x) ? x : INVALID
+      pred.call(x) ? x : :"Speculation/invalid"
     else
       raise "#{pred} is not a class, proc, set or regexp"
     end
@@ -723,16 +719,16 @@ module Speculation
   end
 
   # @private
-  def self.spec_impl(pred, gen, should_conform)
+  def self.spec_impl(pred, gen, should_conform, unconformer = nil)
     if spec?(pred)
-      with_gen(pred, gen)
+      with_gen(pred, &gen)
     elsif regex?(pred)
       RegexSpec.new(pred, gen)
     elsif Utils.ident?(pred)
       spec = the_spec(pred)
-      gen ? with_gen(spec, gen) : spec
+      gen ? with_gen(spec, &gen) : spec
     else
-      PredicateSpec.new(pred, should_conform, gen)
+      PredicateSpec.new(pred, should_conform, gen, unconformer)
     end
   end
 
@@ -761,7 +757,7 @@ module Speculation
     p = reg_resolve!(p)
 
     id, op, ps, ks, p1, p2, ret, id, gen = p.values_at(
-      :id, OP, :predicates, :keys, :p1, :p2, :return_value, :id, GEN
+      :id, :op, :predicates, :keys, :p1, :p2, :return_value, :id, :gfn
     ) if regex?(p)
 
     id = p.id if spec?(p)
@@ -786,19 +782,21 @@ module Speculation
       overrides[path]
 
     if ogen
+      gen = ogen.call
+
       if [:accept, nil].include?(op)
-        return ->(rantly) { [*ogen.call(rantly)] }
+        return Gen.fmap(gen) { |x| [x] }
       else
-        return ->(rantly) { ogen.call(rantly) }
+        return gen
       end
     end
 
-    return gen if gen
+    return gen.call if gen
 
     if p
       case op
-      when ACCEPT
-        if ret == NIL
+      when :accept
+        if ret == :nil
           ->(_rantly) { [] }
         else
           ->(_rantly) { [ret] }
@@ -806,10 +804,10 @@ module Speculation
       when nil
         g = gensub(p, overrides, path, rmap)
 
-        ->(rantly) { [g.call(rantly)] }
-      when AMP
+        Gen.fmap(g) { |x| [x] }
+      when :amp
         re_gen(p1, overrides, path, rmap)
-      when PCAT
+      when :pcat
         gens = ggens.call(ps, ks)
 
         if gens.all?
@@ -817,11 +815,11 @@ module Speculation
             gens.flat_map { |gg| gg.call(rantly) }
           end
         end
-      when ALT
+      when :alt
         gens = ggens.call(ps, ks).compact
 
         ->(rantly) { rantly.branch(*gens) } unless gens.empty?
-      when REP
+      when :rep
         if recur_limit?(rmap, id, [id], id)
           ->(_rantly) { [] }
         else
@@ -841,15 +839,45 @@ module Speculation
   def self.re_conform(regex, data)
     data.each do |x|
       regex = deriv(regex, x)
-      return INVALID unless regex
+      return :"Speculation/invalid" unless regex
     end
 
     if accept_nil?(regex)
       return_value = preturn(regex)
 
-      return_value == NIL ? nil : return_value
+      return_value == :nil ? nil : return_value
     else
-      INVALID
+      :"Speculation/invalid"
+    end
+  end
+
+  # @private
+  def self.op_unform(regex, value)
+    return unform(regex, value) unless regex?(regex)
+
+    case regex[:op]
+    when :accept
+      [regex[:return_value]]
+    when :amp
+      px = regex[:predicates].reverse.reduce(value) { |val, pred| op_unform(pred, val) }
+      op_unform(regex[:p1], px)
+    when :rep
+      value.flat_map { |val| op_unform(regex[:p1], val) }
+    when :pcat
+      if regex[:keys] # it's a `cat`
+        kps = Hash[regex[:keys].zip(regex[:predicates])]
+        regex[:keys].flat_map { |key| value.include?(key) ? op_unform(kps[key], value[key]) : [] }
+      else            # it's a `one_or_more`
+        value.flat_map { |val| op_unform(regex[:predicates].first, val) }
+      end
+    when :alt
+      if regex[:keys] # it's an `alt`
+        kps = Hash[regex[:keys].zip(regex[:predicates])]
+        k, v = value
+        op_unform(kps[k], v)
+      else            # it's a `zero_or_one`
+        [unform(regex[:predicates].first, value)]
+      end
     end
   end
 
@@ -866,7 +894,7 @@ module Speculation
       end
 
       if accept?(p)
-        if p[OP] == PCAT
+        if p[:op] == :pcat
           return op_explain(p, path, via, Utils.conj(inn, index), input[index..-1])
         else
           return [{ :path   => path,
@@ -929,7 +957,7 @@ module Speculation
       if Utils.ident?(spec)
         spec
       elsif regex?(spec)
-        spec.merge(NAME => name)
+        spec.merge(:name => name)
       else
         spec.tap { |s| s.name = name }
       end
@@ -939,7 +967,7 @@ module Speculation
       if Utils.ident?(spec)
         spec
       elsif regex?(spec)
-        spec[NAME]
+        spec[:name]
       elsif spec.respond_to?(:name)
         spec.name
       end
@@ -973,7 +1001,7 @@ module Speculation
     def and_preds(x, preds)
       preds.each do |pred|
         x = dt(pred, x)
-        return INVALID if invalid?(x)
+        return :"Speculation/invalid" if invalid?(x)
       end
 
       x
@@ -986,6 +1014,8 @@ module Speculation
         case spec
         when Symbol, MethodIdentifier
           specize(reg_resolve!(spec))
+        when nil
+          raise ArgumentError, "#{spec.inspect} can not be a spec"
         else
           spec_impl(spec, nil, false)
         end
@@ -995,12 +1025,12 @@ module Speculation
     ### regex ###
 
     def accept(x)
-      { OP => ACCEPT, :return_value => x }
+      { :op => :accept, :return_value => x }
     end
 
     def accept?(hash)
       if hash.is_a?(Hash)
-        hash[OP] == ACCEPT
+        hash[:op] == :accept
       end
     end
 
@@ -1013,7 +1043,7 @@ module Speculation
       return unless regex[:predicates].all?
 
       unless accept?(predicate)
-        return { OP            => PCAT,
+        return { :op           => :pcat,
                  :predicates   => regex[:predicates],
                  :keys         => keys,
                  :return_value => regex[:return_value] }
@@ -1034,7 +1064,7 @@ module Speculation
     def rep(p1, p2, return_value, splice)
       return unless p1
 
-      regex = { OP => REP, :p2 => p2, :splice => splice, :id => SecureRandom.uuid }
+      regex = { :op => :rep, :p2 => p2, :splice => splice, :id => SecureRandom.uuid }
 
       if accept?(p1)
         regex.merge(:p1 => p2, :return_value => Utils.conj(return_value, p1[:return_value]))
@@ -1059,7 +1089,7 @@ module Speculation
       predicate, *rest_predicates = predicates
       key, *_rest_keys = keys
 
-      return_value = { OP => ALT, :predicates => predicates, :keys => keys }
+      return_value = { :op => :alt, :predicates => predicates, :keys => keys }
       return return_value unless rest_predicates.empty?
 
       return predicate unless key
@@ -1077,24 +1107,24 @@ module Speculation
     end
 
     def no_ret?(p1, pret)
-      return true if pret == NIL
+      return true if pret == :nil
 
       regex = reg_resolve!(p1)
-      op = regex[OP]
+      op = regex[:op]
 
-      [REP, PCAT].include?(op) && pret.empty? || nil
+      [:rep, :pcat].include?(op) && pret.empty? || nil
     end
 
     def accept_nil?(regex)
       regex = reg_resolve!(regex)
       return unless regex?(regex)
 
-      case regex[OP]
-      when ACCEPT then true
-      when PCAT   then regex[:predicates].all? { |p| accept_nil?(p) }
-      when ALT    then regex[:predicates].any? { |p| accept_nil?(p) }
-      when REP    then (regex[:p1] == regex[:p2]) || accept_nil?(regex[:p1])
-      when AMP
+      case regex[:op]
+      when :accept then true
+      when :pcat   then regex[:predicates].all? { |p| accept_nil?(p) }
+      when :alt    then regex[:predicates].any? { |p| accept_nil?(p) }
+      when :rep    then (regex[:p1] == regex[:p2]) || accept_nil?(regex[:p1])
+      when :amp
         p1 = regex[:p1]
 
         return false unless accept_nil?(p1)
@@ -1102,7 +1132,7 @@ module Speculation
         no_ret?(p1, preturn(p1)) ||
           !invalid?(and_preds(preturn(p1), regex[:predicates]))
       else
-        raise "Unexpected #{OP} #{regex[OP]}"
+        raise "Unexpected op #{regex[:op]}"
       end
     end
 
@@ -1113,30 +1143,30 @@ module Speculation
       p0, *_pr = regex[:predicates]
       k, *_ks = regex[:keys]
 
-      case regex[OP]
-      when ACCEPT then regex[:return_value]
-      when PCAT   then add_ret(p0, regex[:return_value], k)
-      when REP    then add_ret(regex[:p1], regex[:return_value], k)
-      when AMP
+      case regex[:op]
+      when :accept then regex[:return_value]
+      when :pcat   then add_ret(p0, regex[:return_value], k)
+      when :rep    then add_ret(regex[:p1], regex[:return_value], k)
+      when :amp
         pret = preturn(regex[:p1])
 
         if no_ret?(regex[:p1], pret)
-          NIL
+          :nil
         else
           and_preds(pret, regex[:predicates])
         end
-      when ALT
+      when :alt
         pred, key = regex[:predicates].zip(Array(regex[:keys])).find { |(p, _k)| accept_nil?(p) }
 
         r = if pred.nil?
-              NIL
+              :nil
             else
               preturn(pred)
             end
 
         key ? [key, r] : r
       else
-        raise "Unexpected #{OP} #{regex[OP]}"
+        raise "Unexpected op #{regex[:op]}"
       end
     end
 
@@ -1144,16 +1174,16 @@ module Speculation
       regex = reg_resolve!(regex)
       return r unless regex?(regex)
 
-      case regex[OP]
-      when ACCEPT, ALT, AMP
+      case regex[:op]
+      when :accept, :alt, :amp
         return_value = preturn(regex)
 
-        if return_value == NIL
+        if return_value == :nil
           r
         else
           Utils.conj(r, key ? { key => return_value } : return_value)
         end
-      when PCAT, REP
+      when :pcat, :rep
         return_value = preturn(regex)
 
         if return_value.empty?
@@ -1164,7 +1194,7 @@ module Speculation
           regex[:splice] ? Utils.into(r, val) : Utils.conj(r, val)
         end
       else
-        raise "Unexpected #{OP} #{regex[OP]}"
+        raise "Unexpected op #{regex[:op]}"
       end
     end
 
@@ -1187,9 +1217,9 @@ module Speculation
       pred, *rest_preds = predicates
       key, *rest_keys = keys
 
-      case regex[OP]
-      when ACCEPT then nil
-      when PCAT
+      case regex[:op]
+      when :accept then nil
+      when :pcat
         regex1 = pcat(:predicates => [deriv(pred, value), *rest_preds], :keys => keys, :return_value => return_value)
         regex2 = nil
 
@@ -1201,9 +1231,9 @@ module Speculation
         end
 
         alt2(regex1, regex2)
-      when ALT
+      when :alt
         _alt(predicates.map { |p| deriv(p, value) }, keys)
-      when REP
+      when :rep
         regex1 = rep(deriv(p1, value), p2, return_value, splice)
         regex2 = nil
 
@@ -1212,18 +1242,18 @@ module Speculation
         end
 
         alt2(regex1, regex2)
-      when AMP
+      when :amp
         p1 = deriv(p1, value)
         return unless p1
 
-        if p1[OP] == ACCEPT
+        if p1[:op] == :accept
           ret = and_preds(preturn(p1), predicates)
           accept(ret) unless invalid?(ret)
         else
           constrained(p1, *predicates)
         end
       else
-        raise "Unexpected #{OP} #{regex[OP]}"
+        raise "Unexpected op #{regex[:op]}"
       end
     end
 
@@ -1251,9 +1281,9 @@ module Speculation
         end
       end
 
-      case p[OP]
-      when ACCEPT then nil
-      when AMP
+      case p[:op]
+      when :accept then nil
+      when :amp
         if input.empty?
           if accept_nil?(p[:p1])
             explain_pred_list(p[:predicates], path, via, inn, preturn(p[:p1]))
@@ -1269,7 +1299,7 @@ module Speculation
             op_explain(p[:p1], path, via, inn, input)
           end
         end
-      when PCAT
+      when :pcat
         pks = p[:predicates].zip(Array(p[:keys]))
         pred, k = if pks.count == 1
                     pks.first
@@ -1284,7 +1314,7 @@ module Speculation
         else
           op_explain(pred, path, via, inn, input)
         end
-      when ALT
+      when :alt
         return insufficient(p, path, via, inn) if input.empty?
 
         probs = p[:predicates].zip(Array(p[:keys])).flat_map { |(predicate, key)|
@@ -1292,21 +1322,21 @@ module Speculation
         }
 
         probs.compact
-      when REP
+      when :rep
         op_explain(p[:p1], path, via, inn, input)
       else
-        raise "Unexpected #{OP} #{p[OP]}"
+        raise "Unexpected :op #{p[:op]}"
       end
     end
   end
 
   @registry_ref.reset(
-    ns(:any)              => with_gen(Utils.constantly(true), ->(r) { r.branch(*Gen::GEN_BUILTINS.values) }),
+    ns(:any)              => with_gen(Utils.constantly(true)) { ->(r) { r.branch(*Gen::GEN_BUILTINS.values) } },
     ns(:boolean)          => Set[true, false],
-    ns(:positive_integer) => with_gen(self.and(Integer, ->(x) { x > 0 }), ->(r) { r.range(1) }),
+    ns(:positive_integer) => with_gen(self.and(Integer, ->(x) { x > 0 })) { ->(r) { r.range(1) } },
     # Rantly#positive_integer is actually a natural integer
-    ns(:natural_integer)  => with_gen(self.and(Integer, ->(x) { x >= 0 }), :positive_integer.to_proc),
-    ns(:negative_integer) => with_gen(self.and(Integer, ->(x) { x < 0 }), ->(r) { r.range(nil, -1) }),
-    ns(:empty)            => with_gen(Utils.method(:empty?), Utils.constantly([]))
+    ns(:natural_integer)  => with_gen(self.and(Integer, ->(x) { x >= 0 })) { :positive_integer.to_proc },
+    ns(:negative_integer) => with_gen(self.and(Integer, ->(x) { x < 0 })) { ->(r) { r.range(nil, -1) } },
+    ns(:empty)            => with_gen(Predicates.method(:empty?)) { Utils.constantly([]) }
   )
 end