foxtail-runtime 0.5.0

data/lib/foxtail/bundle/resolver.rb

@@ -0,0 +1,444 @@
+# frozen_string_literal: true
+
+require "bigdecimal"
+
+module Foxtail
+  class Bundle
+    # Pattern resolution engine
+    # Corresponds to fluent-bundle/src/resolver.ts
+    class Resolver
+      # Unicode bidi isolation characters
+      FSI = "\u2068" # First Strong Isolate
+      private_constant :FSI
+
+      PDI = "\u2069" # Pop Directional Isolate
+      private_constant :PDI
+
+      def initialize(bundle) = @bundle = bundle
+
+      # Resolve a pattern with the given scope
+      def resolve_pattern(pattern, scope)
+        case pattern
+        when String
+          pattern
+        when Array
+          resolve_complex_pattern(pattern, scope)
+        else
+          raise ArgumentError, "Unexpected pattern type: #{pattern.class}"
+        end
+      end
+
+      # Resolve a complex pattern (array of elements)
+      def resolve_complex_pattern(elements, scope)
+        # Apply bidi isolation only when use_isolating is true and pattern has multiple elements
+        use_isolating = @bundle.use_isolating? && elements.size > 1
+
+        elements.map {|element| resolve_pattern_element(element, scope, use_isolating:) }.join
+      end
+
+      # Resolve individual pattern elements
+      def resolve_pattern_element(element, scope, use_isolating: false)
+        case element
+        when String
+          # Text elements are not wrapped with isolation marks
+          element
+        when Parser::AST::NumberLiteral
+          result = resolve_expression(element, scope)
+          # For numeric values in patterns, format for display
+          formatted = element.precision > 0 ? format_number(result, element.precision) : result.to_s
+          wrap_with_isolation(formatted, use_isolating)
+        when Parser::AST::VariableReference
+          # Apply implicit NUMBER/DATETIME formatting for variables at display time
+          result = resolve_expression(element, scope)
+          formatted = apply_implicit_function(result)
+          wrap_with_isolation(format_value(formatted), use_isolating)
+        when Parser::AST::FunctionReference
+          # Function results are Function::Value objects that need formatting
+          result = resolve_expression(element, scope)
+          wrap_with_isolation(format_value(result), use_isolating)
+        when Parser::AST::StringLiteral, Parser::AST::TermReference,
+             Parser::AST::MessageReference, Parser::AST::SelectExpression
+
+          result = resolve_expression(element, scope)
+          wrap_with_isolation(result.to_s, use_isolating)
+        else
+          wrap_with_isolation(element.to_s, use_isolating)
+        end
+      end
+
+      # Resolve expressions (variables, terms, messages, functions, etc.)
+      def resolve_expression(expr, scope)
+        case expr
+        when Parser::AST::StringLiteral
+          expr.value.to_s
+        when Parser::AST::NumberLiteral
+          # Return raw numeric value, not formatted string
+          expr.value
+        when Parser::AST::VariableReference
+          resolve_variable_reference(expr, scope)
+        when Parser::AST::TermReference
+          resolve_term_reference(expr, scope)
+        when Parser::AST::MessageReference
+          resolve_message_reference(expr, scope)
+        when Parser::AST::FunctionReference
+          resolve_function_call(expr, scope)
+        when Parser::AST::SelectExpression
+          resolve_select_expression(expr, scope)
+        else
+          scope.add_error("Unknown expression type: #{expr.class}")
+          "{#{expr.class}}"
+        end
+      end
+
+      private def format_number(value, precision=nil)
+        if precision && precision > 0
+          # Format with specified precision
+          "%.#{precision}f" % value
+        elsif value != Integer(value)
+          # Float without precision - keep as is
+          value.to_s
+        else
+          # Integer - format without decimal point
+          Integer(value).to_s
+        end
+      end
+
+      # Format a value for display
+      # Function::Value objects are formatted with the bundle
+      private def format_value(value)
+        case value
+        when Function::Value
+          value.format(bundle: @bundle)
+        else
+          value.to_s
+        end
+      end
+
+      private def wrap_with_isolation(value, use_isolating)
+        use_isolating ? "#{FSI}#{value}#{PDI}" : value
+      end
+
+      # Resolve variable references
+      # Returns raw value; implicit formatting is applied at display time
+      private def resolve_variable_reference(expr, scope)
+        name = expr.name
+
+        value = scope.variable(name)
+
+        if value.nil?
+          scope.add_error("Unknown variable: $#{name}")
+          "{$#{name}}"
+        else
+          value
+        end
+      end
+
+      # Apply implicit function based on value type
+      # Returns formatted string for numeric/time types, raw value otherwise
+      private def apply_implicit_function(value)
+        if implicit_number_type?(value)
+          apply_implicit_number(value)
+        elsif implicit_datetime_type?(value)
+          apply_implicit_datetime(value)
+        else
+          value
+        end
+      end
+
+      # Check if value should have NUMBER implicitly applied
+      private def implicit_number_type?(value) = value.is_a?(Integer) || value.is_a?(Float) || value.is_a?(BigDecimal)
+
+      # Check if value should have DATETIME implicitly applied
+      private def implicit_datetime_type?(value) = value.is_a?(Time) || value.respond_to?(:to_time)
+
+      # Apply NUMBER function implicitly
+      private def apply_implicit_number(value)
+        func = @bundle.functions["NUMBER"]
+        return value unless func
+
+        func.call(value)
+      end
+
+      # Apply DATETIME function implicitly
+      private def apply_implicit_datetime(value)
+        func = @bundle.functions["DATETIME"]
+        return value unless func
+
+        func.call(value)
+      end
+
+      # Resolve term references
+      private def resolve_term_reference(expr, scope)
+        name = expr.name
+        attr = expr.attr
+
+        # Circular reference check
+        unless scope.track(name)
+          return "{-#{name}}"
+        end
+
+        term = @bundle.term("-#{name}")
+
+        if term.nil?
+          scope.add_error("Unknown term: -#{name}")
+          scope.release(name)
+          return "{-#{name}}"
+        end
+
+        # Resolve term value
+        if attr
+          result = resolve_term_attribute(term, attr, scope)
+        elsif term.value
+          result = resolve_pattern(term.value, scope)
+        else
+          scope.add_error("No value: -#{name}")
+          result = "{-#{name}}"
+        end
+
+        scope.release(name)
+        result
+      end
+
+      # Resolve message references
+      private def resolve_message_reference(expr, scope)
+        name = expr.name
+        attr = expr.attr
+
+        # Circular reference check
+        unless scope.track(name)
+          return "{#{name}}"
+        end
+
+        message = @bundle.message(name)
+
+        if message.nil?
+          scope.add_error("Unknown message: #{name}")
+          scope.release(name)
+          return "{#{name}}"
+        end
+
+        # Resolve message value
+        if attr
+          result = resolve_message_attribute(message, attr, scope)
+        elsif message.value
+          result = resolve_pattern(message.value, scope)
+        else
+          scope.add_error("No value: #{name}")
+          result = "{#{name}}"
+        end
+
+        scope.release(name)
+        result
+      end
+
+      # Resolve function calls
+      private def resolve_function_call(expr, scope)
+        func_name = expr.name
+        args = expr.args || []
+
+        func = @bundle.functions[func_name]
+
+        if func.nil?
+          scope.add_error("Unknown function: #{func_name}")
+          return "{#{func_name}()}"
+        end
+
+        # Check if any arguments failed to resolve (contain error markers)
+        initial_error_count = scope.errors.length
+
+        # Process arguments: first arg is positional, rest are named args (narg)
+        positional_args = []
+        options = {}
+
+        args.each do |arg|
+          case arg
+          when Parser::AST::NamedArgument
+            # Named argument - add to options hash
+            key = arg.name.to_sym
+            value = resolve_expression(arg.value, scope)
+            options[key] = value
+          else
+            # Positional argument
+            positional_args << resolve_expression(arg, scope)
+          end
+        end
+
+        # If arguments resolution generated errors, fail the entire function call
+        if scope.errors.length > initial_error_count
+          arg_list = args.map {|arg|
+            case arg
+            when Parser::AST::VariableReference then "$#{arg.name}"
+            when Parser::AST::NamedArgument then "#{arg.name}: #{arg.value}"
+            else arg.to_s
+            end
+          }.join(", ")
+          return "{#{func_name}(#{arg_list})}"
+        end
+
+        begin
+          # Create child scope for function execution
+          scope.child_scope
+
+          # Normalize arguments to Function::Value
+          normalized_args = positional_args.map {|arg| wrap_as_value(arg) }
+          normalized_opts = options.transform_values {|v| wrap_as_value(v) }
+
+          func.call(*normalized_args, **normalized_opts)
+        rescue => e
+          scope.add_error("Function error in #{func_name}: #{e.message}")
+          "{#{func_name}()}"
+        end
+      end
+
+      # Resolve select expressions
+      private def resolve_select_expression(expr, scope)
+        selector = expr.selector
+        variants = expr.variants
+        star_index = expr.star || 0
+
+        # Resolve selector value
+        selector_value = resolve_expression(selector, scope)
+
+        # Find matching variant
+        selected_variant = find_matching_variant(variants, selector_value, scope)
+
+        # Use default variant if no match
+        if selected_variant.nil? && star_index && star_index < variants.length
+          selected_variant = variants[star_index]
+        end
+
+        if selected_variant
+          resolve_pattern(selected_variant.value, scope)
+        else
+          scope.add_error("No variant found for selector: #{selector_value}")
+          selector_value.to_s
+        end
+      end
+
+      # Find a matching variant for the selector value
+      private def find_matching_variant(variants, selector_value, scope)
+        variants.find do |variant|
+          key = variant.key
+          key_value = resolve_expression(key, scope)
+
+          case key
+          when Parser::AST::NumberLiteral
+            # Numeric comparison
+            # If precision is 0, compare as integers
+            # Otherwise compare as floats
+            actual_selector = selector_value.is_a?(Function::Number) ? selector_value.value : selector_value
+            if actual_selector.is_a?(Numeric) && key_value.is_a?(Numeric)
+              if key.precision == 0
+                # Integer comparison when precision is 0
+                Integer(key_value) == Integer(actual_selector)
+              else
+                # Float comparison when precision > 0
+                key_value == actual_selector
+              end
+            else
+              # Fallback to string comparison if not both numeric
+              key_value.to_s == actual_selector.to_s
+            end
+          when Parser::AST::StringLiteral
+            # String comparison - check for ICU plural category match
+            if numeric_selector?(selector_value)
+              # Try ICU plural rules matching first
+              plural_category_match?(key_value, selector_value, scope) ||
+                # Fall back to direct string comparison
+                key_value.to_s == selector_value.to_s
+            else
+              # Direct string comparison for non-numeric selectors
+              key_value.to_s == selector_value.to_s
+            end
+          else
+            # General comparison
+            key_value == selector_value
+          end
+        end
+      end
+
+      # Check if selector value is numeric for plural rules processing
+      private def numeric_selector?(value)
+        value.is_a?(Numeric) ||
+          value.is_a?(Function::Number) ||
+          (value.is_a?(String) && value.match?(/^\d+(\.\d+)?$/))
+      end
+
+      # Check if key matches selector via ICU plural rules
+      private def plural_category_match?(key_str, selector_value, scope)
+        # Convert selector to numeric if needed
+        numeric_value =
+          case selector_value
+          when Numeric
+            selector_value
+          when Function::Number
+            selector_value.value
+          when String
+            if selector_value.match?(/^\d+$/)
+              Integer(selector_value)
+            elsif selector_value.match?(/^\d+\.\d+$/)
+              Float(selector_value)
+            else
+              return false
+            end
+          else
+            return false
+          end
+
+        # Use bundle's locale for plural rules
+        plural_rules = ICU4XCache.instance.plural_rules(@bundle.locale)
+        plural_category = plural_rules.select(numeric_value).to_s
+        key_str.to_s == plural_category
+      rescue => e
+        scope.add_error("Plural rule error: #{e.message}")
+        false
+      end
+
+      # Resolve term attributes
+      private def resolve_term_attribute(term, attr, scope)
+        attributes = term.attributes || {}
+        attr_pattern = attributes[attr]
+
+        if attr_pattern
+          resolve_pattern(attr_pattern, scope)
+        else
+          scope.add_error("Unknown term attribute: #{term.id}.#{attr}")
+          "{#{term.id}.#{attr}}"
+        end
+      end
+
+      # Resolve message attributes
+      private def resolve_message_attribute(message, attr, scope)
+        attributes = message.attributes || {}
+        attr_pattern = attributes[attr]
+
+        if attr_pattern
+          resolve_pattern(attr_pattern, scope)
+        else
+          scope.add_error("Unknown message attribute: #{message.id}.#{attr}")
+          "{#{message.id}.#{attr}}"
+        end
+      end
+
+      # Wrap a value as Function::Value for consistent function argument handling
+      # @param value [Object] the value to wrap
+      # @return [Function::Value] the wrapped value
+      private def wrap_as_value(value)
+        case value
+        when Function::Value
+          value
+        when Numeric
+          Function::Number[value, {}]
+        when Time
+          Function::DateTime[value, {}]
+        else
+          if value.respond_to?(:to_time)
+            Function::DateTime[value, {}]
+          else
+            Function::Value[value, {}]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/foxtail/bundle/scope.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Foxtail
+  class Bundle
+    # Variable scope and state management during resolution
+    # Corresponds to fluent-bundle/src/scope.ts
+    class Scope
+      attr_reader :bundle
+      attr_reader :args
+      attr_reader :locals
+      attr_reader :errors
+      attr_reader :dirty
+
+      def initialize(bundle, **args)
+        @bundle = bundle
+        @args = args      # External variables passed to format()
+        @locals = {}      # Local variables (set within functions)
+        @errors = []      # Error collection during resolution
+        @dirty = Set.new  # Circular reference detection (message/term IDs)
+      end
+
+      # Get a variable value (checks locals first, then args)
+      def variable(name) = @locals[name.to_sym] || @args[name.to_sym]
+
+      # Set a local variable (used within functions)
+      def set_local(name, value) = @locals[name.to_sym] = value
+
+      # Track a message/term ID to detect circular references
+      def track(id)
+        if @dirty.include?(id)
+          add_error("Circular reference detected: #{id}")
+          return false
+        end
+
+        @dirty.add(id)
+        true
+      end
+
+      # Release tracking of a message/term ID
+      def release(id) = @dirty.delete(id)
+
+      # Add an error to the collection
+      def add_error(message) = @errors << message
+
+      # Check if an ID is currently being tracked (circular reference check)
+      def tracking?(id) = @dirty.include?(id)
+
+      # Create a child scope (for function calls)
+      def child_scope(**)
+        child = self.class.new(@bundle, **@args, **)
+        child.instance_variable_set(:@locals, @locals.dup)
+        child.instance_variable_set(:@dirty, @dirty.dup)
+        child
+      end
+
+      # Reset locals (used in some resolution contexts)
+      def clear_locals = @locals.clear
+
+      # Get all available variables (locals + args)
+      def all_variables = @args.merge(@locals)
+    end
+  end
+end

