odin-foundation 1.1.0 → 1.2.0

data/lib/odin/transform/transform_expr.rb

@@ -0,0 +1,222 @@
+# frozen_string_literal: true
+
+module Odin
+  module Transform
+    # Compiles an infix arithmetic formula string into a tree of existing verbs
+    # at parse time. No runtime evaluator: the result is an ordinary verb
+    # expression, so arithmetic runs through the deterministic verbs (add,
+    # subtract, multiply, divide, mod, negate, pow, and a whitelist of numeric
+    # functions). Variables resolve under an explicit bindings object passed as
+    # the second argument: in %expr "a + b" @.vars, the name a reads @.vars.a.
+    #
+    # Precedence, high to low:
+    #   1. parentheses, function call
+    #   2. ^ power (right-associative)
+    #   3. unary - / +   (looser than ^, so -2^2 = -(2^2) = -4; (-2)^2 = 4)
+    #   4. * / %  (left-associative)
+    #   5. + -    (left-associative)
+    module Expr
+      class ExprSyntaxError < StandardError
+        attr_reader :code
+
+        def initialize(message)
+          @code = "T015"
+          super("Invalid %expr formula: #{message}")
+        end
+      end
+
+      BINARY_OP = { "+" => "add", "-" => "subtract", "*" => "multiply", "/" => "divide", "%" => "mod" }.freeze
+
+      FUNCTIONS = {
+        "abs" => { verb: "abs", min: 1, max: 1 },
+        "floor" => { verb: "floor", min: 1, max: 1 },
+        "ceil" => { verb: "ceil", min: 1, max: 1 },
+        "trunc" => { verb: "trunc", min: 1, max: 1 },
+        "sqrt" => { verb: "sqrt", min: 1, max: 1 },
+        "round" => { verb: "round", min: 1, max: 2 },
+        "pow" => { verb: "pow", min: 2, max: 2 },
+        "min" => { verb: "minOf", min: 1, max: Float::INFINITY },
+        "max" => { verb: "maxOf", min: 1, max: Float::INFINITY }
+      }.freeze
+
+      Token = Struct.new(:kind, :value, :is_float)
+
+      module_function
+
+      def compile(formula, binding_path = nil)
+        Parser.new(tokenize(formula), binding_path).parse
+      end
+
+      def tokenize(src)
+        tokens = []
+        i = 0
+        len = src.length
+        while i < len
+          c = src[i]
+          if c =~ /\s/
+            i += 1
+            next
+          end
+          if c =~ /[0-9]/
+            j = i
+            is_float = false
+            j += 1 while j < len && src[j] =~ /[0-9]/
+            if src[j] == "."
+              is_float = true
+              j += 1
+              j += 1 while j < len && src[j] =~ /[0-9]/
+            end
+            if src[j] == "e" || src[j] == "E"
+              is_float = true
+              j += 1
+              j += 1 if src[j] == "+" || src[j] == "-"
+              j += 1 while j < len && src[j] =~ /[0-9]/
+            end
+            tokens << Token.new(:num, src[i...j], is_float)
+            i = j
+            next
+          end
+          if c =~ /[A-Za-z_]/
+            j = i
+            j += 1 while j < len && src[j] =~ /[A-Za-z0-9_.]/
+            tokens << Token.new(:ident, src[i...j], false)
+            i = j
+            next
+          end
+          case c
+          when "(" then tokens << Token.new(:lparen, c, false)
+          when ")" then tokens << Token.new(:rparen, c, false)
+          when "," then tokens << Token.new(:comma, c, false)
+          when "+", "-", "*", "/", "%", "^" then tokens << Token.new(:op, c, false)
+          else raise ExprSyntaxError, "unexpected character '#{c}'"
+          end
+          i += 1
+        end
+        tokens
+      end
+
+      def literal(text, is_float)
+        value = is_float ? Types::DynValue.of_float(text.to_f) : Types::DynValue.of_integer(text.to_i)
+        LiteralExpr.new(value)
+      end
+
+      def verb_node(verb, args)
+        VerbExpr.new(verb, args, custom: false)
+      end
+
+      class Parser
+        def initialize(tokens, binding_path)
+          @tokens = tokens
+          @binding_path = binding_path
+          @pos = 0
+        end
+
+        def parse
+          raise ExprSyntaxError, "empty formula" if @tokens.empty?
+          expr = parse_additive
+          raise ExprSyntaxError, "unexpected token '#{peek.value}'" if @pos < @tokens.length
+          expr
+        end
+
+        private
+
+        def peek
+          @tokens[@pos]
+        end
+
+        def advance
+          t = @tokens[@pos]
+          @pos += 1
+          t
+        end
+
+        def parse_additive
+          left = parse_multiplicative
+          while peek&.kind == :op && (peek.value == "+" || peek.value == "-")
+            op = advance.value
+            right = parse_multiplicative
+            left = Expr.verb_node(BINARY_OP[op], [left, right])
+          end
+          left
+        end
+
+        def parse_multiplicative
+          left = parse_unary
+          while peek&.kind == :op && %w[* / %].include?(peek.value)
+            op = advance.value
+            right = parse_unary
+            left = Expr.verb_node(BINARY_OP[op], [left, right])
+          end
+          left
+        end
+
+        def parse_unary
+          t = peek
+          if t&.kind == :op && (t.value == "-" || t.value == "+")
+            advance
+            operand = parse_unary
+            return t.value == "-" ? Expr.verb_node("negate", [operand]) : operand
+          end
+          parse_power
+        end
+
+        def parse_power
+          base = parse_primary
+          if peek&.kind == :op && peek.value == "^"
+            advance
+            exponent = parse_unary
+            return Expr.verb_node("pow", [base, exponent])
+          end
+          base
+        end
+
+        def parse_primary
+          t = advance
+          raise ExprSyntaxError, "unexpected end of formula" if t.nil?
+
+          case t.kind
+          when :num
+            Expr.literal(t.value, t.is_float)
+          when :lparen
+            inner = parse_additive
+            close = advance
+            raise ExprSyntaxError, "missing closing parenthesis" if close.nil? || close.kind != :rparen
+            inner
+          when :ident
+            return parse_call(t.value) if peek&.kind == :lparen
+            if @binding_path.nil?
+              raise ExprSyntaxError, "variable '#{t.value}' requires a bindings object, e.g. %expr \"...\" @.vars"
+            end
+            CopyExpr.new("#{@binding_path}.#{t.value}")
+          else
+            raise ExprSyntaxError, "unexpected token '#{t.value}'"
+          end
+        end
+
+        def parse_call(name)
+          fn = FUNCTIONS[name]
+          raise ExprSyntaxError, "unknown function '#{name}'" if fn.nil?
+
+          advance # consume '('
+          args = []
+          if peek&.kind != :rparen
+            args << parse_additive
+            while peek&.kind == :comma
+              advance
+              args << parse_additive
+            end
+          end
+          close = advance
+          raise ExprSyntaxError, "missing ) after #{name}(" if close.nil? || close.kind != :rparen
+
+          if args.length < fn[:min] || args.length > fn[:max]
+            bound = fn[:min] == fn[:max] ? fn[:min].to_s : "#{fn[:min]}-#{fn[:max]}"
+            raise ExprSyntaxError, "#{name}() takes #{bound} arguments, got #{args.length}"
+          end
+          args << LiteralExpr.new(Types::DynValue.of_integer(0)) if name == "round" && args.length == 1
+          Expr.verb_node(fn[:verb], args)
+        end
+      end
+    end
+  end
+end

data/lib/odin/transform/transform_parser.rb

@@ -71,6 +71,20 @@ module Odin
         "has" => 2, "merge" => 2, "jsonPath" => 2,
         "assert" => 2,
         "formatPhone" => 2, "movingAvg" => 2, "businessDays" => 2,
+        "fromEntries" => 1, "invert" => 1, "defaults" => 2, "renameKeys" => 2,
+        "compactObject" => 1,
+        "intersection" => 2, "union" => 2, "difference" => 2,
+        "symmetricDifference" => 2, "countBy" => 2, "keyBy" => 2,
+        "explode" => 2, "window" => 2,
+        "base64urlEncode" => 1, "base64urlDecode" => 1, "hmac" => 3,
+        "parseUrl" => 1, "buildUrl" => 1, "parseQuery" => 1, "buildQuery" => 1,
+        "stableStringify" => 1, "canonicalHash" => 1,
+        "escapeHtml" => 1, "unescapeHtml" => 1, "escapeXml" => 1, "stripTags" => 1,
+        "template" => 2,
+        "gcd" => 2, "lcm" => 2, "factorial" => 1,
+        "expr" => 2,
+        "countIf" => 4, "sumIf" => 5, "avgIf" => 5,
+        "xnpv" => 3, "xirr" => 3,
 
         # Arity 3
         "ifElse" => 3, "between" => 3,
@@ -100,7 +114,7 @@ module Odin
       }.freeze
 
       VARIADIC_VERBS = %w[
-        concat coalesce cond switch lookup lookupDefault minOf maxOf
+        concat coalesce cond switch lookup lookupDefault minOf maxOf pick omit
       ].freeze
 
       ALL_DIRECTIVES = %w[
@@ -717,8 +731,9 @@ module Odin
           when "_literalBody"
             literal_body = raw_val
           else
-            next if key.start_with?("_") && key != "_"
-
+            # An unrecognized `_`-prefixed field is a computation-only sink:
+            # it runs for side effects but is not emitted. Recognized loop
+            # directives are handled above; these flow through as mappings.
             mapping = parse_field_mapping(key, raw_val)
             field_mappings << mapping
           end
@@ -1047,6 +1062,11 @@ module Odin
           verb_name = verb_token[1..]
         end
 
+        # %expr is a parse-time macro: compile the formula string into a verb tree.
+        if verb_name == "expr" && !custom
+          return compile_expr_macro(tokens)
+        end
+
         arity = VERB_ARITY[verb_name]
 
         if arity.nil?
@@ -1070,6 +1090,27 @@ module Odin
         end
       end
 
+      # Compile a %expr formula from the remaining tokens. arg0 is a quoted
+      # formula string; arg1, if present, is an @-reference bindings object.
+      def compile_expr_macro(tokens)
+        formula_token = tokens.shift
+        unless formula_token&.match?(/\A".*"\z/m)
+          raise Expr::ExprSyntaxError, "expected a quoted formula string"
+        end
+        formula = unescape_string(formula_token[1...-1])
+
+        binding_path = nil
+        if !tokens.empty? && !tokens.first.start_with?(":")
+          ref_token = tokens.shift
+          unless ref_token.start_with?("@")
+            raise Expr::ExprSyntaxError, "the bindings argument must be a reference such as @.vars"
+          end
+          binding_path = ref_token == "@" ? "" : ref_token[1..]
+        end
+
+        [Expr.compile(formula, binding_path), tokens]
+      end
+
       EXTRACTION_DIRECTIVES = %w[pos len field trim].freeze
       # Directives that take a value argument (not boolean flags)
       VALUE_DIRECTIVES = %w[pos len field].freeze

data/lib/odin/transform/verbs/collection_verbs.rb

@@ -7,17 +7,22 @@ module Odin
         module_function
 
         def extract_items(v)
-          return [] if v.nil? || v.null?
+          as_items(v) || []
+        end
+
+        # Returns the underlying array items, or nil when v is not array-like.
+        def as_items(v)
+          return nil if v.nil? || v.null?
           return v.value if v.array?
           if v.string?
             begin
               parsed = Types::DynValue.extract_array(v.value)
-              return parsed.value
+              return parsed.value if parsed.array?
             rescue
-              return []
+              return nil
             end
           end
-          []
+          nil
         end
 
         def compare_dyn_values(a, b)
@@ -222,9 +227,15 @@ module Odin
           }
 
           registry["every"] = ->(args, _ctx) {
-            items = CollectionVerbs.extract_items(args[0])
+            items = CollectionVerbs.as_items(args[0])
+            return dv.of_null if items.nil?
             return dv.of_bool(true) if items.empty?
-            if args.length >= 2
+            if args.length >= 4
+              field = args[1]&.to_string || ""
+              op = args[2]&.to_string || "="
+              compare = args[3]
+              dv.of_bool(items.all? { |item| CollectionVerbs.matches_condition?(item, field, op, compare) })
+            elsif args.length >= 2
               field = args[1]&.to_string || ""
               dv.of_bool(items.all? { |item| (item.object? ? item.get(field) : item)&.truthy? || false })
             else
@@ -233,9 +244,15 @@ module Odin
           }
 
           registry["some"] = ->(args, _ctx) {
-            items = CollectionVerbs.extract_items(args[0])
+            items = CollectionVerbs.as_items(args[0])
+            return dv.of_null if items.nil?
             return dv.of_bool(false) if items.empty?
-            if args.length >= 2
+            if args.length >= 4
+              field = args[1]&.to_string || ""
+              op = args[2]&.to_string || "="
+              compare = args[3]
+              dv.of_bool(items.any? { |item| CollectionVerbs.matches_condition?(item, field, op, compare) })
+            elsif args.length >= 2
               field = args[1]&.to_string || ""
               dv.of_bool(items.any? { |item| (item.object? ? item.get(field) : item)&.truthy? || false })
             else
@@ -272,24 +289,19 @@ module Odin
           }
 
           registry["concatArrays"] = ->(args, _ctx) {
+            extracted = args.map { |a| CollectionVerbs.as_items(a) }
+            return dv.of_null if extracted.all?(&:nil?)
             result = []
-            args.each do |a|
-              if a&.array?
-                result.concat(a.value)
-              elsif !a.nil? && !a.null?
-                result << a
-              end
-            end
+            extracted.each { |items| result.concat(items) if items }
             dv.of_array(result)
           }
 
           registry["zip"] = ->(args, _ctx) {
-            arrays = args.map { |a| CollectionVerbs.extract_items(a) }
-            return dv.of_array([]) if arrays.empty?
-            max_len = arrays.map(&:length).max || 0
-            result = (0...max_len).map do |i|
-              pair = arrays.map { |arr| i < arr.length ? arr[i] : dv.of_null }
-              dv.of_array(pair)
+            extracted = args.map { |a| CollectionVerbs.as_items(a) }
+            return dv.of_null if extracted.any?(&:nil?) || extracted.empty?
+            min_len = extracted.map(&:length).min || 0
+            result = (0...min_len).map do |i|
+              dv.of_array(extracted.map { |arr| arr[i] })
             end
             dv.of_array(result)
           }
@@ -331,22 +343,24 @@ module Odin
           }
 
           registry["take"] = ->(args, _ctx) {
-            items = CollectionVerbs.extract_items(args[0])
+            items = CollectionVerbs.as_items(args[0])
             n = NumericVerbs.to_double(args[1])&.to_i || 0
-            dv.of_array(items.first([n, 0].max))
+            return dv.of_null if items.nil? || n < 0
+            dv.of_array(items.first(n))
           }
           registry["limit"] = registry["take"]
 
           registry["drop"] = ->(args, _ctx) {
-            items = CollectionVerbs.extract_items(args[0])
+            items = CollectionVerbs.as_items(args[0])
             n = NumericVerbs.to_double(args[1])&.to_i || 0
-            dv.of_array(items.drop([n, 0].max))
+            return dv.of_null if items.nil? || n < 0
+            dv.of_array(items.drop(n))
           }
 
           registry["chunk"] = ->(args, _ctx) {
-            items = CollectionVerbs.extract_items(args[0])
+            items = CollectionVerbs.as_items(args[0])
             size = NumericVerbs.to_double(args[1])&.to_i || 1
-            size = 1 if size < 1
+            return dv.of_null if items.nil? || size < 1
             chunks = items.each_slice(size).map { |c| dv.of_array(c) }
             dv.of_array(chunks)
           }
@@ -386,7 +400,8 @@ module Odin
           }
 
           registry["compact"] = ->(args, _ctx) {
-            items = CollectionVerbs.extract_items(args[0])
+            items = CollectionVerbs.as_items(args[0])
+            return dv.of_null if items.nil?
             dv.of_array(items.reject { |item| item.null? || (item.string? && item.value.empty?) })
           }
 
@@ -435,7 +450,8 @@ module Odin
           }
 
           registry["dedupe"] = ->(args, _ctx) {
-            items = CollectionVerbs.extract_items(args[0])
+            items = CollectionVerbs.as_items(args[0])
+            return dv.of_null if items.nil?
             field = args[1]&.to_string
             result = []
             last_key = nil
@@ -454,7 +470,8 @@ module Odin
           }
 
           registry["cumsum"] = ->(args, _ctx) {
-            items = CollectionVerbs.extract_items(args[0])
+            items = CollectionVerbs.as_items(args[0])
+            return dv.of_null if items.nil?
             sum = 0.0
             result = items.map do |item|
               n = NumericVerbs.to_double(item)
@@ -469,7 +486,8 @@ module Odin
           }
 
           registry["cumprod"] = ->(args, _ctx) {
-            items = CollectionVerbs.extract_items(args[0])
+            items = CollectionVerbs.as_items(args[0])
+            return dv.of_null if items.nil?
             prod = 1.0
             result = items.map do |item|
               n = NumericVerbs.to_double(item)
@@ -484,7 +502,8 @@ module Odin
           }
 
           registry["diff"] = ->(args, _ctx) {
-            items = CollectionVerbs.extract_items(args[0])
+            items = CollectionVerbs.as_items(args[0])
+            return dv.of_null if items.nil?
             lag = args[1] ? (NumericVerbs.to_double(args[1])&.to_i || 1) : 1
             result = items.each_with_index.map do |item, i|
               if i < lag
@@ -503,7 +522,8 @@ module Odin
           }
 
           registry["pctChange"] = ->(args, _ctx) {
-            items = CollectionVerbs.extract_items(args[0])
+            items = CollectionVerbs.as_items(args[0])
+            return dv.of_null if items.nil?
             lag = args[1] ? (NumericVerbs.to_double(args[1])&.to_i || 1) : 1
             result = items.each_with_index.map do |item, i|
               if i < lag
@@ -514,7 +534,7 @@ module Odin
                 if curr.nil? || prev.nil? || prev == 0.0
                   dv.of_null
                 else
-                  dv.of_float((curr - prev) / prev)
+                  NumericVerbs.numeric_result((curr - prev) / prev)
                 end
               end
             end

data/lib/odin/transform/verbs/datetime_verbs.rb

@@ -21,6 +21,19 @@ module Odin
           end
         end
 
+        # Strict yyyy-MM-dd parse; returns nil for any other shape or invalid date.
+        def parse_iso_date(s)
+          s = s.to_string if s.is_a?(Types::DynValue)
+          return nil unless s.is_a?(String)
+          m = s.match(/\A(\d{4})-(\d{2})-(\d{2})\z/)
+          return nil unless m
+          begin
+            Date.new(m[1].to_i, m[2].to_i, m[3].to_i)
+          rescue ArgumentError
+            nil
+          end
+        end
+
         def parse_timestamp(s)
           return nil if s.nil?
           s = s.to_string if s.is_a?(Types::DynValue)
@@ -511,7 +524,7 @@ module Odin
             d1 = DateTimeVerbs.parse_date(v1)
             d2 = DateTimeVerbs.parse_date(v2)
             return dv.of_null unless d1 && d2
-            dv.of_integer((d2 - d1).to_i.abs)
+            dv.of_integer((d2 - d1).to_i)
           }
 
           registry["ageFromDate"] = ->(args, _ctx) {
@@ -532,8 +545,12 @@ module Odin
           registry["isValidDate"] = ->(args, _ctx) {
             s = args[0]&.to_string
             return dv.of_bool(false) if s.nil? || s.empty?
-            d = DateTimeVerbs.parse_date(s)
-            dv.of_bool(!d.nil?)
+            return dv.of_bool(true) unless DateTimeVerbs.parse_iso_date(s).nil?
+            if args.length >= 2
+              pattern = args[1]&.to_string || ""
+              return dv.of_bool(true) unless DateTimeVerbs.parse_date_with_pattern(s, pattern).nil?
+            end
+            dv.of_bool(false)
           }
 
           registry["formatLocaleDate"] = ->(args, _ctx) {