human_number 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 7acf2929c3de8758cfbf05e32ec42a46c87ae2afb582f6fbbf0aeb8bcf6f9ede
+  data.tar.gz: 2ef9d5f7c7381ab0f13e1b4ec6936a9c55c16762fd87090a51810c1c7b6054af
+SHA512:
+  metadata.gz: db81f31340cffd25a57aaaa6ecfe465231342c7cdefc420c37aa6855b23fe34abe4e06fddce0d5d1b0fd453115b01fb5a1718fdc0a54340c713e860bd4a2ae80
+  data.tar.gz: 2030078ab34f98cac34b8588c20cd240f9065f2be0dcfaf4d750e8123d4d232fcdc8b9fdac1588d8f3bbc5344b13bc4f4b4cdb7965b69c387cec1fef9c5e8bf5

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,63 @@
+AllCops:
+  TargetRubyVersion: 3.1
+  NewCops: enable
+  SuggestExtensions: false
+  Exclude:
+    - 'vendor/**/*'
+    - 'bin/**/*'
+    - 'tmp/**/*'
+    - 'db/schema.rb'
+    - 'node_modules/**/*'
+
+# Layout and formatting
+Layout/LineLength:
+  Max: 120
+  AllowedPatterns: 
+    - '\A\s*#.*\z'  # Allow long comments
+
+Layout/MultilineMethodCallIndentation:
+  EnforcedStyle: indented
+
+# Style preferences for open source
+Style/Documentation:
+  Enabled: false
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+Style/StringLiteralsInInterpolation:
+  EnforcedStyle: double_quotes
+
+Style/HashSyntax:
+  EnforcedStyle: ruby19
+
+Style/TrailingCommaInArrayLiteral:
+  EnforcedStyleForMultiline: consistent_comma
+
+Style/TrailingCommaInHashLiteral:
+  EnforcedStyleForMultiline: consistent_comma
+
+Style/FrozenStringLiteralComment:
+  Enabled: true
+  EnforcedStyle: always
+
+# Metrics
+Metrics/BlockLength:
+  Exclude:
+    - 'spec/**/*'
+    - '*.gemspec'
+    - 'Rakefile'
+
+Metrics/ModuleLength:
+  Max: 300
+
+Metrics/ClassLength:
+  Max: 300
+
+Metrics/MethodLength:
+  Max: 20
+
+Metrics/ParameterLists:
+  Max: 6
+
+# RSpec rules removed - using basic RuboCop only

data/CHANGELOG.md

