ruby-rego 0.1.0

data/lib/ruby/rego/builtins/registry.rb

@@ -0,0 +1,199 @@
+# frozen_string_literal: true
+
+require_relative "base"
+require_relative "../errors"
+require_relative "../value"
+
+module Ruby
+  module Rego
+    module Builtins
+      # Shared builtin invocation helpers.
+      module BuiltinInvocation
+        private
+
+        def normalize_name(name)
+          normalized = name.to_s
+          raise ArgumentError, "Builtin name cannot be empty" if normalized.strip.empty?
+
+          normalized
+        end
+
+        # :reek:FeatureEnvy
+        # :reek:TooManyStatements
+        def invoke_entry(entry, args)
+          entry_name = entry.name
+          args = ensure_array_args(args, entry_name)
+          Builtins::Base.assert_arity(args, entry.arity, name: entry_name)
+          Value.from_ruby(entry.handler.call(*args.map { |arg| Value.from_ruby(arg) }))
+        rescue Ruby::Rego::BuiltinArgumentError
+          UndefinedValue.new
+        end
+
+        # :reek:FeatureEnvy
+        def ensure_array_args(args, builtin_name)
+          return args if args.is_a?(Array)
+
+          raise Ruby::Rego::BuiltinArgumentError.new(
+            "Expected arguments to be an Array",
+            expected: Array,
+            actual: args.class,
+            context: "builtin #{builtin_name}",
+            location: nil
+          )
+        end
+      end
+
+      # Registry for built-in function implementations.
+      class BuiltinRegistry
+        include BuiltinInvocation
+
+        # Represents a registered built-in definition.
+        Entry = Struct.new(:name, :arity, :handler, keyword_init: true)
+
+        # @return [BuiltinRegistry]
+        def self.instance
+          @instance ||= new
+        end
+
+        private_class_method :new
+
+        def initialize
+          @builtins = {}
+        end
+
+        # @param name [String, Symbol]
+        # @param arity [Integer]
+        # @yieldparam args [Array<Ruby::Rego::Value>]
+        # @return [void]
+        def register(name, arity, &block)
+          raise ArgumentError, "Builtin registration requires a block" unless block
+
+          builtin_name = normalize_name(name)
+          validate_arity(arity)
+          raise ArgumentError, "Builtin already registered: #{builtin_name}" if @builtins.key?(builtin_name)
+
+          @builtins[builtin_name] = Entry.new(name: builtin_name, arity: arity, handler: block)
+        end
+
+        # @param name [String, Symbol]
+        # @param args [Array<Object>]
+        # @return [Ruby::Rego::Value]
+        def call(name, args)
+          entry = fetch_entry(normalize_name(name))
+          invoke_entry(entry, args)
+        end
+
+        # @param name [String, Symbol]
+        # @return [Entry]
+        def entry_for(name)
+          fetch_entry(normalize_name(name))
+        end
+
+        # @param name [String, Symbol]
+        # @param entry [Entry]
+        # @yieldreturn [Object]
+        # @return [Object]
+        def with_entry_override(name, entry)
+          builtin_name = normalize_name(name)
+          previous = fetch_entry(builtin_name)
+          @builtins[builtin_name] = entry
+          yield
+        ensure
+          @builtins[builtin_name] = previous
+        end
+
+        # @param name [String, Symbol]
+        # @param entry [Entry]
+        # @return [BuiltinRegistryOverlay]
+        def with_override(name, entry)
+          BuiltinRegistryOverlay.new(
+            base_registry: self,
+            overrides: { normalize_name(name) => entry }
+          )
+        end
+
+        # @param name [String, Symbol]
+        # @return [Boolean]
+        def registered?(name)
+          @builtins.key?(normalize_name(name))
+        end
+
+        private
+
+        # :reek:UtilityFunction
+        # :reek:FeatureEnvy
+        def validate_arity(arity)
+          return if integer_arity_valid?(arity)
+          return if array_arity_valid?(arity)
+
+          raise ArgumentError, "Arity must be a non-negative Integer or Array of Integers"
+        end
+
+        # :reek:UtilityFunction
+        def integer_arity_valid?(arity)
+          arity.is_a?(Integer) && arity >= 0
+        end
+
+        # :reek:UtilityFunction
+        def array_arity_valid?(arity)
+          return false unless arity.is_a?(Array)
+          return false if arity.empty?
+
+          arity.all? { |value| value.is_a?(Integer) && value >= 0 }
+        end
+
+        def fetch_entry(builtin_name)
+          @builtins.fetch(builtin_name) do
+            raise EvaluationError, "Undefined built-in function: #{builtin_name}"
+          end
+        end
+      end
+
+      # Registry wrapper that overlays builtin entries without mutating the base registry.
+      class BuiltinRegistryOverlay
+        include BuiltinInvocation
+
+        # @param base_registry [BuiltinRegistry]
+        # @param overrides [Hash{String => BuiltinRegistry::Entry}]
+        def initialize(base_registry:, overrides: {})
+          @base_registry = base_registry
+          @overrides = overrides
+        end
+
+        # @param name [String, Symbol]
+        # @param entry [BuiltinRegistry::Entry]
+        # @return [BuiltinRegistryOverlay]
+        def with_override(name, entry)
+          normalized = normalize_name(name)
+          self.class.new(base_registry: base_registry, overrides: overrides.merge(normalized => entry))
+        end
+
+        # @param name [String, Symbol]
+        # @param args [Array<Object>]
+        # @return [Ruby::Rego::Value]
+        def call(name, args)
+          entry = entry_for(name)
+          invoke_entry(entry, args)
+        end
+
+        # @param name [String, Symbol]
+        # @return [BuiltinRegistry::Entry]
+        def entry_for(name)
+          normalized = normalize_name(name)
+          overrides.fetch(normalized) { base_registry.entry_for(normalized) }
+        end
+
+        # @param name [String, Symbol]
+        # @return [Boolean]
+        def registered?(name)
+          normalized = normalize_name(name)
+          overrides.key?(normalized) || base_registry.registered?(normalized)
+        end
+
+        private
+
+        attr_reader :base_registry, :overrides
+      end
+    end
+  end
+end

