i18n-message_format 0.1.0

data/lib/i18n/message_format/parser.rb

@@ -0,0 +1,328 @@
+# frozen_string_literal: true
+
+module I18n
+  module MessageFormat
+    # Raised when {Parser} encounters a syntax error in a message format pattern.
+    class ParseError < Error
+      # The zero-based character position in the pattern where the error occurred.
+      #
+      # @return [Integer, nil]
+      attr_reader :position
+
+      # @param message [String] human-readable description of the parse error
+      # @param position [Integer, nil] zero-based position in the pattern string
+      def initialize(message, position = nil)
+        @position = position
+        super(position ? "#{message} at position #{position}" : message)
+      end
+    end
+
+    # Parses an ICU MessageFormat pattern string into an AST.
+    #
+    # The parser understands the following ICU constructs:
+    #
+    # * Simple argument: +{name}+
+    # * Number format: +{name, number}+ / +{name, number, style}+
+    # * Date format: +{name, date}+ / +{name, date, style}+
+    # * Time format: +{name, time}+ / +{name, time, style}+
+    # * Plural: +{name, plural, one {…} other {…}}+
+    # * Select: +{name, select, foo {…} other {…}}+
+    # * Select ordinal: +{name, selectordinal, one {…} other {…}}+
+    # * Quoted literals using single quotes (+'+)
+    #
+    # The produced AST is a flat array of {Nodes} objects.
+    #
+    # @example
+    #   nodes = I18n::MessageFormat::Parser.new("Hello, {name}!").parse
+    #   # => [#<TextNode value="Hello, ">, #<ArgumentNode name="name">, #<TextNode value="!">]
+    class Parser
+      # Creates a new parser for the given pattern string.
+      #
+      # @param pattern [String] the ICU MessageFormat pattern to parse
+      def initialize(pattern)
+        @pattern = pattern
+        @pos = 0
+      end
+
+      # Parses the pattern and returns its AST representation.
+      #
+      # @return [Array<Nodes::TextNode, Nodes::ArgumentNode, Nodes::NumberFormatNode,
+      #   Nodes::DateFormatNode, Nodes::TimeFormatNode, Nodes::PluralNode,
+      #   Nodes::SelectNode, Nodes::SelectOrdinalNode>]
+      # @raise [ParseError] if the pattern contains a syntax error
+      def parse
+        nodes = parse_message
+        nodes
+      end
+
+      private
+
+      def parse_message(terminate_on = nil)
+        nodes = []
+
+        until eof?
+          char = current_char
+
+          if terminate_on&.include?(char)
+            break
+          elsif char == "{"
+            @pos += 1
+            nodes << parse_argument
+          elsif char == "}"
+            raise ParseError.new("Unexpected }", @pos)
+          elsif char == "'"
+            nodes << parse_quoted_or_literal(nodes)
+          else
+            nodes << parse_text(terminate_on)
+          end
+        end
+
+        merge_adjacent_text(nodes)
+      end
+
+      def parse_text(terminate_on = nil)
+        start = @pos
+        while !eof? && current_char != "{" && current_char != "}" && current_char != "'" && !terminate_on&.include?(current_char)
+          @pos += 1
+        end
+        Nodes::TextNode.new(@pattern[start...@pos])
+      end
+
+      def parse_quoted_or_literal(preceding_nodes)
+        @pos += 1 # skip opening quote
+
+        if eof?
+          Nodes::TextNode.new("'")
+        elsif current_char == "'"
+          # '' => literal single quote
+          @pos += 1
+          Nodes::TextNode.new("'")
+        elsif current_char == "{" || current_char == "}"
+          # '{ or '} => literal brace, read until closing quote or end
+          text = +""
+          while !eof? && current_char != "'"
+            text << current_char
+            @pos += 1
+          end
+          @pos += 1 unless eof? # skip closing quote
+          Nodes::TextNode.new(text)
+        else
+          # standalone quote, treat as literal
+          Nodes::TextNode.new("'")
+        end
+      end
+
+      def parse_argument
+        skip_whitespace
+        name = parse_identifier
+        skip_whitespace
+
+        if eof?
+          raise ParseError.new("Unclosed argument", @pos)
+        end
+
+        if current_char == "}"
+          @pos += 1
+          return Nodes::ArgumentNode.new(name)
+        end
+
+        if current_char == ","
+          @pos += 1
+          skip_whitespace
+          return parse_typed_argument(name)
+        end
+
+        raise ParseError.new("Expected ',' or '}' in argument", @pos)
+      end
+
+      def parse_typed_argument(name)
+        type = parse_identifier
+        skip_whitespace
+
+        case type
+        when "number"
+          parse_number_arg(name)
+        when "date"
+          parse_date_arg(name)
+        when "time"
+          parse_time_arg(name)
+        when "plural"
+          parse_plural_arg(name)
+        when "select"
+          parse_select_arg(name)
+        when "selectordinal"
+          parse_select_ordinal_arg(name)
+        else
+          raise ParseError.new("Unknown argument type '#{type}'", @pos)
+        end
+      end
+
+      def parse_number_arg(name)
+        if current_char == "}"
+          @pos += 1
+          return Nodes::NumberFormatNode.new(name)
+        end
+
+        expect(",")
+        skip_whitespace
+        style = parse_identifier
+        skip_whitespace
+        expect("}")
+        Nodes::NumberFormatNode.new(name, style)
+      end
+
+      def parse_date_arg(name)
+        if current_char == "}"
+          @pos += 1
+          return Nodes::DateFormatNode.new(name)
+        end
+
+        expect(",")
+        skip_whitespace
+        style = parse_identifier
+        skip_whitespace
+        expect("}")
+        Nodes::DateFormatNode.new(name, style)
+      end
+
+      def parse_time_arg(name)
+        if current_char == "}"
+          @pos += 1
+          return Nodes::TimeFormatNode.new(name)
+        end
+
+        expect(",")
+        skip_whitespace
+        style = parse_identifier
+        skip_whitespace
+        expect("}")
+        Nodes::TimeFormatNode.new(name, style)
+      end
+
+      def parse_plural_arg(name)
+        expect(",")
+        skip_whitespace
+
+        offset = 0
+        if @pattern[@pos..].start_with?("offset:")
+          @pos += 7
+          skip_whitespace
+          offset = parse_number
+          skip_whitespace
+        end
+
+        branches = parse_branches
+        expect("}")
+        Nodes::PluralNode.new(name, branches, offset)
+      end
+
+      def parse_select_arg(name)
+        expect(",")
+        skip_whitespace
+        branches = parse_branches
+        expect("}")
+        Nodes::SelectNode.new(name, branches)
+      end
+
+      def parse_select_ordinal_arg(name)
+        expect(",")
+        skip_whitespace
+
+        offset = 0
+        if @pattern[@pos..].start_with?("offset:")
+          @pos += 7
+          skip_whitespace
+          offset = parse_number
+          skip_whitespace
+        end
+
+        branches = parse_branches
+        expect("}")
+        Nodes::SelectOrdinalNode.new(name, branches, offset)
+      end
+
+      def parse_branches
+        branches = {}
+
+        while !eof? && current_char != "}"
+          skip_whitespace
+          break if eof? || current_char == "}"
+
+          key = parse_branch_key
+          skip_whitespace
+          expect("{")
+          value = parse_message("}")
+          expect("}")
+          skip_whitespace
+
+          branches[key] = value
+        end
+
+        branches
+      end
+
+      def parse_branch_key
+        if current_char == "="
+          @pos += 1
+          :"=#{parse_number}"
+        else
+          parse_identifier.to_sym
+        end
+      end
+
+      def parse_identifier
+        start = @pos
+        while !eof? && identifier_char?(current_char)
+          @pos += 1
+        end
+        raise ParseError.new("Expected identifier", start) if @pos == start
+        @pattern[start...@pos]
+      end
+
+      def parse_number
+        start = @pos
+        @pos += 1 if !eof? && current_char == "-"
+        while !eof? && current_char.match?(/[0-9]/)
+          @pos += 1
+        end
+        raise ParseError.new("Expected number", start) if @pos == start
+        @pattern[start...@pos].to_i
+      end
+
+      def identifier_char?(char)
+        char.match?(/[a-zA-Z0-9_]/)
+      end
+
+      def skip_whitespace
+        @pos += 1 while !eof? && current_char.match?(/\s/)
+      end
+
+      def expect(char)
+        if eof? || current_char != char
+          raise ParseError.new("Expected '#{char}'", @pos)
+        end
+        @pos += 1
+      end
+
+      def current_char
+        @pattern[@pos]
+      end
+
+      def eof?
+        @pos >= @pattern.length
+      end
+
+      def merge_adjacent_text(nodes)
+        merged = []
+        nodes.each do |node|
+          if node.is_a?(Nodes::TextNode) && merged.last.is_a?(Nodes::TextNode)
+            merged.last.value = +(merged.last.value) + node.value
+          else
+            merged << node
+          end
+        end
+        merged
+      end
+    end
+  end
+end

data/lib/i18n/message_format/version.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module I18n
+  module MessageFormat
+    # The current version of the i18n-message_format gem.
+    VERSION = "0.1.0"
+  end
+end

data/lib/i18n/message_format.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require_relative "message_format/cache"
+require_relative "message_format/nodes"
+require_relative "message_format/version"
+
+module I18n
+  # Top-level namespace for the i18n-message_format gem.
+  module MessageFormat
+    # Base error class for all errors raised by this gem.
+    class Error < StandardError; end
+  end
+end
+
+require_relative "message_format/parser"
+require_relative "message_format/formatter"
+require_relative "message_format/backend"
+require_relative "message_format/ordinal_rules"
+
+module I18n
+  # Provides ICU message format support for the I18n gem.
+  #
+  # Patterns follow the ICU MessageFormat syntax and support simple argument
+  # interpolation as well as `plural`, `select`, and `selectordinal` constructs.
+  #
+  # @example Simple argument interpolation
+  #   I18n::MessageFormat.format("Hello, {name}!", name: "world")
+  #   # => "Hello, world!"
+  #
+  # @example Plural
+  #   I18n::MessageFormat.format(
+  #     "{count, plural, one {# item} other {# items}}",
+  #     count: 3
+  #   )
+  #   # => "3 items"
+  module MessageFormat
+    @cache = Cache.new
+
+    class << self
+      # Formats an ICU message format pattern with the given arguments.
+      #
+      # Parsed ASTs are memoized in an internal LRU cache keyed by the pattern
+      # string, so repeated calls with the same pattern are efficient.
+      #
+      # @param pattern [String] an ICU MessageFormat pattern string
+      # @param arguments [Hash] a hash of argument names (Symbol or String keys)
+      #   to their values. May be omitted in favour of keyword arguments.
+      # @param locale [Symbol, String] the locale to use for pluralisation and
+      #   number/date/time localisation. Defaults to {I18n.locale}.
+      # @param kwargs [Hash] keyword arguments merged into +arguments+ when
+      #   +arguments+ is empty.
+      # @return [String] the formatted message
+      # @raise [ParseError] if +pattern+ contains a syntax error
+      # @raise [MissingArgumentError] if a placeholder in +pattern+ has no
+      #   corresponding entry in +arguments+
+      def format(pattern, arguments = {}, locale: ::I18n.locale, **kwargs)
+        arguments = kwargs if arguments.empty? && !kwargs.empty?
+        nodes = @cache.fetch(pattern) do
+          Parser.new(pattern).parse
+        end
+        Formatter.new(nodes, arguments, locale).format
+      end
+
+      # Clears the internal parse-result cache.
+      #
+      # Useful in tests or whenever you need to reclaim memory.
+      #
+      # @return [void]
+      def clear_cache!
+        @cache.clear
+      end
+    end
+  end
+end

data/sig/i18n/message_format.rbs

@@ -0,0 +1,6 @@
+module I18n
+  module MessageFormat
+    VERSION: String
+    # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+  end
+end

metadata

@@ -0,0 +1,78 @@
+--- !ruby/object:Gem::Specification
+name: i18n-message_format
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Chris Fung
+bindir: exe
+cert_chain: []
+date: 1980-01-01 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: i18n
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+description: A pure Ruby implementation of ICU Message Format that integrates with
+  the ruby-i18n gem via a chainable backend.
+email:
+- aergonaut@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".envrc"
+- CHANGELOG.md
+- CODE_OF_CONDUCT.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- devenv.lock
+- devenv.nix
+- devenv.yaml
+- docs/plans/2026-02-25-icu-message-format-design.md
+- docs/plans/2026-02-25-icu-message-format-plan.md
+- lib/i18n/message_format.rb
+- lib/i18n/message_format/backend.rb
+- lib/i18n/message_format/cache.rb
+- lib/i18n/message_format/formatter.rb
+- lib/i18n/message_format/nodes.rb
+- lib/i18n/message_format/ordinal_rules.rb
+- lib/i18n/message_format/parser.rb
+- lib/i18n/message_format/version.rb
+- sig/i18n/message_format.rbs
+homepage: https://github.com/aergonaut/i18n-message_format
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/aergonaut/i18n-message_format
+  source_code_uri: https://github.com/aergonaut/i18n-message_format
+  changelog_uri: https://github.com/aergonaut/i18n-message_format/blob/main/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.7.2
+specification_version: 4
+summary: ICU Message Format support for Ruby i18n
+test_files: []