num2words 0.3.1 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 78f705a73f571176b4d920dfe220590d2bd217ea513fb817028a0ae2c22221cd
-  data.tar.gz: 1e8726b93feee82a3b87143ae8a25edf388d726f65ecf424ec713fcc4323ea08
+  metadata.gz: 131bb24135ba3f8c1345bbd7ccf5c3b27d79b9c9776d7e0ec45b259960be1dbd
+  data.tar.gz: 27a943ef2bbaae410ae51d1aca3fe009375f68632e1928b4639a570919619c25
 SHA512:
-  metadata.gz: d8a078fef78bc1e26fc28d90c6604e6a3a09aa05e3b716df2faea6d7423bb91a4de1c907eaa7d7e9c85b0d3019fa98257f6b499113f1987d646c902680bcdd66
-  data.tar.gz: a87e663b01668bdf114cba5eb2c2f9f55b453b4aae314b5ceceac78047574e1fc5917a46d97fddaf60cea2a64333c2b1f0901694daed5aade3beff7d6682c1b9
+  metadata.gz: 3601c493e2cf40b2a908daca5980f79c95933316fa2a87393306c479919ec795c15af731e2eb075fd92b9aa61a97fd72badaa575723d8201e5093cecc89e6d88
+  data.tar.gz: 5000cdf5a8fcaa4cf2af57cb2ad7640e111f9f2a1eb7fdf94783ac19a76a2cd8aedd2ef44cbecd7eee9647d3bb1be064f2d70f711634aa3de679f83ede17a47d

data/CHANGELOG.md

@@ -11,6 +11,38 @@
 
 ---
 
+## [0.5.0] - 2026-07-06
+
+### Added
+- Опция `strict: true` для `to_currency`, которая вызывает `Num2words::UnsupportedCurrencyError` при недоступной валюте вместо fallback на валюту по умолчанию.
+- Классы ошибок `Num2words::UnsupportedInputError`, `Num2words::UnsupportedOptionError` и `Num2words::UnsupportedCurrencyAmountError`, совместимые с `ArgumentError`.
+- Rails/ActiveModel сообщения ошибок для валидаторов `num2words_currency` и `num2words_locale`.
+- Публичный metadata API `Num2words.currency_options` для select-полей и настроек.
+- Публичный metadata API `Num2words.locale_options` для select-полей и настроек.
+
+---
+
+## [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`.
 
 ---
@@ -81,6 +84,9 @@ Num2words.to_currency(BigDecimal("21.05"), :ru)
 12.50.to_currency(:ru, code: :USD)
 # => "двенадцать долларов пятьдесят центов"
 
+Num2words.to_currency(12.50, :ru, code: :XYZ, strict: true)
+# raises Num2words::UnsupportedCurrencyError
+
 1.to_currency(:ru, minor: :nonzero)
 # => "один рубль"
 
@@ -142,6 +148,7 @@ Num2words.to_currency(BigDecimal("21.05"), :ru)
 - `word_case: :default | :upper | :downcase | :capitalize | :title` — регистр результата.
 - `minor: :always | :nonzero | :never` — вывод младшей денежной единицы.
 - `code: :USD` — выбор валюты для `to_currency`.
+- `strict: true` — ошибка вместо fallback при недоступной валюте в `to_currency`.
 
 Полная справка по API:
 