data/lib/ruby/rego/builtins/registry_helpers.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Ruby
+  module Rego
+    module Builtins
+      # Shared helpers for registering builtin functions.
+      module RegistryHelpers
+        def register_configured_functions(registry, mapping)
+          mapping.each do |name, config|
+            register_configured_function(registry, name, config)
+          end
+        end
+
+        private
+
+        # :reek:FeatureEnvy
+        def register_configured_function(registry, name, config)
+          return if registry.registered?(name)
+
+          registry.register(name, config.fetch(:arity)) do |*args|
+            public_send(config.fetch(:handler), *args)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ruby/rego/builtins/strings/case_ops.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Ruby
+  module Rego
+    module Builtins
+      # Built-in string helpers.
+      module Strings
+        # @param string [Ruby::Rego::Value]
+        # @return [Ruby::Rego::StringValue]
+        def self.lower(string)
+          StringValue.new(string_value(string, context: "lower").downcase)
+        end
+
+        # @param string [Ruby::Rego::Value]
+        # @return [Ruby::Rego::StringValue]
+        def self.upper(string)
+          StringValue.new(string_value(string, context: "upper").upcase)
+        end
+      end
+    end
+  end
+end

data/lib/ruby/rego/builtins/strings/concat.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Ruby
+  module Rego
+    module Builtins
+      # Built-in string helpers.
+      module Strings
+        # @param delimiter [Ruby::Rego::Value]
+        # @param array [Ruby::Rego::Value]
+        # @return [Ruby::Rego::StringValue]
+        def self.concat(delimiter, array)
+          delimiter_string = string_value(delimiter, context: "concat delimiter")
+          parts = string_array(array, name: "concat")
+          StringValue.new(parts.join(delimiter_string))
+        end
+      end
+    end
+  end
+end

