constrain 0.2.2 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 21ca1b88c0ffb91b40a2a2335ead91e2570108f8b67eaa9ea7fa3ebe00ada4c4
-  data.tar.gz: '083da1149466231ca8de0dc216cb00c46c540ebc1b7558a0d26422c33b5af9c4'
+  metadata.gz: fda0b95a5d43c197c9df1134d68dbe4fbc1f8f71ad9dc7a8e995daf729eaea2c
+  data.tar.gz: 2fe722e5085bc9b396e203b3f3514a1f123c18843e293f902392519ef6a3d5ed
 SHA512:
-  metadata.gz: 7b40d638495bf36bd661fd1f8ab7845ec177a3f5cb2f73ddfd400976a9b02f9f8b2f16b2b0301b287cd419c43a2e961e895f96b6e9fd7a46545c96c71a954a28
-  data.tar.gz: 7be37bc44024db00f04d1355cc4bf340ca8728b2ff3014e27bda54f551bab85843f383f61890a8eaf63c65a14907061b3ce49f676732e1b0ad774b0e0e727541
+  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
@@ -62,14 +47,19 @@ have it available in all child classes
 
 ## Methods
 
-#### constrain(value, \*class-expressions, message = nil, unwind: 0)
+#### constrain(value, \*expressions, message = nil, unwind: 0)
 
-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
+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 
+
+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 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
@@ -77,84 +67,71 @@ 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-expressions, message = nil, unwind: 0)
+#### Constrain.constrain(value, \*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
+#### Constrain.constrain?(value, \*expressions) -> 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 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
+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
 
-## 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:
+## Expressions
 
-```ruby
-constrain 42, Integer         # Success
-constrain 42, Comparable      # Success
-constrain nil, Comparable     # Failure
-```
+Expressions can be simple values, class expressions, or lambdas. You can mix
+simple values and class expressions but not lambdas
 
-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
-```
+### Simple expressions
 
-#### nil, true and false
-
-NilClass is a valid argument and can be used to allow nil values:
+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 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:
@@ -211,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/lib/constrain/version.rb

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

data/lib/constrain.rb

@@ -1,25 +1,11 @@
 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
   class Error < StandardError; end
 
   # Raised if types doesn't match a class expression
-  class TypeError < Error
+  class MatchError < Error
     def initialize(value, exprs, msg = nil, unwind: 0)
       super msg || "Expected #{value.inspect} to match #{Constrain.fmt_exprs(exprs)}"
     end
@@ -34,15 +20,18 @@ module Constrain
     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::TypeError if
+  # 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)
@@ -79,7 +68,7 @@ module Constrain
     begin
       !exprs.empty? or raise Error, "Empty class expression"
       exprs.any? { |expr| Constrain.do_constrain?(value, expr) } or 
-          raise TypeError.new(value, exprs, msg, unwind: unwind)
+          raise MatchError.new(value, exprs, msg, unwind: unwind)
     rescue Error => ex
       ex.set_backtrace(caller[1 + unwind..-1])
       raise
@@ -109,7 +98,7 @@ module Constrain
       when Proc
         expr.call(value)
     else
-      raise Error, "Illegal expression #{expr.inspect}"
+      expr === value
     end
   end
 
@@ -126,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.2.2
+  version: 0.3.0
 platform: ruby
 authors:
 - Claus Rasmussen
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2021-05-24 00:00:00.000000000 Z
+date: 2021-09-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: simplecov
@@ -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