@@ -153,6 +160,86 @@ 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: "₽"
+#    }
+
+Num2words.currency_options(:ru)
+# => [["RUB — ₽", :RUB], ["USD — $", :USD], ...]
+
+Num2words.locale_options
+# => [["ar", :ar], ["be", :be], ["bg", :bg], ...]
+```
+
+---
+
+## Ошибки
+
+```ruby
+Num2words.to_currency(10, :ru, code: :XYZ, strict: true)
+# raises Num2words::UnsupportedCurrencyError
+
+Num2words.to_words(Object.new, :ru)
+# raises Num2words::UnsupportedInputError
+
+Num2words.to_words(0.5, :ru, joiner: :plus)
+# raises Num2words::UnsupportedOptionError
+
+Num2words.to_currency("abc", :ru)
+# raises Num2words::UnsupportedCurrencyAmountError
+```
+
+Ошибки пользовательских аргументов наследуются от `ArgumentError`, поэтому существующий код с `rescue ArgumentError` продолжает работать.
+
 ---
 
 ## Консоль

data/config/locales/en.yml

@@ -184,3 +184,7 @@ en:
         major_unit: ["shilling", "shillings", "shillings"]
         minor_unit: ["cent", "cents", "cents"]
         symbol: "Sh"
+  errors:
+    messages:
+      unsupported_currency: "is not supported for this locale"
+      unsupported_locale: "is not supported"

data/config/locales/ru.yml

@@ -204,3 +204,7 @@ ru:
         major_unit: ["шиллинг", "шиллинга", "шиллингов"]
         minor_unit: ["цент", "цента", "центов"]
         symbol: "Sh"
+  errors:
+    messages:
+      unsupported_currency: "не поддерживается для выбранной локали"
+      unsupported_locale: "не поддерживается"

data/docs/api.md

@@ -318,6 +318,15 @@ Num2words.to_currency(12.50, :ru, code: :USD)
 
 If the currency is not available for the locale, `num2words` falls back to the locale default currency and may emit a warning depending on configuration.
 
+### `strict`
+
+For `to_currency`, enables strict currency validation. When `code:` is unavailable for the locale, the method raises `Num2words::UnsupportedCurrencyError` instead of falling back to the default currency.
+
+```ruby
+Num2words.to_currency(12.50, :ru, code: :XYZ, strict: true)
+# raises Num2words::UnsupportedCurrencyError
+```
+
 ### `minor`
 
 Controls minor currency unit output.
@@ -364,6 +373,99 @@ 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.currency_options`
+
+Returns an array for select inputs and settings screens.
+
+```ruby
+Num2words.currency_options(:ru)
+# => [["RUB — ₽", :RUB], ["USD — $", :USD], ...]
+
+Num2words.currency_options(:ru, format: :code)
+# => [["RUB", :RUB], ["USD", :USD], ...]
+
+Num2words.currency_options(:ru, format: :name)
+# => [["рубль", :RUB], ["доллар", :USD], ...]
+```
+
+Supported `format:` values:
+
+- `:symbol` - currency code and symbol, default.
+- `:code` - currency code only.
+- `:name` - localized major currency unit name.
+
+### `Num2words.available_locales`
+
+Returns supported locale codes.
+
+```ruby
+Num2words.available_locales
+# => [:ar, :be, :bg, :bn, :cs, ...]
+```
+
+### `Num2words.locale_options`
+
+Returns an array of locales for select inputs and settings screens.
+
+```ruby
+Num2words.locale_options
+# => [["ar", :ar], ["be", :be], ["bg", :bg], ...]
+
+Num2words.locale_options(format: :upcase)
+# => [["AR", :ar], ["BE", :be], ["BG", :bg], ...]
+```
+
+Supported `format:` values:
+
+- `:code` - locale code, default.
+- `:upcase` - upper-case locale code.
+
 ### `Num2words.currency_warnings`
 
 Controls warnings when requested currency is unavailable.
@@ -391,32 +493,42 @@ KZT MYR NOK PKR PLN RON RSD RUB SAR SEK THB TRY UAH USD VND
 
 ## Errors
 
+User argument errors inherit from `ArgumentError`, so existing code using `rescue ArgumentError` continues to work.
+
 Unsupported input type:
 
 ```ruby
 Num2words.to_words(Object.new, :en)
-# raises ArgumentError: Unsupported input type: ...
+# raises Num2words::UnsupportedInputError
 ```
 
 Unsupported options:
 
 ```ruby
 Num2words.to_words(0.5, :ru, joiner: :plus)
-# raises ArgumentError: Unsupported joiner option: :plus
+# raises Num2words::UnsupportedOptionError
 
 Num2words.to_currency(12, :ru, minor: :sometimes)
-# raises ArgumentError: Unsupported minor option: :sometimes
+# raises Num2words::UnsupportedOptionError
 ```
 
 Unsupported currency amount:
 
 ```ruby
 Num2words.to_currency("abc", :en)
-# raises ArgumentError: Unsupported currency amount: "abc"
+# raises Num2words::UnsupportedCurrencyAmountError
+```
+
+Unsupported currency in strict mode:
+
+```ruby
+Num2words.to_currency(10, :ru, code: :XYZ, strict: true)
+# raises Num2words::UnsupportedCurrencyError
 ```
 
 ## 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

@@ -318,6 +318,15 @@ Num2words.to_currency(12.50, :ru, code: :USD)
 
 Если валюта недоступна для локали, `num2words` использует валюту локали по умолчанию и может вывести warning в зависимости от настроек.
 
+### `strict`
+
+Для `to_currency` включает строгую проверку валюты. Если `code:` недоступен для локали, метод вызывает `Num2words::UnsupportedCurrencyError` вместо fallback на валюту по умолчанию.
+
+```ruby
+Num2words.to_currency(12.50, :ru, code: :XYZ, strict: true)
+# raises Num2words::UnsupportedCurrencyError
+```
+
 ### `minor`
 
 Управляет выводом младшей денежной единицы.
