constrain 0.1.1 → 0.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ef3357b49faba9f9d3bfe5dbfb3d27b70d1493456b4dea29afb96c811b4eff8b
-  data.tar.gz: 590bb604f5566f76d4473f1f9191ef2ca21bfdcf9a904b92a0b6fa0388263c12
+  metadata.gz: 21ca1b88c0ffb91b40a2a2335ead91e2570108f8b67eaa9ea7fa3ebe00ada4c4
+  data.tar.gz: '083da1149466231ca8de0dc216cb00c46c540ebc1b7558a0d26422c33b5af9c4'
 SHA512:
-  metadata.gz: ec0d44e4cb0a7b4c3c8291bc10d821000769d36fe30c44aed85c30b3993076796169f7efa394cd47b0694744b47e6354e7413fb1c8b3a814d3a42d91cdeff04d
-  data.tar.gz: 9b60ecec9cb4edd2dc507b10835df150094b9fc3a939735be6935a93df4d5f049bbf4fe963eebb7ebf07a4faf21fa13cf3908a4ea44ac93178f97ef9b29d2612
+  metadata.gz: 7b40d638495bf36bd661fd1f8ab7845ec177a3f5cb2f73ddfd400976a9b02f9f8b2f16b2b0301b287cd419c43a2e961e895f96b6e9fd7a46545c96c71a954a28
+  data.tar.gz: 7be37bc44024db00f04d1355cc4bf340ca8728b2ff3014e27bda54f551bab85843f383f61890a8eaf63c65a14907061b3ce49f676732e1b0ad774b0e0e727541

data/README.md

@@ -58,38 +58,49 @@ end
 ```
 
 The alternative is to include the constrain Module in a common root class to
-have it available in all child class
+have it available in all child classes
 
-The #constrain method has the following signature
+## Methods
 
-```ruby
-constrain(value, *class-expressions, message = nil)
-```
+#### constrain(value, \*class-expressions, message = nil, unwind: 0)
 
-It checks that the value matches at least one of the class-expressions
-and raise a Constrain::TypeError if not. The error message can be customized by
-added the message argument. #constrain also raise a Constrain::Error exception
-if there is an error in the class expression. It is typically used to
-type-check parameters in methods
+Return the given value if it matches at least one of the class-expressions and raise a
+Constrain::TypeError if not. The error message can be customized by added the
+message argument and a number of backtrace leves can be skipped by setting
+:unwind option. By default the backtrace will refer to the point of the call of
+\#constrain. \#constrain raises a Constrain::Error exception if there is
+an error in the syntax of the class expression
 
-Constrain also defines a #check class method with the signature
+\#constrain is typically used to type-check parameters in methods where you
+want an exception if the parameters doesn't match the expected, but because it
+returns the value if successful it can be used to check the validity of
+variables in expressions too, eg. `return constrain(result_of_complex_computation, Integer)` 
+to check the return value of a method
 
-```ruby
-Constrain.check(value, *class-expression) -> true or false
-```
+#### Constrain.constrain(value, \*class-expressions, message = nil, unwind: 0)
+
+Class method version of #constrain. It is automatically added to classes that
+include Constrain
+
+
+#### Constrain.constrain?(value, \*class-expression) -> true or false
 
 It matches value against the class expressions like #constrain but returns true
-or false as result
+or false as result and can be used to handle complex type expressions
+dynamically. It is automatically added to classes that include Constrain.
+Constrain.constrain? raises a Constrain::Error exception if there is an error
+in the syntax of the class expression
 
 ## Class Expressions
 
-Constrain#constrain and Constrain::check use class expressions composed of
-Class objects, Proc objects, or arrays and hashes of class expressions. Class
-objects match if the value is an instance of the class:
+Constrain#constrain and Constrain::constrain? use class expressions composed of
+class or module objects, Proc objects, or arrays and hashes of class expressions. Class or module
+objects match if `value.is_a?(class_or_module)` returns true:
 
 ```ruby
-constrain 42, Integer   # Success
-constrain 42, String    # Failure
+constrain 42, Integer         # Success
+constrain 42, Comparable      # Success
+constrain nil, Comparable     # Failure
 ```
 
 More than one class expression is allowed. It matches if at least one of the expressions match:
@@ -134,10 +145,15 @@ constrain 0, Integer                          # Success
 constrain 0, lambda { |value| value > 1 }     # Failure
 ```
 
-Proc objects can check every aspect of an object but you should not overuse it
-because as checks becomes more complex they tend to include business logic that
-should be kept in the production code. Constrain is only thouhgt of as a tool
-to catch developer errors - not errors that stem from corrupted data
+Proc objects are a little more verbose than checking the constraint without
+\#constrain but it allows the use of the :unwind option to manipulate the
+apparent origin in the source of the exception
+
+Note that even though Proc objects can check every aspect of an object but you
+should not overuse it because as checks becomes more complex they tend to
+include business logic that should be kept in the production code. Constrain is
+only thouhgt of as a tool to catch developer errors - not errors that stem from
+corrupted data
 
 #### Arrays
 

data/constrain.gemspec

@@ -26,7 +26,7 @@ Gem::Specification.new do |spec|
 
     Constrain works with ruby-2 (and maybe ruby-3)
   }
-  spec.homepage      = "http://www.nowhere.com/"
+  spec.homepage      = "https://github.com/clrgit/constrain/"
   spec.required_ruby_version = Gem::Requirement.new(">= 2.3.0")
 
   spec.metadata["homepage_uri"] = spec.homepage

