equation 0.5.0 → 0.6.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f4f1469e22a3d098dfcb0c2ca974a2d081c0c7be90afddb20fea36f65bdc0804
-  data.tar.gz: 5925da1a74a22bfe8e1cc1b7f4dd43a61cf02b05a61ca2a15821f184ff45e5a7
+  metadata.gz: bc3a0622cdb38f0db990030f8ec8b9c70fec671e1dbe5d26167787e272ed4bbc
+  data.tar.gz: 1c4ca3a83d2cb17b0fb954f84ed53ae6f919aef866a05cb87ea219092cf13165
 SHA512:
-  metadata.gz: 5ef71408034ed55d48efadd5b99c6e3c41ae49680b673f658b5fa0689731834a0260e4810c3a189f670b97c6451845b3c082ef9ad82ff65c813de5b13a6dee27
-  data.tar.gz: 595552e82f8f4412b0a379025883669b0f05e1199948de2ed1221c14092a17cd2b296f396ad2e3e0091e1095307b392904866457222d21895c0c7b66978dda87
+  metadata.gz: edf2c16a123be3141a6757b95423fae213ee3b5028f48ea00fab72a75cb5bf1bd3d19ba4f7509466b9f8bfc4a5f572e0781beff8d5d152dc9b7d0d9e660dff8d
+  data.tar.gz: e3d07dc903426b9d718b0cd4d32cfefd08e2eeb09ab5069079fc95100302a74f0ae526a96d618827810d4834a0cbe5e98f7371b43ef20916f264f3aba423a109

data/README.md

@@ -10,6 +10,10 @@ Use cases include:
 
 Modeled loosely after [Symfony Expression Language](https://symfony.com/doc/current/components/expression_language.html).
 
+## Demos
+
+Take a look at the examples directory for some demonstrations of Equation's capabilities. The main example is a [web application firewall](https://github.com/ancat/equation/tree/main/examples/rails_waf) for Rails; rules can be managed from any ActiveStorage compatible backend (e.g. filesystem, Amazon AWS, etc) and updated independently of application code, allowing for faster and more expressive blocking logic without having to wait for a deploy to go through.
+
 ## Example
 
 In this example, we'll use a rule to determine whether a request should be dropped or not. While the rule here is hardcoded into the program, it could just as easily be pulled from a database, some redis cache, etc instead. Rules can also be cached, saving you an extra parsing step.
@@ -29,3 +33,59 @@ if suspicious_request
   # log some things, notify some people
 end
 ```
+
+## Language Features
+
+Because Equation is modeled after [Symfony Expression Language](https://symfony.com/doc/current/components/expression_language/syntax.html), it supports a lot of the same features. For a more exhaustive list, check out the [tests](https://github.com/ancat/equation/blob/main/spec/equation_spec.rb).
+
+### Literals
+
+* Strings: double quotes, e.g. `"hello world"`
+* Numbers: all treated as floats, e.g. `0`, `-10`, `0.5`
+* Arrays: square brackets, e.g. `[403, 404]` or `["yes", "no", "maybe"]`; can be mixed types
+* Booleans: `true`, `false`
+* Null: `nil`
+
+### Variables
+
+Variables are only made available to the engine at initialization. For example, given this setup code:
+
+```ruby
+engine = EquationEngine.new(default: {name: "OMAR", age: 12})
+```
+
+These variables and all their properties are accessible from within rules:
+
+```
+$name == "OMAR" # true
+$name.length    # 4
+$name.reverse   # RAMO
+```
+
+### Methods
+
+Like variables, methods are only made available to the engine at initialization. They can take any number and type of arguments, including variables or return values from other methods.
+
+```ruby
+engine = EquationEngine.new(default: {age: 12}, methods: {is_even: ->(n) {n%2==0}})
+```
+
+`is_even` can now be called as follows:
+
+```
+is_even(5)    # false
+is_even($age) # true
+```
+
+### Comparisons
+
+```
+$name == "Dumpling" && $age >= 12
+$name in ["Dumpling", "Meatball"] || $age == 12
+```
+
+## Development
+
+* To work on the expression language itself, take a look at `lib/equation_grammar.treetop`. Equation is built using [treetop](https://cjheath.github.io/treetop/).
+* Run `bundle exec rake build_grammar` to generate the corresponding parser Ruby code.
+* Run `bundle exec rake spec` to run tests.

data/lib/equation.rb

@@ -3,28 +3,31 @@ require_relative 'equation_node_classes'
 require_relative 'equation_grammar'
 
 class Context
+  attr_accessor :transient_symbols
+
   def initialize(default: {}, methods: {})
     @symbol_table = default
+    @transient_symbols = {}
     @methods = methods
   end
 
-  def set(identifier:, value:)
-    @symbol_table[identifier.to_sym] = value
+  def symbols
+    @symbol_table.merge(@transient_symbols)
   end
 
   def get(identifier:, path: {})
     assert_defined!(identifier: identifier)
-    @symbol_table[identifier.to_sym]
-    root = @symbol_table[identifier.to_sym]
-    child = root
+    child = symbols[identifier.to_sym]
     path.each{|segment|
-      segment_name = segment.elements[1].text_value.to_sym
-      if child.respond_to?(segment_name)
-        child = child.send(segment_name)
-      elsif child.include?(segment_name)
-        child = child[segment_name]
+      segment_name = segment.elements[1].text_value
+      if child.respond_to?(segment_name.to_sym)
+        child = child.send(segment_name.to_sym)
+      elsif child.is_a? Hash and child.include?(segment_name.to_sym)
+        child = child[segment_name.to_sym]
+      elsif child.is_a? Hash and child.include?(segment_name.to_s)
+        child = child[segment_name.to_s]
       else
-        raise "no"
+        return nil
       end
     }
 
@@ -38,7 +41,7 @@ class Context
 
   private
   def assert_defined!(identifier:)
-    raise "Undefined variable: #{identifier}" unless @symbol_table.has_key?(identifier.to_sym)
+    raise "Undefined variable: #{identifier}" unless symbols.has_key?(identifier.to_sym)
   end
 
   def assert_method_exists!(method:)
@@ -47,6 +50,8 @@ class Context
 end
 
 class EquationEngine
+  attr_accessor :parser, :context
+
   def initialize(default: {}, methods: {})
     @parser = EquationParser.new
     @context = Context.new(default: default, methods: methods)
@@ -59,10 +64,17 @@ class EquationEngine
     parsed_rule
   end
 
+  def parse_and_eval(rule:)
+    parse(rule: rule).value(ctx: @context)
+  end
+
   def eval(rule:)
-    parsed_rule = @parser.parse(rule)
-    raise "Parse Error: #{rule}" unless parsed_rule
+    rule.value(ctx: @context)
+  end
 
-    parsed_rule.value(ctx: @context)
+  def eval_with(rule:, values: {})
+    rule.value(ctx: @context.tap { |x|
+      x.transient_symbols = values
+    })
   end
 end

data/lib/equation_grammar.rb

@@ -709,6 +709,8 @@ module Equation
             base *= k.operand.value(ctx: ctx)
           when '/'
             base /= k.operand.value(ctx: ctx)
+          when '%'
+            base %= k.operand.value(ctx: ctx)
         end
       end
 
@@ -760,17 +762,29 @@ module Equation
               r7 = SyntaxNode.new(input, (index-1)...index) if r7 == true
               r5 = r7
             else
-              @index = i5
-              r5 = nil
+              if (match_len = has_terminal?('%', false, index))
+                r8 = true
+                @index += match_len
+              else
+                terminal_parse_failure('\'%\'')
+                r8 = nil
+              end
+              if r8
+                r8 = SyntaxNode.new(input, (index-1)...index) if r8 == true
+                r5 = r8
+              else
+                @index = i5
+                r5 = nil
+              end
             end
           end
           s3 << r5
           if r5
-            r8 = _nt_space
-            s3 << r8
-            if r8
-              r9 = _nt_standalone
-              s3 << r9
+            r9 = _nt_space
+            s3 << r9
+            if r9
+              r10 = _nt_standalone
+              s3 << r10
             end
           end
         end
@@ -804,6 +818,27 @@ module Equation
     r0
   end
 
+  module Standalone0
+    def negate
+      elements[0]
+    end
+
+    def unit
+      elements[1]
+    end
+  end
+
+  module Standalone1
+    def value(ctx:)
+      base = unit.value(ctx: ctx)
+      negate.text_value.length.times {
+        base = !base
+      }
+
+      base
+    end
+  end
+
   def _nt_standalone
     start_index = index
     if node_cache[:standalone].has_key?(index)
@@ -815,32 +850,61 @@ module Equation
       return cached
     end
 
-    i0 = index
-    r1 = _nt_symbol
-    if r1
-      r1 = SyntaxNode.new(input, (index-1)...index) if r1 == true
-      r0 = r1
-    else
-      r2 = _nt_method_call
+    i0, s0 = index, []
+    s1, i1 = [], index
+    loop do
+      if (match_len = has_terminal?('!', false, index))
+        r2 = true
+        @index += match_len
+      else
+        terminal_parse_failure('\'!\'')
+        r2 = nil
+      end
       if r2
-        r2 = SyntaxNode.new(input, (index-1)...index) if r2 == true
-        r0 = r2
+        s1 << r2
       else
-        r3 = _nt_literals
-        if r3
-          r3 = SyntaxNode.new(input, (index-1)...index) if r3 == true
-          r0 = r3
+        break
+      end
+    end
+    r1 = instantiate_node(SyntaxNode,input, i1...index, s1)
+    s0 << r1
+    if r1
+      i3 = index
+      r4 = _nt_symbol
+      if r4
+        r4 = SyntaxNode.new(input, (index-1)...index) if r4 == true
+        r3 = r4
+      else
+        r5 = _nt_method_call
+        if r5
+          r5 = SyntaxNode.new(input, (index-1)...index) if r5 == true
+          r3 = r5
         else
-          r4 = _nt_subexpression
-          if r4
-            r4 = SyntaxNode.new(input, (index-1)...index) if r4 == true
-            r0 = r4
+          r6 = _nt_literals
+          if r6
+            r6 = SyntaxNode.new(input, (index-1)...index) if r6 == true
+            r3 = r6
           else
-            @index = i0
-            r0 = nil
+            r7 = _nt_subexpression
+            if r7
+              r7 = SyntaxNode.new(input, (index-1)...index) if r7 == true
+              r3 = r7
+            else
+              @index = i3
+              r3 = nil
+            end
           end
         end
       end
+      s0 << r3
+    end
+    if s0.last
+      r0 = instantiate_node(SyntaxNode,input, i0...index, s0)
+      r0.extend(Standalone0)
+      r0.extend(Standalone1)
+    else
+      @index = i0
+      r0 = nil
     end
 
     node_cache[:standalone][start_index] = r0

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: equation
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.1
 platform: ruby
 authors:
 - OMAR
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2022-08-08 00:00:00.000000000 Z
+date: 2023-01-29 00:00:00.000000000 Z
 dependencies: []
 description: Equation exposes a minimal environment to allow safe execution of Ruby
   code represented via a custom expression language.
@@ -24,8 +24,7 @@ files:
 homepage: https://github.com/ancat/equation
 licenses:
 - MIT
-metadata:
-  rubygems_mfa_required: 'true'
+metadata: {}
 post_install_message: 
 rdoc_options: []
 require_paths:
@@ -41,7 +40,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.19
+rubygems_version: 3.1.6
 signing_key: 
 specification_version: 4
 summary: A rules engine for your Ruby apps.