predicate 2.3.0 → 2.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 901370b7a22028c4557c52fb7f5cd8d3ac92c97a440cf4d0f772bd592198c3a5
-  data.tar.gz: 7dc1e4912f365fc08657fc1b7289f1796989511c8b5e7c5e219bf8fe9eb16ccd
+  metadata.gz: 4bd1cc5bc76250463f8dd68f07852df3838d8e9e553da27b188a87d968f83e5d
+  data.tar.gz: eab52fff1970e5a74f21170e6486ec8082065be352053206b819fec2a2da3075
 SHA512:
-  metadata.gz: 9515618b5f501b1774cae70cd88784d8bc965f2c331132c5c1f11363e3f690df9233f423195e3d0938fdf42cde4f90a68a69f1273e544014a0f43b386b322b8b
-  data.tar.gz: 4c4870c03e0aa43e7082136e68d6c17873febcb5608090713fc5ee0873f8f5e5c061a74eb5d57159bac3962f3ca9ce906e629e329bd654c4fd4be61cedad4ea8
+  metadata.gz: b3b4f2354d525a6c7a80de4fe6edba8459270ab34a2a5f15e17f233d485761b2c8e2f4c86c93349b2ffc06380cd37a4621da0df6ffa14672d1b43fa24ae9f428
+  data.tar.gz: af95ddb5a971f2f7631046ed59e05982a5ff5309cbb1ac1a892c949ac9ed7305f4188f40616efce485978854561a756b3a722c0db192abb0b42e925beed42834

data/Gemfile

@@ -1,2 +1,6 @@
 source "https://rubygems.org"
 gemspec
+
+group :development do
+  gem "jeny", github: "enspirit/jeny"
+end

data/LICENSE.md

@@ -1,22 +1,20 @@
-# The MIT Licence
+Copyright (c) 2017-2020 - Enspirit SPRL (Bernard Lambeau)
 
-    Copyright (c) 2017 - Enspirit SPRL (Bernard Lambeau)
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
 
-    Permission is hereby granted, free of charge, to any person obtaining
-    a copy of this software and associated documentation files (the
-    "Software"), to deal in the Software without restriction, including
-    without limitation the rights to use, copy, modify, merge, publish,
-    distribute, sublicense, and/or sell copies of the Software, and to
-    permit persons to whom the Software is furnished to do so, subject to
-    the following conditions:
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
 
-    The above copyright notice and this permission notice shall be
-    included in all copies or substantial portions of the Software.
-
-    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
-    EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
-    MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
-    NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
-    LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
-    OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
-    WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,433 @@
+# Predicate
+
+Boolean (truth-value) expressions that can be evaluated, manipulated,
+optimized, translated to code, etc.
+
+## Example(s)
+
+```ruby
+# Let's build a simple predicate for 'x = 2 and not(y <= 3)'
+p = Predicate.eq(:x, 2) & !Predicate.lte(:y, 3)
+
+p.evaluate(:x => 2, :y => 6)
+# => true
+
+p.evaluate(:x => 2, :y => 3)
+# => false
+```
+
+When building complex expressions, you can use the `dsl` method.
+
+```ruby
+# This builds the same predicate
+p = Predicate.dsl{
+  eq(:x, 2) & !lte(:y, 3)
+}
+```
+
+The `dsl` block also have all predicates in camelCase, negated, and full text
+variants:
+
+```ruby
+p = Predicate.dsl{
+  notEq(:x, "foo") & hasSize(:y, 1..10) & lessThan(:z, 3)
+}
+```
+
+If you have complex expressions where many members apply to the same variable,
+a `currying` dsl extension is provided. It allows using all `dsl` methods
+while omitting their first argument.
+
+```ruby
+# Instead of this
+p = Predicate.gt(:x, 1) & Predicate.lt(:x, 10)
+
+# or this
+p = Predicate.dsl{
+  gt(:x, 1) & lt(:x, 10)
+}
+
+# do this
+p = Predicate.currying(:x){
+  gt(1) & lt(10)
+}
+p.evaluate(:x => 6)
+# => true
+```
+
+Predicate also works if you want to evaluate an expression on a single object
+without having to introduce a variable like `:x`...
+
+```ruby
+p = Predicate.currying{
+  gt(1) & lt(10)
+}
+p.evaluate(6)
+# => true
+```
+
+... or, in contrast, if you want to evaluate boolean expressions over more
+complex data structures that a flat Hash like `{:x => 6, ...}`
+
+```ruby
+x, y = Predicate.vars("items.0.price", "items.1.price")
+p = Predicate.eq(x, 6) & Predicate.lt(y, 10)
+p.evaluate({
+  items: [
+    { name: "Candy", price: 6 },
+    { name: "Crush", price: 4 }
+  ]
+})
+# => true
+```
+
+The following sections explain a) why we created this library, b) how to build
+expressions, c) what operators are available, and d) how abstract variables
+work and what features are supported when using them (because not all are).
+
+## Rationale
+
+This reusable library is used in various ruby gems developed and maintained
+by Enspirit where boolean expressions are first-class citizen. It provides
+a common API for expressing, evaluating, and manipulating them.
+
+* [Bmg](https://github.com/enspirit/bmg)
+* [Finitio](https://github.com/blambeau/finitio-rb)
+* [Webspicy](https://github.com/enspirit/webspicy)
+
+The library represents an expression as an AST internally. This allows for
+subsequent manipulations & reasoning. Please check the `Predicate::Factory`
+module for details.
+
+Best-effort simplifications are also performed at construction and when
+boolean logic is used (and, or, not). For instance, `eq(:x, 6) & eq(:x, 10)`
+yields a `contradiction` predicate. There is currently no way to disable those
+simplifications that were initially implemented for `Bmg`.
+
+## Building expressions
+
+The following list of operators is currently available.
+
+### True and False
+
+```ruby
+Predicate.tautology                  # aka True
+Predicate.contradiction              # aka False
+```
+
+### Logical operators
+
+For every valid Predicate instances `p` and `q`:
+
+```ruby
+p & q                                # Boolean conjunction
+p | q                                # Boolean disjunction
+!p                                   # Boolean negation
+```
+
+### Comparison operators
+
+```ruby
+Predicate.eq(:x, 2)                  # x = 2
+Predicate.eq(:x, :y)                 # x = y
+Predicate.neq(:x, 2)                 # x != 2
+Predicate.neq(:x, :y)                # x != y
+Predicate.lt(:x, 2)                  # x < 2
+Predicate.lt(:x, :y)                 # x < y
+Predicate.lte(:x, 2)                 # x <= 2
+Predicate.lte(:x, :y)                # x <= y
+Predicate.gt(:x, 2)                  # x > 2
+Predicate.gt(:x, :y)                 # x > y
+Predicate.gte(:x, 2)                 # x >= 2
+Predicate.gte(:x, :y)                # x >= y
+```
+
+Shortcuts (translated immediately, no trace kept in AST) :
+
+```ruby
+Predicate.eq(x: 2, y: 6)             # eq(:x, 2) & eq(:y, 6)
+Predicate.eq(x: 2, y: :z)            # eq(:x, 2) & eq(:y, :z)
+# ... and so on for neq, lt, lte, gt, gte
+
+Predicate.between(:x, l, h)          # gte(:x, l) & lte(:x, h), for all l and h
+Predicate.in(:x, 1..10)              # gte(:x, 1) & lte(:x, 10)
+Predicate.in(:x, 1...10)             # gte(:x, 1) & lt(:x, 10)
+#
+
+Predicate.is_null(:x)                # eq(:x, nil)
+```
+
+### Set-based operators
+
+```ruby
+Predicate.in(:x, [2, 4, 6])          # x ∈ {2, 4, 6}
+Predicate.in(:x, :y)                 # x ∈ y
+Predicate.intersect(:x, [2, 4, 6])   # x ∩ {2, 4, 6} ≠ ∅
+Predicate.intersect(:x, :y)          # x ∩ y ≠ ∅
+Predicate.subset(:x, [2, 4, 6])      # x ⊆ {2, 4, 6}
+Predicate.subset(:x, :y)             # x ⊆ y
+Predicate.superset(:x, [2, 4, 6])    # x ⊇ {2, 4, 6}
+Predicate.superset(:x, :y)           # x ⊇ y
+```
+
+### Other operators
+
+The following operators have no clear mathematical semantics. Their semantics
+depends on the underlying type system. Most are currently not supported outside
+of ruby (e.g. SQL compilation). The documentation below applies to a Ruby usage.
+
+```ruby
+Predicate.match(:x, /abc/)           # ruby's ===
+Predicate.empty(:x)                  # ruby's empty?
+Predicate.has_size(:x, 1..10)        # ruby's size and ===
+Predicate.has_size(:x, 10)           # Same as has_size(:x, 10..10)
+Predicate.has_size(:x, :y)           # y must resolve to a Range or Integer
+```
+
+Shortcuts (translated immediately, no trace kept in AST) :
+
+```ruby
+Predicate.min_size(:x, 10)           # has_size(:x, 10..)
+Predicate.max_size(:x, 10)           # has_size(:x, 0..10)
+```
+
+### Native expressions
+
+Ruby `Proc` can be used to capture complex predicates. Native predicates always
+receive the top evaluation context as first argument.
+
+```ruby
+p = Predicate.native(->(t){
+  # t here is the {:x => 2, :y => 6} Hash below
+  Foo::Bar.call_to_ruby_code?(t)
+})
+p.evaluate(:x => 2, :y => 6)
+```
+
+Resulting predicates cannot be translated to, e.g. SQL, and typically prevent
+optimizations and manipulations:
+
+## Available operators
+
+The following operators are available on predicates.
+
+### Evaluate
+
+`Predicate#evaluate` takes a Hash mapping each free variable to a value,
+and returns the Boolean evaluation of the expression.
+
+```ruby
+# Let's build a simple predicate for 'x = 2 and not(y <= 3)'
+p = Predicate.eq(:x, 2) & !Predicate.lte(:y, 3)
+
+p.evaluate(:x => 2, :y => 6)
+# => true
+```
+
+### Rename
+
+`Predicate#rename` allows renaming variables.
+
+```ruby
+p = Predicate.eq(:x, 4)       # x = 4
+p = p.rename(:x => :z)        # z = 4
+```
+
+### Bind
+
+`Predicate#bind` allows late binding of placeholders to values.
+
+```ruby
+pl = Predicate.placeholder
+p = Predicate.eq(:x, pl)      # x = _
+p = p.bind(pl, 5)             # x = 5
+p.evaluate(:x => 10)
+# => false
+```
+
+### Quality & Unqualify
+
+`Predicate#qualify` allows adding a qualifier to each variable, for
+disambiguation when composing predicates from different contexts.
+`Predicate#unqualify` does the opposite.
+
+```ruby
+p = Predicate.eq(:x, 2)       # x = 2
+p.qualify(:t)                 # t.x = 2
+p.unqualify                   # x = 2
+```
+
+Qualify accepts a Hash to use different qualifiers for variables.
+
+```ruby
+p = Predicate.eq(x: 2, y: 4)  # x = 2 & y = 4
+p.qualify(:x => :t, :y => :s)       # t.x = 2 & s.y = 4
+```
+
+### And split
+
+`Predicate#and_split` split a predicate `p` as two predicates `p1` and `p2`
+so that `p <=> p1 & p2` and `p2` makes no reference to any variable of the
+given list.
+
+```ruby
+p = Predicate.eq(x: 2, y: 4)  # x = 2 & y = 4
+p1, p2 = p.and_split([:x])    # p1 is x = 2 ; p2 is y = 4 
+```
+
+Observe that `and_split` is always possible but may degenerate to an
+uninteresting `p2`, typically when disjunctions are used. For instance,
+
+```ruby
+p = Predicate.eq(x: 2) | Predicate.eq(y: 4)  # x = 2 | y = 4
+p1, p2 = p.and_split([:x])    # p1 is x = 2 | y = 4 ; p2 is true
+```
+
+### Attr split
+
+`Predicate#attr_split` can be used to split a predicate `p` as n+1 predicates
+`p1, p2, ..., pn, pz`, such that `p <=> p1 & p2 & ... & pn & pz`. Each
+predicate `pi` makes references to variable `i` only, except `pz` which can
+reference all of them.
+
+The result is a Hash mapping each variable to its predicate. A `nil` key maps
+to `pz`.
+
+```ruby
+p = Predicate.eq(x: 2, y: 4)  # x = 2 & y = 4
+split = p.attr_split
+# => {
+#   :x => Predicate.eq(:x, 2),
+#   :y => Predicate.eq(:y, 4)
+# }
+```
+
+## Working with abstract variables
+
+WARNING: this `var` feature is only compatible with `Predicate#evaluate`
+and `Predicate#bind` so far. Other operators have not been tested and may fail
+in unexpected ways or raise a NotImplementedError. Also, predicates using
+abstract variables are not properly translated to e.g. SQL.
+
+By default, Predicate expects variable identifiers to be represented by
+ruby Symbols. `#evaluate` then takes a mapping between variables and values as
+a Hash:
+
+```ruby
+# :x and :y are variable identifiers
+p = Predicate.eq(:x, 2) & !Predicate.lte(:y, 3)
+
+# the Hash below is a mapping between variables and values
+p.evaluate(:x => 2, :y => 6)
+# => true
+```
+
+There are situations where you would like variables to be kept simple in
+expressions while evaluating the latter on complex data structures.
+
+`Predicate#var` can be used as an abstraction mechanism in such cases.
+It takes a variable definition as first argument and a semantics as second.
+The semantics defines how a value is extracted when the variable value must
+be evaluated.
+
+Supported protocols are `:dig`, `:send` and `:public_send`. Only `:dig`
+must be considered safe while the two other ones used with great care.
+
+* `:dig` relies on Ruby's `dig` protocol introduced in Ruby 2.3. It
+  will work out of the box with Hash, Array, Struct, OpenStruct and
+  more generally any object responding to `:dig`:
+
+  ```ruby
+  xyz = Predicate.var([:x, :y, :z], :dig)
+  p = Predicate.eq(xyz, 2)
+  p.evaluate({ :x => { :y => { :z => 2 } } })
+  # => true
+  ```
+
+  When using `:dig` the variable definition can be passed as a String
+  that will be automatically decomposed for you. Variable names are
+  transformed to Symbols and integer literals to Integers. You must
+  use the explicit version above if you don't want those conversions.
+
+  ```ruby
+  # this
+  Predicate.var("x.0.y", :dig)
+
+  # is equivalent to
+  Predicate.var([:x, 0, :y], :dig)
+  ```
+
+* `:send` relies on Ruby's `__send__` method and is generally less
+  safe if variable definitions are not strictly controlled. But it
+  allows evaluating predicates over any data structure made of pure
+  ruby objects:
+
+  ```ruby
+  class C
+    attr_reader :x
+    def initialize(x)
+      @x = x
+    end
+  end
+
+  xy = Predicate.var([:x, :y], :send)
+  p = Predicate.eq(xy, 2)
+  p.evaluate(C.new(OpenStruct.new(y: 2)))
+  # => true
+    ```
+
+  The variable can similarly be passed as a dotted String that will be
+  decomposed as a sequence of Symbols.
+
+  ```ruby
+  xy = Predicate.var("x.y", :send)
+  p = Predicate.eq(xy, 2)
+  p.evaluate(C.new(OpenStruct.new(y: 2)))
+  # => true
+  ```
+
+* `:public_send` is similar to `:send` but slightly safer as it only
+  allows calling Ruby's public methods.
+
+## Public API
+
+This library follows semantics versioning 2.0. Its public API is:
+
+* Class methods of the `Predicate` class, such as those covered in the
+  "Building expressions" section above.
+
+* DSL methods contributed by `Predicate::Factory`, `Predicate::Sugar`,
+  and `Predicate::Dsl` modules ; including dynamic ones (negation,
+  camelCase, etc.)
+
+* Instance methods of the `Predicate` class, such as those covered in the
+  "Available operators" section above.
+
+* Instance and class methods contributed by plugins (e.g. `predicate/sequel`).
+
+* Exception classes: `Predicate::NotSupportedError`,
+  `Predicate::UnboundError` and `Predicate::TypeError`.
+
+The AST representation of predicate expressions is NOT part of the public API.
+We bump the minor version of the library when it changes, though.
+
+Everything else is condidered private and may change any time (i.e. on patch
+releases).
+
+## Contributing
+
+Please use github issues and pull requests, and favor the latter if possible.
+
+This repository uses the help of [jeny](https://github.com/enspirit/jeny) to
+generate code snippets when adding new predicates. It supports `predicate`
+and `sugar` snippets and add code to be completed in various places:
+
+```
+bundle exec jeny s predicate -d op_name:my_predicate -d arity:unary
+bundle exec jeny s sugar     -d op_name:my_shortcut
+```
+
+## Licence
+
+This software is distributed by Enspirit SRL under a MIT Licence. Please
+contact Bernard Lambeau (blambeau@gmail.com) with any question.