@@ -364,6 +373,99 @@ 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.currency_options`
+
+Возвращает массив для select-полей и настроек.
+
+```ruby
+Num2words.currency_options(:ru)
+# => [["RUB — ₽", :RUB], ["USD — $", :USD], ...]
+
+Num2words.currency_options(:ru, format: :code)
+# => [["RUB", :RUB], ["USD", :USD], ...]
+
+Num2words.currency_options(:ru, format: :name)
+# => [["рубль", :RUB], ["доллар", :USD], ...]
+```
+
+Поддерживаемые значения `format:`:
+
+- `:symbol` - код и символ валюты, значение по умолчанию.
+- `:code` - только код валюты.
+- `:name` - локализованное название основной денежной единицы.
+
+### `Num2words.available_locales`
+
+Возвращает список поддерживаемых локалей.
+
+```ruby
+Num2words.available_locales
+# => [:ar, :be, :bg, :bn, :cs, ...]
+```
+
+### `Num2words.locale_options`
+
+Возвращает массив локалей для select-полей и настроек.
+
+```ruby
+Num2words.locale_options
+# => [["ar", :ar], ["be", :be], ["bg", :bg], ...]
+
+Num2words.locale_options(format: :upcase)
+# => [["AR", :ar], ["BE", :be], ["BG", :bg], ...]
+```
+
+Поддерживаемые значения `format:`:
+
+- `:code` - код локали, значение по умолчанию.
+- `:upcase` - код локали в верхнем регистре.
+
 ### `Num2words.currency_warnings`
 
 Управляет warning при запросе валюты, недоступной для локали.
@@ -391,32 +493,42 @@ KZT MYR NOK PKR PLN RON RSD RUB SAR SEK THB TRY UAH USD VND
 
 ## Ошибки
 
+Ошибки пользовательских аргументов наследуются от `ArgumentError`, поэтому существующий код с `rescue ArgumentError` продолжает работать.
+
 Неподдерживаемый тип входных данных:
 
 ```ruby
 Num2words.to_words(Object.new, :en)
-# raises ArgumentError: Unsupported input type: ...
+# raises Num2words::UnsupportedInputError
 ```
 
 Неподдерживаемые опции:
 
 ```ruby
 Num2words.to_words(0.5, :ru, joiner: :plus)
-# raises ArgumentError: Unsupported joiner option: :plus
+# raises Num2words::UnsupportedOptionError
 
 Num2words.to_currency(12, :ru, minor: :sometimes)
-# raises ArgumentError: Unsupported minor option: :sometimes
+# raises Num2words::UnsupportedOptionError
 ```
 
 Некорректная денежная сумма:
 
 ```ruby
 Num2words.to_currency("abc", :en)
