foxtail-runtime 0.5.0

data/lib/foxtail/function/datetime.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Foxtail
+  module Function
+    # Wraps a datetime value with formatting options
+    # The raw value is preserved for selector matching
+    class DateTime < Value
+      # Convert FTL/JS style datetime options to ICU4X options
+      # @param options [Hash] FTL/JS style options (camelCase)
+      # @return [Hash] ICU4X style options (snake_case with symbols)
+      def self.convert_options(options)
+        result = {}
+
+        options.each do |key, value|
+          case key
+          when :dateStyle
+            result[:date_style] = value.to_sym
+          when :timeStyle
+            result[:time_style] = value.to_sym
+          when :timeZone
+            result[:time_zone] = value.to_s
+          else
+            warn "Unknown DATETIME option: #{key}"
+          end
+        end
+
+        result
+      end
+
+      # Format the datetime using ICU4X
+      # @param bundle [Foxtail::Bundle] The bundle providing locale and context
+      # @return [String] The formatted datetime
+      def format(bundle:)
+        icu_options = self.class.convert_options(options)
+        ICU4XCache.instance.datetime_formatter(bundle.locale, **icu_options).format(value)
+      end
+    end
+  end
+end

data/lib/foxtail/function/number.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Foxtail
+  module Function
+    # Wraps a numeric value with formatting options
+    # The raw value is preserved for selector matching (plural rules)
+    class Number < Value
+      # Convert FTL/JS style number options to ICU4X options
+      # @param options [Hash] FTL/JS style options (camelCase)
+      # @return [Hash] ICU4X style options (snake_case with symbols)
+      def self.convert_options(options)
+        result = {}
+
+        options.each do |key, value|
+          case key
+          when :style
+            result[:style] = value.to_sym
+          when :currency
+            result[:currency] = value.to_s
+          when :minimumIntegerDigits
+            result[:minimum_integer_digits] = Integer(value)
+          when :minimumFractionDigits
+            result[:minimum_fraction_digits] = Integer(value)
+          when :maximumFractionDigits
+            result[:maximum_fraction_digits] = Integer(value)
+          when :useGrouping
+            result[:use_grouping] = value
+          else
+            warn "Unknown NUMBER option: #{key}"
+          end
+        end
+
+        result
+      end
+
+      # Format the number using ICU4X
+      # @param bundle [Foxtail::Bundle] The bundle providing locale and context
+      # @return [String] The formatted number
+      def format(bundle:)
+        icu_options = self.class.convert_options(options)
+        ICU4XCache.instance.number_formatter(bundle.locale, **icu_options).format(value)
+      end
+    end
+  end
+end

data/lib/foxtail/function/value.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Foxtail
+  module Function
+    Value = Data.define(:value, :options)
+
+    # Base class for deferred-formatting values
+    # Wraps a value with formatting options, deferring locale-specific formatting until display time
+    #
+    # @!attribute [r] value
+    #   @return [Object] The wrapped raw value
+    # @!attribute [r] options
+    #   @return [Hash] Formatting options
+    class Value
+      # Format the value for display
+      # Subclasses may override for locale-specific formatting
+      # @param bundle [Foxtail::Bundle] The bundle providing locale and context (unused in base implementation)
+      # @return [String] The formatted value
+      def format(**) = value.to_s
+
+      # String representation for interpolation
+      # @return [String] The string representation of the wrapped value
+      def to_s = value.to_s
+    end
+  end
+end

data/lib/foxtail/function.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Foxtail
+  # Built-in formatting functions for FTL
+  # Uses ICU4X for number and datetime formatting
+  module Function
+    # Default functions available to all bundles
+    # @return [Hash{String => #call}] Function name to callable object mapping
+    def self.defaults
+      {
+        "NUMBER" => ->(value, **options) {
+          # Unwrap value and merge options from nested function calls (like fluent.js)
+          raw_value, existing_options = unwrap_value(value)
+          unwrapped_options = unwrap_options(options)
+          Number[raw_value, existing_options.merge(unwrapped_options)]
+        },
+        "DATETIME" => ->(value, **options) {
+          # Unwrap value and merge options from nested function calls (like fluent.js)
+          raw_value, existing_options = unwrap_value(value)
+          unwrapped_options = unwrap_options(options)
+          DateTime[raw_value, existing_options.merge(unwrapped_options)]
+        }
+      }
+    end
+
+    # Unwrap a Function::Value to get raw value and options
+    # @param value [Object] the value to unwrap
+    # @return [Array(Object, Hash)] the raw value and options
+    def self.unwrap_value(value)
+      if value.is_a?(Value)
+        [value.value, value.options]
+      else
+        [value, {}]
+      end
+    end
+
+    # Unwrap option values that may be Function::Value instances
+    # @param options [Hash] the options hash
+    # @return [Hash] options with unwrapped values
+    def self.unwrap_options(options)
+      options.transform_values do |v|
+        v.is_a?(Value) ? v.value : v
+      end
+    end
+  end
+end

