speculation 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: b293a72669d39d6366f5c1f42a3112fdfa03e6c5
+  data.tar.gz: a90bc4265285e116cb93978928546a0f9f18256e
+SHA512:
+  metadata.gz: 7c0f3352a89d81340eaf8ddd583b8d5f2dcaeb68a1da4d025f4af680a0edc5aba522cfeb997152484753ee072217efd3bb64877e297937e03af16852779f751e
+  data.tar.gz: d4a90effba95011da873b7aa3c03d496a59379dd7d890c0aaf5e3101a0ec2a1e8ef9840710c13e257f10ecbef7144457679b47e7a14acafd8bb92a8835f6e572

data/.gitignore

@@ -0,0 +1,9 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/

data/.rubocop.yml

@@ -0,0 +1,87 @@
+AllCops:
+  Exclude:
+    - 'bin/*'
+    - '*.*'
+    - 'vendor/**/*'
+  TargetRubyVersion: 2.4
+
+Metrics/ClassLength:
+  Enabled: false
+
+Metrics/BlockLength:
+  Enabled: false
+
+Metrics/ParameterLists:
+  Enabled: false
+
+Metrics/ModuleLength:
+  Enabled: false
+
+Metrics/LineLength:
+  Enabled: false
+
+Metrics/MethodLength:
+  Enabled: false
+
+Metrics/AbcSize:
+  Enabled: false
+
+Metrics/PerceivedComplexity:
+  Enabled: false
+
+Metrics/CyclomaticComplexity:
+  Enabled: false
+
+Metrics/BlockNesting:
+  Enabled: false
+
+Style/AlignHash:
+  EnforcedHashRocketStyle: table
+
+Style/HashSyntax:
+  EnforcedStyle: hash_rockets
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+Style/BlockDelimiters:
+  EnforcedStyle: semantic
+
+Style/DotPosition:
+  EnforcedStyle: trailing
+
+Style/IfUnlessModifier:
+  Enabled: false
+
+Style/GuardClause:
+  Enabled: false
+
+Style/MultilineMethodCallIndentation:
+  EnforcedStyle: indented
+
+Style/Lambda:
+  EnforcedStyle: literal
+
+Style/WordArray:
+  EnforcedStyle: brackets
+
+Style/Documentation:
+  Enabled: false
+
+Style/CaseEquality:
+  Enabled: false
+
+Style/MultilineOperationIndentation:
+  EnforcedStyle: indented
+
+Style/MultilineIfModifier:
+  Enabled: false
+
+Style/AccessorMethodName:
+  Enabled: false
+
+Style/NumericLiterals:
+  Enabled: false
+
+Style/NumericPredicate:
+  Enabled: false

data/.travis.yml

@@ -0,0 +1,16 @@
+sudo: false
+language: ruby
+cache: bundler
+rvm:
+  - 2.2.6
+  - 2.3.3
+  - 2.4.0
+  - jruby-9.0.5.0
+  - jruby-9.1.5.0
+before_install:
+  - gem update --system
+  - gem install bundler
+matrix:
+  allow_failures:
+    - rvm: 2.2.6
+    - rvm: jruby-9.0.5.0

data/.yardopts

@@ -0,0 +1,3 @@
+--no-private
+lib/**/*.rb -
+README.md LICENSE.txt

