constrain 0.1.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b37ca58d51de33d6c5d6810c5b8e4b77e0d1d19355d4e381241b923f44918817
-  data.tar.gz: c64f19d94bb2e4dae6e4fbaf61a74d1fb6caee56f58a9006915a5749ee35b906
+  metadata.gz: e48891d02cd81470d1f83543f6db1f7da99d75f3afe05cdc57b2c1e63d7a2ff9
+  data.tar.gz: dd37d53ea1080db393871ede639a653f985cc38373314d8b23b5013f3d8f9803
 SHA512:
-  metadata.gz: bd6114ec7c7b5516c409ef41beae62d979c582f8f53c149634a1fc8ed8b4c595a7b3fd2d12d07a08fd2b7b587515adef890e6f68cdf6dd897d6ef79e8bad9c50
-  data.tar.gz: 9eec4bc8dac6976bbe2eb22e45bcf57589b5f1e04092596e1cb99f658c0b9144a68182eab73e0e5ae3eb9be9bb9434184f8c71122aaddba284d15f90cac4600e
+  metadata.gz: f2b8bf75caa5936d24773c662f4f43da95820c7245770a1b07c80e82e397aaeea06927e749fb9e1d615daebee3be92ccfa0001ebf334a1d4ceab19d87c225c3c
+  data.tar.gz: '082302ac6cbd3a638f4175a2a91cb3e6bb73e75032d08e9eb21c1e41fff122a3909c983bdf1068bf383b1c32fd93e91808abc687301e446f9c4ef0b05ab2b21e'

data/README.md

@@ -4,6 +4,23 @@
 typically used to check the type of method parameters and is an alternative to
 using Ruby-3 .rbs files but with a different syntax and only dynamic checks
 
+```ruby
+include Constrain
+
+# f takes a String and an array of Integer objects and raises otherwise
+def f(a, b)
+  constrain a, String
+  constrain b, [Integer]
+  ...
+end
+
+f("Hello", [1, 2])    # Doesn't raise
+f("Hello", "world")   # Boom
+```
+
+It is intended to be an aid in development only and to be deactivated in
+production (TODO: Make it possible to deactivate)
+
 Constrain works with ruby-2 (and maybe ruby-3)
 
 ## Installation
@@ -24,62 +41,149 @@ Or install it yourself as:
 
 ## Usage
 
-You'll typically include the Constrain module and use the #constrain method to chech values:
+You will typically include Constrain globally to have #constrain available everywhere
+
+```ruby
+require 'constrain'
+
+# Include globally to make #constrain available everywhere
+include Constrain
+
+def f(a, b, c)
+  constrain a, Integer                      # An integer
+  constrain b, [Symbol, String] => Integer  # Hash with String or Symbol keys
+  constrain c, [String], NilClass           # Array of strings or nil
+  ...
+end
+```
+
+The alternative is to include the constrain Module in a common root class to
+have it available in all child class
+
+## Methods
+
+#### constrain(value, \*class-expressions, message = nil, unwind: 0)
 
-    include Constrain
+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
 
