mini_sanity 1.1.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: ba5fd068770843f3044c6dade58282429e1330e5
-  data.tar.gz: 1aa0bfd6c7f88f9a0e1d992cd18289c5a9328ac1
+SHA256:
+  metadata.gz: 7c8c35bb9700789272562d521aac498397bbc97c889147386fd9381787ea59f0
+  data.tar.gz: 8be2caee26ff3dd317f5cd7efe81c2c2628fcb7870f14d0b7e8fb4295a2b32fd
 SHA512:
-  metadata.gz: 1dfe7f149c334cd7ea7eb2330ddf834b72a17bb3009cdd45f42dd8e1347278084a65c835a1d7d438e881a64d42750ab8fda3eefd0fb498a919e76faa38a59bd3
-  data.tar.gz: ea9642cd25487cf2f54d990843f79ba98cece1b560811ea791644e2c010707d910fb5def8800a9518bec04ef274b9db7bf9884a1612549888ee6dfe5102f7260
+  metadata.gz: d61148344efa1863fdf331cc9a2e42deec1e92e5d40d596b566592b3accc826f6042eeaa440340acd7e456e0ccffcef5c0fc5cc13cbf2e573cf9695d1befeb8e
+  data.tar.gz: bbf8dbfbb7c41a1cdd0084ab81a938e85a99d3271716d6fb2d67593a503ed026bc2439c3d489097c8fd0190c6741eed8c2ba56d197d2883e20be06904e04f728

data/.travis.yml

@@ -1,5 +1,5 @@
-sudo: false
 language: ruby
+
 rvm:
-  - 2.2.5
-before_install: gem install bundler -v 1.15.1
+  - 2.6
+  - 2.7

data/CHANGELOG.md

@@ -1,30 +1,66 @@
-## 1.1.0
+## 2.0.0
+
+* [BREAKING] Drop support for Ruby < 2.6
+* Add `Object#assert!`
+* Add `Object#refute!`
+* [BREAKING] Remove methods obsoleted by `Object#assert!` and `#refute!`
+  * `Object#assert_equal!` => `assert!(expected *OR* Set[expected])`
+  * `Object#assert_in!` => `assert!(permitted.to_set)`
+  * `Object#assert_instance_of!` => `assert!(Set[klass], &:class)`
+  * `Object#assert_kind_of!` => `assert!(klass)`
+  * `Object#assert_nil!` => `assert!(nil)`
+  * `Object#refute_equal!` => `refute!(forbidden *OR* Set[forbidden])`
+  * `Object#refute_in!` => `refute!(prohibited.to_set)`
+  * `Object#refute_nil!` => `refute!(nil)`
+  * `Array#assert_length!` => `assert!(permitted_length, &:length)`
+  * `Array#refute_length!` => `refute!(prohibited_length, &:length)`
+  * `Enumerable#assert_empty!` => `assert!(&:empty?)`
+  * `Enumerable#refute_empty!` => `refute!(&:empty?)`
+  * `String#assert_empty!` => `assert!(&:empty?)`
+  * `String#assert_length!` => `assert!(permitted_length, &:length)`
+  * `String#assert_match!` => `assert!(pattern)`
+  * `String#refute_empty!` => `refute!(&:empty?)`
+  * `String#refute_length!` => `refute!(prohibited_length, &:length)`
+  * `String#refute_match!` => `refute!(pattern)`
+  * `Pathname#assert_dir!` => `assert!(&:directory?)`
+  * `Pathname#assert_exist!` => `assert!(&:exist?)`
+  * `Pathname#assert_file!` => `assert!(&:file?)`
+  * `Pathname#refute_dir!` => `refute!(&:directory?)`
+  * `Pathname#refute_exist!` => `refute!(&:exist?)`
+  * `Pathname#refute_file!` => `refute!(&:file?)`
+* [BREAKING] Remove `Object#assert_respond_to!`
+* [BREAKING] Remove `Enumerable#first!`
+  * Replacement for most cases: `assert!(n.., &:size).first(n)`
+* [BREAKING] `require "mini_sanity"` now loads all pieces of the API.
+  However, individual pieces of the API can be loaded a la carte via
+  e.g. `require "mini_sanity/assert"`.
+* Add `Enumerator#result!`
+* Add `Enumerator#results!`
 
-* Standardized exception error messages
 
-* Added sanity check methods:
-  * Array#assert_length!
-  * Array#refute_length!
-  * Enumerable#assert_empty!
-  * Object#assert_equal!
-  * Object#assert_in!
-  * Object#assert_nil!
-  * Object#refute_equal!
-  * Object#refute_in!
-  * Pathname#assert_dir!
-  * Pathname#assert_file!
-  * Pathname#refute_dir!
-  * Pathname#refute_file!
-  * String#assert_empty!
-  * String#assert_length!
-  * String#refute_length!
+## 1.1.0
 
-* Added utility methods:
-  * Enumerable#first!
-  * Regexp#match!
-  * String#change
-  * String#change!
-  * String#match!
+* Standardize error messages
+* Add `Array#assert_length!`
+* Add `Array#refute_length!`
+* Add `Enumerable#assert_empty!`
+* Add `Object#assert_equal!`
+* Add `Object#assert_in!`
+* Add `Object#assert_nil!`
+* Add `Object#refute_equal!`
+* Add `Object#refute_in!`
+* Add `Pathname#assert_dir!`
+* Add `Pathname#assert_file!`
+* Add `Pathname#refute_dir!`
+* Add `Pathname#refute_file!`
+* Add `String#assert_empty!`
+* Add `String#assert_length!`
+* Add `String#refute_length!`
+* Add `Enumerable#first!` (loaded via `require "mini_sanity/util"`)
+* Add `Regexp#match!` (loaded via `require "mini_sanity/util"`)
+* Add `String#change` (loaded via `require "mini_sanity/util"`)
+* Add `String#change!` (loaded via `require "mini_sanity/util"`)
+* Add `String#match!` (loaded via `require "mini_sanity/util"`)
 
 
 ## 1.0.0

data/Gemfile

@@ -2,3 +2,6 @@ source "https://rubygems.org"
 
 # Specify your gem's dependencies in mini_sanity.gemspec
 gemspec
+
+gem "rake", "~> 12.0"
+gem "minitest", "~> 5.0"

data/README.md

@@ -1,10 +1,10 @@
-# mini_sanity
+# mini_sanity [![Build Status](https://travis-ci.org/jonathanhefner/mini_sanity.svg?branch=master)](https://travis-ci.org/jonathanhefner/mini_sanity)
 
 In-line [sanity checks], written as extensions to core Ruby objects.
 See API listing below, or browse the [full documentation].
 
 [sanity checks]: https://en.wikipedia.org/wiki/Sanity_check
-[full documentation]: http://www.rubydoc.info/gems/mini_sanity/
+[full documentation]: https://www.rubydoc.info/gems/mini_sanity/
 
 
 ## Example
@@ -13,91 +13,54 @@ See API listing below, or browse the [full documentation].
 require "json"
 require "pathname"
 
-path = Pathname.new("hosted_files.json").assert_exist!
+path = Pathname.new("hosted_files.json").assert!(&:exist?)
 
-hosted_files = JSON.parse(path.read).assert_instance_of!(Array)
+hosted_files = JSON.parse(path.read).assert!(Array)
 
 urls = hosted_files.flat_map do |file_info|
-  file_info.fetch("mirror_urls").refute_empty!
+  file_info.fetch("mirror_urls").refute!(&:empty?)
 end
 
 domains = urls.map do |url|
-  url.assert_match!(%r"^https?://").split("/")[2]
+  url.assert!(%r"^https?://").split("/")[2]
 end.uniq
 ```
 
 
 ## API
 
-- [Object](http://www.rubydoc.info/gems/mini_sanity/Object)
-  - [#assert_equal!](http://www.rubydoc.info/gems/mini_sanity/Object:assert_equal%21)
-  - [#assert_in!](http://www.rubydoc.info/gems/mini_sanity/Object:assert_in%21)
-  - [#assert_instance_of!](http://www.rubydoc.info/gems/mini_sanity/Object:assert_instance_of%21)
-  - [#assert_kind_of!](http://www.rubydoc.info/gems/mini_sanity/Object:assert_kind_of%21)
-  - [#assert_nil!](http://www.rubydoc.info/gems/mini_sanity/Object:assert_nil%21)
-  - [#assert_respond_to!](http://www.rubydoc.info/gems/mini_sanity/Object:assert_respond_to%21)
-  - [#refute_equal!](http://www.rubydoc.info/gems/mini_sanity/Object:refute_equal%21)
-  - [#refute_in!](http://www.rubydoc.info/gems/mini_sanity/Object:refute_in%21)
-  - [#refute_nil!](http://www.rubydoc.info/gems/mini_sanity/Object:refute_nil%21)
-- [Array](http://www.rubydoc.info/gems/mini_sanity/Array)
-  - [#assert_length!](http://www.rubydoc.info/gems/mini_sanity/Array:assert_length%21)
-  - [#refute_length!](http://www.rubydoc.info/gems/mini_sanity/Array:refute_length%21)
-- [Enumerable](http://www.rubydoc.info/gems/mini_sanity/Enumerable)
-  - [#assert_empty!](http://www.rubydoc.info/gems/mini_sanity/Enumerable:assert_empty%21)
-  - [#refute_empty!](http://www.rubydoc.info/gems/mini_sanity/Enumerable:refute_empty%21)
-- [String](http://www.rubydoc.info/gems/mini_sanity/String)
-  - [#assert_empty!](http://www.rubydoc.info/gems/mini_sanity/String:assert_empty%21)
-  - [#assert_length!](http://www.rubydoc.info/gems/mini_sanity/String:assert_length%21)
-  - [#assert_match!](http://www.rubydoc.info/gems/mini_sanity/String:assert_match%21)
-  - [#refute_empty!](http://www.rubydoc.info/gems/mini_sanity/String:refute_empty%21)
-  - [#refute_length!](http://www.rubydoc.info/gems/mini_sanity/String:refute_length%21)
-  - [#refute_match!](http://www.rubydoc.info/gems/mini_sanity/String:refute_match%21)
-- [Pathname](http://www.rubydoc.info/gems/mini_sanity/Pathname)
-  - [#assert_dir!](http://www.rubydoc.info/gems/mini_sanity/Pathname:assert_dir%21)
-  - [#assert_exist!](http://www.rubydoc.info/gems/mini_sanity/Pathname:assert_exist%21)
-  - [#assert_file!](http://www.rubydoc.info/gems/mini_sanity/Pathname:assert_file%21)
-  - [#refute_dir!](http://www.rubydoc.info/gems/mini_sanity/Pathname:refute_dir%21)
-  - [#refute_exist!](http://www.rubydoc.info/gems/mini_sanity/Pathname:refute_exist%21)
-  - [#refute_file!](http://www.rubydoc.info/gems/mini_sanity/Pathname:refute_file%21)
-
-
-## Util API
-
-*mini_sanity* also includes a few optional utility methods which perform
-some function, check an assertion on the result, and raise an error with
-a helpful message if the assertion fails.  You must add
-`require "mini_sanity/util"` to your script to access these methods.
-
-- [Enumerable](http://www.rubydoc.info/gems/mini_sanity/Enumerable)
-  - [#first!](http://www.rubydoc.info/gems/mini_sanity/Enumerable:first%21)
-- [Regexp](http://www.rubydoc.info/gems/mini_sanity/Regexp)
-  - [#match!](http://www.rubydoc.info/gems/mini_sanity/Regexp:match%21)
-- [String](http://www.rubydoc.info/gems/mini_sanity/String)
-  - [#change](http://www.rubydoc.info/gems/mini_sanity/String:change)
-  - [#change!](http://www.rubydoc.info/gems/mini_sanity/String:change%21)
-  - [#match!](http://www.rubydoc.info/gems/mini_sanity/String:match%21)
+- `"mini_sanity/assert"`
+  - [Object#assert!](https://www.rubydoc.info/gems/mini_sanity/Object:assert%21)
+  - [Object#refute!](https://www.rubydoc.info/gems/mini_sanity/Object:refute%21)
+- `"mini_sanity/change"`
+  - [String#change](https://www.rubydoc.info/gems/mini_sanity/String:change)
+  - [String#change!](https://www.rubydoc.info/gems/mini_sanity/String:change%21)
+- `"mini_sanity/match"`
+  - [Regexp#match!](https://www.rubydoc.info/gems/mini_sanity/Regexp:match%21)
+  - [String#match!](https://www.rubydoc.info/gems/mini_sanity/String:match%21)
+- `"mini_sanity/results"`
+  - [Enumerator#result!](https://www.rubydoc.info/gems/mini_sanity/Enumerator:result%21)
+  - [Enumerator#results!](https://www.rubydoc.info/gems/mini_sanity/Enumerator:results%21)
 
 
 ## Installation
 
-Install from [Ruby Gems](https://rubygems.org/gems/mini_sanity):
+Install the [gem](https://rubygems.org/gems/mini_sanity):
 
 ```bash
 $ gem install mini_sanity
 ```
 
-Then require in your Ruby script:
+Then require in your Ruby code:
 
 ```ruby
 require "mini_sanity"