data/lib/ruby/rego/builtins/strings/formatting.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+# rubocop:disable Naming/RescuedExceptionsVariableName
+
+module Ruby
+  module Rego
+    module Builtins
+      # Built-in string helpers.
+      module Strings
+        # @param number [Ruby::Rego::Value]
+        # @param base [Ruby::Rego::Value]
+        # @return [Ruby::Rego::StringValue]
+        def self.format_int(number, base)
+          number_value = NumericHelpers.integer_value(number, context: "format_int number")
+          base_value = NumericHelpers.integer_value(base, context: "format_int base")
+          ensure_base(base_value)
+          StringValue.new(base_encode(number_value, base_value))
+        end
+
+        # @param format [Ruby::Rego::Value]
+        # @param args [Ruby::Rego::Value]
+        # @return [Ruby::Rego::StringValue]
+        def self.sprintf(format, args)
+          format_value = string_value(format, context: "sprintf format")
+          values = sprintf_values(args)
+          StringValue.new(Kernel.sprintf(format_value, *values))
+        rescue ArgumentError, ::TypeError => error
+          raise_sprintf_error(error)
+        end
+      end
+    end
+  end
+end
+
+# rubocop:enable Naming/RescuedExceptionsVariableName

data/lib/ruby/rego/builtins/strings/helpers.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Ruby
+  module Rego
+    module Builtins
+      # Built-in string helpers.
+      module Strings
+        BASE_DIGITS = %w[
+          0 1 2 3 4 5 6 7 8 9
+          a b c d e f g h i j
+          k l m n o p q r s t
+          u v w x y z
+        ].freeze
+
+        def self.string_value(value, context:)
+          Base.assert_type(value, expected: StringValue, context: context)
+          value.value
+        end
+        private_class_method :string_value
+
+        def self.array_values(value, name:)
+          Base.assert_type(value, expected: ArrayValue, context: name)
+          value.value
+        end
+        private_class_method :array_values
+
+        def self.string_array(value, name:)
+          array_values(value, name: name).map.with_index do |element, index|
+            Base.assert_type(element, expected: StringValue, context: "#{name} element #{index}")
+            element.value
+          end
+        end
+        private_class_method :string_array
+
+        # :reek:LongParameterList
+        def self.string_pair(left, right, left_context:, right_context:)
+          [
+            string_value(left, context: left_context),
+            string_value(right, context: right_context)
+          ]
+        end
+        private_class_method :string_pair
+
+        def self.sprintf_values(args)
+          array_values(args, name: "sprintf args").map { |value| Base.to_ruby(value) }
+        end
+        private_class_method :sprintf_values
+
+        def self.raise_sprintf_error(error)
+          raise Ruby::Rego::BuiltinArgumentError.new(
+            error.message,
+            expected: "sprintf-compatible arguments",
+            actual: error.class.name,
+            context: "sprintf",
+            location: nil
+          )
+        end
+        private_class_method :raise_sprintf_error
+      end
+    end
+  end
+end

data/lib/ruby/rego/builtins/strings/number_helpers.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Ruby
+  module Rego
+    module Builtins
+      # Built-in string helpers.
+      module Strings
+        def self.ensure_base(base_value)
+          return if base_value.between?(2, 36)
+
+          raise Ruby::Rego::BuiltinArgumentError.new(
+            "Invalid base",
+            expected: "base between 2 and 36",
+            actual: base_value,
+            context: "format_int",
+            location: nil
+          )
+        end
+        private_class_method :ensure_base
+
+        def self.base_encode(number_value, base_value)
+          return "0" if number_value.zero?
+
+          prefix = negative_prefix(number_value)
+          encoded = encode_digits(number_value.abs, base_value)
+          "#{prefix}#{encoded}"
+        end
+        private_class_method :base_encode
+
+        def self.negative_prefix(number_value)
+          number_value.negative? ? "-" : ""
+        end
+        private_class_method :negative_prefix
+
+        def self.encode_digits(remaining, base_value)
+          digits = [] # @type var digits: Array[String]
+          while remaining.positive?
+            digits << BASE_DIGITS.fetch(remaining % base_value)
+            remaining /= base_value
+          end
+
+          digits.reverse.join
+        end
+        private_class_method :encode_digits
+      end
+    end
+  end
+end

data/lib/ruby/rego/builtins/strings/search.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Ruby
+  module Rego
+    module Builtins
+      # Built-in string helpers.
+      module Strings
+        # @param haystack [Ruby::Rego::Value]
+        # @param needle [Ruby::Rego::Value]
+        # @return [Ruby::Rego::BooleanValue]
+        def self.contains(haystack, needle)
+          haystack_text, needle_text = string_pair(
+            haystack,
+            needle,
+            left_context: "contains haystack",
+            right_context: "contains needle"
+          )
+          BooleanValue.new(haystack_text.include?(needle_text))
+        end
+
+        # @param string [Ruby::Rego::Value]
+        # @param prefix [Ruby::Rego::Value]
+        # @return [Ruby::Rego::BooleanValue]
+        def self.startswith(string, prefix)
+          string_text, prefix_text = string_pair(
+            string,
+            prefix,
+            left_context: "startswith string",
+            right_context: "startswith prefix"
+          )
+          BooleanValue.new(string_text.start_with?(prefix_text))
+        end
+
+        # @param string [Ruby::Rego::Value]
+        # @param suffix [Ruby::Rego::Value]
+        # @return [Ruby::Rego::BooleanValue]
+        def self.endswith(string, suffix)
+          string_text, suffix_text = string_pair(
+            string,
+            suffix,
+            left_context: "endswith string",
+            right_context: "endswith suffix"
+          )
+          BooleanValue.new(string_text.end_with?(suffix_text))
+        end
+
+        # @param haystack [Ruby::Rego::Value]
+        # @param needle [Ruby::Rego::Value]
+        # @return [Ruby::Rego::NumberValue]
+        def self.indexof(haystack, needle)
+          haystack_text, needle_text = string_pair(
+            haystack,
+            needle,
+            left_context: "indexof haystack",
+            right_context: "indexof needle"
+          )
+          index = haystack_text.index(needle_text)
+          NumberValue.new(index || -1)
+        end
+      end
+    end
+  end
+end

data/lib/ruby/rego/builtins/strings/split.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Ruby
+  module Rego
+    module Builtins
+      # Built-in string helpers.
+      module Strings
+        # @param string [Ruby::Rego::Value]
+        # @param delimiter [Ruby::Rego::Value]
+        # @return [Ruby::Rego::ArrayValue]
+        def self.split(string, delimiter)
+          string_text = string_value(string, context: "split string")
+          delimiter_text = string_value(delimiter, context: "split delimiter")
+          ArrayValue.new(string_text.split(delimiter_text, -1))
+        end
+      end
+    end
+  end
+end

data/lib/ruby/rego/builtins/strings/substring.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Ruby
+  module Rego
+    module Builtins
+      # Built-in string helpers.
+      module Strings
+        # @param string [Ruby::Rego::Value]
+        # @param offset [Ruby::Rego::Value]
+        # @param length [Ruby::Rego::Value]
+        # @return [Ruby::Rego::StringValue]
+        def self.substring(string, offset, length)
+          string_text = string_value(string, context: "substring string")
+          offset_value = NumericHelpers.non_negative_integer(offset, context: "substring offset")
+          length_value = NumericHelpers.non_negative_integer(length, context: "substring length")
+          substring = string_text.slice(offset_value, length_value) || ""
+          StringValue.new(substring)
+        end
+      end
+    end
+  end
+end

data/lib/ruby/rego/builtins/strings/trim.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Ruby
+  module Rego
+    module Builtins
+      # Built-in string helpers.
+      module Strings
+        # @param string [Ruby::Rego::Value]
+        # @param cutset [Ruby::Rego::Value]
+        # @return [Ruby::Rego::StringValue]
+        def self.trim(string, cutset)
+          trim_with_cutset(string, cutset, { mode: :both, name: "trim" })
+        end
+
+        # @param string [Ruby::Rego::Value]
+        # @param cutset [Ruby::Rego::Value]
+        # @return [Ruby::Rego::StringValue]
+        def self.trim_left(string, cutset)
+          trim_with_cutset(string, cutset, { mode: :left, name: "trim_left" })
+        end
+
+        # @param string [Ruby::Rego::Value]
+        # @param cutset [Ruby::Rego::Value]
+        # @return [Ruby::Rego::StringValue]
+        def self.trim_right(string, cutset)
+          trim_with_cutset(string, cutset, { mode: :right, name: "trim_right" })
+        end
+
+        # @param string [Ruby::Rego::Value]
+        # @return [Ruby::Rego::StringValue]
+        def self.trim_space(string)
+          StringValue.new(string_value(string, context: "trim_space").strip)
+        end
+
+        def self.trim_with_cutset(string, cutset, context)
+          StringValue.new(trimmed_text(string, cutset, context))
+        end
+        private_class_method :trim_with_cutset
+      end
+    end
+  end
+end

data/lib/ruby/rego/builtins/strings/trim_helpers.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Ruby
+  module Rego
+    module Builtins
+      # Built-in string helpers.
+      module Strings
+        def self.trim_regex(cutset_text, mode:)
+          escaped = Regexp.escape(cutset_text)
+          Regexp.new(trim_patterns(escaped, mode).join("|"))
+        end
+        private_class_method :trim_regex
+
+        def self.trimmed_text(string, cutset, context)
+          name, mode = trim_context(context)
+          string_text, cutset_text = trim_inputs(string, cutset, name)
+          apply_trim_or_original(string_text, cutset_text, mode)
+        end
+        private_class_method :trimmed_text
+
+        def self.trim_context(context)
+          [context.fetch(:name), context.fetch(:mode)]
+        end
+        private_class_method :trim_context
+
+        def self.trim_inputs(string, cutset, name)
+          [
+            string_value(string, context: "#{name} string"),
+            string_value(cutset, context: "#{name} cutset")
+          ]
+        end
+        private_class_method :trim_inputs
+
+        def self.apply_trim_or_original(string_text, cutset_text, mode)
+          return string_text if cutset_text.empty?
+
+          apply_trim(string_text, cutset_text, mode)
+        end
+        private_class_method :apply_trim_or_original
+
+        def self.apply_trim(string_text, cutset_text, mode)
+          string_text.gsub(trim_regex(cutset_text, mode: mode), "")
+        end
+        private_class_method :apply_trim
+
+        def self.trim_patterns(escaped, mode)
+          case mode
+          when :left
+            ["\\A[#{escaped}]+"]
+          when :right
+            ["[#{escaped}]+\\z"]
+          when :both
+            ["\\A[#{escaped}]+", "[#{escaped}]+\\z"]
+          else
+            raise ArgumentError, "Unknown trim mode: #{mode}"
+          end
+        end
+        private_class_method :trim_patterns
+      end
+    end
+  end
+end

data/lib/ruby/rego/builtins/strings.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require_relative "base"
+require_relative "registry"
+require_relative "numeric_helpers"
+require_relative "registry_helpers"
+require_relative "strings/helpers"
+require_relative "strings/number_helpers"
+require_relative "strings/trim_helpers"
+require_relative "strings/concat"
+require_relative "strings/search"
+require_relative "strings/case_ops"
+require_relative "strings/formatting"
+require_relative "strings/split"
+require_relative "strings/substring"
+require_relative "strings/trim"
+
+module Ruby
+  module Rego
+    module Builtins
+      # Built-in string helpers.
+      module Strings
+        extend RegistryHelpers
+
+        STRING_FUNCTIONS = {
+          "concat" => { arity: 2, handler: :concat },
+          "contains" => { arity: 2, handler: :contains },
+          "startswith" => { arity: 2, handler: :startswith },
+          "endswith" => { arity: 2, handler: :endswith },
+          "format_int" => { arity: 2, handler: :format_int },
+          "indexof" => { arity: 2, handler: :indexof },
+          "lower" => { arity: 1, handler: :lower },
+          "upper" => { arity: 1, handler: :upper },
+          "split" => { arity: 2, handler: :split },
+          "sprintf" => { arity: 2, handler: :sprintf },
+          "substring" => { arity: 3, handler: :substring },
+          "trim" => { arity: 2, handler: :trim },
+          "trim_left" => { arity: 2, handler: :trim_left },
+          "trim_right" => { arity: 2, handler: :trim_right },
+          "trim_space" => { arity: 1, handler: :trim_space }
+        }.freeze
+
+        # @return [Ruby::Rego::Builtins::BuiltinRegistry]
+        def self.register!
+          registry = BuiltinRegistry.instance
+
+          register_configured_functions(registry, STRING_FUNCTIONS)
+
+          registry
+        end
+
+        private_class_method :register_configured_functions, :register_configured_function
+      end
+    end
+  end
+end
+
+Ruby::Rego::Builtins::Strings.register!