num2words 0.3.0 → 0.4.0

data/docs/rails.md

@@ -0,0 +1,130 @@
+# Rails Integration
+
+`num2words` provides optional Rails helpers without adding Rails as a runtime dependency.
+
+If Rails is available, `Num2words::Railtie` automatically includes helpers into Action View. Outside Rails, the helper module can be included manually.
+
+The integration is covered by specs with a minimal Rails application, but Rails remains a development/test dependency only.
+
+## Helpers
+
+Available helpers:
+
+- `number_to_words(number, locale: I18n.locale, **options)`
+- `currency_to_words(amount, locale: I18n.locale, **options)`
+- `date_to_words(date, locale: I18n.locale, **options)`
+- `time_to_words(time, locale: I18n.locale, **options)`
+- `datetime_to_words(datetime, locale: I18n.locale, **options)`
+
+## Rails Views
+
+```erb
+<%= number_to_words(123, locale: :ru) %>
+<%= currency_to_words(@invoice.total, locale: :ru, code: :RUB) %>
+<%= date_to_words(Date.current, locale: I18n.locale) %>
+<%= time_to_words(Time.current, locale: I18n.locale) %>
+```
+
+When `locale:` is omitted, helpers use `I18n.locale`.
+
+```erb
+<%= number_to_words(123) %>
+```
+
+## Controllers
+
+Helpers are also exposed through the controller helper context:
+
+```ruby
+class PaymentsController < ApplicationController
+  def show
+    @amount_in_words = helpers.currency_to_words(@payment.amount, locale: :ru, code: @payment.currency)
+  end
+end
+```
+
+## ActiveModel Validations
+
+`num2words` provides a currency validator for Rails and ActiveModel models:
+
+```ruby
+class Payment < ApplicationRecord
+  validates :currency, num2words_currency: { locale: :ru }
+end
+```
+
+Valid values are checked against `Num2words.currency_available?(locale, currency)`.
+
+```ruby
+Payment.new(currency: "RUB").valid?
+# => true
+
+Payment.new(currency: "XYZ").valid?
+# => false
+```
+
+The locale can also be dynamic:
+
+```ruby
+class Payment < ApplicationRecord
+  validates :currency, num2words_currency: { locale: ->(payment) { payment.locale } }
+end
+```
+
+Locale validation is also available:
+
+```ruby
+class Payment < ApplicationRecord
+  validates :locale, num2words_locale: true
+end
+```
+
+```ruby
+Payment.new(locale: "ru").valid?
+# => true
+
+Payment.new(locale: "xx").valid?
+# => false
+```
+
+Valid values are checked against `Num2words.available_locales`.
+
+## Metadata API
+
+For forms, select inputs and settings screens, use the public metadata API:
+
+```ruby
+Num2words.available_locales
+Num2words.available_currencies(:ru)
+Num2words.currency_available?(:ru, :RUB)
+Num2words.currency_info(:ru, :RUB)
+Num2words.default_currency_info(:ru)
+```
+
+## Manual Usage
+
+The helpers can be used without Rails:
+
+```ruby
+helper = Object.new.extend(Num2words::Rails::Helpers)
+
+helper.number_to_words(123, locale: :en)
+# => "one hundred twenty three"
+
+helper.currency_to_words("12.50", locale: :ru, code: :USD)
+# => "двенадцать долларов пятьдесят центов"
+```
+
+## Options
+
+Helpers forward all options to `Num2words.to_words` or `Num2words.to_currency`.
+
+```ruby
+number_to_words(0.5, locale: :ru, joiner: :and)
+# => "ноль и пять десятых"
+
+currency_to_words(12, locale: :ru, minor: :nonzero)
+# => "двенадцать рублей"
+```
+
+See [API reference](api.md) for the full option list.

data/docs/rails.ru.md

@@ -0,0 +1,130 @@
+# Rails-интеграция
+
+`num2words` предоставляет optional Rails helpers без добавления Rails как runtime-зависимости.
+
+Если Rails доступен, `Num2words::Railtie` автоматически подключает helpers в Action View. Вне Rails модуль helpers можно подключить вручную.
+
+Интеграция покрыта specs с минимальным Rails-приложением, но Rails остается зависимостью только для development/test.
+
+## Helpers
+
+Доступные helpers:
+
+- `number_to_words(number, locale: I18n.locale, **options)`
+- `currency_to_words(amount, locale: I18n.locale, **options)`
+- `date_to_words(date, locale: I18n.locale, **options)`
+- `time_to_words(time, locale: I18n.locale, **options)`
+- `datetime_to_words(datetime, locale: I18n.locale, **options)`
+
+## Rails views
+
+```erb
+<%= number_to_words(123, locale: :ru) %>
+<%= currency_to_words(@invoice.total, locale: :ru, code: :RUB) %>
+<%= date_to_words(Date.current, locale: I18n.locale) %>
+<%= time_to_words(Time.current, locale: I18n.locale) %>
+```
+
+Если `locale:` не передан, helpers используют `I18n.locale`.
+
+```erb
+<%= number_to_words(123) %>
+```
+
+## Controllers
+
+Helpers также доступны через controller helper context:
+
+```ruby
+class PaymentsController < ApplicationController
+  def show
+    @amount_in_words = helpers.currency_to_words(@payment.amount, locale: :ru, code: @payment.currency)
+  end
+end
+```
+
+## ActiveModel validations
+
+`num2words` предоставляет валидатор валюты для Rails и ActiveModel моделей:
+
+```ruby
+class Payment < ApplicationRecord
+  validates :currency, num2words_currency: { locale: :ru }
+end
+```
+
+Валидные значения проверяются через `Num2words.currency_available?(locale, currency)`.
+
+```ruby
+Payment.new(currency: "RUB").valid?
+# => true
+
+Payment.new(currency: "XYZ").valid?
+# => false
+```
+
+Локаль может быть динамической:
+
+```ruby
+class Payment < ApplicationRecord
+  validates :currency, num2words_currency: { locale: ->(payment) { payment.locale } }
+end
+```
+
+Также доступна проверка локали:
+
+```ruby
+class Payment < ApplicationRecord
+  validates :locale, num2words_locale: true
+end
+```
+
+```ruby
+Payment.new(locale: "ru").valid?
+# => true
+
+Payment.new(locale: "xx").valid?
+# => false
+```
+
+Валидные значения проверяются через `Num2words.available_locales`.
+
+## Metadata API
+
+Для форм, select-полей и настроек можно использовать публичные методы metadata API:
+
+```ruby
+Num2words.available_locales
+Num2words.available_currencies(:ru)
+Num2words.currency_available?(:ru, :RUB)
+Num2words.currency_info(:ru, :RUB)
+Num2words.default_currency_info(:ru)
+```
+
+## Ручное использование
+
+Helpers можно использовать без Rails:
+
+```ruby
+helper = Object.new.extend(Num2words::Rails::Helpers)
+
+helper.number_to_words(123, locale: :en)
+# => "one hundred twenty three"
+
+helper.currency_to_words("12.50", locale: :ru, code: :USD)
+# => "двенадцать долларов пятьдесят центов"
+```
+
+## Опции
+
+Helpers передают все опции в `Num2words.to_words` или `Num2words.to_currency`.
+
+```ruby
+number_to_words(0.5, locale: :ru, joiner: :and)
+# => "ноль и пять десятых"
+
+currency_to_words(12, locale: :ru, minor: :nonzero)
+# => "двенадцать рублей"
+```
+
+Полный список опций смотри в [справочнике API](api.ru.md).

data/lib/num2words/config.rb

@@ -27,6 +27,34 @@ module Num2words
       I18n.t("num2words.currencies", locale: locale).keys.map(&:to_sym)
     end
 
+    def currency_available?(locale, currency)
+      available_currencies(locale).include?(currency.to_s.upcase.to_sym)
+    end
+
+    def currency_info(locale, currency)
+      code = currency.to_s.upcase.to_sym
+      data = I18n.t("num2words.currencies", locale: locale)[code]
+
+      return unless data
+
+      {
+        code: code,
+        major_unit: data[:major_unit],
+        minor_unit: data[:minor_unit],
+        symbol: data[:symbol]
+      }
+    end
+
+    def default_currency_info(locale = I18n.locale)
+      currency_info(locale, default_currency(locale))
+    end
+
+    def available_locales
+      @available_locales ||= Dir[File.expand_path("../../config/locales/*.yml", __dir__)]
+                             .map { |file| File.basename(file, ".yml").to_sym }
+                             .sort
+    end
+
     def reset!(locale = nil)
       return @local_currency.delete(locale) if locale
 
@@ -52,6 +80,22 @@ module Num2words
     config.available_currencies(locale)
   end
 
+  def self.currency_available?(locale, currency)
+    config.currency_available?(locale, currency)
+  end
+
+  def self.currency_info(locale, currency)
+    config.currency_info(locale, currency)
+  end
+
+  def self.default_currency_info(locale = I18n.locale)
+    config.default_currency_info(locale)
+  end
+
+  def self.available_locales
+    config.available_locales
+  end
+
   def self.currency_warnings
     config.currency_warnings
   end

data/lib/num2words/converter.rb

@@ -383,7 +383,8 @@ module Num2words
         time_format = short && only == :time ? :short : :default
 
         date_part = to_words_date(datetime.to_date, locale, locale_data, format: date_format, date_case: date_case)
-        time_part = to_words_time(datetime.to_time, locale, locale_data, format: time_format, short: short)
+        time_part = to_words_time(Time.new(datetime.year, datetime.month, datetime.day, datetime.hour, datetime.min, datetime.sec),
+                                  locale, locale_data, format: time_format, short: short)
 
         return date_part if only == :date
         return time_part if only == :time

data/lib/num2words/rails/helpers.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Num2words
+  module Rails
+    module Helpers
+      def number_to_words(number, locale: I18n.locale, **options)
+        Num2words.to_words(number, locale: locale, **options)
+      end
+
+      def currency_to_words(amount, locale: I18n.locale, **options)
+        Num2words.to_currency(amount, locale: locale, **options)
+      end
+
+      def date_to_words(date, locale: I18n.locale, **options)
+        Num2words.to_words(date, locale: locale, **options)
+      end
+
+      def time_to_words(time, locale: I18n.locale, **options)
+        Num2words.to_words(time, locale: locale, **options)
+      end
+
+      def datetime_to_words(datetime, locale: I18n.locale, **options)
+        Num2words.to_words(datetime, locale: locale, **options)
+      end
+    end
+  end
+end

data/lib/num2words/rails/validators/currency_validator.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require "active_model"
+
+module Num2words
+  module Rails
+    module Validators
+      class CurrencyValidator < ActiveModel::EachValidator
+        def validate_each(record, attribute, value)
+          locale = resolve_locale(record)
+          currency = value.to_s.upcase.to_sym
+
+          return if Num2words.currency_available?(locale, currency)
+
+          record.errors.add(attribute, :unsupported_currency, currency: currency, locale: locale)
+        end
+
+        private
+
+        def resolve_locale(record)
+          locale = options[:locale]
+          locale.respond_to?(:call) ? locale.call(record) : locale || I18n.locale
+        end
+      end
+    end
+  end
+end
+
+class Num2wordsCurrencyValidator < Num2words::Rails::Validators::CurrencyValidator
+end

data/lib/num2words/rails/validators/locale_validator.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require "active_model"
+
+module Num2words
+  module Rails
+    module Validators
+      class LocaleValidator < ActiveModel::EachValidator
+        def validate_each(record, attribute, value)
+          locale = value.to_s.to_sym
+
+          return if Num2words.available_locales.include?(locale)
+
+          record.errors.add(attribute, :unsupported_locale, locale: locale)
+        end
+      end
+    end
+  end
+end
+
+class Num2wordsLocaleValidator < Num2words::Rails::Validators::LocaleValidator
+end

data/lib/num2words/railtie.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require_relative "rails/helpers"
+
+begin
+  require "rails/railtie"
+  require_relative "rails/validators/currency_validator"
+  require_relative "rails/validators/locale_validator"
+rescue LoadError
+  nil
+end
+
+if defined?(::Rails::Railtie)
+  module Num2words
+    class Railtie < ::Rails::Railtie
+      initializer "num2words.helpers" do
+        ActiveSupport.on_load(:action_view) do
+          include Num2words::Rails::Helpers
+        end
+
+        ActiveSupport.on_load(:action_controller) do
+          helper Num2words::Rails::Helpers if respond_to?(:helper)
+        end
+      end
+    end
+  end
+end

data/lib/num2words/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Num2words
-  VERSION = "0.3.0"
+  VERSION = "0.4.0"
 end

data/lib/num2words.rb

@@ -6,6 +6,8 @@ require_relative "num2words/converter"
 require_relative "num2words/core_ext"
 require_relative "num2words/locales"
 require_relative "num2words/config"
+require_relative "num2words/rails/helpers"
+require_relative "num2words/railtie"
 
 module Num2words
   def self.to_words(number, *args, **opts)

data/num2words.gemspec

@@ -26,4 +26,5 @@ Gem::Specification.new do |spec|
   spec.require_paths = ["lib"]
 
   spec.add_runtime_dependency "i18n", "~> 1.8"
+  spec.add_runtime_dependency "bigdecimal", "~> 3.1"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: num2words
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Ruslan Fedotov
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-06-27 00:00:00.000000000 Z
+date: 2026-07-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: i18n
@@ -24,6 +24,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.8'
+- !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'
 description: Converts numbers, currency amounts, dates, and times to words with locale-aware
   grammar across supported locales.
 email:
@@ -33,12 +47,14 @@ executables:
 extensions: []
 extra_rdoc_files: []
 files:
+- ".github/workflows/ci.yml"
 - ".gitignore"
 - CHANGELOG.md
 - Gemfile
 - LICENSE.txt
 - README.md
 - Rakefile
+- benchmark/converter_benchmark.rb
 - bin/console
 - bin/setup
 - config/locales/ar.yml
@@ -91,6 +107,14 @@ files:
 - config/locales/ur.yml
 - config/locales/vi.yml
 - config/locales/zh.yml
+- docs/api.md
+- docs/api.ru.md
+- docs/limits.md
+- docs/limits.ru.md
+- docs/locale_development.md
+- docs/locale_development.ru.md
+- docs/rails.md
+- docs/rails.ru.md
 - exe/num2words-console
 - lib/num2words.rb
 - lib/num2words/config.rb
@@ -149,6 +173,10 @@ files:
 - lib/num2words/locales/ur.rb
 - lib/num2words/locales/vi.rb
 - lib/num2words/locales/zh.rb
+- lib/num2words/rails/helpers.rb
+- lib/num2words/rails/validators/currency_validator.rb
+- lib/num2words/rails/validators/locale_validator.rb
+- lib/num2words/railtie.rb
 - lib/num2words/version.rb
 - num2words.gemspec
 homepage: https://github.com/skyrusx/num2words