-    # f takes a String and an array of Integer objects
-    def f(a, b)
-      constrain a, String
-      constrain b, [Integer]
-    end
+\#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
+
+
+#### Constrain.constrain?(value, \*class-expression) -> true or false
+
+It matches value against the class expressions like #constrain but returns true
+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::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, Comparable      # Success
+constrain nil, Comparable     # Failure
+```
+
+More than one class expression is allowed. It matches if at least one of the expressions match:
+
+```ruby
+constrain "str", Symbol, String   # Success
+constrain :sym, Symbol, String    # Success
+constrain 42, Symbol, String      # Failure
+```
 
-The constrain instance method raises a Constrain::TypeError if the value
-doesn't match the class expression. Constrain also defines the Constrain::check
-class method that returns true/false depending on if the value match the
-expression. Both methods raise a Constrain::Error if the expression is invalid
+#### nil, true and false
 
-### Class Expressions
+NilClass is a valid argument and can be used to allow nil values:
 
-Constrain#constrain and Constrain::check use class expressions composed of
-Class objects, Proc objects, or arrays and hashes of class objects. Class
-objects match if the value is an instance of the class:
+```ruby
+constrain nil, Integer             # Failure
+constrain nil, Integer, NilClass   # Success
+```
 
-    constrain 42, Integer   # Success
-    constrain 42, String    # Failure
+Boolean values are a special case since ruby doesn't have a boolean type use a
+list to match for a boolean argument:
 
-Note that NilClass and TrueClass and FalseClass are valid arguments and allows
-you to do value comparison for those types:
+```ruby
+constrain true, TrueClass, FalseClass   # Success
+constrain false, TrueClass, FalseClass  # Success
+constrain nil, TrueClass, FalseClass    # Failure
+```
 
-    constrain nil, Integer             # Failure
-    constrain nil, Integer, NilClass   # Success
+#### Proc objects
 
 Proc objects are called with the value as argument and should return truish or falsy:
 
-    proc = lambda { |value| value > 1 }
-    constrain 42, proc   # Success
-    constrain 0, proc    # Failure
+```ruby
+constrain 42, lambda { |value| value > 1 }    # Success
+constrain 0, lambda { |value| value > 1 }     # Failure
+```
+
+Note that it is not possible to first match against a class expression and then use the proc object. You will either have to check for the type too in the proc object or make two calls to #constrain:
 
-Proc objects can check every aspect of an object and but you should not overuse
-them as `Constrain` is throught of as a poor-man's type checker. More elaborate
-constraints should be checked explicitly
+```ruby
+constrain 0, Integer                          # Success
+constrain 0, lambda { |value| value > 1 }     # Failure
+```
+
+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
 
 Arrays match if the value is an Array and all its element match the given class expression:
 
-    constrain [42], [Integer]   # Success
-    constrain [42], [String]    # Failure
+```ruby
+constrain [42], [Integer]   # Success
+constrain [42], [String]    # Failure
+```
 
 Arrays can be nested
 
-    constrain [[42]], [[Integer]]
+```ruby
+constrain [[42]], [[Integer]]   # Success
+constrain [42], [[Integer]]     # Failure
+```
+
+More than one element class is allowed
+
+```ruby
+constrain ["str"], [String, Symbol]   # Success
+constrain [:sym], [String, Symbol]    # Success
+constrain [42], [String, Symbol]      # Failure
+```
+
+Note that `[` ... `]` is treated specially in hashes
 
-Note that arrays are treated specially in hashes
+#### Hashes
 
 Hashes match if value is a hash and every key/value pair match one of the given
 key-class/value-class expressions:
 
-    constrain({"str" => 42}, String => Integer)   # Success
-    constrain({"str" => 42}, String => String)    # Failure
+```ruby
+constrain({"str" => 42}, String => Integer)   # Success
+constrain({"str" => 42}, String => String)    # Failure
+```
 
 Note that the parenthesis are needed because otherwise the Ruby parser would
 interpret the hash as block argument to #constrain
@@ -89,13 +193,17 @@ expression match. List are annotated as an array but contains more than one
 element so that `[String, Symbol]` matches either a String or a Symbol value
 while `[String]` matches an array of String objects:
 
-    constrain({ sym: 42 }, [Symbol, String] => Integer)       # Success
-    constrain({ [sym] => 42 }, [Symbol, String] => Integer)   # Failure
+```ruby
+constrain({ sym: 42 }, [Symbol, String] => Integer)       # Success
+constrain({ [sym] => 42 }, [Symbol, String] => Integer)   # Failure
+```
 
 To specify an array of Symbol or String objects in hash keys or values, make
 sure the list expression is enclosed in an array:
 
-    constrain({ [sym] => 42 }, [[Symbol, String]] => Integer)   # Success
+```ruby
+constrain({ [sym] => 42 }, [[Symbol, String]] => Integer)   # Success
+```
 
 ## Contributing
 

data/TODO

@@ -0,0 +1,5 @@
+
+o Class | Class syntax
+o attr_reader :variable, ClassExpr
+
++ constrain value, class-expr, "Error message"

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,38 +6,53 @@ module Constrain
 
   # Raised if types doesn't match a class expression
   class TypeError < Error
-    def initialize(value, exprs)
-      super "Expected #{value.inspect} to match #{Constrain.fmt_exprs(exprs)}"
+    def initialize(value, exprs, msg = nil, unwind: 0)
+      super msg || "Expected #{value.inspect} to match #{Constrain.fmt_exprs(exprs)}"
     end
   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)
-    return if exprs.any? { |expr| Constrain.check(value, expr) }
-    error = TypeError.new(value, exprs)
-    error.set_backtrace(caller[1..-1])
-    raise error
+  # the value doesn't match. The exception's backtrace skips :unwind number of entries
+  def constrain(value, *exprs) #, unwind: 0)
+    if exprs.last.is_a?(Hash)
+      unwind = exprs.last.delete(:unwind) || 0
+      !exprs.last.empty? or exprs.pop
+    else
+      unwind = 0
+    end
+    msg = exprs.pop if exprs.last.is_a?(String)
+    begin
+      !exprs.empty? or raise Error, "Empty class expression"
+      exprs.any? { |expr| Constrain.constrain?(value, expr) } or 
+          raise TypeError.new(value, exprs, msg, unwind: unwind)
+    rescue Error => ex
+      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
+      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
             }
           }
@@ -61,7 +76,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.0"
+  VERSION = "0.2.1"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: constrain
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.1
 platform: ruby
 authors:
 - Claus Rasmussen
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2021-05-15 00:00:00.000000000 Z
+date: 2021-05-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: simplecov
@@ -46,15 +46,16 @@ files:
 - Gemfile
 - README.md
 - Rakefile
+- TODO
 - bin/console
 - bin/setup
 - 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: