mini_sanity 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: c5da04d9d5a007087a446a04332d0ffc6384a5d8
-  data.tar.gz: a26754f66a63338980c31d97461d8a443d868106
+  metadata.gz: ba5fd068770843f3044c6dade58282429e1330e5
+  data.tar.gz: 1aa0bfd6c7f88f9a0e1d992cd18289c5a9328ac1
 SHA512:
-  metadata.gz: d595fc9b17a60fb29ece9f2d553c0549aaa341ce055d16589157e4be2be072b0c28d92c8ea3a35973d6bce0aaf30444b1644f6f3704033e39462eb3289c9d8e7
-  data.tar.gz: '08db65b91fc28caa65d47a711afb0cb338ad0edfd1a601e78e642bb1846f4e150547612b42f996e77222c9ac27c8a35a86fa437da97a7c12fbc8c7af4cadb005'
+  metadata.gz: 1dfe7f149c334cd7ea7eb2330ddf834b72a17bb3009cdd45f42dd8e1347278084a65c835a1d7d438e881a64d42750ab8fda3eefd0fb498a919e76faa38a59bd3
+  data.tar.gz: ea9642cd25487cf2f54d990843f79ba98cece1b560811ea791644e2c010707d910fb5def8800a9518bec04ef274b9db7bf9884a1612549888ee6dfe5102f7260

data/CHANGELOG.md

@@ -0,0 +1,32 @@
+## 1.1.0
+
+* 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!
+
+* Added utility methods:
+  * Enumerable#first!
+  * Regexp#match!
+  * String#change
+  * String#change!
+  * String#match!
+
+
+## 1.0.0
+
+* Initial release

data/README.md

@@ -1,13 +1,13 @@
 # mini_sanity
 
-In-line [sanity checks], written as extensions to core Ruby objects.  See
-API listing below, or browse the [full documentation].
+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/
 
 
-# Example
+## Example
 
 ```ruby
 require "json"
@@ -27,22 +27,55 @@ end.uniq
 ```
 
 
-# API
+## 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)
 
 
 ## Installation
@@ -57,6 +90,7 @@ Then require in your Ruby script:
 
 ```ruby
 require "mini_sanity"
+require "mini_sanity/util" # OPTIONAL
 ```
 
 

data/Rakefile

@@ -9,6 +9,7 @@ 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

data/lib/mini_sanity.rb

@@ -1,5 +1,6 @@
 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"

data/lib/mini_sanity/array.rb

@@ -0,0 +1,63 @@
+class Array
+
+  # Checks that the Array matches a given length, and returns the Array
+  # unmodified.  If the Array fails this check, an exception is
+  # raised.
+  #
+  # @example
+  #   coord = [0, 0, 0]
+  #   coord.assert_length(3)!  # == [0, 0, 0]
+  #
+  #   coord = [0, 0]
+  #   coord.assert_length(3)!  # raises exception
+  #
+  #   coord = [0, 0]
+  #   coord.assert_length(2..3)!  # == [0, 0]
+  #
+  # @param length [Integer, Range<Integer>]
+  #   length to match
+  # @param name [String, Symbol]
+  #   optional name to include in the error message
+  # @return [self]
+  # @raise [MiniSanity::Error]
+  #   if the Array length does not match +length+
+  def assert_length!(length, name = nil)
+    if !(length === self.length)
+      raise MiniSanity::Error.new(name,
+        "#{self.class} having #{length} elements",
+        self.inspect)
+    end
+    self
+  end
+
+  # Checks that the Array does not match a given length, and returns the
+  # Array unmodified.  If the Array fails this check, an exception is
+  # raised.
+  #
+  # @example
+  #   some = ["one"]
+  #   some.refute_length!(0)  # == ["one"]
+  #
+  #   some = []
+  #   some.refute_length(0)!  # raises exception
+  #
+  #   many = ["one", "many"]
+  #   many.refute_length!(0..1)  # == ["one", "many"]
+  #
+  # @param length [Integer, Range<Integer>]
+  #   length to not match
+  # @param name [String, Symbol]
+  #   optional name to include in the error message
+  # @return [self]
+  # @raise [MiniSanity::Error]
+  #   if the Array length matches +length+
+  def refute_length!(length, name = nil)
+    if length === self.length
+      raise MiniSanity::Error.new(name,
+        "#{self.class} not having #{length} elements",
+        self.inspect)
+    end
+    self
+  end
+
+end

data/lib/mini_sanity/enumerable.rb

@@ -1,12 +1,37 @@
 module Enumerable
 
+  # Checks that the Enumerable is empty, and returns the Enumerable
+  # unmodified.  If the Enumerable fails this check, an exception is
+  # raised.
+  #
+  # @example
+  #   errors = []
+  #   errors.assert_empty!  # == []
+  #
+  #   errors = ["something went wrong"]
+  #   errors.assert_empty!  # raises exception
+  #
+  # @param name [String, Symbol]
+  #   optional name to include in the error message
+  # @return [self]
+  # @raise [MiniSanity::Error]
+  #   if the Enumerable is not empty
+  def assert_empty!(name = nil)
+    if self.any?{ true }
+      raise MiniSanity::Error.new(name,
+        "empty #{self.class}",
+        self.inspect)
+    end
+    self
+  end
+
   # Checks that the Enumerable is not empty, and returns the Enumerable
   # unmodified.  If the Enumerable fails this check, an exception is
   # raised.
   #
   # @example
-  #   [7, 8].refute_empty!  # == [7, 8]
-  #   [].refute_empty!      # raises exception
+  #   ["result 1"].refute_empty!  # == ["result 1"]
+  #   [].refute_empty!            # raises exception
   #
   # @param name [String, Symbol]
   #   optional name to include in the error message
@@ -14,8 +39,12 @@ module Enumerable
   # @raise [MiniSanity::Error]
   #   if the Enumerable is empty
   def refute_empty!(name = nil)
-    if self.empty?
-      raise MiniSanity::Error.new("#{name || self.class} is empty")
+    # NOTE use #any? instead of #none? because Array#none? seems to be
+    # significantly slower than Array#any? (and likewise for Hash)
+    if !self.any?{ true }
+      raise MiniSanity::Error.new(name,
+        "non-empty #{self.class}",
+        self.inspect)
     end
     self
   end

data/lib/mini_sanity/error.rb

@@ -1,2 +1,11 @@
 class MiniSanity::Error < RuntimeError
+
+  def initialize(name, expected, actual)
+    super(
+      "\n#{name || "value"} violates expectations\n" \
+      "  expected: #{expected}\n" \
+      "  actual: #{actual}\n"
+    )
+  end
+
 end

data/lib/mini_sanity/object.rb

@@ -1,11 +1,35 @@
 class Object
 
+  # Checks that the Object is nil, and returns nil.  If the Object fails
+  # this check, an exception is raised.
+  #
+  # @example
+  #   result = {}
+  #   result[:error].assert_nil!  # == nil
+  #
+  #   result = { error: "something went wrong" }
+  #   result[:error].assert_nil!  # == raises exception
+  #
+  # @param name [String, Symbol]
+  #   optional name to include in the error message
+  # @return [self]
+  # @raise [MiniSanity::Error]
+  #   if the Object is not nil
+  def assert_nil!(name = nil)
+    if !self.nil?
+      raise MiniSanity::Error.new(name,
+        "nil",
+        self.inspect)
+    end
+    self
+  end
+
   # Checks that the Object is not nil, and returns the Object
   # unmodified.  If the Object fails this check, an exception is raised.
   #
   # @example
-  #   [7, 8].first.refute_nil!  # == 7
-  #   [].first.refute_nil!      # raises exception
+  #   ["result 1"].first.refute_nil!  # == "result 1"
+  #   [].first.refute_nil!            # raises exception
   #
   # @param name [String, Symbol]
   #   optional name to include in the error message
@@ -14,8 +38,105 @@ class Object
   #   if the Object is nil
   def refute_nil!(name = nil)
     if self.nil?
-      message = name ? "#{name} is nil" : "unexpected nil"
-      raise MiniSanity::Error.new(message)
+      raise MiniSanity::Error.new(name,
+        "non-nil value",
+        "nil")
+    end
+    self
+  end
+
+  # Checks that the Object equals a given expected value, and returns
+  # the Object unmodified.  If the Object fails this check, an exception
+  # is raised.
+  #
+  # @example
+  #   "good".assert_equal!("good")  # == "good"
+  #   "bad".assert_equal!("good")   # raises exception
+  #
+  # @param expect [Object]
+  #   value to expect
+  # @param name [String, Symbol]
+  #   optional name to include in the error message
+  # @return [self]
+  # @raise [MiniSanity::Error]
+  #   if the Object does not equal +expect+
+  def assert_equal!(expect, name = nil)
+    if self != expect
+      raise MiniSanity::Error.new(name,
+        expect.inspect,
+        self.inspect)
+    end
+    self
+  end
+
+  # Checks that the Object does not equal a given reject value, and
+  # returns the Object unmodified.  If the Object fails this check, an
+  # exception is raised.
+  #
+  # @example
+  #   "good".refute_equal!("bad")  # == "good"
+  #   "bad".refute_equal!("bad")   # raises exception
+  #
+  # @param reject [Object]
+  #   value to reject
+  # @param name [String, Symbol]
+  #   optional name to include in the error message
+  # @return [self]
+  # @raise [MiniSanity::Error]
+  #   if the Object equals +reject+
+  def refute_equal!(reject, name = nil)
+    if self == reject
+      raise MiniSanity::Error.new(name,
+        "not #{reject.inspect}",
+        self.inspect)
+    end
+    self
+  end
+
+  # Checks that the Object is included in a given collection, and
+  # returns the Object unmodified.  If the Object fails this check, an
+  # exception is raised.
+  #
+  # @example
+  #   "good".assert_in!(["ok", "good", "great"])  # == "good"
+  #   "bad".assert_in!(["ok", "good", "great"])   # raises exception
+  #
+  # @param permitted [Enumerable, #include?]
+  #   collection of permitted values
+  # @param name [String, Symbol]
+  #   optional name to include in the error message
+  # @return [self]
+  # @raise [MiniSanity::Error]
+  #   if the Object is not included in +permitted+
+  def assert_in!(permitted, name = nil)
+    if !permitted.include?(self)
+      raise MiniSanity::Error.new(name,
+        "value included in #{permitted.inspect}",
+        self.inspect)
+    end
+    self
+  end
+
+  # Checks that the Object is not included in a given collection, and
+  # returns the Object unmodified.  If the Object fails this check, an
+  # exception is raised.
+  #
+  # @example
+  #   "good".refute_in!(["bad", "poor", "fail"])  # == "good"
+  #   "bad".refute_in!(["bad", "poor", "fail"])   # raises exception
+  #
+  # @param prohibited [Enumerable, #include?]
+  #   collection of prohibited values
+  # @param name [String, Symbol]
+  #   optional name to include in the error message
+  # @return [self]
+  # @raise [MiniSanity::Error]
+  #   if the Object is included in +prohibited+
+  def refute_in!(prohibited, name = nil)
+    if prohibited.include?(self)
+      raise MiniSanity::Error.new(name,
+        "value not included in #{prohibited.inspect}",
+        self.inspect)
     end
     self
   end
@@ -25,8 +146,8 @@ class Object
   # is raised.
   #
   # @example
-  #   "abc".assert_instance_of!(String)   # == "abc"
-  #   "abc".assert_instance_of!(Numeric)  # raises exception
+  #   123.assert_instance_of!(Numeric)  # == 123
+  #   123.assert_instance_of!(String)   # raises exception
   #
   # @param klass [Class]
   #   class to check
@@ -36,9 +157,10 @@ class Object
   # @raise [MiniSanity::Error]
   #   if the Object is not an instance of +klass+
   def assert_instance_of!(klass, name = nil)
-    unless self.instance_of?(klass)
-      prelude = name ? "#{name} is instance of #{self.class}" : "unexpected #{self.class}"
-      raise MiniSanity::Error.new("#{prelude}; expected #{klass}")
+    if !self.instance_of?(klass)
+      raise MiniSanity::Error.new(name,
+        "instance of #{klass}",
+        "instance of #{self.class}: #{self.inspect}")
     end
     self
   end
@@ -48,8 +170,8 @@ class Object
   # this check, an exception is raised.
   #
   # @example
-  #   42.assert_kind_of!(Numeric)  # == 42
-  #   42.assert_kind_of!(Float)    # raises exception
+  #   123.assert_kind_of!(Numeric)  # == 123
+  #   123.assert_kind_of!(Float)    # raises exception
   #
   # @param klass [Class]
   #   class to check
@@ -59,9 +181,10 @@ class Object
   # @raise [MiniSanity::Error]
   #   if the Object is not an instance of +klass+ or its subclasses
   def assert_kind_of!(klass, name = nil)
-    unless self.kind_of?(klass)
-      prelude = name ? "#{name} is instance of #{self.class}" : "unexpected #{self.class}"
-      raise MiniSanity::Error.new("#{prelude}; expected #{klass} or one of its subclasses")
+    if !self.kind_of?(klass)
+      raise MiniSanity::Error.new(name,
+        "instance of #{klass} or one of its subclasses",
+        "instance of #{self.class}: #{self.inspect}")
     end
     self
   end
@@ -82,8 +205,10 @@ class Object
   # @raise [MiniSanity::Error]
   #   if the Object does not respond to +method_name+
   def assert_respond_to!(method_name, name = nil)
-    unless self.respond_to?(method_name)
-      raise MiniSanity::Error.new("#{name || self.class} does not respond to #{method_name}")
+    if !self.respond_to?(method_name)
+      raise MiniSanity::Error.new(name,
+        "object responding to method #{method_name}",
+        "instance of #{self.class}: #{self.inspect}")
     end
     self
   end

data/lib/mini_sanity/pathname.rb

@@ -1,6 +1,6 @@
 class Pathname
 
-  # Checks that the file or directory indicated by the Pathname exists,
+  # Checks that the Pathname represents an existing file or directory,
   # and returns the Pathname unmodified.  If the Pathname fails this
   # check, an exception is raised.
   #
@@ -12,18 +12,19 @@ class Pathname
   #   optional name to include in the error message
   # @return [self]
   # @raise [MiniSanity::Error]
-  #   if the file or directory indicated by the Pathname does not exist
+  #   if the Pathname does not represent an existing file or directory
   def assert_exist!(name = nil)
-    unless self.exist?
-      descriptor = name ? "#{name} (#{self})" : self.to_s
-      raise MiniSanity::Error.new("#{descriptor} does not exist")
+    if !self.exist?
+      raise MiniSanity::Error.new(name,
+        "existent file or directory",
+        "#{self} does not exist")
     end
     self
   end
 
-  # Checks that the file or directory indicated by the Pathname does
-  # not already exist, and returns the Pathname unmodified.  If the
-  # Pathname fails this check, an exception is raised.
+  # Checks that the Pathname does not represent an existing file or
+  # directory, and returns the Pathname unmodified.  If the Pathname
+  # fails this check, an exception is raised.
   #
   # @example
   #   Pathname.new("/dev/null/nope").refute_exist!  # == Pathname.new("/dev/null/nope")
@@ -33,11 +34,100 @@ class Pathname
   #   optional name to include in the error message
   # @return [self]
   # @raise [MiniSanity::Error]
-  #   if the file or directory indicated by the Pathname already exists
+  #   if the Pathname represents an existing file or directory
   def refute_exist!(name = nil)
     if self.exist?
-      descriptor = name ? "#{name} (#{self})" : self.to_s
-      raise MiniSanity::Error.new("#{descriptor} already exists")
+      raise MiniSanity::Error.new(name,
+        "non-existent file or directory",
+        "#{self} already exists")
+    end
+    self
+  end
+
+  # Checks that the Pathname represents an existing directory, and
+  # returns the Pathname unmodified.  If the Pathname fails this check,
+  # an exception is raised.
+  #
+  # @example
+  #   Pathname.new(__dir__).assert_dir!   # == Pathname.new(__dir__)
+  #   Pathname.new(__FILE__).assert_dir!  # == raises exception
+  #
+  # @param name [String, Symbol]
+  #   optional name to include in the error message
+  # @return [self]
+  # @raise [MiniSanity::Error]
+  #   if the Pathname does not represent an existing directory
+  def assert_dir!(name = nil)
+    if !self.directory?
+      raise MiniSanity::Error.new(name,
+        "existent directory",
+        "#{self} is not a directory")
+    end
+    self
+  end
+
+  # Checks that the Pathname does not represent an existing directory,
+  # and returns the Pathname unmodified.  If the Pathname fails this
+  # check, an exception is raised.
+  #
+  # @example
+  #   Pathname.new(__FILE__).refute_dir!  # == Pathname.new(__FILE__)
+  #   Pathname.new(__dir__).refute_dir!   # raises exception
+  #
+  # @param name [String, Symbol]
+  #   optional name to include in the error message
+  # @return [self]
+  # @raise [MiniSanity::Error]
+  #   if the Pathname represents an existing directory
+  def refute_dir!(name = nil)
+    if self.directory?
+      raise MiniSanity::Error.new(name,
+        "not an existent directory",
+        "#{self} is a directory")
+    end
+    self
+  end
+
+  # Checks that the Pathname represents an existing file, and returns
+  # the Pathname unmodified.  If the Pathname fails this check, an
+  # exception is raised.
+  #
+  # @example
+  #   Pathname.new(__FILE__).assert_file!  # == Pathname.new(__FILE__)
+  #   Pathname.new(__dir__).assert_file!   # == raises exception
+  #
+  # @param name [String, Symbol]
+  #   optional name to include in the error message
+  # @return [self]
+  # @raise [MiniSanity::Error]
+  #   if the Pathname does not represent an existing file
+  def assert_file!(name = nil)
+    if !self.file?
+      raise MiniSanity::Error.new(name,
+        "existent file",
+        "#{self} is not a file")
+    end
+    self
+  end
+
+  # Checks that the Pathname does not represent an existing file, and
+  # returns the Pathname unmodified.  If the Pathname fails this check,
+  # an exception is raised.
+  #
+  # @example
+  #   Pathname.new(__dir__).refute_file!   # == Pathname.new(__dir__)
+  #   Pathname.new(__FILE__).refute_file!  # raises exception
+  #
+  # @param name [String, Symbol]
+  #   optional name to include in the error message
+  # @return [self]
+  # @raise [MiniSanity::Error]
+  #   if the Pathname represents an existing file
+  def refute_file!(name = nil)
+    if self.file?
+      raise MiniSanity::Error.new(name,
+        "not an existent file",
+        "#{self} is a file")
     end
     self
   end

data/lib/mini_sanity/string.rb

@@ -1,11 +1,32 @@
 class String
 
+  # Checks that the String is empty, and returns the String unmodified.
+  # If the String fails this check, an exception is raised.
+  #
+  # @example
+  #   "".assert_empty!     # == ""
+  #   "bad".assert_empty!  # raises exception
+  #
+  # @param name [String, Symbol]
+  #   optional name to include in the error message
+  # @return [self]
+  # @raise [MiniSanity::Error]
+  #   if the String is not empty
+  def assert_empty!(name = nil)
+    if !self.empty?
+      raise MiniSanity::Error.new(name,
+        "empty #{self.class}",
+        self.inspect)
+    end
+    self
+  end
+
   # Checks that the String is not empty, and returns the String
   # unmodified.  If the String fails this check, an exception is raised.
   #
   # @example
-  #   "abc".refute_empty!  # == "abc"
-  #   "".refute_empty!     # raises exception
+  #   "result".refute_empty!  # == "result"
+  #   "".refute_empty!        # raises exception
   #
   # @param name [String, Symbol]
   #   optional name to include in the error message
@@ -14,7 +35,59 @@ class String
   #   if the String is empty
   def refute_empty!(name = nil)
     if self.empty?
-      raise MiniSanity::Error.new("#{name || self.class} is empty")
+      raise MiniSanity::Error.new(name,
+        "non-empty #{self.class}",
+        self.inspect)
+    end
+    self
+  end
+
+  # Checks that the String matches a given length, and returns the
+  # String unmodified.  If the String fails this check, an exception is
+  # raised.
+  #
+  # @example
+  #   "password".assert_length!(8)           # == "password"
+  #   "long password".assert_length!(8..64)  # == "long password"
+  #   "pass".assert_length!(8..64)           # == raises exception
+  #
+  # @param length [Integer, Range<Integer>]
+  #   length to match
+  # @param name [String, Symbol]
+  #   optional name to include in the error message
+  # @return [self]
+  # @raise [MiniSanity::Error]
+  #   if the String length does not match +length+
+  def assert_length!(length, name = nil)
+    if !(length === self.length)
+      raise MiniSanity::Error.new(name,
+        "#{self.class} having #{length} characters",
+        self.inspect)
+    end
+    self
+  end
+
+  # Checks that the String does not match a given length, and returns
+  # the String unmodified.  If the String fails this check, an exception
+  # is raised.
+  #
+  # @example
+  #   "password".refute_length!(0)           # == "password"
+  #   "long password".refute_length!(0...8)  # == "long password"
+  #   "pass".refute_length!(0...8)           # == raises exception
+  #
+  # @param length [Integer, Range<Integer>]
+  #   length to not match
+  # @param name [String, Symbol]
+  #   optional name to include in the error message
+  # @return [self]
+  # @raise [MiniSanity::Error]
+  #   if the String length matches +length+
+  def refute_length!(length, name = nil)
+    if length === self.length
+      raise MiniSanity::Error.new(name,
+        "#{self.class} not having #{length} characters",
+        self.inspect)
     end
     self
   end
