num2words 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 82267cd5645c3767f5b34c5c7c54d6f997ee26f19425b86937ee021f747f19f4
-  data.tar.gz: 33da5152ce64b117d4d9e59f2f33a63331b037cea6562f3c6fafc77d6b9f9f71
+  metadata.gz: 288098773139982ac980a108f2bde3e3220c7b090cadd82cf8bada24053cce84
+  data.tar.gz: 0103cff58a94f52fd255aec76b83d4d487cd3767a7861ea25b2aff44c334797b
 SHA512:
-  metadata.gz: 9808bb66c09d3acecb944d1c1b37a3af17e46f758f6f500d5f618eecca798b3bf1e5b8bff415e23f9eb0d47804b672c1b509de2d89e77861dbc2fec2e88a8775
-  data.tar.gz: fac35c5117774db5619fc82d4153f8ce0495dcb13e27fdba3b4726e211f6a155788f4b1a035987f4a083ec7035ea0b6429bb8d3549d03c8c64906d1325731f81
+  metadata.gz: e9570c86cb884cd7abc6c8f16df6946d85ab8292c38a05a8567b48179a1aa04fdc3d4ecfb8252f358c35bcac4d093c5f236c04a63b16009ee04487b47d5fad3d
+  data.tar.gz: 613f2887655f9b5dcd1d9dcf927bf6d368337fa95abe2f2e7b909a87df7caf8d5ea88fda30e167ab22f9b624ef20bc68371ed916a52d239ea3156c9f6ef09bdb

data/.github/workflows/ci.yml

@@ -0,0 +1,40 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - main
+      - master
+  pull_request:
+
+jobs:
+  test:
+    name: Ruby ${{ matrix.ruby }}
+    runs-on: ubuntu-22.04
+
+    strategy:
+      fail-fast: false
+      matrix:
+        ruby:
+          - "2.7"
+          - "3.0"
+          - "3.1"
+          - "3.2"
+          - "3.3"
+          - "3.4"
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby }}
+          bundler-cache: true
+
+      - name: Run specs
+        run: bundle exec rspec
+
+      - name: Build gem
+        run: gem build num2words.gemspec

data/CHANGELOG.md

@@ -11,6 +11,45 @@
 
 ---
 
+## [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
+- Набор benchmark-проверок: `benchmark/converter_benchmark.rb` и `bundle exec rake benchmark`.
+- Справочник API: `docs/api.md` и `docs/api.ru.md`.
+- Документация по числовым лимитам: `docs/limits.md` и `docs/limits.ru.md`.
+- Rake-задачи для разработки и релизной проверки:
+  - `bundle exec rake spec`
+  - `bundle exec rake build`
+  - `bundle exec rake release:check`
+  - `bundle exec rake locales`
+  - `bundle exec rake currencies`
+
+### Fixed
+- Добавлена runtime-зависимость `bigdecimal` для совместимости с Ruby 3.4+.
+
+---
+
 ## [0.3.0] - 2026-06-27
 
 ### 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`.
 
 ---
@@ -143,6 +146,70 @@ Num2words.to_currency(BigDecimal("21.05"), :ru)
 - `minor: :always | :nonzero | :never` — вывод младшей денежной единицы.
 - `code: :USD` — выбор валюты для `to_currency`.
 
+Полная справка по API:
+
+- [English](docs/api.md)
+- [Русский](docs/api.ru.md)
+
+Ограничения числовых разрядов:
+
+- [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: "₽"
+#    }
+```
+
 ---
 
 ## Консоль
@@ -203,6 +270,11 @@ KZT MYR NOK PKR PLN RON RSD RUB SAR SEK THB TRY UAH USD VND
 
 После добавления локали стоит покрыть ее отдельным spec и добавить в `spec/currency_catalog_spec.rb`.
 
+Подробная инструкция:
+
+- [English](docs/locale_development.md)
+- [Русский](docs/locale_development.ru.md)
+
 ---
 
 ## Тестирование
@@ -211,6 +283,17 @@ KZT MYR NOK PKR PLN RON RSD RUB SAR SEK THB TRY UAH USD VND
 bundle exec rspec
 ```
 
+## Rake tasks
+
+```bash
+bundle exec rake spec
+bundle exec rake build
+bundle exec rake release:check
+bundle exec rake locales
+bundle exec rake currencies
+bundle exec rake benchmark
+```
+
 ---
 
 ## Roadmap

data/Rakefile

@@ -2,9 +2,45 @@
 
 require "bundler/gem_tasks"
 require "rspec/core/rake_task"
+require "yaml"
 
-# таска для запуска тестов
 RSpec::Core::RakeTask.new(:spec)
 
-# по умолчанию запускаем тесты
+task build: "build:clean"
+
+namespace :build do
+  task :clean do
+    Dir.glob("num2words-*.gem").each { |file| File.delete(file) }
+  end
+end
+
+namespace :release do
+  desc "Run tests and build the gem"
+  task check: [:spec, :build]
+end
+
+desc "Print supported locale codes"
+task :locales do
+  locales = Dir[File.expand_path("config/locales/*.yml", __dir__)]
+            .map { |file| File.basename(file, ".yml") }
+            .sort
+
+  puts locales.join(" ")
+end
+
+desc "Print supported currency codes"
+task :currencies do
+  currencies = YAML.load_file(File.expand_path("config/locales/ru.yml", __dir__))
+                   .dig("ru", "num2words", "currencies")
+                   .keys
+                   .sort
+
+  puts currencies.join(" ")
+end
+
+desc "Run converter benchmark"
+task :benchmark do
+  sh "ruby benchmark/converter_benchmark.rb"
+end
+
 task default: :spec

data/benchmark/converter_benchmark.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require "benchmark"
+require_relative "../lib/num2words"
+
+DEFAULT_ITERATIONS = 100
+
+def all_locales
+  Dir[File.expand_path("../config/locales/*.yml", __dir__)]
+    .map { |file| File.basename(file, ".yml").to_sym }
+    .sort
+end
+
+def selected_locales
+  requested = ENV.fetch("LOCALES", "").split(",").map(&:strip).reject(&:empty?).map(&:to_sym)
+  return all_locales if requested.empty?
+
+  unknown = requested - all_locales
+  abort "Unknown locales: #{unknown.join(', ')}" unless unknown.empty?
+
+  requested
+end
+
+def iterations
+  Integer(ENV.fetch("ITERATIONS", DEFAULT_ITERATIONS.to_s))
+rescue ArgumentError
+  abort "ITERATIONS must be an integer"
+end
+
+SCENARIOS = {
+  integer: ->(locale) { Num2words.to_words(123_456_789, locale) },
+  decimal: ->(locale) { Num2words.to_words("12345.67", locale) },
+  date: ->(locale) { Num2words.to_words("2024-08-21", locale) },
+  time: ->(locale) { Num2words.to_words("14:35:42", locale) },
+  datetime: ->(locale) { Num2words.to_words("2024-08-21 14:35:42", locale) },
+  currency: ->(locale) { Num2words.to_currency("12345.67", locale) }
+}.freeze
+
+def measure_scenarios(locales, iterations_count)
+  SCENARIOS.map do |name, callable|
+    calls = locales.size * iterations_count
+    elapsed = Benchmark.realtime do
+      iterations_count.times do
+        locales.each { |locale| callable.call(locale) }
+      end
+    end
+
+    [name, calls, elapsed]
+  end
+end
+
+def measure_slowest_locales(locales, iterations_count)
+  locales.map do |locale|
+    calls = SCENARIOS.size * iterations_count
+    elapsed = Benchmark.realtime do
+      iterations_count.times do
+        SCENARIOS.each_value { |callable| callable.call(locale) }
+      end
+    end
+
+    [locale, calls, elapsed]
+  end.sort_by { |(_, _, elapsed)| -elapsed }.first(10)
+end
+
+def print_table(headers, rows)
+  widths = headers.each_with_index.map do |header, index|
+    ([header.length] + rows.map { |row| row[index].to_s.length }).max
+  end
+
+  puts headers.each_with_index.map { |header, index| header.ljust(widths[index]) }.join("  ")
+  puts widths.map { |width| "-" * width }.join("  ")
+  rows.each do |row|
+    puts row.each_with_index.map { |value, index| value.to_s.ljust(widths[index]) }.join("  ")
+  end
+end
+
+locales = selected_locales
+iterations_count = iterations
+
+puts "num2words benchmark"
+puts "Locales: #{locales.join(', ')}"
+puts "Iterations per locale: #{iterations_count}"
+puts
+
+scenario_rows = measure_scenarios(locales, iterations_count).map do |name, calls, elapsed|
+  [name, calls, format("%.4f", elapsed), format("%.4f", (elapsed / calls) * 1000)]
+end
+
+print_table(["Scenario", "Calls", "Total, s", "ms/call"], scenario_rows)
+puts
+
+slowest_rows = measure_slowest_locales(locales, iterations_count).map do |locale, calls, elapsed|
+  [locale, calls, format("%.4f", elapsed), format("%.4f", (elapsed / calls) * 1000)]
+end
+
+print_table(["Slowest locale", "Calls", "Total, s", "ms/call"], slowest_rows)