constrain 0.8.0 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7b497524127f01a38cc3c6f4061e91e0cad65b587538d57f69b194a550d46bf1
-  data.tar.gz: 95cff0709eb06ab088fee635c5629de99d16f521f9d24ea0a603ddb4d0968780
+  metadata.gz: ceffc61373ff30143743c0cca412f43abe64bbb6e012722c1ba2ab5035fe939b
+  data.tar.gz: ed70c819e47438f269c1d58d1291d4cde4eef22fc73049fd67c4b4d1b9c3da7a
 SHA512:
-  metadata.gz: f843d4f4b653ab255f52d9c5188b3d9d72c0170e0f4af4522404e4d993b97f6629b0b61c665a9cc47f3fc89a22ca7f7beb9efd68dfdae186c5d1502b320004d7
-  data.tar.gz: 70654e57d920e7f13a92394d57f7b5ddff2529ebe346507de201f47ce9aad77beef17992419dea84f1ba795b4de7d8443a65d3250b9a46298f8b1896d43dbeb4
+  metadata.gz: 94aeb7517bb00357f29bedf15a0b509fcefb28664e9c31e59f3a592e64c69da601a1e379cfeb473e7af590f69d1879c0dded102e55f159ecb8ef5dd8d8a84f58
+  data.tar.gz: e1eb0ec5ad04063965262a6be821027859a61c5fa42ec3b97da18d2e95e5193b95a8f96e4bf3a222bf866bd8e0c38579f7d50dd5380b305b3cc3badb66eceebf

data/README.md

@@ -22,7 +22,7 @@ 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)
+Constrain works with ruby-3
 
 ## Usage
 
@@ -35,15 +35,24 @@ require 'constrain'
 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
+  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 classes
+Constrain only defines the methods \#constrain and \#constrain? so it is
+acceptible in most cases. An alternative is to include the constrain module
+in a common root class to have it available in all child classes:
+
+```ruby
+  class BaseClass
+    include Constrain
+    ...
+  end
+```
+
 
 ## Methods
 
@@ -103,11 +112,11 @@ Simple values are compared to the expected result using the #=== operator. This
 means you can use regular expressions too:
 
 ```ruby
-# Simple email regular expression (https://stackoverflow.com/a/719543)
-EMAIL_RE = /^[a-zA-Z0-9_.+-]+@[a-zA-Z0-9-]+\.[a-zA-Z0-9.-]+$/
+# Simple (!) email address regular expression (https://stackoverflow.com/a/719543)
+EMAIL_ADDRESS_RE = /^[a-zA-Z0-9_.+-]+@[a-zA-Z0-9-]+\.[a-zA-Z0-9.-]+$/
 
-def email(address)
-  constrain address, EMAIL_RE
+def send_email(address)
+  constrain address, EMAIL_ADDRESS_RE
   ...
 end
 ```
@@ -164,8 +173,8 @@ Hashes match if value is a hash and every key/value pair match one of the given
 key-class/value-class expressions:
 
 ```ruby
-constrain({"str" => 42}, String => Integer)   # Success
-constrain({"str" => 42}, String => String)    # Failure
+constrain({"str" => 42}, { String => Integer })   # Success
+constrain({"str" => 42}, { String => String })    # Failure
 ```
 
 Note that the parenthesis are needed because otherwise the Ruby parser would
@@ -177,15 +186,15 @@ element so that `[String, Symbol]` matches either a String or a Symbol value
 while `[String]` matches an array of String objects:
 
 ```ruby
-constrain({ sym: 42 }, [Symbol, String] => Integer)       # Success
-constrain({ [sym] => 42 }, [Symbol, String] => Integer)   # Failure
+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:
 
 ```ruby