@@ -0,0 +1,90 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2024-01-31
+
+### Added
+
+#### Core Number Formatting
+- **Human-readable number formatting** with intelligent, culturally-appropriate abbreviations
+- **Three cultural number systems** automatically selected by locale:
+  - **Western System**: K/M/B/T (thousand/million/billion/trillion) for English, German, French, Spanish, Italian, Portuguese, Russian, Dutch, Swedish, Danish, Norwegian
+  - **East Asian System**: 천/만/억/조 (Korean) and 千/万/億/兆 (Japanese/Chinese) for ko, ja, zh, zh-CN, zh-TW locales
+  - **Indian System**: thousand/lakh/crore for Hindi, Urdu, Bengali, and Indian English (hi, ur, bn, en-IN)
+
+#### Currency Formatting
+- **ISO 4217 currency code support** with native locale precision rules
+- **Cross-locale consistency**: USD always shows 2 decimals, JPY shows 0, regardless of display locale
+- **40+ currency mappings** with native locale associations for accurate formatting
+- **Human-readable currency formatting** combining cultural abbreviations with currency symbols
+
+#### API Methods
+- `HumanNumber.human_number(number, **options)` - Formats numbers with cultural abbreviations
+- `HumanNumber.currency(number, currency_code:, locale:)` - Standard currency formatting
+- `HumanNumber.human_currency(number, currency_code:, locale:, **options)` - Currency with abbreviations
+
+#### Formatting Options
+- **Precision control**: `max_digits` parameter for significant digit control (1-4 digits or nil for complete mode)
+- **Unit preferences**: `abbr_units` to choose between abbreviated (K/M) vs full words (thousand/million)
+- **Minimum thresholds**: `min_unit` to prevent abbreviation below specified amounts
+- **Zero trimming**: `trim_zeros` to control trailing decimal zero display
+- **Complete mode**: `max_digits: nil` shows full breakdown across multiple units (e.g., "1M 234K 567")
+
+#### Rails Integration
+- **Automatic Rails detection** and helper loading via Railtie
+- **View helpers**: `human_number`, `currency`, `human_currency` with Rails-friendly parameter handling
+- **I18n integration**: Automatic locale detection from `I18n.locale`
+- **Legacy compatibility**: `number_to_human_size` alias for backward compatibility
+
+#### Locale Data System
+- **Hybrid locale approach**: Combines rails-i18n for base formatting with custom locale files for unit symbols
+- **14 custom locale files**: bn, de, en-GB, en-IN, en, es, fr, hi, ja, ko, ur, zh-CN, zh-TW, zh
+- **Rails-i18n structure**: `number.human.decimal_units.units` for unit translations
+- **Automatic locale file loading** from `config/locales/` directory
+
+#### Architecture & Performance
+- **Configuration-free design**: No global state, explicit parameters for predictable behavior
+- **Direct class methods**: Zero object instantiation overhead for optimal performance
+- **Thread-safe implementation**: No shared mutable state between calls
+- **Two-stage formatting**: Clean separation between number formatting and currency application
+- **Efficient I18n**: Leverages Rails I18n caching mechanisms
+
+#### Standards Compliance
+- **Microsoft Globalization documentation** compliance for cultural number formatting
+- **Unicode CLDR standards** for locale-specific formatting rules
+- **ISO 4217 standard** for currency codes and precision rules
+- **rails-i18n integration** for verified locale data
+
+#### Development Infrastructure
+- **Comprehensive test suite**: 106 test examples with 100% code coverage
+- **RuboCop compliance**: Complete adherence to Ruby style guidelines
+- **Rake tasks**: Integrated testing and linting workflow
+- **Gem packaging**: Ready for RubyGems distribution
+
+#### Dependencies
+- **Runtime dependencies**: `actionview` (>= 5.2), `i18n` (>= 1.6, < 2), `rails-i18n` (>= 5.1)
+- **Ruby requirement**: >= 3.1.0
+- **Development dependencies**: `rspec`, `rubocop`, `simplecov`, `yard`
+
+### Technical Details
+
+#### Number System Architecture
+- **DefaultSystem**: Handles Western locales with standard thousand/million/billion/trillion units
+- **EastAsianSystem**: Implements East Asian counting with ten-thousand (만/万) and hundred-million (억/億) bases
+- **IndianSystem**: Supports Indian numbering with lakh (100,000) and crore (10,000,000) units
+
+#### Currency Precision System
+- **LocaleSupport module**: Centralized currency-to-locale mapping for consistent precision
+- **Native locale detection**: Automatic selection of appropriate formatting locale for each currency
+- **Precision inheritance**: Currency formatting inherits precision rules from native locales
+
+#### Formatter Pattern
+- **Formatters::Number**: Core number formatting with intelligent unit system selection
+- **Formatters::Currency**: Currency symbol and format string application
+- **Clean separation**: Number formatting independent of currency concerns
+
+[0.1.0]: https://github.com/yourusername/human_number/releases/tag/v0.1.0

data/CLAUDE.md