data/lib/foxtail/icu4x_cache.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require "dry/core/cache"
+require "singleton"
+
+module Foxtail
+  # Singleton cache for ICU4X formatter and rules instances.
+  #
+  # ICU4X formatters and rules internally load and parse locale data,
+  # making instance creation non-trivial. This cache stores instances
+  # keyed by locale and options to avoid repeated instantiation.
+  #
+  # Thread safety is provided by Dry::Core::Cache, which uses
+  # Concurrent::Map internally.
+  #
+  # @example
+  #   cache = Foxtail::ICU4XCache.instance
+  #   formatter = cache.number_formatter(locale)
+  #   formatter.format(1234)  #=> "1,234"
+  class ICU4XCache
+    extend Dry::Core::Cache
+    include Singleton
+
+    # Returns a cached ICU4X::NumberFormat instance.
+    #
+    # @param locale [ICU4X::Locale] The locale for formatting
+    # @param options [Hash] Formatting options passed to ICU4X::NumberFormat.new
+    # @return [ICU4X::NumberFormat] Cached formatter instance
+    def number_formatter(locale, **options)
+      self.class.fetch_or_store(:number_formatter, locale, options) do
+        ICU4X::NumberFormat.new(locale, **options)
+      end
+    end
+
+    # Returns a cached ICU4X::DateTimeFormat instance.
+    #
+    # @param locale [ICU4X::Locale] The locale for formatting
+    # @param options [Hash] Formatting options passed to ICU4X::DateTimeFormat.new
+    # @return [ICU4X::DateTimeFormat] Cached formatter instance
+    def datetime_formatter(locale, **options)
+      self.class.fetch_or_store(:datetime_formatter, locale, options) do
+        ICU4X::DateTimeFormat.new(locale, **options)
+      end
+    end
+
+    # Returns a cached ICU4X::PluralRules instance.
+    #
+    # @param locale [ICU4X::Locale] The locale for plural rules
+    # @param type [Symbol] Plural rule type (:cardinal or :ordinal)
+    # @return [ICU4X::PluralRules] Cached rules instance
+    def plural_rules(locale, type: :cardinal)
+      self.class.fetch_or_store(:plural_rules, locale, type) do
+        ICU4X::PluralRules.new(locale, type:)
+      end
+    end
+  end
+end

data/lib/foxtail/resource.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module Foxtail
+  # Container for parsed FTL entries (messages and terms).
+  #
+  # Created via {.from_string} or {.from_file}, which use the runtime parser
+  # ({Bundle::Parser}) optimized for performance with error recovery.
+  # Invalid entries are silently skipped; comments are not preserved.
+  #
+  # For full AST with source positions, comments, and error details,
+  # use {Syntax::Parser} instead.
+  class Resource
+    include Enumerable
+
+    # @return [Array<Bundle::Parser::AST::Message, Bundle::Parser::AST::Term>] Parsed FTL entries (messages and terms)
+    attr_reader :entries
+
+    # Parse FTL source string into a Resource
+    #
+    # @param source [String] FTL source text to parse
+    # @return [Foxtail::Resource] New resource with parsed entries
+    #
+    # @example Parse FTL content
+    #   source = <<~FTL
+    #     hello = Hello, {$name}!
+    #     goodbye = Goodbye!
+    #   FTL
+    #   resource = Foxtail::Resource.from_string(source)
+    # @raise [ArgumentError] if source is not a String
+    def self.from_string(source)
+      raise ArgumentError, "source must be a String, got #{source.class}" unless source.is_a?(String)
+
+      parser = Bundle::Parser.new
+      entries = parser.parse(source)
+
+      new(entries)
+    end
+
+    # Parse FTL file into a Resource
+    #
+    # @param path [Pathname] Path to FTL file
+    # @return [Foxtail::Resource] New resource with parsed entries
+    def self.from_file(path)
+      source = path.read
+      from_string(source)
+    end
+
+    def initialize(entries)
+      @entries = entries
+    end
+
+    private_class_method :new
+
+    # Check if resource has any entries
+    # @return [Boolean]
+    def empty? = @entries.empty?
+
+    # Get the number of entries
+    # @return [Integer]
+    def size = @entries.size
+
+    # Iterate over entries
+    # @return [self]
+    def each(&)
+      @entries.each(&)
+      self
+    end
+
+    # Get message entries (IDs not starting with "-")
+    # @return [Array<Bundle::Parser::AST::Message>]
+    def messages = @entries.select {|entry| entry.id && !entry.id.start_with?("-") }
+
+    # Get term entries (IDs starting with "-")
+    # @return [Array<Bundle::Parser::AST::Term>]
+    def terms = @entries.select {|entry| entry.id&.start_with?("-") }
+
+    # Find entry by ID
+    # @return [Bundle::Parser::AST::Message, Bundle::Parser::AST::Term, nil]
+    def find(id) = @entries.find {|entry| entry.id == id }
+  end
+end

data/lib/foxtail/runtime/version.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Foxtail
+  module Runtime
+    # Current version of the Foxtail runtime gem
+    VERSION = "0.5.0"
+    public_constant :VERSION
+  end
+end

data/lib/foxtail/sequence.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Foxtail
+  # Manages ordered sequences of Bundles for language fallback.
+  #
+  # @example Basic usage
+  #   sequence = Foxtail::Sequence.new(bundle_en_us, bundle_en, bundle_default)
+  #   sequence.format("hello", name: "World")
+  #
+  # @example Finding the bundle that contains a message
+  #   bundle = sequence.find("hello")
+  #   puts "Using locale: #{bundle.locale}" if bundle
+  #
+  # @see https://projectfluent.org/fluent.js/sequence/
+  class Sequence
+    # Creates a new Sequence with the given bundles.
+    #
+    # @param bundles [Array<Bundle>] Bundles in priority order (first = highest priority)
+    def initialize(*bundles)
+      @bundles = bundles.flatten.freeze
+    end
+
+    # Finds the first bundle that contains a message with the given ID(s).
+    #
+    # @param ids [Array<String>] One or more message IDs to find
+    # @return [Bundle, nil] The first bundle containing the message (single ID)
+    # @return [Array<Bundle, nil>] Array of bundles for each ID (multiple IDs)
+    def find(*ids)
+      if ids.size == 1
+        find_bundle(ids.first)
+      else
+        ids.map {|id| find_bundle(id) }
+      end
+    end
+
+    # Formats a message using the first bundle that contains it.
+    # Keyword arguments are passed through to the bundle's format method.
+    #
+    # @param id [String] The message ID
+    # @param errors [Array, nil] If provided, errors are collected into this array instead of being ignored.
+    # @return [String] The formatted message, or the ID if not found
+    def format(id, errors=nil, **)
+      bundle = find_bundle(id)
+      bundle ? bundle.format(id, errors, **) : id.to_s
+    end
+
+    private def find_bundle(id) = @bundles.find {|bundle| bundle.message?(id) }
+  end
+end

data/lib/foxtail-runtime.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require "icu4x"
+require "zeitwerk"
+require_relative "foxtail/runtime/version"
+
+# Ruby implementation of Project Fluent localization system
+module Foxtail
+  # Configure Zeitwerk loader for this gem
+  loader = Zeitwerk::Loader.new
+  loader.push_dir(__dir__ + "/foxtail", namespace: Foxtail)
+
+  # Ignore version.rb since it's required by gemspec before Zeitwerk loads
+  loader.ignore(__dir__ + "/foxtail/runtime/version.rb")
+  # Ignore gem entrypoint file (no constant defined)
+  loader.ignore(__dir__ + "/foxtail.rb")
+  loader.ignore(__dir__ + "/foxtail-runtime.rb")
+
+  # Configure inflections for acronyms
+  loader.inflector.inflect(
+    "ast" => "AST",
+    "datetime" => "DateTime",
+    "icu4x_cache" => "ICU4XCache"
+  )
+
+  loader.setup
+end

data/lib/foxtail.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require "foxtail-runtime"

metadata

@@ -0,0 +1,125 @@
+--- !ruby/object:Gem::Specification
+name: foxtail-runtime
+version: !ruby/object:Gem::Version
+  version: 0.5.0
+platform: ruby
+authors:
+- OZAWA Sakuro
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-05-08 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bigdecimal
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.1'
+- !ruby/object:Gem::Dependency
+  name: dry-core
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.1'
+- !ruby/object:Gem::Dependency
+  name: icu4x
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+- !ruby/object:Gem::Dependency
+  name: zeitwerk
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.7'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.7'
+description: 'Runtime components for Foxtail: bundle parsing, message formatting,
+  and ICU4X integration.
+
+  '
+email:
+- 10973+sakuro@users.noreply.github.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/foxtail-runtime.rb
+- lib/foxtail.rb
+- lib/foxtail/bundle.rb
+- lib/foxtail/bundle/parser.rb
+- lib/foxtail/bundle/parser/ast.rb
+- lib/foxtail/bundle/resolver.rb
+- lib/foxtail/bundle/scope.rb
+- lib/foxtail/error.rb
+- lib/foxtail/function.rb
+- lib/foxtail/function/datetime.rb
+- lib/foxtail/function/number.rb
+- lib/foxtail/function/value.rb
+- lib/foxtail/icu4x_cache.rb
+- lib/foxtail/resource.rb
+- lib/foxtail/runtime/version.rb
+- lib/foxtail/sequence.rb
+homepage: https://github.com/sakuro/foxtail
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/sakuro/foxtail
+  source_code_uri: https://github.com/sakuro/foxtail.git
+  changelog_uri: https://github.com/sakuro/foxtail/blob/main/foxtail-runtime/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.3'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Foxtail runtime for Project Fluent localization
+test_files: []