num2words 0.1.4 → 0.1.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1809289bec98157e0b78b8bbe9f18b5fab8fa5f111293105e89b5747d866e43d
-  data.tar.gz: 1e5cfdd50831c7e9f75a8216488268564cda27b7972c70feca0a9d34c05c907b
+  metadata.gz: 7fbb8e0f384b3baf9ca9081c7d2c2095817d883b55796d48196f0bfd5a111fcc
+  data.tar.gz: 1dd172a547a50ac707b78cb626e1ae81b0af1a631e7313b30a48afe414dc5d26
 SHA512:
-  metadata.gz: 353353c876466e244bf2748073d7a3534a5ead257bc8d7f70f35d975a45762f4d2e0023d2cbf6e55136587974278093987fd2bba4d20ec972f33bedc9a1820c2
-  data.tar.gz: 8037de95f9896db0f4b00aa16710836de2337416c646dfc40900f3021a019aba9c04ae7f06842ebc6be73904aca9156258ee766992a861196a3274008ca13ab4
+  metadata.gz: 73b3f95666700ff9ad74b73c47f207becb76541d185dd0bdee98cbc89b2b33921a7b97651c844bc83029706cc52a84fde1cac98da8151bff8cfa1f77867cd1c2
+  data.tar.gz: 9008411287c518ecbc87c16426e9eaa9aebdb4f526a044a84a135df1c698cde43a16841cd9397faa97a890a3d1326df0945437a2b9112b608454e258f41b8f5f

data/CHANGELOG.md

@@ -15,6 +15,29 @@
 
 ---
 
+## [0.1.5] - 2025-08-22
+### Added
+- Расширение `Time#to_words`, возможность преобразовать строки с временем
+```ruby
+"14:35:42".to_words(:ru)
+# => "четырнадцать часов тридцать пять минут сорок две секунды"
+```
+- Добавлен параметр `short: true` для `time` и `datetime`
+Возвращает краткий вариант записи для time (`HH:MM`)
+```ruby
+"14:35:42".to_words(:ru, short: true)
+# => "четырнадцать часов тридцать пять минут" 
+```
+Возвращает краткий вариант записи для datetime на выбор - дата или время
+```ruby
+"2024-08-21 14:35:42".to_words(:ru, :time)
+# => "двадцать первого августа две тысячи двадцать четвёртого года"
+```
+- Поддержка перевода времени в разных форматах:
+  - `:hours_only` — только часы
+  - `:hours_minutes` — часы и минуты
+  - `:hours_minutes_seconds` — часы, минуты и секунды
+
 ## [0.1.4] - 2025-08-21
 ### Added
 - Расширение `String#to_words`, возможность преобразовать строки с датами

data/README.md

@@ -6,17 +6,20 @@
 
 ## ✨ Основные возможности
 
-- Поддержка **современных локалей** (включая русский и английский) через YAML-файлы `config/locales/*.yml`.
-- Удобные методы:
-    - `Num2words.to_words(123)`
-    - `Num2words.to_currency(12.34)`
-- Расширение `Integer` и `Float`:
-    - `123.to_words(:en)`
-    - `12.5.to_currency(locale: :ru)`
-- Короткая запись локали (символом): `123.to_words(:en)`
-- Lazy‑загрузка локалей (`lib/num2words/locales.rb`).
-- Унифицированный `Converter`, делегирующий логику нужной локали.
-- Разряды чисел и валюты настраиваются через I18n YAML.
+- Поддержка **чисел, времени, дат и валют**:
+  - `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`) → `"четырнадцать часов тридцать пять минут"`
+  - Форматы времени (`:hours_only`, `:hours_minutes`, `:hours_minutes_seconds`)
+  - Выбор локали: `:ru`, `:en` (из коробки), легко расширить YAML-файлами
+- Расширение **Integer**, **Float**, **Date**, **Time**, **DateTime** удобными методами.
+- Локали инициализируются только при обращении к ним (`lazy loading`) через `lib/num2words/locales.rb`.
+- Унифицированный `Converter`, делегирующий работу нужной локали.
+- Настраиваемые правила разрядов чисел и валют через I18n YAML.
+
 
 ---
 
@@ -40,21 +43,64 @@ gem install num2words
 
 ```ruby
 require "num2words"
+```
+
+### 🔢 Числа
+```ruby
+# Integer
+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"
+```
 
-# По умолчанию используется I18n.locale или fallback :ru
-Num2words.to_words(21)          # => "двадцать один"
-Num2words.to_currency(21.05)    # => "двадцать один рубль пять копеек"
+### 💰 Валюта
+```ruby
+21.05.to_currency(:ru)     # => "двадцать один рубль пять копеек"
+12.5.to_currency(:en)      # => "twelve dollars fifty cents"
+```
 
-# Short-style:
-123.to_words                    # "сто двадцать три"
-123.to_words(:en)               # "one hundred twenty three"
-123.to_words(locale: :en)       # "one hundred twenty three"
+### 📅 Дата
+```ruby
+"2024-08-21".to_words(:ru, :date)
+# => "двадцать первое августа две тысячи двадцать четвертого года"
 
-# Валюта:
-12.5.to_currency(:en)           # "twelve rubles fifty kopeks"
-12.5.to_currency(locale: :ru)   # "двенадцать рублей пятьдесят копеек"
+"2024-08-21".to_words(:en, :date)
+# => "the twenty-first of August, two thousand twenty four"
 ```
 
+### ⏰ Время
+```ruby
+"14:35:42".to_words(:ru, :time)
+# => "четырнадцать часов тридцать пять минут сорок две секунды"
+
+"14:35:42".to_words(:ru, :time, short: true) # или короткая запись: "14:35:42".to_words(:ru, :time, true)
+# => "четырнадцать часов тридцать пять минут"
+
+"14:35:42".to_words(:en, :time)
+# => "fourteen hours thirty five minutes forty two seconds"
+```
+
+### 🕓 Дата и время
+
+```ruby
+"2024-08-21 14:35:42".to_words(:ru)
+# =>  "двадцать первого августа две тысячи двадцать четвёртого года, четырнадцать часов тридцать пять минут сорок две секунды"
+
+"2024-08-21 14:35:42".to_words(:en)
+# => "the twenty-first of August, two thousand twenty four at fourteen hours thirty five minutes forty two seconds" 
+```
+
+### ⚙️ Опции
+
+- `locale: :ru | :en` — язык (по умолчанию берётся I18n.locale или :ru).
+- `:date, :time, :datetime` — формат преобразования для строк.
+- `short: true` — краткая форма для даты/времени.
+- `Num2words.to_words(number, locale: :en)` — универсальный способ вызова без расширения базовых классов.
+- `Num2words.to_currency(number)` — преобразование число в валюту.
+
 ### Консоль 💻
 
 Num2words поддерживает интерактивную консоль для быстрого тестирования.  
@@ -138,6 +184,20 @@ bin/console
 - YAML-файл: `config/locales/xx.yml`
 - Обёртка: `lib/num2words/locales/xx.rb`
 
+### 🌍 Поддержка локалей (ru / en)
+
+| Возможность                   | ru        | en         |
+| ----------------------------- | --------- | ---------- |
+| 🔢 Числа (Integer)            | ✔         | ✔          |
+| 🔢 Числа (Float)              | ✔         | ✔          |
+| 💰 Валюта                     | ✔ (рубли) | ✔ (rubles) |
+| 💰 Валюта (short)             | ✖         | ✖          |
+| 💱 Выбор валюты (USD/EUR/…)   | ✖         | ✖          |
+| 📅 Дата                       | ✔         | ✔          |
+| ⏰ Время                      | ✔         | ✔          |
+| 🕓 Дата и время               | ✔         | ✔          |
+| 📝 Краткая форма даты/времени | ✔         | ✔          |
+
 ---
 
 ## 🧪 Тестирование
@@ -149,8 +209,10 @@ bundle exec rspec
 ## 📌 Roadmap
 
 - [x] 🇬🇧 Поддержка английского языка
-- [ ] 💵 Поддержка других валют (USD, EUR)
-- [ ] 🔠 Опция выбора регистра (строчные/Прописные)
+- [x] 🔠 Опция выбора регистра (строчные/Прописные)
+- [x] ⏰ Краткая форма даты/времени
+- [ ] 💵 Поддержка других валют (USD, EUR и т.д)
+- [ ] 💰 Краткая форма валюты
 
 ---
 

data/config/locales/en.yml

@@ -40,12 +40,6 @@ en:
       100000000: ["hundred-millionth", "hundred-millionths", "hundred-millionths"]
       1000000000: ["billionth", "billionths", "billionths"]
 
-    date:
-      template:
-        default: "the %{day} of %{month}, %{year}"
-      months:
-        default: ["January", "February", "March", "April", "May", "June", "July", "August", "September", "October", "November", "December"]
-
     numbers:
       ordinals:
         default:
@@ -53,3 +47,19 @@ en:
                       "tenth", "eleventh", "twelfth", "thirteenth", "fourteenth" ,"fifteenth", "sixteenth", "seventeenth", "eighteenth", "nineteenth",
                       "twentieth", "twenty-first", "twenty-second", "twenty-third", "twenty-fourth", "twenty-fifth", "twenty-sixth", "twenty-seventh", "twenty-eighth", "twenty-ninth",
                       "thirtieth","thirty-first"]
+    datetime:
+      template: "%{date} at %{time}"
+    date:
+      template:
+        default: "the %{day} of %{month}, %{year}"
+      months:
+        default: [ "January", "February", "March", "April", "May", "June", "July", "August", "September", "October", "November", "December" ]
+    time:
+      template:
+        hours_only: "%{hours}"
+        hours_minutes: "%{hours} %{minutes}"
+        hours_minutes_seconds: "%{hours} %{minutes} %{seconds}"
+      words:
+        hour: ["hour", "hours", "hours"]
+        minute: ["minute", "minutes", "minutes"]
+        second: ["second", "seconds", "seconds"]

data/config/locales/ru.yml

@@ -35,14 +35,6 @@ ru:
       100000000: ["стомиллионная", "стомиллионные", "стомиллионных"]
       1000000000: ["миллиардная", "миллиардные", "миллиардных"]
 
-    date:
-      template:
-        default: "%{day} %{month} %{year} года"
-        nominative: "%{day} %{month} %{year} год"
-      months:
-        default: ["января", "февраля", "марта", "апреля", "мая", "июня", "июля", "августа", "сентября", "октября", "ноября", "декабря"]
-        nominative: ["января", "февраля", "марта", "апреля", "мая", "июня", "июля", "августа", "сентября", "октября", "ноября", "декабря"]
-
     numbers:
       ordinals:
         nominative:
@@ -63,3 +55,22 @@ ru:
                       "десятого", "одиннадцатого", "двенадцатого", "тринадцатого", "четырнадцатого", "пятнадцатого", "шестнадцатого", "семнадцатого", "восемнадцатого", "девятнадцатого",
                       "двадцатого", "двадцать первого", "двадцать второго", "двадцать третьего", "двадцать четвёртого", "двадцать пятого", "двадцать шестого", "двадцать седьмого", "двадцать восьмого", "двадцать девятого",
                       "тридцатого", "тридцать первого"]
+
+    datetime:
+      template: "%{date}, %{time}"
+    date:
+      template:
+        default: "%{day} %{month} %{year} года"
+        nominative: "%{day} %{month} %{year} год"
+      months:
+        default: [ "января", "февраля", "марта", "апреля", "мая", "июня", "июля", "августа", "сентября", "октября", "ноября", "декабря" ]
+        nominative: [ "января", "февраля", "марта", "апреля", "мая", "июня", "июля", "августа", "сентября", "октября", "ноября", "декабря" ]
+    time:
+      template:
+        hours_only: "%{hours}"
+        hours_minutes: "%{hours} %{minutes}"
+        hours_minutes_seconds: "%{hours} %{minutes} %{seconds}"
+      words:
+        hour: ["час", "часа", "часов"]
+        minute: ["минута", "минуты", "минут"]
+        second: ["секунда", "секунды", "секунд"]

data/lib/num2words/converter.rb

@@ -1,22 +1,29 @@
 # frozen_string_literal: true
 
 require "date"
+require "time"
 
 module Num2words
   class Converter
     class << self
       def to_words(number, *args, **opts)
-        locale    = args.first.is_a?(Symbol) ? args.first : opts[:locale] || I18n.default_locale
-        feminine  = opts[:feminine] || false
-        style     = opts[:style] || :fraction
-        word_case = opts[:word_case] || :default
+        locale      = args[0].is_a?(Symbol) ? args[0] : opts[:locale] || I18n.default_locale
+        type_only   = args[1].is_a?(Symbol) ? args[1] : opts[:only]
+        type_short  = args[2].is_a?(TrueClass) || args[2].is_a?(FalseClass) ? args[2] : opts[:short] || false
+
+        feminine    = opts[:feminine] || false
+        style       = opts[:style] || :fraction
+        word_case   = opts[:word_case] || :default
         date_format = opts[:format] || :default
+
         locale_data = Locales[locale]
 
         result = case detect_type(number)
                  when :float then to_words_fractional(number, locale, feminine, locale_data, style: style)
                  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 :time then to_words_time(number, locale, locale_data, short: type_short)
                  else nil
                  end
 
@@ -47,6 +54,7 @@ module Num2words
       private
 
       def pluralize(number, singular, few, plural)
+        number = number.abs
         return plural if (11..14).include?(number % 100)
 
         case number % 10
@@ -134,8 +142,10 @@ module Num2words
 
         day, month, year = [date.day, date.month, date.year]
 
+        return date.strftime("%d.%m.%Y") if format == :short
+
         months = locale_data::DATE[:months][format] || locale_data::DATE[:months][:default]
-        template = locale_data::TEMPLATE[format] || locale_data::TEMPLATE[:default]
+        template = locale_data::DATE_TEMPLATE[format] || locale_data::DATE_TEMPLATE[:default]
 
         raise ArgumentError, "Months not found for locale #{locale}" unless months
         raise ArgumentError, "Template not found for locale #{locale}" unless template
@@ -170,6 +180,64 @@ module Num2words
         to_words_integer(value, locale, false, locale_data)
       end
 
+      def to_words_time(time, locale, locale_data, format: :default, short: false)
+        time = Time.parse(time) if time.is_a?(String)
+
+        return time.strftime("%H:%M") if format == :short
+
+        words    = locale_data::TIME[:words]
+        template = locale_data::TIME_TEMPLATE
+
+        hours = [
+          to_words_integer(time.hour, locale, false, locale_data),
+          pluralize(time.hour, *words[:hour])
+        ].join(" ")
+        minutes = [
+          to_words_integer(time.min, locale, true, locale_data),
+          pluralize(time.min, *words[:minute])
+        ].join(" ")
+        seconds = [
+          to_words_integer(time.sec, locale, true, locale_data),
+          pluralize(time.sec, *words[:second])
+        ].join(" ")
+
+        format = if short
+                   time.min.zero? && time.sec.zero? ? :hours_only : :hours_minutes
+                 else
+                   format
+                 end
+
+        case format
+        when :hours_only
+          template[:hours_only] % { hours: hours }
+        when :hours_minutes
+          template[:hours_minutes] % { hours: hours, minutes: minutes }
+        when :hours_minutes_seconds, :default
+          template[:hours_minutes_seconds] % { hours: hours, minutes: minutes, seconds: seconds }
+        else
+          raise ArgumentError, "Unsupported time format: #{format}"
+        end
+      end
+
+
+      def to_words_datetime(datetime, locale, locale_data, format: :default, only: nil, short: false)
+        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)
+        time_part = to_words_time(datetime.to_time, locale, locale_data, format: time_format, short: short)
+
+        return date_part if only == :date
+        return time_part if only == :time
+
+        return "#{date_part}, #{time_part}" if short
+
+        template = locale_data::DATETIME_TEMPLATE
+        template % { date: date_part, time: time_part }
+      end
+
       def apply_case(text, word_case)
         case word_case
         when :upper then text.upcase
