human_number 0.1.0

data/lib/human_number/railtie.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require "rails/railtie"
+
+module HumanNumber
+  class Railtie < Rails::Railtie
+    initializer "human_number.configure_rails_initialization" do
+      ActiveSupport.on_load(:action_view) do
+        require "human_number/rails/helpers"
+        include HumanNumber::Rails::Helpers
+      end
+
+      ActiveSupport.on_load(:action_controller) do
+        require "human_number/rails/helpers"
+        include HumanNumber::Rails::Helpers
+      end
+    end
+
+    initializer "human_number.load_locale_data" do
+      I18n.load_path += Dir[File.expand_path("../../config/locales/*.yml", __dir__)]
+    end
+  end
+end

data/lib/human_number/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module HumanNumber
+  VERSION = "0.1.0"
+end

data/lib/human_number.rb

@@ -0,0 +1,196 @@
+# frozen_string_literal: true
+
+require "i18n"
+require "action_view"
+require "rails-i18n"
+
+# Ensure Rails I18n locales are available
+I18n.load_path += Dir[File.expand_path("**/*.yml", Gem.loaded_specs["rails-i18n"].full_gem_path)]
+
+require_relative "human_number/version"
+require_relative "human_number/locale_support"
+require_relative "human_number/formatters/number"
+require_relative "human_number/formatters/currency"
+
+module HumanNumber
+  class Error < StandardError; end
+
+  # Load locale files
+  I18n.load_path += Dir[File.expand_path("../config/locales/*.yml", __dir__)]
+
+  extend ActionView::Helpers::NumberHelper
+
+  class << self
+    # Formats a number with intelligent, locale-aware abbreviations.
+    #
+    # This method provides culturally-appropriate number formatting with automatic
+    # unit system selection based on locale:
+    # - **Western locales**: K/M/B/T (thousand/million/billion/trillion)
+    # - **East Asian locales**: 천/만/억/조 or 千/万/億/兆
+    # - **Indian locales**: thousand/lakh/crore
+    #
+    # @param number [Numeric] The number to format
+    # @param locale [Symbol, String] The locale for formatting (default: current I18n locale)
+    #   Determines both number formatting rules and cultural unit systems
+    #
+    # @option options [Boolean] :abbr_units (true) Use abbreviated unit symbols (K/M/B)
+    #   vs full words. Only affects Western locales
+    # @option options [Integer, nil] :max_digits (2) Maximum significant digits to display.
+    #   When nil, displays complete number using multiple units without decimals
+    # @option options [Integer, nil] :min_unit (nil) Minimum unit threshold for abbreviation.
+    #   Numbers below this won't be abbreviated
+    # @option options [Boolean] :trim_zeros (true) Remove trailing decimal zeros.
+    #   Only applies in abbreviated mode (when max_digits is set)
+    #
+    # @return [String] The formatted number string
+    #
+    # @example Basic usage
+    #   HumanNumber.human_number(1234567)           #=> "1.2M"
+    #   HumanNumber.human_number(50000, locale: :ko) #=> "5만"
+    #
+    # @example Precision control
+    #   HumanNumber.human_number(1234567, max_digits: 2)   #=> "1.2M"
+    #   HumanNumber.human_number(1234567, max_digits: nil) #=> "1M 234K 567"
+    #
+    # @example Unit preferences
+    #   HumanNumber.human_number(1000000, abbr_units: true)  #=> "1M"
+    #   HumanNumber.human_number(1000000, abbr_units: false) #=> "1 million"
+    #
+    # @example Minimum thresholds
+    #   HumanNumber.human_number(5000, min_unit: 10000)  #=> "5000"
+    #   HumanNumber.human_number(50000, min_unit: 10000) #=> "5만"
+    #
+    # @example Zero trimming
+    #   HumanNumber.human_number(1000000, trim_zeros: true)  #=> "1M"
+    #   HumanNumber.human_number(1000000, trim_zeros: false) #=> "1.0M"
+    #
+    # @note Complete mode (max_digits: nil) shows full precision across multiple units
+    # @see Formatters::Number.format The underlying formatter implementation
+    # @since 1.0.0
+    def human_number(number, locale: I18n.locale, **options)
+      validate_number_input!(number)
+      validate_locale!(locale)
+
+      final_options = Formatters::Number.default_options.merge(options)
+
+      Formatters::Number.format(number, locale:, **final_options)
+    end
+
+    # Formats a currency amount using standard Rails currency formatting.
+    #
+    # This method applies currency-specific precision rules (e.g., 2 decimals for USD,
+    # 0 decimals for JPY/KRW) based on the currency's native locale, ensuring
+    # consistent precision regardless of the display locale.
+    #
+    # @param number [Numeric] The amount to format
+    # @param currency_code [String] ISO 4217 currency code (e.g., 'USD', 'EUR', 'KRW', 'JPY')
+    # @param locale [Symbol, String] Display locale for formatting rules
+    #
+    # @return [String] The formatted currency string
+    #
+    # @example Standard currency formatting
+    #   HumanNumber.currency(1234.56, currency_code: 'USD', locale: :en) #=> "$1,234.56"
+    #   HumanNumber.currency(50000, currency_code: 'KRW', locale: :ko)   #=> "50,000원"
+    #   HumanNumber.currency(1234.99, currency_code: 'JPY', locale: :ja) #=> "1,235円"
+    #
+    # @example Cross-locale precision consistency
+    #   # USD always shows 2 decimals regardless of display locale
+    #   HumanNumber.currency(1234.56, currency_code: 'USD', locale: :ko) #=> "$1,234.56"
+    #
+    #   # JPY always shows 0 decimals regardless of display locale
+    #   HumanNumber.currency(1234.56, currency_code: 'JPY', locale: :en) #=> "1,235円"
+    #
+    # @note Precision is determined by currency's native locale, not display locale
+    # @see Formatters::Number.format_with_currency_precision Currency precision logic
+    # @see Formatters::Currency.format Currency symbol and format application
+    # @since 1.0.0
+    def currency(number, currency_code:, locale:)
+      validate_number_input!(number)
+      validate_currency_code!(currency_code)
+      validate_locale!(locale)
+
+      formatted_number = Formatters::Number.format_with_currency_precision(number, currency_code:, locale:)
+      Formatters::Currency.format(formatted_number, currency_code:, locale:)
+    end
+
+    # Formats a currency amount with intelligent, locale-aware abbreviations.
+    #
+    # This method combines human-readable number formatting with currency symbols,
+    # providing culturally-appropriate abbreviations while maintaining currency
+    # symbol and format conventions.
+    #
+    # @param number [Numeric] The amount to format
+    # @param currency_code [String] ISO 4217 currency code (e.g., 'USD', 'EUR', 'KRW', 'JPY')
+    # @param locale [Symbol, String] Locale for formatting and unit system selection
+    #
+    # @option options [Boolean] :abbr_units (true) Use abbreviated unit symbols (K/M/B)
+    #   vs full words. Only affects Western locales
+    # @option options [Integer, nil] :max_digits (2) Maximum significant digits to display.
+    #   When nil, displays complete amount using multiple units without decimals
+    # @option options [Integer, nil] :min_unit (nil) Minimum unit threshold for abbreviation.
+    #   Amounts below this won't be abbreviated
+    # @option options [Boolean] :trim_zeros (true) Remove trailing decimal zeros.
+    #   Only applies in abbreviated mode (when max_digits is set)
+    #
+    # @return [String] The formatted currency string with abbreviations
+    #
+    # @example Basic usage
+    #   HumanNumber.human_currency(1234567, currency_code: 'USD', locale: :en) #=> "$1.2M"
+    #   HumanNumber.human_currency(50000, currency_code: 'KRW', locale: :ko)   #=> "5만원"
+    #
+    # @example Precision control
+    #   HumanNumber.human_currency(1234567, currency_code: 'USD', locale: :en, max_digits: 2) #=> "$1.23M"
+    #   HumanNumber.human_currency(1234567, currency_code: 'USD', locale: :en, max_digits: nil) #=> "$1M 234K 567"
+    #
+    # @example Unit preferences
+    #   HumanNumber.human_currency(1000000, currency_code: 'USD', locale: :en, abbr_units: true)  #=> "$1M"
+    #   HumanNumber.human_currency(1000000, currency_code: 'USD', locale: :en, abbr_units: false) #=> "$1 million"
+    #
+    # @example Cultural unit systems
+    #   HumanNumber.human_currency(12345678, currency_code: 'JPY', locale: :ja) #=> "1234.6万円"
+    #   HumanNumber.human_currency(10000000, currency_code: 'INR', locale: :hi) #=> "1 crore₹"
+    #
+    # @note Combines human number formatting with currency-specific symbol placement
+    # @see #human_number For detailed number formatting options
+    # @see #currency For standard currency formatting without abbreviations
+    # @since 1.0.0
+    def human_currency(number, currency_code:, locale:, **options)
+      validate_number_input!(number)
+      validate_currency_code!(currency_code)
+      validate_locale!(locale)
+
+      final_options = Formatters::Number.default_currency_number_options.merge(options)
+
+      formatted_number = Formatters::Number.format(number, locale:, **final_options)
+      Formatters::Currency.format(formatted_number, currency_code:, locale:)
+    end
+
+    private
+
+    # Input validation methods - minimal validation for stability
+    def validate_number_input!(number)
+      # Only check for the most basic issues that would cause runtime errors
+      return if number.respond_to?(:to_f)
+
+      raise ArgumentError, "Number must be numeric, got #{number.class}"
+    end
+
+    def validate_currency_code!(currency_code)
+      # Basic validation only - let downstream handle specifics
+      return unless currency_code.nil? || (currency_code.respond_to?(:empty?) && currency_code.empty?)
+
+      raise ArgumentError, "Currency code cannot be nil or empty"
+    end
+
+    def validate_locale!(locale)
+      # Very minimal validation - just ensure it's not something that would break
+      return if locale.nil?
+
+      return if locale.respond_to?(:to_sym)
+
+      raise ArgumentError, "Locale must be convertible to symbol, got #{locale.class}"
+    end
+  end
+end
+
+require_relative "human_number/railtie" if defined?(Rails::Railtie)