-constrain({ [sym] => 42 }, [[Symbol, String]] => Integer)   # Success
+constrain({ [sym] => 42 }, { [[Symbol, String]] => Integer })   # Success
 ```
 
 #### nil, true and false
@@ -245,6 +254,38 @@ 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
 
+## Other uses
+
+Constrain can be used to type-check complex structures like YAML documents:
+
+```ruby
+# A YAML value
+value = {
+  "str" => "a",
+  "int" => 42,
+  "arr" => [1, 2],
+  "hash" => {
+    "key1" => "b",
+    "key2" => 42
+  }
+}
+
+# Type description
+type = {
+  "str" => String,
+  "int" => Integer,
+  "arr" => [Integer],
+  "hash" => {
+    "key1" => [String, Integer],
+    "key2" => [String, Integer]
+  }
+}
+
+puts constrain?(value, type) ? "yes" : "no"    # Outputs 'yes'
+value["str"] = 42
+puts constrain?(value, type) ? "yes" : "no"    # Outputs 'no'
+```
+
 ## Installation
 
 Add this line to your application's Gemfile:

data/TODO

@@ -1,14 +1,25 @@
 
+o A constrain_class method that allows for inherited-from tests
+o Allow single-argument boolean expressions: 'constrain !a.empty?'
+o This seems to cause a stack error: 'constrain some-hash, Symbol'
+o Allow range as value expressions. And REs!
 o Use | to create class-or expressions
-  o Old: Class | Class syntax
+  o Class | Class syntax
+  o Will solve problem with [String, Integer] as a String/Integer vs. An array
+    of strings and integers
 o Use & to construct tuple expressions
-  o Old: A tuple method: "Symbol => constrain.tuple(String, Integer)"
+  o Class & Class (doesn't look good - maybe Class + Class ?)
+  o Alt: A tuple method: "Symbol => constrain.tuple(String, Integer)"
 o Better error message for 'constrain EXPR'
 o Explain that 'constrain EXPR' can be used for 'constrain SomeClass < AnotherClass'
 o Match ranges and regular expressions
 o An array and hash method: "Symbol => constrain.array(Integer), String => constrain.hash(Symbol, Integer)"
+  Nope. Solved by | syntax
 o Constrained attributes: constrain_reader, constrain_writer, constrain_accessor: 
-o Messages should include info about the unexpected element type in arrays (and maybe more): "Expected [#<PgGraph::Data::Record:public.pings[1] {id: 1, name: 'Ping A'}>, #<PgGraph::Data::Record:public.pings[2] {id: 2, name: 'Ping B'}>, nil] to match [PgGraph::Data::Record]
+o Messages should include info about the unexpected element type in arrays (and
+  maybe more): "Expected [#<PgGraph::Data::Record:public.pings[1] {id: 1, name:
+  'Ping A'}>, #<PgGraph::Data::Record:public.pings[2] {id: 2, name: 'Ping B'}>,
+  nil] to match [PgGraph::Data::Record]
 
 + constrain value, class-expr, "Error message"
 + Check against values: 'constrain arg, :one_value, :another_value, 1, 2, 3'

data/lib/constrain/version.rb

@@ -1,3 +1,3 @@
 module Constrain
-  VERSION = "0.8.0"
+  VERSION = "0.10.0"
 end

data/lib/constrain.rb

@@ -3,8 +3,12 @@ require "constrain/version"
 module Constrain
   # Raised if types doesn't match a class expression
   class MatchError < StandardError
-    def initialize(value, exprs, message: nil, unwind: 0)
-      super message || "Expected #{value.inspect} to match #{Constrain.fmt_exprs(exprs)}"
+    def initialize(value, exprs, message: nil, unwind: 0, not_argument: false, not_value: nil)
+      if not_argument
+        super message || "Expected #{value.inspect} to not equal #{not_value.inspect}"
+      else
+        super message || "Expected #{value.inspect} to match #{Constrain.fmt_exprs(exprs)}"
+      end
     end
   end
 
@@ -12,17 +16,6 @@ module Constrain
     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, *exprs)
-    Constrain.do_constrain?(value, *exprs)
-  end
-
   # :call-seq:
   #   constrain(value, *class-expressions, unwind: 0)
   #   constrain(value, *values, unwind: 0)
@@ -31,39 +24,38 @@ module Constrain
   # ArgumentError 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)
+  def self.constrain(value, *exprs, **opts)
+    do_constrain(value, *exprs, **opts)
   end
 
-  # Return true if the value matches the class expression. Raises a
-  # ArgumentError if the expression is invalid
-  def self.constrain?(value, *exprs)
-    do_constrain?(value, *exprs)
+  # See Constrain.constrain
+  def constrain(...) = Constrain.do_constrain(...)
+
+  # Like #constrain but returns true/false to indicate the result instead of
+  # raising an exception
+  def self.constrain?(value, *exprs, **opts)
+    do_constrain?(value, *exprs, **opts)
   end
 
+  # See Constrain.constrain?
+  def constrain?(...) = Constrain.do_constrain?(...)
+
   module ClassMethods
     # See Constrain.constrain
-    def constrain(*args) 
-
-    Constrain.do_constrain(*args) end
+    def constrain(...) Constrain.do_constrain(...) end
 
     # See Constrain.constrain?
-    def constrain?(*args) Constrain.do_constrain?(*args) end
+    def constrain?(...) Constrain.do_constrain?(...) end
   end
 
+  # :call-seq:
+  #   do_constrain(value, *exprs, unwind: 0, message: nil, not: nil)
+  #
   # 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
-      message = exprs.last.delete(:message)
-      !exprs.last.empty? or exprs.pop # Remove option hash if empty
-    else
-      unwind = 1
-      message = nil
-    end
-    
+  def self.do_constrain(value, *exprs, unwind: 0, message: nil)
+    unwind += 1
     begin
       if exprs.empty?
         value or raise MatchError.new(value, [], message: message, unwind: unwind)
@@ -78,11 +70,13 @@ module Constrain
     value
   end
 
-  def self.do_constrain?(value, *exprs)
+  def self.do_constrain?(...)
     begin
-      !exprs.empty? or raise ArgumentError, "Empty constraint"
-      exprs.any? { |expr| Constrain.do_constrain_value?(value, expr) }
+      do_constrain(...)
+    rescue MatchError
+      return false
     end
+    true
   end
 
   def self.do_constrain_value?(value, expr)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: constrain
 version: !ruby/object:Gem::Version
-  version: 0.8.0
+  version: 0.10.0
 platform: ruby
 authors:
 - Claus Rasmussen
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2022-09-17 00:00:00.000000000 Z
+date: 2023-12-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: simplecov