num2words 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 288098773139982ac980a108f2bde3e3220c7b090cadd82cf8bada24053cce84
-  data.tar.gz: 0103cff58a94f52fd255aec76b83d4d487cd3767a7861ea25b2aff44c334797b
+  metadata.gz: 131bb24135ba3f8c1345bbd7ccf5c3b27d79b9c9776d7e0ec45b259960be1dbd
+  data.tar.gz: 27a943ef2bbaae410ae51d1aca3fe009375f68632e1928b4639a570919619c25
 SHA512:
-  metadata.gz: e9570c86cb884cd7abc6c8f16df6946d85ab8292c38a05a8567b48179a1aa04fdc3d4ecfb8252f358c35bcac4d093c5f236c04a63b16009ee04487b47d5fad3d
-  data.tar.gz: 613f2887655f9b5dcd1d9dcf927bf6d368337fa95abe2f2e7b909a87df7caf8d5ea88fda30e167ab22f9b624ef20bc68371ed916a52d239ea3156c9f6ef09bdb
+  metadata.gz: 3601c493e2cf40b2a908daca5980f79c95933316fa2a87393306c479919ec795c15af731e2eb075fd92b9aa61a97fd72badaa575723d8201e5093cecc89e6d88
+  data.tar.gz: 5000cdf5a8fcaa4cf2af57cb2ad7640e111f9f2a1eb7fdf94783ac19a76a2cd8aedd2ef44cbecd7eee9647d3bb1be064f2d70f711634aa3de679f83ede17a47d

data/CHANGELOG.md

@@ -11,6 +11,17 @@
 
 ---
 
+## [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

data/README.md

@@ -84,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)
 # => "один рубль"
 
@@ -145,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:
 
@@ -208,10 +212,36 @@ Num2words.default_currency_info(:ru)
 #      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.
@@ -410,6 +419,27 @@ Num2words.default_currency_info(:ru)
 #    }
 ```
 
+### `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.
@@ -419,6 +449,23 @@ 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.
@@ -446,28 +493,37 @@ 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

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`
 
 Управляет выводом младшей денежной единицы.
@@ -410,6 +419,27 @@ Num2words.default_currency_info(:ru)
 #    }
 ```
 
+### `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`
 
 Возвращает список поддерживаемых локалей.
@@ -419,6 +449,23 @@ 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 при запросе валюты, недоступной для локали.
@@ -446,28 +493,37 @@ 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
 ```
 
 ## Документация для разработки

data/docs/rails.md

@@ -89,6 +89,8 @@ Payment.new(locale: "xx").valid?
 
 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:
@@ -99,6 +101,15 @@ 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

data/docs/rails.ru.md

@@ -89,6 +89,8 @@ Payment.new(locale: "xx").valid?
 
 Валидные значения проверяются через `Num2words.available_locales`.
 
+Сообщения ошибок для `unsupported_currency` и `unsupported_locale` уже добавлены в locale files гема. Их можно переопределить в Rails-приложении стандартным способом через `errors.messages`.
+
 ## Metadata API
 
 Для форм, select-полей и настроек можно использовать публичные методы metadata API:
@@ -99,6 +101,15 @@ 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 %>
 ```
 
 ## Ручное использование

data/lib/num2words/config.rb

@@ -49,12 +49,30 @@ module Num2words
       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
 
@@ -62,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
@@ -92,10 +138,18 @@ module Num2words
     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)

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/validators/currency_validator.rb

@@ -12,7 +12,7 @@ module Num2words
 
           return if Num2words.currency_available?(locale, currency)
 
-          record.errors.add(attribute, :unsupported_currency, currency: currency, locale: locale)
+          record.errors.add(attribute, :unsupported_currency, currency: currency, num2words_locale: locale)
         end
 
         private

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

@@ -11,7 +11,7 @@ module Num2words
 
           return if Num2words.available_locales.include?(locale)
 
-          record.errors.add(attribute, :unsupported_locale, locale: locale)
+          record.errors.add(attribute, :unsupported_locale, unsupported_locale: locale)
         end
       end
     end

data/lib/num2words/version.rb

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

data/lib/num2words.rb

@@ -2,6 +2,7 @@
 
 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"

metadata

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