data/lib/constrain.rb

@@ -1,4 +1,18 @@
 require "constrain/version"
+module Foo
+
+  module InstanceMethods
+    def bar1
+      'bar1'
+    end
+  end
+
+  module ClassMethods
+    def bar2
+      'bar2'
+    end
+  end
+end
 
 module Constrain
   # Raised on any error
@@ -6,42 +20,88 @@ module Constrain
 
   # Raised if types doesn't match a class expression
   class TypeError < Error
-    def initialize(value, exprs, msg = nil)
+    def initialize(value, exprs, msg = nil, unwind: 0)
       super msg || "Expected #{value.inspect} to match #{Constrain.fmt_exprs(exprs)}"
     end
   end
 
+  def self.included base
+    base.extend ClassMethods
+  end
+
+  # See Constrain.constrain
+  def constrain(value, *exprs)
+    Constrain.do_constrain(value, *exprs)
+  end
+
+  def constrain?(value, expr)
+    Constrain.do_constrain?(value, expr)
+  end
+
+  # :call-seq:
+  #   constrain(value, *class-expressions, unwind: 0)
+  #
   # Check that value matches one of the class expressions. Raises a
   # Constrain::Error if the expression is invalid and a Constrain::TypeError if
-  # the value doesn't match
-  def constrain(value, *exprs)
+  # the value doesn't match. The exception's backtrace skips :unwind number of
+  # entries
+  def self.constrain(value, *exprs)
+    do_constrain(value, *exprs)
+  end
+
+  # Return true if the value matches the class expression. Raises a
+  # Constrain::Error if the expression is invalid
+  #
+  # TODO: Allow *exprs
+  def self.constrain?(value, expr)
+    do_constrain?(value, expr)
+  end
+
+  module ClassMethods
+    # See Constrain.constrain
+    def constrain(*args) Constrain.do_constrain(*args) end
+
+    # See Constrain.constrain?
+    def constrain?(*args) Constrain.do_constrain?(*args) end
+  end
+
+  # unwind is automatically incremented by one because ::do_constrain is always
+  # called from one of the other constrain methods
+  #
+  def self.do_constrain(value, *exprs)
+    if exprs.last.is_a?(Hash)
+      unwind = (exprs.last.delete(:unwind) || 0) + 1
+      !exprs.last.empty? or exprs.pop
+    else
+      unwind = 1
+    end
     msg = exprs.pop if exprs.last.is_a?(String)
     begin
       !exprs.empty? or raise Error, "Empty class expression"
-      exprs.any? { |expr| Constrain.check(value, expr) } or raise TypeError.new(value, exprs, msg)
+      exprs.any? { |expr| Constrain.do_constrain?(value, expr) } or 
+          raise TypeError.new(value, exprs, msg, unwind: unwind)
     rescue Error => ex
-      ex.set_backtrace(caller[1..-1])
+      ex.set_backtrace(caller[1 + unwind..-1])
       raise
     end
+    value
   end
 
-  # Return true if the value matches the class expression. Raises a
-  # Constrain::Error if the expression is invalid
-  def self.check(value, expr)
+  def self.do_constrain?(value, expr)
     case expr
-      when Class
+      when Class, Module
         value.is_a?(expr)
       when Array
         !expr.empty? or raise Error, "Empty array"
-        value.is_a?(Array) && value.all? { |elem| expr.any? { |e| check(elem, e) } }
+        value.is_a?(Array) && value.all? { |elem| expr.any? { |e| Constrain.constrain?(elem, e) } }
       when Hash
         value.is_a?(Hash) && value.all? { |key, value|
           expr.any? { |key_expr, value_expr|
             [[key, key_expr], [value, value_expr]].all? { |value, expr|
               if expr.is_a?(Array) && (expr.size > 1 || expr.first.is_a?(Array))
-                expr.any? { |e| check(value, e) }
+                expr.any? { |e| Constrain.do_constrain?(value, e) }
               else
-                check(value, expr)
+                Constrain.constrain?(value, expr)
               end
             }
           }
@@ -65,7 +125,7 @@ module Constrain
   #
   def self.fmt_expr(expr)
     case expr
-      when Class; expr.to_s
+      when Class, Module; expr.to_s
       when Array; "[" + expr.map { |expr| fmt_expr(expr) }.join(", ") + "]"
       when Hash; "{" + expr.map { |k,v| "#{fmt_expr(k)} => #{fmt_expr(v)}" }.join(", ") + "}"
       when Proc; "Proc@#{expr.source_location.first}:#{expr.source_location.last}"

data/lib/constrain/version.rb

@@ -1,3 +1,3 @@
 module Constrain
-  VERSION = "0.1.1"
+  VERSION = "0.2.2"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: constrain
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.2
 platform: ruby
 authors:
 - Claus Rasmussen
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2021-05-16 00:00:00.000000000 Z
+date: 2021-05-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: simplecov
@@ -52,10 +52,10 @@ files:
 - constrain.gemspec
 - lib/constrain.rb
 - lib/constrain/version.rb
-homepage: http://www.nowhere.com/
+homepage: https://github.com/clrgit/constrain/
 licenses: []
 metadata:
-  homepage_uri: http://www.nowhere.com/
+  homepage_uri: https://github.com/clrgit/constrain/
 post_install_message: 
 rdoc_options: []
 require_paths: