constrain 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b37ca58d51de33d6c5d6810c5b8e4b77e0d1d19355d4e381241b923f44918817
-  data.tar.gz: c64f19d94bb2e4dae6e4fbaf61a74d1fb6caee56f58a9006915a5749ee35b906
+  metadata.gz: ef3357b49faba9f9d3bfe5dbfb3d27b70d1493456b4dea29afb96c811b4eff8b
+  data.tar.gz: 590bb604f5566f76d4473f1f9191ef2ca21bfdcf9a904b92a0b6fa0388263c12
 SHA512:
-  metadata.gz: bd6114ec7c7b5516c409ef41beae62d979c582f8f53c149634a1fc8ed8b4c595a7b3fd2d12d07a08fd2b7b587515adef890e6f68cdf6dd897d6ef79e8bad9c50
-  data.tar.gz: 9eec4bc8dac6976bbe2eb22e45bcf57589b5f1e04092596e1cb99f658c0b9144a68182eab73e0e5ae3eb9be9bb9434184f8c71122aaddba284d15f90cac4600e
+  metadata.gz: ec0d44e4cb0a7b4c3c8291bc10d821000769d36fe30c44aed85c30b3993076796169f7efa394cd47b0694744b47e6354e7413fb1c8b3a814d3a42d91cdeff04d
+  data.tar.gz: 9b60ecec9cb4edd2dc507b10835df150094b9fc3a939735be6935a93df4d5f049bbf4fe963eebb7ebf07a4faf21fa13cf3908a4ea44ac93178f97ef9b29d2612

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,139 @@ 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
+
+The #constrain method has the following signature
+
+```ruby
+constrain(value, *class-expressions, message = nil)
+```
 
-    include Constrain
+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
 
-    # f takes a String and an array of Integer objects
-    def f(a, b)
-      constrain a, String
-      constrain b, [Integer]
-    end
+Constrain also defines a #check class method with the signature
 
-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
+```ruby
+Constrain.check(value, *class-expression) -> true or false
+```
 
-### Class Expressions
+It matches value against the class expressions like #constrain but returns true
+or false as result
+
+## Class Expressions
 
 Constrain#constrain and Constrain::check use class expressions composed of
-Class objects, Proc objects, or arrays and hashes of class objects. Class
+Class objects, Proc objects, or arrays and hashes of class expressions. Class
 objects match if the value is an instance of the class:
 
-    constrain 42, Integer   # Success
-    constrain 42, String    # Failure
+```ruby
+constrain 42, Integer   # Success
+constrain 42, String    # 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
+```
 
-Note that NilClass and TrueClass and FalseClass are valid arguments and allows
-you to do value comparison for those types:
+#### nil, true and false
 
-    constrain nil, Integer             # Failure
-    constrain nil, Integer, NilClass   # Success
+NilClass is a valid argument and can be used to allow nil values:
+
+```ruby
+constrain nil, Integer             # Failure
+constrain nil, Integer, NilClass   # Success
+```
+
+Boolean values are a special case since ruby doesn't have a boolean type use a
+list to match for a boolean argument:
+
+```ruby
+constrain true, TrueClass, FalseClass   # Success
+constrain false, TrueClass, FalseClass  # Success
+constrain nil, TrueClass, FalseClass    # Failure
+```
+
+#### 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:
+
+```ruby
+constrain 0, Integer                          # Success
+constrain 0, lambda { |value| value > 1 }     # Failure
+```
 
-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
+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 +183,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/lib/constrain.rb

@@ -6,8 +6,8 @@ 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)
+      super msg || "Expected #{value.inspect} to match #{Constrain.fmt_exprs(exprs)}"
     end
   end
 
@@ -15,10 +15,14 @@ module Constrain
   # 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
+    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)
+    rescue Error => ex
+      ex.set_backtrace(caller[1..-1])
+      raise
+    end
   end
 
   # Return true if the value matches the class expression. Raises a

data/lib/constrain/version.rb

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

metadata

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