constrain 0.1.3 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c176bf713350005e558d37a3b88b08f2a5f0ba37f0d2a829aa1d4b5dd1e8b0b4
-  data.tar.gz: 02f69468f0130af3c702159b3cff2def10f1755916bc774e903f3d6cb8136fba
+  metadata.gz: fda0b95a5d43c197c9df1134d68dbe4fbc1f8f71ad9dc7a8e995daf729eaea2c
+  data.tar.gz: 2fe722e5085bc9b396e203b3f3514a1f123c18843e293f902392519ef6a3d5ed
 SHA512:
-  metadata.gz: 5117883c01aa7658dd4adefcabb8af14c761090abb407d4141fd6f9321828d8f386f6dccba634d8e08af09bd893d8457d05495cbeba2a91f66d52af92e5c1b4e
-  data.tar.gz: 5dc0238f65e4a6771b9a2bca452ab9eabb160c17ca32cec143a835bceb2296a317a661b7faa613a2c0148b3a3e236aef82e64351064a66b250ba146a8b9b5d36
+  metadata.gz: bc98410262f21b5fea23182cad7c9e80e48a4aff7ff64dc7ff2113581440a191bfa9b77a28045624caf4f6e3102251e175841604c64461287ea7eb1062174bf2
+  data.tar.gz: c19a11b5ab9e22b49ad2204b276658d26b109296815e06298620fdb53104f6ce70625095b4ac5b3fbd3aff79664866de7afb3507cea1b5d1737aaf714c902c7e

data/README.md

@@ -2,9 +2,10 @@
 
 `Constrain` allows you to check if an object match a class expression. It is
 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
+using Ruby-3 .rbs files
 
 ```ruby
+require 'constrain'
 include Constrain
 
 # f takes a String and an array of Integer objects and raises otherwise
@@ -23,22 +24,6 @@ production (TODO: Make it possible to deactivate)
 
 Constrain works with ruby-2 (and maybe ruby-3)
 
-## Installation
-
-Add this line to your application's Gemfile:
-
-```ruby
-gem 'constrain'
-```
-
-And then execute:
-
-    $ bundle install
-
-Or install it yourself as:
-
-    $ gem install constrain
-
 ## Usage
 
 You will typically include Constrain globally to have #constrain available everywhere
@@ -58,88 +43,95 @@ 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, \*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 expressions and raise a
+Constrain::TypeError if not. The value is matched against the expressions using
+the #=== operator so anything you can put into the 'when' clause of a 'case'
+statement can be used. #constrain raise a Constrain::MatchError if the value
+doesn't match any expression 
 
-Constrain also defines a #check class method with the signature
+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
 
-```ruby
-Constrain.check(value, *class-expression) -> true or false
-```
+\#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
 
-It matches value against the class expressions like #constrain but returns true
-or false as result
+#### Constrain.constrain(value, \*expressions, message = nil, unwind: 0)
 
-## Class Expressions
+Class method version of #constrain. It is automatically added to classes that
+include Constrain
 
-Constrain#constrain and Constrain::check 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
-```
+#### Constrain.constrain?(value, \*expressions) -> true or false
 
-More than one class expression is allowed. It matches if at least one of the expressions match:
+It matches value against the class expressions like #constrain but returns true
+or false as result. 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
 
-```ruby
-constrain "str", Symbol, String   # Success
-constrain :sym, Symbol, String    # Success
-constrain 42, Symbol, String      # Failure
-```
 
-#### nil, true and false
+## Expressions
+
+Expressions can be simple values, class expressions, or lambdas. You can mix
+simple values and class expressions but not lambdas
 
-NilClass is a valid argument and can be used to allow nil values:
+
+### Simple expressions
+
+Simple values is an easy way to check arguments with a limited set of allowed
+values like
 
 ```ruby
-constrain nil, Integer             # Failure
-constrain nil, Integer, NilClass   # Success
+def print_color(color)
+  constrain color, :red, :yellow, :green
+  ...
+end
 ```
 
