num2words 0.1.6 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9e2d482146b9f5057e198d38698c764d1db57dcf8ab5d026d5b5d69ed0e05ad2
-  data.tar.gz: 6ca3c5f914998c0fbbf8705effd13030ec2744bfb44d7bba071f62e40bcddb0e
+  metadata.gz: fbd7bda19d94f161e928ec326ce532c9c301746daaa371a041b859aa7262d4d9
+  data.tar.gz: ec621319e9ce5de5657c01d87c9b91cb88da31516cd06c07629924558e5c6017
 SHA512:
-  metadata.gz: bb5de9862a6a78186df96c583a39dd81213d2178613fd9f485b4e2ef131c1cd2409a442b8d12ac241cf69172f5195cda2c2234f8e71fda39cc8b8de6d998e3ea
-  data.tar.gz: 8eebe4f2894050e4e16ffdb086984e2c35dd790ad9d91c86eba045814f9a73be974e05bde26728397c230b4da58928d37174e9209f5929a326575e7cad13a30e
+  metadata.gz: '092432a7d992343146c93337af17af5ea595ab06fff83793f81813ba55c7c4282b66e8bcc0598e82eba7db43e63131b1fba0f63332ede4984b10ef606e77698b'
+  data.tar.gz: dfefff68054582dd62771c9fa87b2ff21996a73ae0d4b0b219b67178a06a8c393ac20ef5f8029bf5f32c77c2ef36bb66760d743c528e066f361ba8592f431013

data/CHANGELOG.md

@@ -9,6 +9,49 @@
 
 ## [Unreleased]
 
+---
+
+## [0.2.0] - 2026-05-31
+
+### Added
+- Поддержка строковых дробей с точкой и запятой:
+```ruby
+Num2words.to_words("3.5", :ru)
+Num2words.to_words("3,5", :ru)
+```
+- Опция `joiner: :and` для разговорного соединителя в дробях:
+```ruby
+Num2words.to_words(0.5, :ru, joiner: :and)
+# => "ноль и пять десятых"
+```
+- Опция `date_case: :genitive` для дат в контексте "когда?":
+```ruby
+Num2words.to_words("2024-08-21", :ru, date_case: :genitive)
+# => "двадцать первого августа две тысячи двадцать четвёртого года"
+```
+- Опция `minor:` для управления выводом младшей денежной единицы:
+  - `:always` — всегда выводить копейки/центы;
+  - `:nonzero` — выводить только ненулевую младшую единицу;
+  - `:never` — не выводить младшую единицу.
+- Поддержка строковых сумм и `BigDecimal` в `to_currency`:
+```ruby
+Num2words.to_currency("21,05", :ru)
+Num2words.to_currency(BigDecimal("21.05"), :ru)
+```
+- Команда `num2words-console` для быстрого запуска интерактивной консоли после установки гема.
+
+### Changed
+- Русские даты по умолчанию выводят день в именительном падеже:
+```ruby
+Num2words.to_words("2024-08-21", :ru)
+# => "двадцать первое августа две тысячи двадцать четвёртого года"
+```
+
+### Fixed
+- `DateTime` теперь корректно определяется как дата и время, а не только как дата.
+- Добавлена валидация опций `joiner`, `date_case` и `minor`.
+
+### Planned
 - Добавление новых локалей (планируется расширение поддерживаемых языков).
 - Оптимизация производительности при больших числах.
 - Улучшения документации.

data/README.md

@@ -7,12 +7,12 @@
 ## ✨ Основные возможности
 
 - Поддержка **чисел, времени, дат и валют**:
-  - `Integer` → `123.to_words(:ru)` → `"сто двадцать три"`
-  - `Float` → `12.5.to_words(:en)` → `"twelve and five tenths"`
-  - `Time / DateTime` → `"2024-08-21 14:35:42".to_words(:ru, :time)` → `"четырнадцать часов тридцать пять минут сорок две секунды"`
-  - `Float.to_currency` → `12.5.to_currency(:ru)` → `"двенадцать рублей пятьдесят копеек"`
+  - `Integer` -> `123.to_words(:ru)` -> `"сто двадцать три"`
+  - `Float` -> `12.5.to_words(:en)` -> `"twelve and five tenths"`
+  - `Time / DateTime` -> `"2024-08-21 14:35:42".to_words(:ru, :time)` -> `"четырнадцать часов тридцать пять минут сорок две секунды"`
+  - `Float.to_currency` -> `12.5.to_currency(:ru)` -> `"двенадцать рублей пятьдесят копеек"`
 - Кастомизация вывода:
-  - Краткая форма (`short: true`) → `"четырнадцать часов тридцать пять минут"`
+  - Краткая форма (`short: true`) -> `"четырнадцать часов тридцать пять минут"`
   - Форматы времени (`:hours_only`, `:hours_minutes`, `:hours_minutes_seconds`)
   - Выбор локали: `:ru`, `:en` (из коробки), легко расширить YAML-файлами
 - Расширение **Integer**, **Float**, **Date**, **Time**, **DateTime** удобными методами.
@@ -48,24 +48,54 @@ require "num2words"
 ### 🔢 Числа
 ```ruby
 # Integer
-123.to_words(:ru)          # => "сто двадцать три"
-123.to_words(:en)          # => "one hundred twenty three"
+123.to_words(:ru)
+# => "сто двадцать три"
+
+123.to_words(:en)
+# => "one hundred twenty three"
 
 # Float
-45.67.to_words(:ru)        # => "сорок пять целых шестьдесят семь сотых"
-45.67.to_words(:en)        # => "forty five and sixty seven hundredths"
+45.67.to_words(:ru)
+# => "сорок пять целых шестьдесят семь сотых"
+
+"45,67".to_words(:ru)
+# => "сорок пять целых шестьдесят семь сотых"
+
+45.67.to_words(:ru, joiner: :and)
+# => "сорок пять и шестьдесят семь сотых"
+
+45.67.to_words(:en)
+# => "forty five and sixty seven hundredths"
 ```
 
 ### 💰 Валюта
 ```ruby
-21.05.to_currency(:ru)     # => "двадцать один рубль пять копеек"
-12.5.to_currency(:en)      # => "twelve dollars fifty cents"
+21.05.to_currency(:ru)
+# => "двадцать один рубль пять копеек"
+
+"21,05".to_currency(:ru)
+# => "двадцать один рубль пять копеек"
+
+Num2words.to_currency(BigDecimal("21.05"), :ru)
+# => "двадцать один рубль пять копеек"
+
+1.to_currency(:ru, minor: :nonzero)
+# => "один рубль"
+
+1.25.to_currency(:ru, minor: :never)
+# => "один рубль"
+
+12.5.to_currency(:en)
+# => "twelve dollars fifty cents"
 ```
 
 ### 📅 Дата
 ```ruby
 "2024-08-21".to_words(:ru, :date)
-# => "двадцать первое августа две тысячи двадцать четвертого года"
+# => "двадцать первое августа две тысячи двадцать четвёртого года"
+
+"2024-08-21".to_words(:ru, :date, date_case: :genitive)
+# => "двадцать первого августа две тысячи двадцать четвёртого года"
 
 "2024-08-21".to_words(:en, :date)
 # => "the twenty-first of August, two thousand twenty four"
@@ -87,6 +117,9 @@ require "num2words"
 
 ```ruby
 "2024-08-21 14:35:42".to_words(:ru)
+# =>  "двадцать первое августа две тысячи двадцать четвёртого года, четырнадцать часов тридцать пять минут сорок две секунды"
+
+"2024-08-21 14:35:42".to_words(:ru, date_case: :genitive)
 # =>  "двадцать первого августа две тысячи двадцать четвёртого года, четырнадцать часов тридцать пять минут сорок две секунды"
 
 "2024-08-21 14:35:42".to_words(:en)
@@ -98,6 +131,8 @@ require "num2words"
 - `locale: :ru | :en` — язык (по умолчанию берётся I18n.locale или :ru).
 - `:date, :time, :datetime` — формат преобразования для строк.
 - `short: true` — краткая форма для даты/времени.
+- `joiner: :and` — разговорный соединитель для дробей: `"ноль и пять десятых"` вместо `"ноль целых пять десятых"`.
+- `date_case: :genitive` — родительный падеж дня для дат в контексте “когда?”.
 - `Num2words.to_words(number, locale: :en)` — универсальный способ вызова без расширения базовых классов.
 - `Num2words.to_currency(number)` — преобразование число в валюту.
 
@@ -106,18 +141,24 @@ require "num2words"
 Num2words поддерживает интерактивную консоль для быстрого тестирования.  
 Это удобно при работе с разными числами и языками.
 
-#### Запуск консоли
+#### Запуск консоли из репозитория
 
 ```bash
 bin/console
 ```
 
+#### Запуск консоли после установки гема
+
+```bash
+num2words-console
+```
+
 После запуска появится приветственное сообщение:
 
 ```bash
-👋 Добро пожаловать в консоль num2words!
-Попробуйте: Num2words.to_words(2025)
------------------------------------------------------
+Добро пожаловать в консоль num2words!
+Можете использовать: Num2words.to_words(2025)
+-------------------------------------------------------------
 ```
 
 👉 Это позволяет проверять работу гема без написания отдельных скриптов.

data/bin/console

@@ -3,18 +3,6 @@
 
 require "bundler/setup"
 require "num2words"
+require "num2words/console"
 
-# You can add fixtures and/or initialization code here to make experimenting
-# with your gem easier. You can also use a different console, if you like.
-
-# (If you use this, don't forget to add pry to your Gemfile!)
-# require "pry"
-# Pry.start
-
-# Красивое приветствие
-puts "👋 Добро пожаловать в консоль num2words!"
-puts "Можете использовать: Num2words.to_words(#{Time.now.year})"
-puts "-------------------------------------------------------------"
-
-require "irb"
-IRB.start(__FILE__)
+Num2words::Console.start

data/config/locales/ru.yml

@@ -48,6 +48,10 @@ ru:
                       "десятого", "одиннадцатого", "двенадцатого", "тринадцатого", "четырнадцатого", "пятнадцатого", "шестнадцатого", "семнадцатого", "восемнадцатого", "девятнадцатого",
                       "двадцатого", "двадцать первого", "двадцать второго", "двадцать третьего", "двадцать четвёртого", "двадцать пятого", "двадцать шестого", "двадцать седьмого", "двадцать восьмого", "двадцать девятого",
                       "тридцатого", "тридцать первого"]
+          neuter: ["первое", "второе", "третье", "четвёртое", "пятое", "шестое", "седьмое", "восьмое", "девятое",
+                   "десятое", "одиннадцатое", "двенадцатое", "тринадцатое", "четырнадцатое", "пятнадцатое", "шестнадцатое", "семнадцатое", "восемнадцатое", "девятнадцатое",
+                   "двадцатое", "двадцать первое", "двадцать второе", "двадцать третье", "двадцать четвёртое", "двадцать пятое", "двадцать шестое", "двадцать седьмое", "двадцать восьмое", "двадцать девятое",
+                   "тридцатое", "тридцать первое"]
 
     datetime:
       template: "%{date}, %{time}"

data/exe/num2words-console

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "num2words"
+require "num2words/console"
+
+Num2words::Console.start

data/lib/num2words/console.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Num2words
+  module Console
+    module_function
+
+    def start
+      puts "Добро пожаловать в консоль num2words!"
+      puts "Можете использовать: Num2words.to_words(#{Time.now.year})"
+      puts "-------------------------------------------------------------"
+
+      require "irb"
+      IRB.start(__FILE__)
+    end
+  end
+end

data/lib/num2words/converter.rb

@@ -2,6 +2,7 @@
 
 require "date"
 require "time"
+require "bigdecimal"
 
 module Num2words
   class Converter
@@ -15,14 +16,19 @@ module Num2words
         style = opts[:style] || :fraction
         word_case = opts[:word_case] || :default
         date_format = opts[:format] || :default
+        date_case = opts[:date_case] || :default
+        joiner = opts[:joiner] || :default
+
+        validate_option!(:date_case, date_case, %i[default genitive])
+        validate_option!(:joiner, joiner, %i[default and])
 
         locale_data = Locales[locale]
 
         result = case detect_type(number)
-                 when :float then to_words_fractional(number, locale, feminine, locale_data, style: style)
+                 when :float then to_words_fractional(number, locale, feminine, locale_data, style: style, joiner: joiner)
                  when :integer then to_words_integer(number, locale, feminine, locale_data)
