constrain 0.1.3 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c176bf713350005e558d37a3b88b08f2a5f0ba37f0d2a829aa1d4b5dd1e8b0b4
-  data.tar.gz: 02f69468f0130af3c702159b3cff2def10f1755916bc774e903f3d6cb8136fba
+  metadata.gz: c8c92be44953ded28f60341e340c7e96a8891124427efb31a06cbc94c7664cf1
+  data.tar.gz: 65196009ea3d69aab1174722296949977bb622a68ac16dd04320dc7816503a2e
 SHA512:
-  metadata.gz: 5117883c01aa7658dd4adefcabb8af14c761090abb407d4141fd6f9321828d8f386f6dccba634d8e08af09bd893d8457d05495cbeba2a91f66d52af92e5c1b4e
-  data.tar.gz: 5dc0238f65e4a6771b9a2bca452ab9eabb160c17ca32cec143a835bceb2296a317a661b7faa613a2c0148b3a3e236aef82e64351064a66b250ba146a8b9b5d36
+  metadata.gz: 4acb8bd66add5cb3937efdbe5272b57acac1ea1fe193df84f2ea48c3aa6a12b0a214a2832aeac7e2968871da9c226ba263dfe0ebec883ff42259d9667edfb92f
+  data.tar.gz: '094404002ee23266e98a58ad7ade0910d0768fa2956440ab1502c768b0fda2785c35d13821e3adb21e571198ed9eb223eac216f04b3406296c34569d71f4a874'

data/README.md

@@ -60,30 +60,34 @@ end
 The alternative is to include the constrain Module in a common root class to
 have it available in all child class
 
-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 araises 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-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 made a class method to minimize namespace pollution
+
 
 ## Class Expressions
 
-Constrain#constrain and Constrain::check use class expressions composed of
+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:
 

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

@@ -6,42 +6,44 @@ 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
 
   # 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 constrain(value, *exprs, unwind: 0)
     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.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.constrain?(value, expr)
     case expr
       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?(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?(value, e) }
               else
-                check(value, expr)
+                constrain?(value, expr)
               end
             }
           }

data/lib/constrain/version.rb

@@ -1,3 +1,3 @@
 module Constrain
-  VERSION = "0.1.3"
+  VERSION = "0.2.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: constrain
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 0.2.0
 platform: ruby
 authors:
 - Claus Rasmussen
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2021-05-17 00:00:00.000000000 Z
+date: 2021-05-22 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: