num2words 0.3.1 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 78f705a73f571176b4d920dfe220590d2bd217ea513fb817028a0ae2c22221cd
-  data.tar.gz: 1e8726b93feee82a3b87143ae8a25edf388d726f65ecf424ec713fcc4323ea08
+  metadata.gz: 288098773139982ac980a108f2bde3e3220c7b090cadd82cf8bada24053cce84
+  data.tar.gz: 0103cff58a94f52fd255aec76b83d4d487cd3767a7861ea25b2aff44c334797b
 SHA512:
-  metadata.gz: d8a078fef78bc1e26fc28d90c6604e6a3a09aa05e3b716df2faea6d7423bb91a4de1c907eaa7d7e9c85b0d3019fa98257f6b499113f1987d646c902680bcdd66
-  data.tar.gz: a87e663b01668bdf114cba5eb2c2f9f55b453b4aae314b5ceceac78047574e1fc5917a46d97fddaf60cea2a64333c2b1f0901694daed5aade3beff7d6682c1b9
+  metadata.gz: e9570c86cb884cd7abc6c8f16df6946d85ab8292c38a05a8567b48179a1aa04fdc3d4ecfb8252f358c35bcac4d093c5f236c04a63b16009ee04487b47d5fad3d
+  data.tar.gz: 613f2887655f9b5dcd1d9dcf927bf6d368337fa95abe2f2e7b909a87df7caf8d5ea88fda30e167ab22f9b624ef20bc68371ed916a52d239ea3156c9f6ef09bdb

data/CHANGELOG.md

@@ -11,6 +11,27 @@
 
 ---
 
+## [0.4.0] - 2026-07-05
+
+### Added
+- Опциональные Rails helpers и Railtie:
+  - `number_to_words`
+  - `currency_to_words`
+  - `date_to_words`
+  - `time_to_words`
+  - `datetime_to_words`
+- Интеграционные specs для проверки Railtie в минимальном Rails-приложении.
+- Подключение Rails helpers в controller helper context.
+- Валидатор ActiveModel `num2words_currency` для проверки валюты по локали.
+- Валидатор ActiveModel `num2words_locale` для проверки поддерживаемой локали.
+- Публичный metadata API `Num2words.available_locales`.
+- Публичный metadata API `Num2words.currency_available?`.
+- Публичный metadata API `Num2words.currency_info`.
+- Публичный metadata API `Num2words.default_currency_info`.
+- Документация по Rails-интеграции: `docs/rails.md` и `docs/rails.ru.md`.
+
+---
+
 ## [0.3.1] - 2026-07-04
 
 ### Added

data/Gemfile

@@ -9,4 +9,5 @@ gem "i18n", "~> 1.10"
 
 group :development, :test do
   gem "rspec", "~> 3.12"
+  gem "rails", "~> 7.1"
 end

data/README.md

@@ -14,6 +14,9 @@ Ruby-гем для преобразования чисел, дробей, ден
 - Даты, время и дата-время.
 - Регистры вывода: `word_case: :upper | :downcase | :capitalize | :title`.
 - Удобные методы для `Integer`, `Float`, `String`, `Date`, `Time`, `DateTime`.
+- Опциональные Rails helpers и Railtie.
+- ActiveModel validators для локалей и валют.
+- Metadata API для локалей и валют.
 - Интерактивная консоль `num2words-console`.
 
 ---
@@ -153,6 +156,60 @@ Num2words.to_currency(BigDecimal("21.05"), :ru)
 - [English](docs/limits.md)
 - [Русский](docs/limits.ru.md)
 
+Rails-интеграция:
+
+- [English](docs/rails.md)
+- [Русский](docs/rails.ru.md)
+
+---
+
+## Rails
+
+Если Rails доступен, helpers подключаются автоматически через Railtie.
+
+```erb
+<%= number_to_words(123, locale: :ru) %>
+<%= currency_to_words(@payment.amount, locale: :ru, code: @payment.currency) %>
+<%= date_to_words(Date.current, locale: I18n.locale) %>
+```
+
+Также доступны ActiveModel validators:
+
+```ruby
+class Payment < ApplicationRecord
+  validates :currency, num2words_currency: { locale: ->(payment) { payment.locale } }
+  validates :locale, num2words_locale: true
+end
+```
+
+---
+
+## Metadata API
+
+```ruby
+Num2words.available_locales
+# => [:ar, :be, :bg, :bn, :cs, ...]
+
+Num2words.currency_available?(:ru, :RUB)
+# => true
+
+Num2words.currency_info(:ru, :RUB)
+# => {
+#      code: :RUB,
+#      major_unit: ["рубль", "рубля", "рублей"],
+#      minor_unit: ["копейка", "копейки", "копеек"],
+#      symbol: "₽"
+#    }
+
+Num2words.default_currency_info(:ru)
+# => {
+#      code: :RUB,
+#      major_unit: ["рубль", "рубля", "рублей"],
+#      minor_unit: ["копейка", "копейки", "копеек"],
+#      symbol: "₽"
+#    }
+```
+
 ---
 
 ## Консоль

data/docs/api.md

@@ -364,6 +364,61 @@ Num2words.available_currencies(:ru)
 # => [:RUB, :USD, :EUR, ...]
 ```
 
+### `Num2words.currency_available?`
+
+Checks whether a currency is available for a locale.
+
+```ruby
+Num2words.currency_available?(:ru, :RUB)
+# => true
+
+Num2words.currency_available?(:ru, "usd")
+# => true
+
+Num2words.currency_available?(:ru, :XYZ)
+# => false
+```
+
+### `Num2words.currency_info`
+
+Returns currency metadata for a locale or `nil` when the currency is unavailable.
+
+```ruby
+Num2words.currency_info(:ru, :RUB)
+# => {
+#      code: :RUB,
+#      major_unit: ["рубль", "рубля", "рублей"],
+#      minor_unit: ["копейка", "копейки", "копеек"],
+#      symbol: "₽"
+#    }
+
+Num2words.currency_info(:ru, :XYZ)
+# => nil
+```
+
+### `Num2words.default_currency_info`
+
+Returns metadata for the locale default currency.
+
+```ruby
+Num2words.default_currency_info(:ru)
+# => {
+#      code: :RUB,
+#      major_unit: ["рубль", "рубля", "рублей"],
+#      minor_unit: ["копейка", "копейки", "копеек"],
+#      symbol: "₽"
+#    }
+```
+
+### `Num2words.available_locales`
+
+Returns supported locale codes.
+
+```ruby
+Num2words.available_locales
+# => [:ar, :be, :bg, :bn, :cs, ...]
+```
+
 ### `Num2words.currency_warnings`
 
 Controls warnings when requested currency is unavailable.
@@ -418,5 +473,6 @@ Num2words.to_currency("abc", :en)
 ## Development References
 
 - [Numeric limits](limits.md)
+- [Rails integration](rails.md)
 - [Locale development guide](locale_development.md)
 - [Russian locale development guide](locale_development.ru.md)

data/docs/api.ru.md

@@ -364,6 +364,61 @@ Num2words.available_currencies(:ru)
 # => [:RUB, :USD, :EUR, ...]
 ```
 
+### `Num2words.currency_available?`
+
+Проверяет, доступна ли валюта для локали.
+
+```ruby
+Num2words.currency_available?(:ru, :RUB)
+# => true
+
+Num2words.currency_available?(:ru, "usd")
+# => true
+
+Num2words.currency_available?(:ru, :XYZ)
+# => false
+```
+
+### `Num2words.currency_info`
+
+Возвращает данные валюты для локали или `nil`, если валюта недоступна.
+
+```ruby
+Num2words.currency_info(:ru, :RUB)
+# => {
+#      code: :RUB,
+#      major_unit: ["рубль", "рубля", "рублей"],
+#      minor_unit: ["копейка", "копейки", "копеек"],
+#      symbol: "₽"
+#    }
+
+Num2words.currency_info(:ru, :XYZ)
+# => nil
+```
+
+### `Num2words.default_currency_info`
+
+Возвращает данные валюты по умолчанию для локали.
+
+```ruby
+Num2words.default_currency_info(:ru)
+# => {
+#      code: :RUB,
+#      major_unit: ["рубль", "рубля", "рублей"],
+#      minor_unit: ["копейка", "копейки", "копеек"],
+#      symbol: "₽"
+#    }
+```
+
+### `Num2words.available_locales`
+
+Возвращает список поддерживаемых локалей.
+
+```ruby
+Num2words.available_locales
+# => [:ar, :be, :bg, :bn, :cs, ...]
+```
+
 ### `Num2words.currency_warnings`
 
 Управляет warning при запросе валюты, недоступной для локали.
@@ -418,5 +473,6 @@ Num2words.to_currency("abc", :en)
 ## Документация для разработки
 
 - [Числовые ограничения](limits.ru.md)
+- [Rails-интеграция](rails.ru.md)
 - [Locale development guide](locale_development.md)
 - [Русская инструкция по разработке локалей](locale_development.ru.md)

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.1"
+  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)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: num2words
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.4.0
 platform: ruby
 authors:
 - Ruslan Fedotov
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-07-04 00:00:00.000000000 Z
+date: 2026-07-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: i18n
@@ -113,6 +113,8 @@ files:
 - 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
@@ -171,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