constrain 0.9.0 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ff3fb59b6d713b01843aa67e4e90855e58f99b1fcffa8ff27ae66b53987d9672
-  data.tar.gz: 98237076729ee99035e1af426308f12ef36963879950287f107486ae0485e061
+  metadata.gz: ceffc61373ff30143743c0cca412f43abe64bbb6e012722c1ba2ab5035fe939b
+  data.tar.gz: ed70c819e47438f269c1d58d1291d4cde4eef22fc73049fd67c4b4d1b9c3da7a
 SHA512:
-  metadata.gz: 533a2c7486903550fa42c3f349417130a8dd69642adf6d2e27599bd9f5e4b6be3fca0dcfcc58370cf4d64169952e06df5a0ad76603d424741f0c7846301f66ac
-  data.tar.gz: 95ee72d76e6ccfdd7faffd971214ecc6b171ab1a58debfd5a6a043a0764e8f154a910a7086399363a4bc88e94406a7a048f5efa32cadf5c1d8ded2e1725fcc37
+  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.9.0"
+  VERSION = "0.10.0"
 end

data/lib/constrain.rb

@@ -54,12 +54,8 @@ module Constrain
   # 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, unwind: 0, message: nil, **opts)
-    opts.keys.empty? || opts.keys == [:not] or raise ArgumentError
+  def self.do_constrain(value, *exprs, unwind: 0, message: nil)
     unwind += 1
-    not_argument = opts.key?(:not)
-    not_value = opts[:not]
-    
     begin
       if exprs.empty?
         value or raise MatchError.new(value, [], message: message, unwind: unwind)
@@ -67,10 +63,6 @@ module Constrain
         exprs.any? { |expr| Constrain.do_constrain_value?(value, expr) } or 
             raise MatchError.new(value, exprs, message: message, unwind: unwind)
       end
-      !not_argument || value != not_value or 
-          raise MatchError.new(
-              value, exprs, message: message, unwind: unwind, not_argument: true, not_value: not_value)
-        
     rescue ArgumentError, Constrain::MatchError => ex
       ex.set_backtrace(caller[1 + unwind..-1])
       raise

metadata

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