@@ -24,8 +97,8 @@ class String
   # exception is raised.
   #
   # @example
-  #   "abc".assert_match!(/b/)  # == "abc"
-  #   "abc".assert_match!(/x/)  # raises exception
+  #   "good result".assert_match!(/^good/)  # == "good result"
+  #   "bad result".assert_match!(/^good/)   # raises exception
   #
   # @param regexp [Regexp]
   #   regular expression to check
@@ -35,9 +108,10 @@ class String
   # @raise [MiniSanity::Error]
   #   if the String does not match +regexp+
   def assert_match!(regexp, name = nil)
-    unless regexp =~ self
-      descriptor = name ? "#{name} (#{self.inspect})" : self.inspect
-      raise MiniSanity::Error.new("#{descriptor} does not match #{regexp.inspect}")
+    if regexp !~ self
+      raise MiniSanity::Error.new(name,
+        "#{self.class} matching #{regexp.inspect}",
+        self.inspect)
     end
     self
   end
@@ -47,8 +121,8 @@ class String
   # an exception is raised.
   #
   # @example
-  #   "abc".refute_match!(/x/)  # == "abc"
-  #   "abc".refute_match!(/b/)  # raises exception
+  #   "good result".refute_match!(/^bad/)  # == "good result"
+  #   "bad result".refute_match!(/^bad/)   # raises exception
   #
   # @param regexp [Regexp]
   #   regular expression to check
@@ -59,8 +133,9 @@ class String
   #   if the String matches +regexp+
   def refute_match!(regexp, name = nil)
     if regexp =~ self
-      descriptor = name ? "#{name} (#{self.inspect})" : self.inspect
-      raise MiniSanity::Error.new("#{descriptor} matches #{regexp.inspect}; expected no match")
+      raise MiniSanity::Error.new(name,
+        "#{self.class} not matching #{regexp.inspect}",
+        self.inspect)
     end
     self
   end

data/lib/mini_sanity/util.rb

@@ -0,0 +1,3 @@
+require_relative "util/enumerable"
+require_relative "util/regexp"
+require_relative "util/string"

data/lib/mini_sanity/util/enumerable.rb

@@ -0,0 +1,31 @@
+module Enumerable
+
+  # Like {https://ruby-doc.org/core/Enumerable.html#method-i-first
+  # +Enumerable#first+}, but raises an exception if the Enumerable does
+  # not contain the requested number of elements.
+  #
+  # @example
+  #   [7, 8, 9].first     # == 7
+  #   [7, 8, 9].first(1)  # == [7]
+  #   [7, 8, 9].first(2)  # == [7, 8]
+  #   [7, 8, 9].first(4)  # raises exception
+  #   [].first            # raises exception
+  #
+  # @param n [Integer]
+  #   requested number of elements
+  # @return [Object, Array]
+  # @raise [MiniSanity::Error]
+  #   if the Enumerable does not contain the requested number of elements
+  def first!(n = nil)
+    result = n.nil? ? self.first : self.first(n)
+
+    if (result.nil? && !self.any?{ true }) || (!n.nil? && result.length < n)
+      raise MiniSanity::Error.new(nil,
+        "Enumerable having at least #{n || 1} elements",
+        self.inspect)
+    end
+
+    result
+  end
+
+end

data/lib/mini_sanity/util/regexp.rb

@@ -0,0 +1,27 @@
+class Regexp
+
+  # Like {https://ruby-doc.org/core/Regexp.html#method-i-match
+  # +Regexp#match+}, but raises an exception if the match fails.
+  #
+  # @example
+  #   /^([^@]+)@(.+)$/.match!("user@example.com")  # === MatchData
+  #   /^([^@]+)@(.+)$/.match!("@user")             # raises exception
+  #
+  # @param str [String]
+  #   string to search
+  # @param pos [Integer]
+  #   position in +str+ to begin the search
+  # @return [MatchData]
+  # @raise [MiniSanity::Error]
+  #   if the Regexp does not match +str+
+  def match!(str, pos = 0)
+    result = self.match(str, pos)
+    if result.nil?
+      raise MiniSanity::Error.new(nil,
+        "String matching #{self.inspect}#{" from position #{pos}" if pos != 0}",
+        str.inspect)
+    end
+    result
+  end
+
+end