-require "mini_sanity/util" # OPTIONAL
 ```
 
 
 ## Contributing
 
-Run `rake test` to run the tests.  You can also run `rake irb` for an
-interactive prompt that pre-loads the project code.
+Run `rake test` to run the tests.
 
 
 ## License

data/Rakefile

@@ -1,19 +1,5 @@
 require "bundler/gem_tasks"
 require "rake/testtask"
-require "yard"
-
-
-YARD::Rake::YardocTask.new(:doc) do |t|
-end
-
-desc "Launch IRB with this gem pre-loaded"
-task :irb do
-  require "mini_sanity"
-  require "mini_sanity/util"
-  require "irb"
-  ARGV.clear
-  IRB.start
-end
 
 Rake::TestTask.new(:test) do |t|
   t.libs << "test"

data/lib/mini_sanity.rb

@@ -1,7 +1,5 @@
 require_relative "mini_sanity/version"
-require_relative "mini_sanity/error"
-require_relative "mini_sanity/array"
-require_relative "mini_sanity/enumerable"
-require_relative "mini_sanity/object"
-require_relative "mini_sanity/pathname"
-require_relative "mini_sanity/string"
+require_relative "mini_sanity/assert"
+require_relative "mini_sanity/change"
+require_relative "mini_sanity/match"
+require_relative "mini_sanity/results"

data/lib/mini_sanity/assert.rb

@@ -0,0 +1,163 @@
+require_relative "error"
+
+
+module MiniSanity
+  # Matches truthy values (i.e. not +false+ or +nil+).
+  TRUTHY = ->(x){ !!x }
+
+  def TRUTHY.inspect
+    "MiniSanity::TRUTHY"
+  end
+end
+
+
+class Object
+
+  # Checks that a given +pattern+ matches the Object (or a derivative
+  # value), and returns the Object.  Raises an exception if the pattern
+  # does not match.
+  #
+  # If a block is given, the Object is yielded to the block, and the
+  # derivative value returned by the block is checked instead.
+  #
+  # @example Match truthy
+  #   "foo".assert!  # == "foo"
+  #   nil.assert!    # raises exception
+  #
+  # @example Match expected value
+  #   "foo".assert!("foo")  # == "foo"
+  #   "bar".assert!("foo")  # raises exception
+  #
+  # @example Match Set of permitted values
+  #   "foo".assert!(Set["foo", "bar"])  # == "foo"
+  #   "bar".assert!(Set["foo", "bar"])  # == "bar"
+  #   "baz".assert!(Set["foo", "bar"])  # raises exception
+  #
+  # @example Match Class
+  #   25.assert!(Integer)   # == 25
+  #   2.5.assert!(Integer)  # raises exception
+  #
+  # @example Match Regexp
+  #   "foo".assert!(/^f/)  # == "foo"
+  #   "bar".assert!(/^f/)  # raises exception
+  #
+  # @example Match Range
+  #   2.assert!(1..4)  # == 2
+  #   5.assert!(1..4)  # raises exception
+  #
+  # @example Match truthy derivative value
+  #   [2, 5].assert!(&:any?)  # == [2, 5]
+  #   [nil].assert!(&:any?)   # raises exception
+  #
+  # @example Match derivative value
+  #   [2, 5].assert!(1.., &:length)  # == [2, 5]
+  #   [].assert!(1.., &:length)      # raises exception
+  #
+  # @overload assert!(pattern = MiniSanity::TRUTHY, hint: nil)
+  #   @param pattern [#===]
+  #   @param hint [String]
+  #     Hint to include in the error message
+  #   @return [self]
+  #   @raise [MiniSanity::Error]
+  #     if +pattern+ does not match the Object
+  #
+  # @overload assert!(pattern = MiniSanity::TRUTHY, hint: nil, &block)
+  #   @param pattern [#===]
+  #   @param hint [String]
+  #     Hint to include in the error message
+  #   @yieldparam itself [self]
+  #   @yieldreturn [Object]
+  #     Derivative value
+  #   @return [self]
+  #   @raise [MiniSanity::Error]
+  #     if +pattern+ does not match the value returned by +block+
+  def assert!(pattern = MiniSanity::TRUTHY, hint: nil, &block)
+    result = block ? block.call(self) : self
+
+    unless pattern === result
+      raise MiniSanity::Error.new("Assert failed", {
+        "Value" => self.inspect,
+        "Derived value (from #{MiniSanity::Error.describe_block(&block) || "block"})" =>
+          (result.inspect if block),
+        "Assert matches" => pattern.inspect,
+        "Hint" => hint,
+      })
+    end
+
+    self
+  end
+
+  # Checks that a given +pattern+ does not match the Object (or a
+  # derivative value), and returns the Object.  Raises an exception if
+  # the pattern matches.
+  #
+  # If a block is given, the Object is yielded to the block, and the
+  # derivative value returned by the block is checked instead.
+  #
+  # @example Refute truthy
+  #   false.refute!  # == false
+  #   "bad".refute!  # raises exception
+  #
+  # @example Refute forbidden value
+  #   "foo".refute!("bad")  # == "foo"
+  #   "bad".refute!("bad")  # raises exception
+  #
+  # @example Refute Set of prohibited values
+  #   "foo".refute!(Set["bad", "worse"])  # == "foo"
+  #   "bad".refute!(Set["bad", "worse"])  # raises exception
+  #
+  # @example Refute Class
+  #   25.refute!(Float)   # == 25
+  #   2.5.refute!(Float)  # raises exception
+  #
+  # @example Refute Regexp
+  #   "foo".refute!(/^ba/)  # == "foo"
+  #   "bad".refute!(/^ba/)  # raises exception
+  #
+  # @example Refute Range
+  #   2.refute!(5..)  # == 2
+  #   5.refute!(5..)  # raises exception
+  #
+  # @example Refute truthy derivative value
+  #   [2].refute!(&:empty?)  # == [2]
+  #   [].refute!(&:empty?)   # raises exception
+  #
+  # @example Refute derivative value
+  #   [2].refute!(1.., &:length)     # == [2]
+  #   [2, 5].refute!(1.., &:length)  # raises exception
+  #
+  # @overload refute!(pattern = MiniSanity::TRUTHY, hint: nil)
+  #   @param pattern [#===]
+  #   @param hint [String]
+  #     Hint to include in the error message
+  #   @return [self]
+  #   @raise [MiniSanity::Error]
+  #     if +pattern+ matches the Object
+  #
+  # @overload refute!(pattern = MiniSanity::TRUTHY, hint: nil, &block)
+  #   @param pattern [#===]
+  #   @param hint [String]
+  #     Hint to include in the error message
+  #   @yieldparam itself [self]
+  #   @yieldreturn [Object]
+  #     Derivative value
+  #   @return [self]
+  #   @raise [MiniSanity::Error]
+  #     if +pattern+ matches the value returned by +block+
+  def refute!(pattern = MiniSanity::TRUTHY, hint: nil, &block)
+    result = block ? block.call(self) : self
+
+    if pattern === result
+      raise MiniSanity::Error.new("Refute failed", {
+        "Value" => self.inspect,
+        "Derived value (from #{MiniSanity::Error.describe_block(&block) || "block"})" =>
+          (result.inspect if block),
+        "Refute matches" => pattern.inspect,
+        "Hint" => hint,
+      })
+    end
+
+    self
+  end
+
+end

data/lib/mini_sanity/change.rb

@@ -0,0 +1,107 @@
+require_relative "error"
+
+
+class String
+
+  # Like {https://docs.ruby-lang.org/en/master/String.html#method-i-sub-21
+  # +String#sub!+}, but raises an exception if no substitution is
+  # performed.
+  #
+  # @example
+  #   info = "library: LIB_NAME\nlanguage: LIB_LANG\n"
+  #   info.change!(/\bLIB_NAME\b/, "mini_sanity")  # == "library: mini_sanity\nlanguage: LIB_LANG\n"
+  #   info                                         # == "library: mini_sanity\nlanguage: LIB_LANG\n"
+  #   info.change!(/\bLIB_LANGUAGE\b/, "Ruby")     # raises exception
+  #
+  # @overload change!(pattern, replacement)
+  #   @param pattern [Regexp, String]
+  #     Pattern to search for
+  #   @param replacement [String]
+  #     Replacement String (see +String#sub+ documentation for more
+  #     information)
+  #   @return [String]
+  #   @raise [MiniSanity::Error]
+  #     if no substitution was performed
+  #
+  # @overload change!(pattern, hash)
+  #   @param pattern [Regexp, String]
+  #     Pattern to search for
+  #   @param hash [Hash]
+  #     Substitution Hash (see +String#sub+ documentation for more
+  #     information)
+  #   @return [String]
+  #   @raise [MiniSanity::Error]
+  #     if no substitution was performed
+  #
+  # @overload change!(pattern, &block)
+  #   @param pattern [Regexp, String]
+  #     Pattern to search for
+  #   @yieldparam match [String]
+  #     Matched String
+  #   @yieldreturn [String]
+  #     Replacement String
+  #   @return [String]
+  #   @raise [MiniSanity::Error]
+  #     if no substitution was performed
+  def change!(pattern, replacement = nil, &block)
+    result = if replacement
+      self.sub!(pattern, replacement)
+    else
+      self.sub!(pattern, &block)
+    end
+
+    if !result
+      raise MiniSanity::Error.new("String does not match pattern", {
+        "String" => self.inspect,
+        "Pattern" => pattern.inspect,
+      })
+    end
+
+    result
+  end
+
+  # Like {https://docs.ruby-lang.org/en/master/String.html#method-i-sub
+  # +String#sub+}, but raises an exception if no substitution is
+  # performed.
+  #
+  # @example
+  #   info = "library: LIB_NAME\nlanguage: LIB_LANG\n"
+  #   info.change(/\bLIB_NAME\b/, "mini_sanity")  # == "library: mini_sanity\nlanguage: LIB_LANG\n"
+  #   info                                        # == "library: LIB_NAME\nlanguage: LIB_LANG\n"
+  #   info.change(/\bLIB_LANGUAGE\b/, "Ruby")     # raises exception
+  #
+  # @overload change(pattern, replacement)
+  #   @param pattern [Regexp, String]
+  #     Pattern to search for
+  #   @param replacement [String]
+  #     Replacement String (see +String#sub+ documentation for more
+  #     information)
+  #   @return [String]
+  #   @raise [MiniSanity::Error]
+  #     if no substitution was performed
+  #
+  # @overload change(pattern, hash)
+  #   @param pattern [Regexp, String]
+  #     Pattern to search for
+  #   @param hash [Hash]
+  #     Substitution Hash (see +String#sub+ documentation for more
+  #     information)
+  #   @return [String]
+  #   @raise [MiniSanity::Error]
+  #     if no substitution was performed
+  #
+  # @overload change(pattern, &block)
+  #   @param pattern [Regexp, String]
+  #     Pattern to search for
+  #   @yieldparam match [String]
+  #     Matched String
+  #   @yieldreturn [String]
+  #     Replacement String
+  #   @return [String]
+  #   @raise [MiniSanity::Error]
+  #     if no substitution was performed
+  def change(pattern, replacement = nil, &block)
+    self.dup.change!(pattern, replacement, &block)
+  end
+
+end