data/Gemfile

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+source "https://rubygems.org"
+
+gem "test-queue", :github => "bboe/test-queue", :ref => "578e1ebe47b171b9d488c61ba112742e32ee0cfc"
+
+# Specify your gem's dependencies in speculation.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2016 Jamie English
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,116 @@
+# 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.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+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:
+
+```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)
+```
+
+### 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:
+
+```rb
+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.
+
+```rb
+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:
+
+```rb
+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`](https://github.com/abargnesi/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
+- write up comparison with clojure.spec
+- write guide
+
+### clojure.spec features
+
+- [`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)
+
+### Improvements
+
+- Find/build an alternative to Rantly
+- Profile and optimise
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+require "bundler/gem_tasks"
+require "rubocop"
+require "yard"
+
+task :rubocop do
+  status = RuboCop::CLI.new.run([])
+  raise "failed with status #{status}" unless status.zero?
+end
+
+task :test do
+  if RUBY_PLATFORM == "java"
+    $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)"
+  end
+end
+
+task :doc do
+  YARD::CLI::Yardoc.run("--no-private", "lib/**/*.rb", "-", "README.md", "LICENSE.txt")
+end
+
+task :default => [:rubocop, :test]

data/bin/bundler

@@ -0,0 +1,17 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+#
+# This file was generated by Bundler.
+#
+# The application 'bundler' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+require "pathname"
+ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../../Gemfile",
+  Pathname.new(__FILE__).realpath)
+
+require "rubygems"
+require "bundler/setup"
+
+load Gem.bin_path("bundler", "bundler")

data/bin/byebug

@@ -0,0 +1,17 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+#
+# This file was generated by Bundler.
+#
+# The application 'byebug' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+require "pathname"
+ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../../Gemfile",
+  Pathname.new(__FILE__).realpath)
+
+require "rubygems"
+require "bundler/setup"
+
+load Gem.bin_path("byebug", "byebug")

data/bin/coderay

@@ -0,0 +1,17 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+#
+# This file was generated by Bundler.
+#
+# The application 'coderay' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+require "pathname"
+ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../../Gemfile",
+  Pathname.new(__FILE__).realpath)
+
+require "rubygems"
+require "bundler/setup"
+
+load Gem.bin_path("coderay", "coderay")

data/bin/console

@@ -0,0 +1,70 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+$LOAD_PATH.unshift File.expand_path("../../test", __FILE__)
+
+require "bundler/setup"
+require 'rubocop'
+require "speculation"
+require "speculation/test"
+require "speculation/gen"
+require "speculation/utils_specs"
+
+def reload!
+  Minitest::Test.reset
+  STest.unstrument if Object.const_defined?(:STest)
+
+  [:Speculation, :S, :STest, :Gen, :U, :H, :V].each do |const|
+    Object.send :remove_const, const if Object.const_defined?(const)
+  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"
+  load "./lib/speculation/error.rb"
+
+  load "./lib/speculation/spec_impl.rb"
+
+  Dir["lib/speculation/spec_impl/*.rb"].each do |f|
+    load f
+  end
+
+  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
+  end
+
+  Object.const_set(:S, Speculation)
+  Object.const_set(:STest, Speculation::Test)
+  Object.const_set(:Gen, Speculation::Gen)
+  Object.const_set(:U, Speculation::Utils)
+
+  # STest.instrument
+end
+
+def t
+  reload!
+  Minitest.run
+end
+
+def r
+  RuboCop::CLI.new.run(['--display-cop-names'])
+end
+
+# allow running minitest assertions
+require "minitest"
+include Minitest::Assertions
+def self.assertions; 1; end
+def self.assertions=(_x); end
+using Speculation::NamespacedSymbols.refine(self)
+
+reload!
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+require "pry"
+Pry.start

data/bin/cucumber-queue

@@ -0,0 +1,17 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+#
+# This file was generated by Bundler.
+#
+# The application 'cucumber-queue' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+require "pathname"
+ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../../Gemfile",
+  Pathname.new(__FILE__).realpath)
+
+require "rubygems"
+require "bundler/setup"
+
+load Gem.bin_path("test-queue", "cucumber-queue")

data/bin/minitest-queue

@@ -0,0 +1,17 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+#
+# This file was generated by Bundler.
+#
+# The application 'minitest-queue' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+require "pathname"
+ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../../Gemfile",
+  Pathname.new(__FILE__).realpath)
+
+require "rubygems"
+require "bundler/setup"
+
+load Gem.bin_path("test-queue", "minitest-queue")

data/bin/pry

@@ -0,0 +1,17 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+#
+# This file was generated by Bundler.
+#
+# The application 'pry' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+require "pathname"
+ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../../Gemfile",
+  Pathname.new(__FILE__).realpath)
+
+require "rubygems"
+require "bundler/setup"
+
+load Gem.bin_path("pry", "pry")

data/bin/rake

@@ -0,0 +1,17 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+#
+# This file was generated by Bundler.
+#
+# The application 'rake' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+require "pathname"
+ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../../Gemfile",
+  Pathname.new(__FILE__).realpath)
+
+require "rubygems"
+require "bundler/setup"
+
+load Gem.bin_path("rake", "rake")

data/bin/rspec-queue

@@ -0,0 +1,17 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+#
+# This file was generated by Bundler.
+#
+# The application 'rspec-queue' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+require "pathname"
+ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../../Gemfile",
+  Pathname.new(__FILE__).realpath)
+
+require "rubygems"
+require "bundler/setup"
+
+load Gem.bin_path("test-queue", "rspec-queue")

data/bin/rubocop

@@ -0,0 +1,17 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+#
+# This file was generated by Bundler.
+#
+# The application 'rubocop' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+require "pathname"
+ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../../Gemfile",
+  Pathname.new(__FILE__).realpath)
+
+require "rubygems"
+require "bundler/setup"
+
+load Gem.bin_path("rubocop", "rubocop")

data/bin/ruby-parse

@@ -0,0 +1,17 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+#
+# This file was generated by Bundler.
+#
+# The application 'ruby-parse' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+require "pathname"
+ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../../Gemfile",
+  Pathname.new(__FILE__).realpath)
+
+require "rubygems"
+require "bundler/setup"
+
+load Gem.bin_path("parser", "ruby-parse")

data/bin/ruby-rewrite

@@ -0,0 +1,17 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+#
+# This file was generated by Bundler.
+#
+# The application 'ruby-rewrite' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+require "pathname"
+ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../../Gemfile",
+  Pathname.new(__FILE__).realpath)
+
+require "rubygems"
+require "bundler/setup"
+
+load Gem.bin_path("parser", "ruby-rewrite")

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/bin/testunit-queue

@@ -0,0 +1,17 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+#
+# This file was generated by Bundler.
+#
+# The application 'testunit-queue' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+require "pathname"
+ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../../Gemfile",
+  Pathname.new(__FILE__).realpath)
+
+require "rubygems"
+require "bundler/setup"
+
+load Gem.bin_path("test-queue", "testunit-queue")

data/bin/yard

@@ -0,0 +1,17 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+#
+# This file was generated by Bundler.
+#
+# The application 'yard' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+require "pathname"
+ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../../Gemfile",
+  Pathname.new(__FILE__).realpath)
+
+require "rubygems"
+require "bundler/setup"
+
+load Gem.bin_path("yard", "yard")

data/bin/yardoc

@@ -0,0 +1,17 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+#
+# This file was generated by Bundler.
+#
+# The application 'yardoc' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+require "pathname"
+ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../../Gemfile",
+  Pathname.new(__FILE__).realpath)
+
+require "rubygems"
+require "bundler/setup"
+
+load Gem.bin_path("yard", "yardoc")

data/bin/yri

@@ -0,0 +1,17 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+#
+# This file was generated by Bundler.
+#
+# The application 'yri' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+require "pathname"
+ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../../Gemfile",
+  Pathname.new(__FILE__).realpath)
+
+require "rubygems"
+require "bundler/setup"
+
+load Gem.bin_path("yard", "yri")