data/lib/foxtail/bundle.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+module Foxtail
+  # Main runtime class for message formatting and localization.
+  #
+  # Bundle manages a collection of messages and terms for a single locale,
+  # providing formatting capabilities with support for pluralization,
+  # variable interpolation, and function calls.
+  #
+  # ICU4X handles locale fallback internally through the locale's parent chain
+  # (e.g., ja-JP → ja → und), so only a single locale is needed.
+  #
+  # @example Basic usage
+  #   locale = ICU4X::Locale.parse("en-US")
+  #   bundle = Foxtail::Bundle.new(locale)
+  #
+  #   resource = Foxtail::Resource.from_string("hello = Hello, {$name}!")
+  #   bundle.add_resource(resource)
+  #
+  #   result = bundle.format("hello", name: "World")
+  #   # => "Hello, World!"
+  #
+  # @example With custom functions (auto-merged with defaults)
+  #   bundle = Foxtail::Bundle.new(locale, functions: {
+  #     "UPPER" => ->(str, **_opts) { str.upcase }
+  #   })
+  #
+  # Corresponds to fluent-bundle/src/bundle.ts in the original JavaScript implementation.
+  class Bundle
+    # @return [ICU4X::Locale] The locale for this bundle
+    attr_reader :locale
+    # @return [Hash{String => Bundle::Parser::AST::Message}] Message entries indexed by ID
+    attr_reader :messages
+    # @return [Hash{String => Bundle::Parser::AST::Term}] Term entries indexed by ID
+    attr_reader :terms
+    # @return [Hash{String => #call}] Custom formatting functions
+    attr_reader :functions
+    # @return [#call, nil] Optional message transformation function
+    attr_reader :transform
+
+    # Create a new Bundle instance.
+    #
+    # @param locale [ICU4X::Locale] The locale for this bundle
+    # @param functions [Hash{String => #call}] Custom formatting functions (defaults to NUMBER and DATETIME)
+    # @param use_isolating [Boolean] Whether to use Unicode bidi isolation marks for placeables (default: true)
+    # @param transform [#call, nil] Optional message transformation function (not currently implemented)
+    # @raise [ArgumentError] if locale is not an ICU4X::Locale instance
+    #
+    # @example Basic bundle creation
+    #   locale = ICU4X::Locale.parse("en-US")
+    #   bundle = Foxtail::Bundle.new(locale)
+    def initialize(locale, functions: {}, use_isolating: true, transform: nil)
+      raise ArgumentError, "locale must be an ICU4X::Locale instance, got: #{locale.class}" unless locale.is_a?(ICU4X::Locale)
+
+      @locale = locale
+      @messages = {}  # id → Bundle::Parser::AST Message
+      @terms = {}     # id → Bundle::Parser::AST Term
+      @functions = Function.defaults.merge(functions).freeze
+      @use_isolating = use_isolating
+      @transform = transform
+    end
+
+    # @return [Boolean] Whether to use Unicode bidi isolation marks
+    def use_isolating? = @use_isolating
+
+    # Add a resource to this bundle
+    #
+    # @param resource [Resource] The resource to add
+    # @param allow_overrides [Boolean] Whether to allow overriding existing messages/terms
+    # @return [self] Returns self for method chaining
+    def add_resource(resource, allow_overrides: false)
+      resource.entries.each do |entry|
+        # In fluent-bundle format, terms have '-' prefix in id
+        if entry.id&.start_with?("-")
+          add_term_entry(entry, allow_overrides)
+        else
+          add_message_entry(entry, allow_overrides)
+        end
+      end
+
+      self
+    end
+
+    # Check if a message exists
+    # @return [Boolean]
+    def message?(id) = @messages.key?(id.to_s)
+
+    # Get a message by ID
+    # @return [Bundle::Parser::AST::Message, nil]
+    def message(id) = @messages[id.to_s]
+
+    # Check if a term exists (private method in fluent-bundle)
+    # @return [Boolean]
+    def term?(id) = @terms.key?(id.to_s)
+
+    # Get a term by ID (private method in fluent-bundle)
+    # @return [Bundle::Parser::AST::Term, nil]
+    def term(id) = @terms[id.to_s]
+
+    # Format a message with the given arguments.
+    # Keyword arguments are substituted into the message as variables.
+    #
+    # @param id [String, Symbol] Message identifier to format
+    # @param errors [Array, nil] If provided, errors are collected into this array instead of being ignored.
+    # @return [String] Formatted message string, or the id itself if message not found
+    #
+    # @example Basic message formatting
+    #   bundle.format("hello", name: "Alice")
+    #   # => "Hello, Alice!" (assuming message: hello = Hello, {$name}!)
+    #
+    # @example Pluralization
+    #   bundle.format("emails", count: 1)
+    #   # => "You have one email." (assuming plural message)
+    #
+    # @example With error collection
+    #   errors = []
+    #   bundle.format("hello", errors, name: "Alice")
+    #   # errors will contain any resolution errors
+    def format(id, errors=nil, **)
+      message = message(id)
+      return id.to_s unless message
+
+      format_pattern(message.value, errors, **)
+    end
+
+    # Format a pattern with the given arguments (using Resolver)
+    #
+    # @param pattern [String, Array] The pattern to format
+    # @param errors [Array, nil] If provided, errors are collected into this array
+    # @return [String] Formatted result
+    def format_pattern(pattern, errors=nil, **)
+      scope = Scope.new(self, **)
+      resolver = Resolver.new(self)
+      result = resolver.resolve_pattern(pattern, scope)
+
+      # Copy errors to provided array if given
+      errors&.concat(scope.errors)
+
+      result
+    end
+
+    private def add_message_entry(entry, allow_overrides)
+      id = entry.id
+      if @messages.key?(id) && !allow_overrides
+        # In full implementation, would add to errors
+        return
+      end
+
+      @messages[id] = entry
+    end
+
+    private def add_term_entry(entry, allow_overrides)
+      id = entry.id
+      if @terms.key?(id) && !allow_overrides
+        # In full implementation, would add to errors
+        return
+      end
+
+      @terms[id] = entry
+    end
+  end
+end

data/lib/foxtail/error.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module Foxtail
+  # Base error class for all Foxtail-specific exceptions
+  class Error < StandardError; end
+end