@@ -182,20 +250,30 @@ module Num2words
 
       def detect_type(value)
         case value
-        when Integer then :integer
-        when Float then :float
-        when Date, Time, ::DateTime then :date
+        when Integer   then :integer
+        when Float     then :float
+        when Date      then :date
+        when Time      then :time
+        when DateTime  then :datetime
         when String
-          return :integer if /\A-?\d+\z/.match?(value)
-          return :float if /\A-?\d+\.\d+\z/.match?(value)
+          return :integer if value.match?(/\A-?\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/)
+
+          # Форматы даты
+          return :date     if value.match?(/\A\d{1,2}[.\-]\d{1,2}[.\-]\d{2,4}\z/)
+          return :date     if value.match?(/\A\d{4}-\d{2}-\d{2}\z/)
+          return :datetime if value.match?(/\A\d{1,2}[.\-]\d{1,2}[.\-]\d{2,4}\s+\d{1,2}:\d{2}(:\d{2})?\z/)
+          return :datetime if value.match?(/\A\d{4}-\d{2}-\d{2}[ T]\d{2}:\d{2}(:\d{2})?([.,]\d+)?(Z|[+\-]\d{2}:?\d{2})?\z/)
 
           begin
-            Date.parse(value)
-            :date
+            date_time = DateTime.parse(value)
+            (date_time.hour != 0 || date_time.min != 0 || date_time.sec != 0) ? :datetime : :date
           rescue ArgumentError
             :string
           end
-        else :unknown
+        else
+          :unknown
         end
       end
     end

data/lib/num2words/core_ext.rb

@@ -31,3 +31,15 @@ class Date
     Num2words::Converter.to_words(self.strftime("%d.%m.%Y"), *args, **opts)
   end
 end
+
+class Time
+  def to_words(*args, **opts)
+    Num2words::Converter.to_words(self.strftime("%H:%M:%S"), *args, **opts)
+  end
+end
+
+class DateTime
+  def to_words(*args, **opts)
+    Num2words::Converter.to_words(self.strftime("%d.%m.%Y %H:%M:%S"), *args, **opts)
+  end
+end

data/lib/num2words/locales/en.rb

@@ -17,7 +17,10 @@ module Num2words
       GRAMMAR = I18n.t("num2words.grammar", locale: :en)
 
       DATE = I18n.t("num2words.date", locale: :en)
-      TEMPLATE = I18n.t("num2words.date.template", locale: :en)
+      DATE_TEMPLATE = I18n.t("num2words.date.template", locale: :en)
+      TIME = I18n.t("num2words.time", locale: :en)
+      TIME_TEMPLATE = I18n.t("num2words.time.template", locale: :en)
+      DATETIME_TEMPLATE = I18n.t("num2words.datetime.template", locale: :en)
 
       ORDINALS = I18n.t("num2words.numbers.ordinals", locale: :en)
     end

data/lib/num2words/locales/ru.rb

@@ -17,7 +17,10 @@ module Num2words
       GRAMMAR = I18n.t("num2words.grammar", locale: :ru)
 
       DATE = I18n.t("num2words.date", locale: :ru)
-      TEMPLATE = I18n.t("num2words.date.template", locale: :ru)
+      DATE_TEMPLATE = I18n.t("num2words.date.template", locale: :ru)
+      TIME = I18n.t("num2words.time", locale: :ru)
+      TIME_TEMPLATE = I18n.t("num2words.time.template", locale: :ru)
+      DATETIME_TEMPLATE = I18n.t("num2words.datetime.template", locale: :ru)
 
       ORDINALS = I18n.t("num2words.numbers.ordinals", locale: :ru)
     end

data/lib/num2words/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: num2words
 version: !ruby/object:Gem::Version
-  version: 0.1.4
+  version: 0.1.5
 platform: ruby
 authors:
 - Ruslan Fedotov
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-08-21 00:00:00.000000000 Z
+date: 2025-08-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: i18n