metadata

@@ -0,0 +1,126 @@
+--- !ruby/object:Gem::Specification
+name: human_number
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Your Name
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: actionview
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.2'
+- !ruby/object:Gem::Dependency
+  name: i18n
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.6'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.6'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2'
+- !ruby/object:Gem::Dependency
+  name: rails-i18n
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.1'
+description: HumanNumber implements accurate number formatting based on international
+  standards including Microsoft Globalization documentation and Unicode CLDR. Provides
+  human-readable number formats with precise locale-specific decimal separators, thousand
+  separators, currency formats, and cultural number conventions.
+email:
+- your.email@example.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rspec"
+- ".rubocop.yml"
+- CHANGELOG.md
+- CLAUDE.md
+- Gemfile
+- LICENSE
+- README.md
+- Rakefile
+- config/locales/bn.yml
+- config/locales/de.yml
+- config/locales/en-GB.yml
+- config/locales/en-IN.yml
+- config/locales/en.yml
+- config/locales/es.yml
+- config/locales/fr.yml
+- config/locales/hi.yml
+- config/locales/ja.yml
+- config/locales/ko.yml
+- config/locales/ur.yml
+- config/locales/zh-CN.yml
+- config/locales/zh-TW.yml
+- config/locales/zh.yml
+- human_number.gemspec
+- lib/human_number.rb
+- lib/human_number/formatters/currency.rb
+- lib/human_number/formatters/number.rb
+- lib/human_number/locale_support.rb
+- lib/human_number/rails/helpers.rb
+- lib/human_number/railtie.rb
+- lib/human_number/version.rb
+homepage: https://github.com/yourusername/human_number
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/yourusername/human_number
+  source_code_uri: https://github.com/yourusername/human_number
+  changelog_uri: https://github.com/yourusername/human_number/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: International standard-based number formatting for Ruby applications
+test_files: []