data/lib/mini_sanity/util/string.rb

@@ -0,0 +1,77 @@
+class String
+
+  # Like {https://ruby-doc.org/core/String.html#method-i-match
+  # +String#match+}, but raises an exception if the match fails.
+  #
+  # @example
+  #   "user@example.com".match!(/^([^@]+)@(.+)$/)  # === MatchData
+  #   "@user".match!(/^([^@]+)@(.+)$/)             # raises exception
+  #
+  # @param pattern [Regexp]
+  #   pattern to search for
+  # @param pos [Integer]
+  #   position in the String to begin the search
+  # @return [MatchData]
+  # @raise [MiniSanity::Error]
+  #   if +pattern+ does not match the String
+  def match!(pattern, pos = 0)
+    result = self.match(pattern, pos)
+    if result.nil?
+      raise MiniSanity::Error.new(nil,
+        "String matching #{pattern.inspect}#{" from position #{pos}" if pos != 0}",
+        self.inspect)
+    end
+    result
+  end
+
+  # Like {https://ruby-doc.org/core/String.html#method-i-sub-21
+  # +String#sub!+}, but raises an exception if no substitution was
+  # performed.
+  #
+  # @example
+  #   "author: YOUR_NAME".change!(/\bYOUR_NAME\b/, "Me")  # == "author: Me"
+  #   "author: TODO".change!(/\bYOUR_NAME\b/, "Me")       # raises exception
+  #
+  # @param pattern [Regexp, String]
+  #   pattern to search for
+  # @param replacement [String, Hash, &block]
+  #   substitution value (see +String#sub!+ documentation for full details)
+  # @return [String]
+  # @raise [MiniSanity::Error]
+  #   if no substitution was performed
+  def change!(pattern, replacement = nil, &replacement_block)
+    result = if replacement
+      self.sub!(pattern, replacement)
+    else
+      self.sub!(pattern, &replacement_block)
+    end
+
+    if !result
+      raise MiniSanity::Error.new(nil,
+        "String matching #{pattern.inspect}",
+        self.inspect)
+    end
+
+    result
+  end
+
+  # Like {https://ruby-doc.org/core/String.html#method-i-sub
+  # +String#sub+}, but raises an exception if no substitution was
+  # performed.
+  #
+  # @example
+  #   "author: YOUR_NAME".change(/\bYOUR_NAME\b/, "Me")  # == "author: Me"
+  #   "author: TODO".change(/\bYOUR_NAME\b/, "Me")       # raises exception
+  #
+  # @param pattern [Regexp, String]
+  #   pattern to search for
+  # @param replacement [String, Hash, &block]
+  #   substitution value (see +String#sub+ documentation for full details)
+  # @return [String]
+  # @raise [MiniSanity::Error]
+  #   if no substitution was performed
+  def change(pattern, replacement = nil, &replacement_block)
+    self.dup.change!(pattern, replacement, &replacement_block)
+  end
+
+end

data/lib/mini_sanity/version.rb

@@ -1,3 +1,3 @@
 module MiniSanity
-  VERSION = "1.0.0"
+  VERSION = "1.1.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: mini_sanity
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Jonathan Hefner
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2017-08-26 00:00:00.000000000 Z
+date: 2018-04-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -75,16 +75,22 @@ extra_rdoc_files: []
 files:
 - ".gitignore"
 - ".travis.yml"
+- CHANGELOG.md
 - Gemfile
 - LICENSE.txt
 - README.md
 - Rakefile
 - lib/mini_sanity.rb
+- lib/mini_sanity/array.rb
 - lib/mini_sanity/enumerable.rb
 - lib/mini_sanity/error.rb
 - lib/mini_sanity/object.rb
 - lib/mini_sanity/pathname.rb
 - lib/mini_sanity/string.rb
+- lib/mini_sanity/util.rb
+- lib/mini_sanity/util/enumerable.rb
+- lib/mini_sanity/util/regexp.rb
+- lib/mini_sanity/util/string.rb
 - lib/mini_sanity/version.rb
 - mini_sanity.gemspec
 homepage: https://github.com/jonathanhefner/mini_sanity
@@ -107,7 +113,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.4.8
+rubygems_version: 2.6.13
 signing_key: 
 specification_version: 4
 summary: In-line sanity checks