-                 when :datetime then to_words_datetime(number, locale, locale_data, format: date_format, only: type_only, short: type_short)
-                 when :date then to_words_date(number, locale, locale_data, format: date_format)
+                 when :datetime then to_words_datetime(number, locale, locale_data, format: date_format, only: type_only, short: type_short, date_case: date_case)
+                 when :date then to_words_date(number, locale, locale_data, format: date_format, date_case: date_case)
                  when :time then to_words_time(number, locale, locale_data, short: type_short)
                  else nil
                  end
@@ -36,6 +42,9 @@ module Num2words
         locale = args.first.is_a?(Symbol) ? args.first : opts[:locale] || I18n.default_locale
         word_case = opts[:word_case] || :downcase
         currency = (opts[:code] || Num2words.default_currency(locale)).to_s.upcase.to_sym
+        minor = opts[:minor] || :always
+
+        validate_option!(:minor, minor, %i[always nonzero never])
 
         unless Num2words.available_currencies(locale).include?(currency)
           warn I18n.t("num2words.warnings.currency_not_available",
@@ -46,22 +55,44 @@ module Num2words
         currency_data = I18n.t("num2words.currencies.#{currency}", locale: locale) or
           raise ArgumentError, "Currency #{currency} not defined in locale #{locale}"
 
-        major_value, minor_value = sprintf('%.2f', amount.abs).split('.').map(&:to_i)
+        decimal_amount = decimal_currency_amount(amount)
+        major_value, minor_value = format('%.2f', decimal_amount.abs).split('.').map(&:to_i)
 
         parts = [
           to_words(major_value, locale: locale),
-          pluralize(major_value, *currency_data[:major_unit]),
-          to_words(minor_value, locale: locale, feminine: true),
-          pluralize(minor_value, *currency_data[:minor_unit])
+          pluralize(major_value, *currency_data[:major_unit])
         ]
 
-        parts.unshift(Locales[locale]::GRAMMAR[:minus] || "minus") if amount.negative?
+        include_minor = minor == :always || (minor == :nonzero && minor_value.positive?)
+        if include_minor
+          parts.concat([
+            to_words(minor_value, locale: locale, feminine: true),
+            pluralize(minor_value, *currency_data[:minor_unit])
+          ])
+        end
+
+        parts.unshift(Locales[locale]::GRAMMAR[:minus] || "minus") if decimal_amount.negative?
 
         apply_case(parts.join(" ").strip, word_case)
       end
 
       private
 
+      def validate_option!(name, value, allowed_values)
+        return if allowed_values.include?(value)
+
+        raise ArgumentError, "Unsupported #{name} option: #{value.inspect}"
+      end
+
+      def decimal_currency_amount(amount)
+        return amount if amount.is_a?(BigDecimal)
+
+        normalized_amount = amount.is_a?(String) ? amount.tr(",", ".") : amount.to_s
+        BigDecimal(normalized_amount)
+      rescue ArgumentError
+        raise ArgumentError, "Unsupported currency amount: #{amount.inspect}"
+      end
+
       def pluralize(number, singular, few, plural)
         number = number.abs
         return plural if (11..14).include?(number % 100)
@@ -94,15 +125,17 @@ module Num2words
         words.compact
       end
 
-      def to_words_fractional(number, locale, feminine, locale_data, style: :fraction)
+      def to_words_fractional(number, locale, feminine, locale_data, style: :fraction, joiner: :default)
         minus_word = locale_data::GRAMMAR[:minus] || "minus"
-        conjunction_word = locale_data::GRAMMAR[:conjunction] || "and"
+        conjunction_word = joiner.to_sym == :and ? "и" : locale_data::GRAMMAR[:conjunction] || "and"
         default_fraction = locale_data::GRAMMAR[:default_fraction] || "parts"
         fractions_data = locale_data::FRACTIONS || {}
 
-        sign_word = number.negative? ? minus_word : ""
+        negative = number.is_a?(String) ? number.start_with?("-") : number.negative?
+        sign_word = negative ? minus_word : ""
 
-        integer_string, fraction_string = number.abs.to_s.split('.', 2)
+        absolute_number = number.is_a?(String) ? number.sub(/\A-/, "").tr(",", ".") : number.abs.to_s
+        integer_string, fraction_string = absolute_number.split('.', 2)
         integer_value = integer_string.to_i
 
         return to_words_integer(integer_value, locale, feminine, locale_data) if fraction_string.to_i.zero?
@@ -130,6 +163,10 @@ module Num2words
       def to_words_integer(number, locale, feminine, locale_data)
         integer_value = Integer(number)
 
+        minus_word = locale_data::GRAMMAR[:minus] || "minus"
+        negative = integer_value.negative?
+        integer_value = integer_value.abs
+
         return (feminine ? locale_data::ONES_FEM[0] : locale_data::ONES_MASC[0]) if integer_value.zero?
 
         groups = integer_value.to_s
@@ -143,10 +180,11 @@ module Num2words
           words.concat triple_to_words(group_value, scale_index, locale_data, feminine: group_feminine)
         end
 
+        words.unshift(minus_word) if negative
         words.join(" ")
       end
 
-      def to_words_date(date, locale, locale_data, format: :default)
+      def to_words_date(date, locale, locale_data, format: :default, date_case: :default)
         date = Date.parse(date.to_s) unless date.is_a?(Date)
 
         day, month, year = [date.day, date.month, date.year]
@@ -159,7 +197,8 @@ module Num2words
         raise ArgumentError, "Months not found for locale #{locale}" unless months
         raise ArgumentError, "Template not found for locale #{locale}" unless template
 
-        day_words = to_words_ordinal(day, locale, format, locale_data, gender: :neuter)
+        day_gender = date_case.to_sym == :genitive ? :masculine : :neuter
+        day_words = to_words_ordinal(day, locale, format, locale_data, gender: day_gender)
         month_words = months[month - 1]
         year_words = to_words_ordinal(year, locale, format, locale_data)
 
@@ -173,7 +212,7 @@ module Num2words
         gender_data = ordinals[gender] || ordinals[:masculine]
         raise ArgumentError, "Gender #{gender} not found for locale #{locale}, format #{format}" unless gender_data
 
-        return gender_data[value - 1] if gender_data[value]
+        return gender_data[value - 1] if value.between?(1, gender_data.length)
 
         if value > 31
           thousands = (value / 100) * 100
@@ -228,13 +267,13 @@ module Num2words
         end
       end
 
-      def to_words_datetime(datetime, locale, locale_data, format: :default, only: nil, short: false)
+      def to_words_datetime(datetime, locale, locale_data, format: :default, only: nil, short: false, date_case: :default)
         datetime = DateTime.parse(datetime) if datetime.is_a?(String)
 
         date_format = short && only == :date ? :short : format
         time_format = short && only == :time ? :short : :default
 
-        date_part = to_words_date(datetime.to_date, locale, locale_data, format: date_format)
+        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)
 
         return date_part if only == :date
@@ -260,12 +299,12 @@ module Num2words
         case value
         when Integer then :integer
         when Float then :float
+        when DateTime then :datetime
         when Date then :date
         when Time then :time
-        when DateTime then :datetime
         when String
           return :integer if value.match?(/\A-?\d+\z/)
-          return :float if value.match?(/\A-?\d+\.\d+\z/)
+          return :float if value.match?(/\A-?\d+[\.,]\d+\z/)
           return :time if value.match?(/\A\d{1,2}:\d{2}(:\d{2})?\z/)
 
           # Форматы даты

data/lib/num2words/version.rb

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

data/num2words.gemspec

@@ -25,5 +25,5 @@ Gem::Specification.new do |spec|
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
 
-  spec.add_runtime_dependency "i18n", ">= 1.8"
+  spec.add_runtime_dependency "i18n", "~> 1.8"
 end

metadata

@@ -1,34 +1,35 @@
 --- !ruby/object:Gem::Specification
 name: num2words
 version: !ruby/object:Gem::Version
-  version: 0.1.6
+  version: 0.2.0
 platform: ruby
 authors:
 - Ruslan Fedotov
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-09-19 00:00:00.000000000 Z
+date: 2026-05-31 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: i18n
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '1.8'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '1.8'
 description: Converts integers and amounts to Russian words with proper gender and
   plural forms.
 email:
 - progruson@gmail.com
-executables: []
+executables:
+- num2words-console
 extensions: []
 extra_rdoc_files: []
 files:
@@ -90,8 +91,10 @@ files:
 - config/locales/ur.yml
 - config/locales/vi.yml
 - config/locales/zh.yml
+- 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/i18n.rb
@@ -170,7 +173,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.6
+rubygems_version: 3.1.2
 signing_key:
 specification_version: 4
 summary: Russian number-to-words with currency (руб/коп) and correct declensions