-Boolean values are a special case since ruby doesn't have a boolean type use a
-list to match for a boolean argument:
+Simple values are compared to the expected result using the #=== operator. This
+means you can use regular expressions too:
 
 ```ruby
-constrain true, TrueClass, FalseClass   # Success
-constrain false, TrueClass, FalseClass  # Success
-constrain nil, TrueClass, FalseClass    # Failure
+# Simple email regular expression (https://stackoverflow.com/a/719543)
+EMAIL_RE = /^[a-zA-Z0-9_.+-]+@[a-zA-Z0-9-]+\.[a-zA-Z0-9-.]+$/
+
+def email(address)
+  constrain address, EMAIL_RE
+  ...
+end
 ```
 
-#### Proc objects
+### Class Expressions
 
-Proc objects are called with the value as argument and should return truish or falsy:
+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, lambda { |value| value > 1 }    # Success
-constrain 0, lambda { |value| value > 1 }     # Failure
+constrain 42, Integer         # Success
+constrain 42, Comparable      # Success
+constrain nil, Comparable     # 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:
+More than one class expression is allowed. It matches if at least one of the expressions match:
 
 ```ruby
-constrain 0, Integer                          # Success
-constrain 0, lambda { |value| value > 1 }     # Failure
+constrain "str", Symbol, String   # Success
+constrain :sym, Symbol, String    # Success
+constrain 42, Symbol, String      # 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
-
 #### Arrays
 
 Arrays match if the value is an Array and all its element match the given class expression:
@@ -196,6 +188,79 @@ sure the list expression is enclosed in an array:
 constrain({ [sym] => 42 }, [[Symbol, String]] => Integer)   # Success
 ```
 
+#### nil, true and false
+
+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
+```
+
+But note that it is often easier to use value expressions:
+
+```ruby
+constrain true, true, false     # Success
+constrain false, true, false    # Success
+constrain nil, true, false      # Failure
+constrain nil, true, false, nil # Success
+```
+
+### Lambda expressions
+
+Proc objects are called with the value as argument and should return truish or falsy:
+
+```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
+```
+
+Alternatively, you can use Constrain::constrain? to mix classes or value with lambdas:
+
+```ruby
+constrain 0, lambda { |value| Constrain::constrain?(Integer) && value > 1 }   # Failure
+```
+
+Note that even though Proc objects can check every aspect of an object, 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
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'constrain'
+```
+
+And then execute:
+
+    $ bundle install
+
+Or install it yourself as:
+
+    $ gem install constrain
+
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/clrgit/constrain.

data/TODO

@@ -1,5 +1,6 @@
 
 o Class | Class syntax
 o attr_reader :variable, ClassExpr
+o 'constrain arg, :one_value, :another_value, 1, 2, 3'
 
 + 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/version.rb

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

data/lib/constrain.rb

@@ -5,43 +5,92 @@ module Constrain
   class Error < StandardError; end
 
   # Raised if types doesn't match a class expression
-  class TypeError < Error
-    def initialize(value, exprs, msg = nil)
+  class MatchError < Error
+    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 self.included base
+    base.extend ClassMethods
+  end
+
+  # See Constrain.constrain
   def constrain(value, *exprs)
+    Constrain.do_constrain(value, *exprs)
+  end
+
+  # Like #constrain but returns true/false to indicate the result instead of
+  # raising an exception
+  def constrain?(value, expr)
+    Constrain.do_constrain?(value, expr)
+  end
+
+  # :call-seq:
+  #   constrain(value, *class-expressions, unwind: 0)
+  #   constrain(value, *values, unwind: 0)
+  #
+  # Check that value matches one of the class expressions. Raises a
+  # Constrain::Error if the expression is invalid and a Constrain::MatchError if
+  # 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 MatchError.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, 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
             }
           }
@@ -49,7 +98,7 @@ module Constrain
       when Proc
         expr.call(value)
     else
-      raise Error, "Illegal expression #{expr.inspect}"
+      expr === value
     end
   end
 
@@ -66,11 +115,12 @@ module Constrain
   def self.fmt_expr(expr)
     case expr
       when Class, Module; expr.to_s
+      when Regexp; 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}"
     else
-      raise Error, "Illegal expression"
+      raise Error, "Illegal expression: #{expr.inspect}"
     end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: constrain
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 0.3.0
 platform: ruby
 authors:
 - Claus Rasmussen
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2021-05-17 00:00:00.000000000 Z
+date: 2021-09-20 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:
@@ -71,7 +71,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.4
+rubygems_version: 3.2.26
 signing_key: 
 specification_version: 4
 summary: Dynamic in-file type checking