-# raises ArgumentError: Unsupported currency amount: "abc"
+# raises Num2words::UnsupportedCurrencyAmountError
+```
+
+Недоступная валюта в строгом режиме:
+
+```ruby
+Num2words.to_currency(10, :ru, code: :XYZ, strict: true)
+# raises Num2words::UnsupportedCurrencyError
 ```
 
 ## Документация для разработки
 
 - [Числовые ограничения](limits.ru.md)
+- [Rails-интеграция](rails.ru.md)
 - [Locale development guide](locale_development.md)
 - [Русская инструкция по разработке локалей](locale_development.ru.md)

data/docs/rails.md

@@ -0,0 +1,141 @@
+# 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`.
+
+Error messages for `unsupported_currency` and `unsupported_locale` are included in the gem locale files. Rails apps can override them through the standard `errors.messages` keys.
+
+## 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)
+Num2words.currency_options(:ru)
+Num2words.locale_options
+```
+
+Rails form example:
+
+```erb
+<%= form.select :currency, Num2words.currency_options(I18n.locale) %>
+<%= form.select :locale, Num2words.locale_options %>
+```
+
+## 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,141 @@
+# 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`.
+
+Сообщения ошибок для `unsupported_currency` и `unsupported_locale` уже добавлены в locale files гема. Их можно переопределить в Rails-приложении стандартным способом через `errors.messages`.
+
+## 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)
+Num2words.currency_options(:ru)
+Num2words.locale_options
+```
+
+Пример для Rails form:
+
+```erb
+<%= form.select :currency, Num2words.currency_options(I18n.locale) %>
+<%= form.select :locale, Num2words.locale_options %>
+```
+
+## Ручное использование
+
+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,52 @@ 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 currency_options(locale = I18n.locale, format: :symbol)
+      validate_currency_options_format!(format)
+
+      available_currencies(locale).map do |code|
+        info = currency_info(locale, code)
+
+        [currency_option_label(info, format), code]
+      end
+    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 locale_options(format: :code)
+      validate_locale_options_format!(format)
+
+      available_locales.map do |locale|
+        [locale_option_label(locale, format), locale]
+      end
+    end
+
     def reset!(locale = nil)
       return @local_currency.delete(locale) if locale
 
@@ -34,6 +80,34 @@ module Num2words
       @local_currency    = {}
       @currency_warnings = true
     end
+
+    private
+
+    def validate_currency_options_format!(format)
+      return if %i[symbol code name].include?(format)
+
+      raise UnsupportedOptionError.new(name: :format, value: format)
+    end
+
+    def validate_locale_options_format!(format)
+      return if %i[code upcase].include?(format)
+
+      raise UnsupportedOptionError.new(name: :format, value: format)
+    end
+
+    def currency_option_label(info, format)
+      case format
+      when :code then info[:code].to_s
+      when :name then info[:major_unit].first
+      else [info[:code], info[:symbol]].compact.join(" — ")
+      end
+    end
+
+    def locale_option_label(locale, format)
+      label = locale.to_s
+
+      format == :upcase ? label.upcase : label
+    end
   end
 
   def self.config
@@ -52,6 +126,30 @@ 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.currency_options(locale = I18n.locale, format: :symbol)
+    config.currency_options(locale, format: format)
+  end
+
+  def self.available_locales
+    config.available_locales
+  end
+
+  def self.locale_options(format: :code)
+    config.locale_options(format: format)
+  end
+
   def self.currency_warnings
     config.currency_warnings
   end

data/lib/num2words/converter.rb

@@ -33,7 +33,7 @@ module Num2words
                  else nil
                  end
 
-        raise ArgumentError, "Unsupported input type: #{number.inspect}" if result.nil?
+        raise UnsupportedInputError, number if result.nil?
 
         apply_case(result, word_case)
       end
@@ -43,12 +43,15 @@ module Num2words
         word_case = opts[:word_case] || :downcase
         currency = (opts[:code] || Num2words.default_currency(locale)).to_s.upcase.to_sym
         minor = opts[:minor] || :always
+        strict = opts[:strict] || false
 
         validate_option!(:minor, minor, %i[always nonzero never])
 
         unless Num2words.available_currencies(locale).include?(currency)
+          raise UnsupportedCurrencyError.new(locale: locale, currency: currency) if strict
+
           warn I18n.t("num2words.warnings.currency_not_available",
-                      currency: currency, locale: locale) if Num2words.currency_warnings
+                      currency: currency, lang: locale, locale: locale) if Num2words.currency_warnings
           currency = Num2words.default_currency(locale)
         end
 
@@ -83,7 +86,7 @@ module Num2words
       def validate_option!(name, value, allowed_values)
         return if allowed_values.include?(value)
 
-        raise ArgumentError, "Unsupported #{name} option: #{value.inspect}"
+        raise UnsupportedOptionError.new(name: name, value: value)
       end
 
       def decimal_currency_amount(amount)
@@ -91,8 +94,8 @@ module Num2words
 
         normalized_amount = amount.is_a?(String) ? amount.tr(",", ".") : amount.to_s
         BigDecimal(normalized_amount)
-      rescue ArgumentError
-        raise ArgumentError, "Unsupported currency amount: #{amount.inspect}"
+      rescue ::ArgumentError
+        raise UnsupportedCurrencyAmountError, amount
       end
 
       def pluralize(number, singular, few, plural)
@@ -383,7 +386,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/errors.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Num2words
+  class Error < StandardError; end
+
+  class ArgumentError < ::ArgumentError; end
+
+  class UnsupportedInputError < ArgumentError
+    attr_reader :input
+
+    def initialize(input)
+      @input = input
+
+      super("Unsupported input type: #{input.inspect}")
+    end
+  end
+
+  class UnsupportedOptionError < ArgumentError
+    attr_reader :name, :value
+
+    def initialize(name:, value:)
+      @name = name
+      @value = value
+
+      super("Unsupported #{name} option: #{value.inspect}")
+    end
+  end
+
+  class UnsupportedCurrencyError < Error
+    attr_reader :locale, :currency
+
+    def initialize(locale:, currency:)
+      @locale = locale
+      @currency = currency
+
+      super("Currency #{currency} is not supported for locale #{locale}")
+    end
+  end
+
+  class UnsupportedCurrencyAmountError < ArgumentError
+    attr_reader :amount
+
+    def initialize(amount)
+      @amount = amount
+
+      super("Unsupported currency amount: #{amount.inspect}")
+    end
+  end
+end

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, num2words_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, unsupported_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.5.0"
 end

data/lib/num2words.rb

@@ -2,10 +2,13 @@
 
 require_relative "num2words/i18n"
 require_relative "num2words/version"
+require_relative "num2words/errors"
 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.5.0
 platform: ruby
 authors:
 - Ruslan Fedotov
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-07-04 00:00:00.000000000 Z
+date: 2026-07-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: i18n
@@ -113,12 +113,15 @@ 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
 - lib/num2words/console.rb
 - lib/num2words/converter.rb
 - lib/num2words/core_ext.rb
+- lib/num2words/errors.rb
 - lib/num2words/i18n.rb
 - lib/num2words/locales.rb
 - lib/num2words/locales/ar.rb
@@ -171,6 +174,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