assume 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 8d8e6d1cef180511bada22d9611eddd535a1f929ca4a38aae70800d66653411e
+  data.tar.gz: ab8ece061eea9f1b900f991ab2197a2ae09e6d832e1e552240bf36651768a6ee
+SHA512:
+  metadata.gz: 3586e10e23cb079f8379235a829dd107106f2aaf444903c8f4a8536522e583e38ed102c1a509673fd660f8e7be5791e0db57839078044ca427b1deeb5a5543d1
+  data.tar.gz: 94fba0ee942779ea52e89342b28ddf358f7c0a0f3ac09440c65a883a21ef4b541c2fd4e3818396e8464a2854f0a11283ba33cb0bae30b41edf777b9370132178

data/.gitignore

@@ -0,0 +1,12 @@
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+
+# rspec failure tracking
+.rspec_status
+/Gemfile.lock

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/CHANGES.md

@@ -0,0 +1,2 @@
+### 0.1.0
+ - initial release

data/Gemfile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+git_source(:github) {|repo_name| "https://github.com/#{repo_name}" }
+
+# Specify your gem's dependencies in assume.gemspec
+gemspec

data/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2020, Odin Heggvold Bekkelund
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

data/README.md

@@ -0,0 +1,219 @@
+# Assume
+
+Assume is a tool that helps you record your assumptions about code directly in the code you're writing. It is similiar in functionality to and directly inspired by [solid_assert](https://rubygems.org/gems/solid_assert).
+
+## What?
+
+We make lots of assumptions when we write code. [Programming with assertions](https://docs.oracle.com/javase/8/docs/technotes/guides/language/assert.html) is a technique that helps you catch problems with your assumptions earlier in the development process.  
+
+Assertions live in a subtle space between testing your code explicitly and
+raising exceptions to enforce your api behaviour or handle edge cases. It is not a replacement for either.
+
+This gem is an attempt to make the concept less computer-sciency and more english, encouraging you to think about and record your assumptions as you go, maybe even leave them in the codebase for your colleagues to find, so they may understand your thinking, and thus your code, better.
+
+## Why tho?
+
+You might have found yourself writing something like this:
+
+```ruby
+# i is the value of some enum 0-3
+if i == 0
+  # do something cool
+elsif i == 1
+  # do something cooler
+elsif i == 2
+  # do something so cool the sun freezes
+else # we know i == 3
+  # do something awesome
+end
+```
+
+We know we don't need to perform another check on i, as we've exhausted all other options, but what happens when 'Dave' comes along next month and extends the enum to allow a 4?
+
+By recording our assumption in code, 'Dave' will (hopefully) test his new enum and quickly discover that he broke our previous assumptions.
+
+If he happens to read our code, it will say *right there in the code* that he's broken it, and he'll know to fix it.
+
+```ruby
+# i is now the value of some enum 0-4
+if i == 0
+  # do something cool
+elsif i == 1
+  # do something cooler
+elsif i == 2
+  # do something so cool the sun freezes
+else
+  assume { i == 3 } # BadAssumption!
+end
+```
+
+If you had written this only as a comment, 'Dave' might've merged a bug because he had no idea this code even existed.
+And if you *didn't even write a comment*, 'Dave' might not have noticed, even if he read your code. (Although in this example he probably would)
+
+## More examples
+
+You're writing a method and assuming it gets called after a certain point. You're actually assuming that there is a certain state available to you.
+
+```ruby
+class ThingDoer
+  # ...
+
+  private def do_the_thing
+    assume { @thingies.size > 0 }
+  end
+
+  # ...
+end
+```
+
+You're doing some control flow you know will never happen
+
+```ruby
+  def something(arg)
+    case arg
+    when 1
+    when 2
+    when 3
+    else
+      # instead of raise "this should never happen"
+      assume { false } # maybe real users don't need to notice, since this is not actually dangerous
+    end
+  end
+```
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem "assume"
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install assume
+
+## Setup
+
+This:
+
+```ruby
+require "assume"
+
+assume { "this" } # NoMethodError!
+assumption { "gravity still works" } # NoMethodError!
+```
+Does not allow you to use the methods alone. You have three options:
+
+```ruby
+require "assume/core_ext" # monkey-patches Object to provide the methods everywhere
+```
+
+```ruby
+require "assume/refine" # Loads Assumptions
+
+class Whatever
+  using Assumptions # assume's methods are now available in this class
+
+  # ...
+
+  def do_the_thing
+    assume { @true == false }
+
+    @true = true
+    # ...
+  end
+end
+
+assume { "yes" == "no" } # NoMethodError!
+```
+
+or you can just do it yourself:
+
+```ruby
+include Assume
+
+# or
+
+class Whatever
+  include Assume
+end
+
+# etc...
+```
+
+## Usage
+
+```ruby
+require "assume"
+require "assume/core_ext"
+
+# assume does nothing by default
+assume { true == false } # => nil
+
+# it is common only to run assertions in development/test environments
+# prod users get to be blissfully unaware, and the application does less work in prod
+# Assume.enabled = Whatever.env != "prod"
+Assume.enabled = true
+
+assume { "yes" == "no" } # Assume::BadAssumption!
+
+Assume.handler = proc { |result, block|
+  $stderr.puts "oh noes"
+}
+
+assume { true } # => nil
+assumption { false } # => nil, (on stderr) => "oh noes\n"
+assert { true } # NoMethodError!
+
+alias assert assume # (if you're old-school like that)
+
+assert { true } # => nil 
+```
+
+## Don'ts
+
+Don't use assume and rescue BadAssumption as an error handling mechanism.
+Make your own error class and `raise`/`rescue` it.  
+Don't use assume to enforce the public api of a class/method. `raise ArgumentError` instead.  
+
+You should probably not use assume directly in a test case (you've already got expect/assert/whatever) but if the code under test uses assume and assume is enabled in your test suite, bonus! Your test suite is now more robust!
+
+## Advanced
+
+This gem has been developed on ruby 2.6.5 and 2.7.2, but it should work on basically all versions. If it doesn't work for whatever reason, it is probably due to the default broken assumption handler. Consider replacing it with something simpler:
+
+```ruby
+Assume.handler = proc { |result, block|
+  raise ::Assume::BadAssumption
+}
+```
+
+Or using Proc#to_source from [sourcify](https://github.com/jhellerstein/sourcify)
+
+```ruby
+Assume.handler = proc { |result, block|
+  raise ::Assume::BadAssumption, "failed assumption:\n\n#{block.to_source}\n"
+}
+```
+
+etc...
+
+The default handler will only print the first line of source code which
+the block's #source_location method points it at. E.g. it will not print any source code in irb, for example.
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+Warning: Do not use `rspec` to run all the tests, they will fail as they are testing require statements. Use `rake`.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/odinhb/assume.

data/Rakefile

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+
+task :spec do
+  sh "rspec spec/assume_spec.rb"
+  sh "rspec spec/core_ext_spec.rb"
+  sh "rspec spec/refine_spec.rb"
+end
+task default: :spec
+
+task :console do
+  exec 'bin/console'
+end

data/assume.gemspec

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+lib = File.expand_path("../lib", __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require "assume/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "assume"
+  spec.version       = Assume::VERSION
+  spec.authors       = ["Odin H B"]
+  spec.email         = ["odinh2908@gmail.com"]
+
+  spec.summary       = "Write your assumptions down - in code"
+  spec.description   = "Assume encourages you to communicate with your team members and build confidence in your code"
+  spec.homepage      = "https://github.com/odinhb/assume"
+
+  # Prevent pushing this gem to RubyGems.org. To allow pushes either set the 'allowed_push_host'
+  # to allow pushing to a single host or delete this section to allow pushing to any host.
+  if spec.respond_to?(:metadata)
+    spec.metadata["allowed_push_host"] = "https://rubygems.org"
+
+    spec.metadata["homepage_uri"] = spec.homepage
+    spec.metadata["source_code_uri"] = spec.homepage
+    spec.metadata["changelog_uri"] = "#{spec.homepage}/CHANGES.md"
+  else
+    raise "RubyGems 2.0 or newer is required to protect against " \
+          "public gem pushes."
+  end
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files = Dir.chdir(File.expand_path('..', __FILE__)) do
+    `git ls-files -z`.split("\x0").reject { |f|
+      f.match(%r{^(test|spec|features)/})
+    }
+  end
+
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 2.1"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "rspec", "~> 3.0"
+  spec.add_development_dependency "irb"
+end

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "assume"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start(__FILE__)

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/lib/assume.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require "assume/version"
+
+module Assume
+  class BadAssumption < StandardError; end
+
+  DEFAULT_HANDLER = lambda do |result, block|
+    filename, line = block.source_location
+    begin
+      lines = File.readlines(filename)
+      line_content = lines[line - 1]
+    rescue Errno::ENOENT => err
+      line_content = "<unable to open source code file>"
+    end
+
+    raise BadAssumption, "\nin #{filename}\nsource" \
+                         "code (line #{line}):\n#{line_content}\n" \
+                         "result was: #{result.inspect}"
+  end
+
+  def assume(&block)
+    raise ArgumentError, "assumptions need a block" if block.nil?
+    return unless Assume.enabled?
+
+    result = block.call
+
+    unless result
+      Assume.broken_assumption_handler.call(result, block)
+    end
+
+    nil
+  end
+  alias assumption assume
+
+  class << self
+    def handler=(handler)
+      @assumption_handler = handler
+    end
+
+    def enabled=(val)
+      @enabled = !!val
+    end
+
+    def enabled?
+      @enabled
+    end
+
+    def broken_assumption_handler
+      @assumption_handler || DEFAULT_HANDLER
+    end
+  end
+end
+
+Assume.enabled = false

data/lib/assume/core_ext.rb

@@ -0,0 +1,3 @@
+class Object
+  include Assume
+end

data/lib/assume/refine.rb

@@ -0,0 +1,5 @@
+module Assumptions
+  refine Kernel do
+    include Assume
+  end
+end

data/lib/assume/version.rb

@@ -0,0 +1,3 @@
+module Assume
+  VERSION = "0.1.0"
+end

metadata

@@ -0,0 +1,118 @@
+--- !ruby/object:Gem::Specification
+name: assume
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Odin H B
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2020-12-10 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.1'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: irb
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Assume encourages you to communicate with your team members and build
+  confidence in your code
+email:
+- odinh2908@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rspec"
+- CHANGES.md
+- Gemfile
+- Gemfile.lock
+- LICENSE
+- README.md
+- Rakefile
+- assume.gemspec
+- bin/console
+- bin/setup
+- lib/assume.rb
+- lib/assume/core_ext.rb
+- lib/assume/refine.rb
+- lib/assume/version.rb
+homepage: https://github.com/odinhb/assume
+licenses: []
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/odinhb/assume
+  source_code_uri: https://github.com/odinhb/assume
+  changelog_uri: https://github.com/odinhb/assume/CHANGES.md
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.1.4
+signing_key:
+specification_version: 4
+summary: Write your assumptions down - in code
+test_files: []