@@ -0,0 +1,219 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+HumanNumber is a Ruby gem that implements accurate number formatting based on international standards (Microsoft Globalization and Unicode CLDR). It provides human-readable number formats with precise locale-specific formatting rules for basic numbers, currency, and large number simplification.
+
+### Key Features
+- International standards-compliant number formatting
+- Currency formatting with ISO 4217 support
+- Large number simplification with cultural variations (K/M/B vs 千/万/億/兆)
+- Rails integration via helpers and Railtie
+- Built on rails-i18n for locale data
+
+## Development Commands
+
+### Testing
+```bash
+# Run all tests
+rake spec
+# or
+bundle exec rspec
+
+# Run a specific test file
+bundle exec rspec spec/human_number_spec.rb
+
+# Run a specific test
+bundle exec rspec spec/human_number_spec.rb:line_number
+```
+
+### Code Quality
+```bash
+# Run RuboCop linting
+rake rubocop
+# or
+bundle exec rubocop
+
+# Auto-fix RuboCop issues
+bundle exec rubocop -a
+```
+
+### Default Development Task
+```bash
+# Runs both tests and linting
+rake
+```
+
+### Gem Management
+```bash
+# Build the gem
+rake build
+
+# Install locally
+rake install
+
+# Release (requires proper credentials)
+rake release
+```
+
+## Architecture
+
+### Core Module Structure
+The gem follows a modular formatter pattern:
+
+- **`HumanNumber`** (main module): Provides public API methods (`human_number`, `currency`, `human_currency`) and configuration
+- **`HumanNumber::Formatters::Number`**: Handles number formatting with intelligent unit system selection
+- **`HumanNumber::Formatters::Currency`**: Applies currency symbols and format strings to formatted numbers
+- **Number System Classes**: `DefaultSystem`, `EastAsianSystem`, `IndianSystem` - each implements locale-specific unit systems
+
+### Two-Stage Formatting Process
+The gem uses a clear separation between number formatting and currency application:
+
+1. **Number Formatting**: Converts numbers to human-readable strings with cultural units
+2. **Currency Application**: Applies currency symbols and format strings
+
+```ruby
+# Internal flow for HumanNumber.human_currency(1234567, currency_code: 'USD', locale: :en)
+formatted_number = Formatters::Number.format(1234567, locale: :en, max_digits: 2)     #=> "1.2M"
+final_result = Formatters::Currency.format("1.2M", currency_code: 'USD', locale: :en) #=> "$1.2M"
+```
+
+### Cultural Number System Architecture
+The gem automatically selects appropriate number systems based on locale:
+
+- **Western System** (`DefaultSystem`): K/M/B/T (thousand/million/billion/trillion)
+  - Used by: English, German, French, Spanish, Italian, Portuguese, Russian, Dutch, Swedish, Danish, Norwegian
+  - Target locales: `%i[en es fr de it pt ru nl sv da no]`
+
+- **East Asian System** (`EastAsianSystem`): 천/만/억/조 or 千/万/億/兆
+  - Used by: Korean, Japanese, Chinese
+  - Target locales: `%i[ko ja zh zh-CN zh-TW]`
+  - Units: 천/千 (thousand), 만/万 (ten thousand), 억/億 (hundred million), 조/兆 (trillion)
+
+- **Indian System** (`IndianSystem`): thousand/lakh/crore
+  - Used by: Hindi, Urdu, Bengali, Indian English
+  - Target locales: `%i[hi ur bn en-IN]`
+  - Units: thousand (1,000), lakh (100,000), crore (10,000,000)
+
+### Locale Data Integration
+The gem uses a hybrid approach combining rails-i18n with custom locale files:
+- Uses `I18n.t("number.format.delimiter")` and `I18n.t("number.format.separator")` for basic number formatting (from rails-i18n)
+- Uses `I18n.t("number.currency.format.*")` for currency formatting (from rails-i18n)
+- Uses `I18n.t("number.human.decimal_units.units.*")` for large number unit symbols (from custom locale files in `config/locales/`)
+- Custom locale files follow rails-i18n structure: `number.human.decimal_units.units`
+- Validates locales against `I18n.available_locales`
+- Railtie automatically loads custom locale files from `config/locales/` directory
+
+### Currency-Locale Mapping System
+`HumanNumber::LocaleSupport` provides centralized currency precision logic:
+
+```ruby
+CURRENCY_NATIVE_LOCALES = {
+  "USD" => [:en], "EUR" => %i[de fr es it nl], 
+  "KRW" => [:ko], "JPY" => [:ja]
+  # ... 40+ currencies
+}
+```
+
+This ensures:
+- **Consistent precision rules**: USD always shows 2 decimals, JPY shows 0
+- **Smart fallbacks**: When user locale doesn't match currency's native locale
+- **Easy maintenance**: New currencies require only one mapping entry
+
+### Rails Integration
+- **`HumanNumber::Railtie`**: Automatically loads Rails helpers when Rails is present
+- **`HumanNumber::Rails::Helpers`**: Provides view/controller helper methods (`human_number`, `currency`, `human_currency`)
+- Rails helpers default to `I18n.locale` and provide Rails-friendly parameter handling
+
+### Dependencies
+- **Runtime**: `i18n`, `rails-i18n`, `actionview`
+- **Development**: `rspec`, `rubocop`, `simplecov`, `yard`
+- **Rails Integration**: Optional Rails dependency for helper integration
+
+## Configuration-Free Design Philosophy
+
+HumanNumber deliberately avoids runtime configuration in favor of explicit parameters:
+
+```ruby
+# No global configuration
+HumanNumber.human_number(1234567, locale: :ko, max_digits: 2)
+
+# Application defaults handled at application level
+class ApplicationController
+  def format_money(amount, currency)
+    HumanNumber.human_currency(amount, currency_code: currency, locale: I18n.locale, max_digits: 2)
+  end
+end
+```
+
+**Benefits:**
+- No shared state or thread safety concerns
+- Predictable behavior (each call is independent)
+- Easier testing (no configuration setup/teardown)
+- Better performance (no configuration object overhead)
+
+## Testing Configuration
+
+- Uses RSpec with documentation format output
+- SimpleCov for test coverage
+- Test setup resets I18n locale and HumanNumber configuration before each test
+- Available locales configured for comprehensive locale testing
+
+## Adding New Features
+
+### Adding New Formatters
+To add a new formatter type:
+1. Create new class in `lib/human_number/formatters/` inheriting from appropriate base
+2. Implement the required methods
+3. Add to main `HumanNumber` module with public method
+4. Update Rails helpers if appropriate
+5. Add comprehensive tests covering locale variations
+
+### Adding New Locales
+To add support for a new locale:
+1. Create new YAML file in `config/locales/` (e.g., `fr.yml`)
+2. Follow rails-i18n structure: `number.human.decimal_units.units`
+3. Define appropriate unit symbols for the locale
+4. Consider cultural number unit systems (Western vs Asian patterns)
+5. Add tests for the new locale in the test suite
+
+### Adding New Number Systems
+To add a new cultural number system:
+1. Create new system class in `Formatters::Number` (e.g., `ArabicSystem`)
+2. Define `TARGET_LOCALES` and `UNIT_DEFINITIONS` constants
+3. Implement `format_number` class method
+4. Add to `determine_system_class` method in `Formatters::Number`
+5. Add locale files for the new system's locales
+6. Add comprehensive test coverage
+
+Example locale file structure:
+```yaml
+fr:
+  number:
+    human:
+      decimal_units:
+        abbr_units:
+          thousand: "k"
+          million: "M"
+          billion: "Md"
+          trillion: "Bn"
+```
+
+## Performance Considerations
+
+- **Zero Allocation**: Direct class methods avoid object instantiation
+- **Thread Safe**: No shared mutable state between calls
+- **Efficient I18n**: Leverages Rails I18n caching mechanisms
+- **Smart Defaults**: Optimized for common use cases
+- **System Class Delegation**: Efficient dispatch to appropriate number system
+
+## Standards Reference
+
+This project is based on the following international standards:
+- [Microsoft Globalization - Number Formatting](https://learn.microsoft.com/en-us/globalization/locale/number-formatting)
+- [Microsoft Globalization - Currency Formats](https://learn.microsoft.com/en-us/globalization/locale/currency-formats)
+- [Unicode CLDR](http://cldr.unicode.org/)
+- [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217)
+- [rails-i18n](https://github.com/svenfuchs/rails-i18n)

data/Gemfile

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+# Ruby version requirement (matches gemspec)
+ruby ">= 3.1.0"
+
+# Specify your gem's dependencies in human_number.gemspec
+gemspec
+
+group :development do
+  gem "bundler", "~> 2.0"
+  gem "rake", "~> 13.0"
+  gem "rubocop", "~> 1.0"
+  gem "rubocop-rspec", "~> 2.0"
+  gem "yard", "~> 0.9"
+end
+
+group :test do
+  gem "rspec", "~> 3.0"
+  gem "rspec-rails", "~> 5.0"
+  gem "simplecov", "~> 0.21", require: false
+end

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Your Name
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.