string_to_number 0.2.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a97e2a69e72adda0aeedace8ab5a9ddae63c1a4741846d6d405a0ef767bdaaaa
-  data.tar.gz: 78553f4c606a717c8bab939e24b18ddd023a8962b902d2fea75b03498b2e3e0a
+  metadata.gz: 336f985b755b77d9518187442a09e117175a12bcc8658abd46a98f0180efd5e3
+  data.tar.gz: acd54764a6df32c72067457f22de32f28a57a3c30c571ca608aba48bd9aa1f63
 SHA512:
-  metadata.gz: 1042d45f537afc86b43883d29a3ef03ffd3ddc365a37c85843bd78fa54c4d35178c140e32c025d7406681dc31d77c06b7f7e526e4255fef1629a468a7ddf1958
-  data.tar.gz: 1f6b2b1e8dc6c17bf72d0ce759da2fe31dd9771188ae6087b23774b06e55f9678ee8bcc049c611ff8b0a68d9b99c8b3cb3088e28f342ae1f0d842cd618cf81da
+  metadata.gz: 8ea31d03afc64fa5400ac6609748bf14e15916bdcc27a605e0e399d170b0db7f2be09b82c46ca43fc43eb5e2bb6ae71e4276eebc97e1b6356f43d230ef320c9a
+  data.tar.gz: 8b962962941a065def976540572e47534fe82ac270f2a5fd9121e640f82fc66aefa7270bedd068cdf02c32f66fd8307a013fe9b4382f6d8466f25f5a78c87e51

data/.github/workflows/ci.yml

@@ -2,9 +2,7 @@ name: CI
 
 on:
   push:
-    branches: [ master, main ]
   pull_request:
-    branches: [ master, main ]
 
 jobs:
   test:

data/.github/workflows/release.yml

@@ -0,0 +1,62 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - 'v*'
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: 'Release tag (e.g., v1.0.0)'
+        required: true
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        ruby-version: ['2.7', '3.0', '3.1', '3.2', '3.3']
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Ruby ${{ matrix.ruby-version }}
+      uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: ${{ matrix.ruby-version }}
+        bundler-cache: true
+
+    - name: Run tests
+      run: bundle exec rake spec
+
+  publish:
+    needs: test
+    runs-on: ubuntu-latest
+    environment: release
+    permissions:
+      contents: write
+      id-token: write
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Ruby
+      uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: '3.3'
+        bundler-cache: true
+
+    - name: Build gem
+      run: gem build string_to_number.gemspec
+
+    - name: Configure RubyGems credentials
+      uses: rubygems/configure-rubygems-credentials@v1.0.0
+
+    - name: Publish to RubyGems
+      run: gem push string_to_number-*.gem
+
+    - name: Create GitHub Release
+      env:
+        GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        TAG: ${{ github.ref_name }}
+      run: gh release create "$TAG" --generate-notes

data/CLAUDE.md

@@ -4,100 +4,38 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## Project Overview
 
-This is a Ruby gem that converts French words into numbers. The gem provides a single public method `StringToNumber.in_numbers(french_string)` that parses French number words and returns their numeric equivalent.
+Ruby gem that converts French written numbers into integers. Single public entry point: `StringToNumber.in_numbers(french_string)`.
 
-## Core Architecture
-
-- **Main module**: `StringToNumber` in `lib/string_to_number.rb` - provides the public API
-- **Optimized parser**: `StringToNumber::Parser` in `lib/string_to_number/parser.rb` - high-performance implementation
-- **Original implementation**: `StringToNumber::ToNumber` in `lib/string_to_number/to_number.rb` - legacy compatibility
-- **Version**: `StringToNumber::VERSION` in `lib/string_to_number/version.rb`
-
-### Parser Architecture
-
-The optimized parser uses:
-- **WORD_VALUES**: Direct French word to number mappings (0-90, including regional variants)
-- **MULTIPLIERS**: Power-of-ten multipliers (cent=2, mille=3, million=6, etc.)
-- **Pre-compiled regex patterns**: Eliminate compilation overhead
-- **Multi-level caching**: Instance cache + LRU conversion cache
-- **Thread-safe design**: Concurrent access with mutex protection
-
-The algorithm maintains the proven recursive parsing logic from the original while adding:
-- Memoization for repeated conversions
-- Instance caching to reduce initialization costs
-- Optimized string operations and hash lookups
-
-## Common Development Commands
+## Commands
 
 ```bash
-# Install dependencies
-bundle install
-
-# Run tests
-rake spec
-
-# Run specific test
-bundle exec rspec spec/string_to_number_spec.rb
-
-# Start interactive console
-rake console
-# or
-bundle exec irb -I lib -r string_to_number
-
-# Install gem locally
-bundle exec rake install
-
-# Release new version (updates version.rb, creates git tag, pushes to rubygems)
-bundle exec rake release
+bundle install              # Install dependencies
+rake spec                   # Run all tests (correctness + performance)
+bundle exec rspec spec/string_to_number_spec.rb       # Correctness tests only
+bundle exec rspec spec/performance_spec.rb            # Performance tests only
+bundle exec rspec spec/string_to_number_spec.rb -e "vingt"  # Run single test by name
+rake rubocop                # Lint (or: bundle exec rubocop)
+rake                        # Default: rubocop + spec
+rake console                # Interactive REPL with gem loaded
 ```
 
-## Testing
-
-Uses RSpec with comprehensive test coverage for French number parsing from 0 to millions. Tests are organized by number ranges (0-9, 10-19, 20-29, etc.) and include complex multi-word numbers.
-
-### Performance Testing
-
-Performance tests are available to measure and monitor the implementation's efficiency:
+## Architecture
 
-```bash
-# Run comprehensive performance test suite
-bundle exec rspec spec/performance_spec.rb
-
-# Run standalone benchmark script
-ruby -I lib benchmark.rb
+Three files under `lib/` matter:
 
-# Run micro-benchmarks to identify bottlenecks
-ruby -I lib microbenchmark.rb
-
-# Run profiling analysis
-ruby -I lib profile.rb
-```
+- `lib/string_to_number.rb` — public API module. Delegates to `Parser` (default) or `ToNumber` (legacy, via `use_optimized: false`).
+- `lib/string_to_number/parser.rb` — optimized implementation. Owns all caching (LRU + instance cache) and thread-safety (two mutexes). Imports data tables from `ToNumber` but never calls its methods.
+- `lib/string_to_number/to_number.rb` — legacy implementation. Owns the canonical data tables: `EXCEPTIONS` (word→value) and `POWERS_OF_TEN` (multiplier→exponent). Must be loaded before `parser.rb`.
 
-**Performance Characteristics (Optimized Implementation):**
-- Simple numbers (0-100): ~0.001ms average, 800,000+ conversions/sec
-- Medium complexity (100-1000): ~0.001ms average, 780,000+ conversions/sec  
-- Complex numbers (1000+): ~0.002ms average, 690,000+ conversions/sec
-- Exceptional scalability: minimal performance degradation with input length
-- Memory efficient: zero object creation during operation
-- Intelligent caching: repeated conversions benefit from memoization
+**Key constraint:** New word mappings go in `ToNumber::EXCEPTIONS` or `ToNumber::POWERS_OF_TEN` — `Parser` inherits them automatically. Don't duplicate data between the two implementations.
 
-**Performance Improvements:**
-- **14-460x faster** than original implementation across all test cases
-- **Excellent scalability**: 1.3x degradation vs 43x in original
-- **Pre-compiled regex patterns** eliminate compilation overhead
-- **Instance caching** reduces initialization costs
-- **Memoization** speeds up repeated conversions
-- **Thread-safe** with concurrent performance >2M conversions/sec
+Both parsers use the same recursive algorithm: decompose input into `factor × multiplier` pairs via regex, with special-case handling for `quatre-vingt` forms.
 
-**Usage Options:**
-```ruby
-# Use optimized implementation (default)
-StringToNumber.in_numbers('vingt et un')
+See `docs/ARCHITECTURE.md` for the full code map and invariants.
 
-# Use original implementation for compatibility
-StringToNumber.in_numbers('vingt et un', use_optimized: false)
+## Style
 
-# Cache management
-StringToNumber.clear_caches!
-StringToNumber.cache_stats
-```
+- RuboCop enforced (`rake rubocop`). Config in `.rubocop.yml`.
+- Single quotes for strings. `frozen_string_literal: true` in every file.
+- Max line length: 120 (specs exempt).
+- Target Ruby: 2.7+.

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    string_to_number (0.2.1)
+    string_to_number (0.3.0)
 
 GEM
   remote: https://rubygems.org/

data/README.md

@@ -1,58 +1,53 @@
-<div align="center">
-  <img src="logo.png" alt="StringToNumber Logo" width="200" height="200">
-  
-  # StringToNumber
-  
-  [![Gem Version](https://badge.fury.io/rb/string_to_number.svg)](https://badge.fury.io/rb/string_to_number)
-  [![Ruby](https://github.com/FabienPiette/string_to_number/workflows/Ruby/badge.svg)](https://github.com/FabienPiette/string_to_number/actions)
-  [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-</div>
-
-A high-performance Ruby gem for converting French written numbers into their numeric equivalents. Features intelligent caching, thread-safe operations, and support for complex French number formats.
-
-## ✨ Features
-
-- **High Performance**: Up to 460x faster than naive implementations with intelligent caching
-- **Thread-Safe**: Concurrent access support with proper locking mechanisms
-- **Comprehensive**: Handles complex French number formats including:
-  - Basic numbers (zéro, un, deux...)
-  - Compound numbers (vingt et un, quatre-vingt-quatorze...)
-  - Large numbers (millions, milliards, billions...)
-  - Special cases (quatre-vingts, soixante-dix...)
-- **Memory Efficient**: LRU cache with configurable limits
-- **Backward Compatible**: Maintains compatibility with original implementation
-
-## 🚀 Performance
-
-| Input Size | Original | Optimized | Improvement |
-|------------|----------|-----------|-------------|
-| Short      | 0.5ms    | 0.035ms   | **14x**     |
-| Medium     | 2.1ms    | 0.045ms   | **47x**     |
-| Long       | 23ms     | 0.05ms    | **460x**    |
-
-## 📦 Installation
-
-Add this line to your application's Gemfile:
+# StringToNumber
+
+<p align="center">
+  <a href="https://badge.fury.io/rb/string_to_number"><img src="https://badge.fury.io/rb/string_to_number.svg" alt="Gem Version"></a>
+  <a href="https://github.com/FabienPiette/string_to_number/actions"><img src="https://github.com/FabienPiette/string_to_number/workflows/CI/badge.svg" alt="CI"></a>
+  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"></a>
+</p>
+
+Convert French written numbers into their numeric equivalents in Ruby.
+
+<p align="center">
+  <img src="docs/demo.gif" alt="goscribe demo" width="800">
+</p>
+
+## Quick Start
 
 ```ruby
-gem 'string_to_number'
+gem 'string_to_number'  # Add to your Gemfile, then: bundle install
 ```
 
-And then execute:
+```ruby
+require 'string_to_number'
 
-```bash
-$ bundle install
+StringToNumber.in_numbers('vingt et un')              #=> 21
+StringToNumber.in_numbers('mille deux cent trente-quatre')  #=> 1234
+StringToNumber.in_numbers('trois milliards')           #=> 3_000_000_000
 ```
 
-Or install it yourself as:
+## Features
+
+- **Fast** — 14-460x faster than naive recursive parsing, via pre-compiled patterns and LRU caching
+- **Complete** — handles all standard French number words from `zéro` to `billions`, including compound forms (`quatre-vingt-quatorze`, `soixante-dix`)
+- **Thread-safe** — concurrent access with mutex-protected caches; >2M conversions/sec under contention
+- **Zero dependencies** — pure Ruby, no external gems required
+
+## Install
+
+**Prerequisites:** Ruby 2.7+
 
 ```bash
-$ gem install string_to_number
+gem install string_to_number
 ```
 
-## 🔧 Usage
+Or in your Gemfile:
+
+```ruby
+gem 'string_to_number'
+```
 
-### Basic Usage
+## Usage
 
 ```ruby
 require 'string_to_number'
@@ -63,153 +58,44 @@ StringToNumber.in_numbers('quinze')        #=> 15
 StringToNumber.in_numbers('cent')          #=> 100
 
 # Compound numbers
-StringToNumber.in_numbers('vingt et un')   #=> 21
-StringToNumber.in_numbers('quatre-vingt-quatorze') #=> 94
-StringToNumber.in_numbers('soixante-dix')  #=> 70
+StringToNumber.in_numbers('vingt et un')                     #=> 21
+StringToNumber.in_numbers('quatre-vingt-quatorze')           #=> 94
+StringToNumber.in_numbers('neuf mille neuf cent quatre-vingt-dix-neuf')  #=> 9999
 
 # Large numbers
-StringToNumber.in_numbers('mille deux cent trente-quatre') #=> 1234
-StringToNumber.in_numbers('un million')    #=> 1_000_000
-StringToNumber.in_numbers('trois milliards') #=> 3_000_000_000
-
-# Complex expressions
-StringToNumber.in_numbers('neuf mille neuf cent quatre-vingt-dix-neuf') #=> 9999
-StringToNumber.in_numbers('deux millions trois cent mille') #=> 2_300_000
+StringToNumber.in_numbers('un million')          #=> 1_000_000
+StringToNumber.in_numbers('deux millions trois cent mille')  #=> 2_300_000
 ```
 
-### Advanced Features
+### Validation and cache management
 
 ```ruby
-# Validation
 StringToNumber.valid_french_number?('vingt et un')  #=> true
 StringToNumber.valid_french_number?('hello world')  #=> false
 
-# Cache management
-StringToNumber.clear_caches!  # Clear all internal caches
-stats = StringToNumber.cache_stats
-puts "Cache hit ratio: #{stats[:cache_hit_ratio]}"
-
-# Backward compatibility mode
-StringToNumber.in_numbers('cent', use_optimized: false)  #=> 100
-```
-
-### Supported Number Formats
-
-| Range | Examples |
-|-------|----------|
-| 0-19 | zéro, un, deux, trois, quatre, cinq, six, sept, huit, neuf, dix, onze, douze, treize, quatorze, quinze, seize, dix-sept, dix-huit, dix-neuf |
-| 20-99 | vingt, trente, quarante, cinquante, soixante, soixante-dix, quatre-vingts, quatre-vingt-dix |
-| 100+ | cent, mille, million, milliard, billion |
-| Compounds | vingt et un, quatre-vingt-quatorze, deux mille trois |
-
-## ⚡ Performance Tips
-
-1. **Reuse conversions**: The gem automatically caches results for better performance
-2. **Batch processing**: Use the optimized parser (default) for better throughput
-3. **Memory management**: Call `clear_caches!` periodically if processing many unique inputs
-4. **Thread safety**: The gem is thread-safe and can be used in concurrent environments
-
-## 🧪 Development
-
-After checking out the repo, run `bin/setup` to install dependencies:
-
-```bash
-$ git clone https://github.com/FabienPiette/string_to_number.git
-$ cd string_to_number
-$ bin/setup
+StringToNumber.cache_stats    # inspect cache hit ratios
+StringToNumber.clear_caches!  # free cached data
 ```
 
-### Running Tests
-
-```bash
-# Run all tests
-$ rake spec
-
-# Run performance tests
-$ ruby benchmark.rb
-
-# Run specific test files
-$ rspec spec/string_to_number_spec.rb
-```
-
-### Performance Benchmarking
-
-```bash
-# Compare implementations
-$ ruby performance_comparison.rb
-
-# Detailed micro-benchmarks
-$ ruby microbenchmark.rb
-```
-
-### Interactive Console
-
-```bash
-$ bin/console
-# => Interactive prompt for experimentation
-```
-
-## 🏗️ Architecture
-
-The gem uses a dual-architecture approach:
-
-- **Optimized Parser** (`StringToNumber::Parser`): High-performance implementation with caching
-- **Original Implementation** (`StringToNumber::ToNumber`): Reference implementation for compatibility
-
-Key performance optimizations:
-- Pre-compiled regex patterns
-- LRU caching with thread-safe access
-- Memoized parser instances
-- Zero-allocation number matching
-
-## 🤝 Contributing
-
-Bug reports and pull requests are welcome on GitHub at https://github.com/FabienPiette/string_to_number.
-
-### Development Process
-
-1. Fork the repository
-2. Create your feature branch (`git checkout -b feature/amazing-feature`)
-3. Write tests for your changes
-4. Ensure all tests pass (`rake spec`)
-5. Run performance tests to avoid regressions
-6. Commit your changes (`git commit -am 'Add amazing feature'`)
-7. Push to the branch (`git push origin feature/amazing-feature`)
-8. Open a Pull Request
-
-### Code of Conduct
-
-This project is intended to be a safe, welcoming space for collaboration. Contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
-
-## 📋 Requirements
-
-- Ruby 2.5 or higher
-- No external dependencies (uses only Ruby standard library)
-
-## 🐛 Troubleshooting
-
-### Common Issues
-
-**Q: Numbers aren't parsing correctly**  
-A: Ensure your input uses proper French number words. Use `valid_french_number?` to validate input.
+For the full API, see the [source documentation](lib/string_to_number.rb).
 
-**Q: Performance seems slow**  
-A: Make sure you're using the default optimized parser. Check cache statistics with `cache_stats`.
+## Known Issues
 
-**Q: Memory usage is high**  
-A: Call `clear_caches!` periodically if processing many unique number strings.
+- Input must be French number words only — mixed text (e.g. `"il y a vingt personnes"`) is not supported
+- Regional Belgian/Swiss variants (`septante`, `nonante`) are recognized, but coverage may be incomplete
 
-## 📝 Changelog
+## Contributing
 
-See [CHANGELOG.md](CHANGELOG.md) for version history and updates.
+Bug reports and pull requests are welcome on [GitHub](https://github.com/FabienPiette/string_to_number).
 
-## 📄 License
+## Acknowledgments
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+Created by [Fabien Piette](https://github.com/FabienPiette). Thanks to all [contributors](https://github.com/FabienPiette/string_to_number/graphs/contributors).
 
-## 🙏 Acknowledgments
+<p align="center">
+<a href="https://buymeacoffee.com/fabienpiette" target="_blank"><img src="https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png" alt="Buy Me A Coffee" height="60"></a>
+</p>
 
-- Original implementation by [Fabien Piette](https://github.com/FabienPiette)
-- Performance optimizations and enhancements
-- Community contributors and testers
+## License
 
+[MIT](LICENSE)

data/SECURITY.md

@@ -0,0 +1,25 @@
+# Security Policy
+
+## Supported Versions
+
+| Version | Supported          |
+|---------|--------------------|
+| 0.2.x   | :white_check_mark: |
+| < 0.2   | :x:                |
+
+## Reporting a Vulnerability
+
+If you discover a security vulnerability in this gem, please report it responsibly.
+
+**Do not open a public GitHub issue.**
+
+Instead, please use [GitHub's private vulnerability reporting](https://github.com/FabienPiette/string_to_number/security/advisories/new) to submit your report. You can also email the maintainer directly at the address listed in the gemspec.
+
+Please include:
+
+- A description of the vulnerability
+- Steps to reproduce
+- Affected versions
+- Any potential impact
+
+You should expect an initial response within 7 days. If the vulnerability is accepted, a fix will be released as a patch version and the advisory will be published after the fix is available.

data/docs/ARCHITECTURE.md

@@ -0,0 +1,131 @@
+# Architecture
+
+This document describes the high-level architecture of StringToNumber.
+If you want to familiarize yourself with the codebase, you are in the
+right place.
+
+## Bird's Eye View
+
+StringToNumber converts French written numbers into Ruby integers. A
+string like `"deux millions trois cent mille"` goes in, and `2_300_000`
+comes out.
+
+The conversion pipeline is:
+
+1. **Normalize** — downcase and strip whitespace
+2. **Cache lookup** — return immediately if this string was converted before
+3. **Parse** — recursively decompose the French phrase into factor/multiplier
+   pairs (e.g. `cinq` × `cent` = 500), then sum the parts
+4. **Cache store** — save the result for future lookups
+
+The parsing relies on two data tables: direct word-to-value mappings
+(`WORD_VALUES`) and power-of-ten multipliers (`MULTIPLIERS`). French
+number grammar has irregular patterns — especially the `quatre-vingt`
+(4×20) family — that require dedicated regex handling.
+
+## Code Map
+
+### `lib/string_to_number.rb`
+
+Public API module. Exposes three class methods: `in_numbers`,
+`clear_caches!`, and `cache_stats`. Also provides `valid_french_number?`
+for input validation.
+
+This file is the only entry point consumers interact with. It delegates
+to either `Parser` or `ToNumber` based on the `use_optimized` flag
+(default: `true`).
+
+Key methods: `StringToNumber.in_numbers`, `StringToNumber.valid_french_number?`.
+
+### `lib/string_to_number/parser.rb`
+
+High-performance parser. Owns all caching logic (LRU conversion cache,
+instance cache) and thread-safety (two mutexes: `@cache_mutex` for
+conversions, `@instance_mutex` for parser instances).
+
+The parsing algorithm mirrors `ToNumber`'s recursive extraction but
+operates on pre-compiled regex patterns (`MULTIPLIER_PATTERN`,
+`QUATRE_VINGT_PATTERN`) instead of building them per call.
+
+Key types: `Parser.convert` (class-level entry point),
+`Parser#parse_optimized` and `Parser#extract_optimized` (recursive core).
+
+**Architecture Invariant:** `Parser` imports data tables from `ToNumber`
+(`WORD_VALUES = ToNumber::EXCEPTIONS`) but never calls `ToNumber` methods.
+The dependency is data-only.
+
+### `lib/string_to_number/to_number.rb`
+
+Original (legacy) implementation. Owns the canonical data tables:
+`EXCEPTIONS` (word-to-value map for 0–90 plus regional variants) and
+`POWERS_OF_TEN` (multiplier words to exponent values, up to `googol`).
+
+Uses the same recursive `extract`/`match` algorithm as `Parser` but
+rebuilds regex patterns on every instantiation and has no caching.
+
+Key types: `ToNumber::EXCEPTIONS`, `ToNumber::POWERS_OF_TEN`,
+`ToNumber#to_number`.
+
+**Architecture Invariant:** `ToNumber` has no knowledge of `Parser`.
+It must remain independently functional for backward compatibility.
+
+### `lib/string_to_number/version.rb`
+
+Single constant `StringToNumber::VERSION`. Updated before gem releases.
+
+### `spec/`
+
+RSpec test suites. `string_to_number_spec.rb` covers correctness across
+number ranges (0–9, 10–19, 20–29, ..., millions). `performance_spec.rb`
+validates throughput thresholds.
+
+### `benchmark.rb`, `microbenchmark.rb`, `profile.rb`, `performance_comparison.rb`
+
+Standalone scripts for measuring and profiling performance. Not part of
+the gem distribution (excluded by gemspec).
+
+## Invariants
+
+`Parser` depends on `ToNumber` for data constants only, never for
+parsing logic. This keeps the legacy implementation independently
+testable while the optimized path reuses proven word mappings.
+
+All shared mutable state lives in `Parser`'s class-level instance
+variables and is accessed exclusively through `@cache_mutex` or
+`@instance_mutex`. No other module holds mutable state.
+
+The `EXCEPTIONS` and `POWERS_OF_TEN` hashes in `ToNumber` are frozen.
+Any new word mapping must be added there — `Parser` inherits changes
+automatically.
+
+Load order matters: `to_number.rb` must be required before `parser.rb`
+because `Parser` references `ToNumber::EXCEPTIONS` and
+`ToNumber::POWERS_OF_TEN` at class body evaluation time.
+
+## Cross-Cutting Concerns
+
+**Caching.** Two layers in `Parser`: an LRU conversion cache (string →
+integer, capped at 1000 entries) and an instance cache (string → Parser
+object). Both are thread-safe. Call `StringToNumber.clear_caches!` to
+reset.
+
+**Thread safety.** Achieved through two separate mutexes to reduce
+contention — one for conversion results, one for parser instances.
+`ToNumber` is not thread-safe but is stateless per call, so concurrent
+use is safe in practice.
+
+**Testing.** RSpec with two suites: correctness (`spec/string_to_number_spec.rb`)
+and performance (`spec/performance_spec.rb`). Run both via `rake spec`
+or individually with `bundle exec rspec <file>`.
+
+## A Typical Change
+
+**Adding a new French number word** (e.g., a regional variant):
+
+1. Add the word-to-value mapping in `ToNumber::EXCEPTIONS` or
+   `ToNumber::POWERS_OF_TEN` in `lib/string_to_number/to_number.rb`
+2. Add test cases in `spec/string_to_number_spec.rb`
+3. Run `rake spec` — `Parser` picks up the new mapping automatically
+   since it references `ToNumber`'s constants
+
+No changes to `parser.rb` or `string_to_number.rb` are needed.

data/lib/string_to_number/parser.rb

@@ -21,21 +21,21 @@ module StringToNumber
     MULTIPLIERS = StringToNumber::ToNumber::POWERS_OF_TEN.freeze
 
     # Pre-compiled regex patterns for optimal performance
-    MULTIPLIER_KEYS = MULTIPLIERS.keys.reject { |k| %w[un dix].include?(k) }
+    MULTIPLIER_KEYS = MULTIPLIERS.keys
+                                 .reject { |k| %w[un dix].include?(k) }
                                  .sort_by(&:length).reverse.freeze
     MULTIPLIER_PATTERN = /(?<f>.*?)\s?(?<m>#{MULTIPLIER_KEYS.join('|')})/.freeze
-    QUATRE_VINGT_PATTERN = /(quatre(-|\s)vingt(s?)((-|\s)dix)?)((-|\s)?)(\w*)/.freeze
+    QUATRE_VINGT_PATTERN = /(?<base>quatre[-\s]vingt(?:s?)(?:[-\s]dix)?)(?:[-\s]?)(?<suffix>\w*)/.freeze
 
     # Cache configuration
     MAX_CACHE_SIZE = 1000
     private_constant :MAX_CACHE_SIZE
 
-    # Thread-safe class-level caches
-    @conversion_cache = {}
-    @cache_access_order = []
-    @instance_cache = {}
+    # Thread-safe LRU cache using Hash insertion order (Ruby 1.9+)
+    @cache = {}
+    @cache_hits = 0
+    @cache_lookups = 0
     @cache_mutex = Mutex.new
-    @instance_mutex = Mutex.new
 
     class << self
       # Convert French text to number using cached parser instance
@@ -49,28 +49,34 @@ module StringToNumber
         normalized = normalize_text(text)
         return 0 if normalized.empty?
 
-        # Check conversion cache first
-        cached_result = get_cached_conversion(normalized)
-        return cached_result if cached_result
+        @cache_mutex.synchronize do
+          @cache_lookups += 1
+
+          if @cache.key?(normalized)
+            @cache_hits += 1
+            # Delete and reinsert to move to end (most recently used)
+            value = @cache.delete(normalized)
+            @cache[normalized] = value
+            return value
+          end
+        end
 
-        # Get or create parser instance and convert
-        parser = get_cached_instance(normalized)
-        result = parser.parse_optimized(normalized)
+        result = new(normalized).parse_optimized(normalized)
+
+        @cache_mutex.synchronize do
+          @cache.delete(@cache.first[0]) if @cache.size >= MAX_CACHE_SIZE
+          @cache[normalized] = result
+        end
 
-        # Cache the result
-        cache_conversion(normalized, result)
         result
       end
 
       # Clear all caches
       def clear_caches!
         @cache_mutex.synchronize do
-          @conversion_cache.clear
-          @cache_access_order.clear
-        end
-
-        @instance_mutex.synchronize do
-          @instance_cache.clear
+          @cache.clear
+          @cache_hits = 0
+          @cache_lookups = 0
         end
       end
 
@@ -78,10 +84,9 @@ module StringToNumber
       def cache_stats
         @cache_mutex.synchronize do
           {
-            conversion_cache_size: @conversion_cache.size,
+            conversion_cache_size: @cache.size,
             conversion_cache_limit: MAX_CACHE_SIZE,
-            instance_cache_size: @instance_cache.size,
-            cache_hit_ratio: calculate_hit_ratio
+            cache_hit_ratio: @cache_lookups.zero? ? 0.0 : @cache_hits.to_f / @cache_lookups
           }
         end
       end
@@ -95,43 +100,6 @@ module StringToNumber
       def normalize_text(text)
         text.to_s.downcase.strip
       end
-
-      def get_cached_conversion(normalized_text)
-        @cache_mutex.synchronize do
-          if @conversion_cache.key?(normalized_text)
-            # Update LRU order
-            @cache_access_order.delete(normalized_text)
-            @cache_access_order.push(normalized_text)
-            return @conversion_cache[normalized_text]
-          end
-        end
-        nil
-      end
-
-      def cache_conversion(normalized_text, result)
-        @cache_mutex.synchronize do
-          # LRU eviction
-          if @conversion_cache.size >= MAX_CACHE_SIZE
-            oldest = @cache_access_order.shift
-            @conversion_cache.delete(oldest)
-          end
-
-          @conversion_cache[normalized_text] = result
-          @cache_access_order.push(normalized_text)
-        end
-      end
-
-      def get_cached_instance(normalized_text)
-        @instance_mutex.synchronize do
-          @instance_cache[normalized_text] ||= new(normalized_text)
-        end
-      end
-
-      def calculate_hit_ratio
-        return 0.0 if @cache_access_order.empty?
-
-        @conversion_cache.size.to_f / @cache_access_order.size
-      end
     end
 
     # Initialize parser with normalized text
@@ -153,7 +121,7 @@ module StringToNumber
       return WORD_VALUES[text] if WORD_VALUES.key?(text)
 
       # Use the proven extraction algorithm from the original implementation
-      extract_optimized(text, MULTIPLIER_KEYS.join('|'))
+      extract_optimized(text)
     end
 
     private
@@ -161,7 +129,7 @@ module StringToNumber
     # Optimized version of the original extract method
     # This maintains the exact logic of the working implementation
     # but with performance improvements
-    def extract_optimized(sentence, keys, detail: false)
+    def extract_optimized(sentence, detail: false)
       return 0 if sentence.nil? || sentence.empty?
 
       # Direct lookup
@@ -179,7 +147,7 @@ module StringToNumber
 
         # Handle compound numbers
         if higher_multiple_exists?(result[:m], sentence)
-          details = extract_optimized(sentence, keys, detail: true)
+          details = extract_optimized(sentence, detail: true)
           factor = (factor * multiple_of_ten) + details[:factor]
           multiple_of_ten = details[:multiple_of_ten]
           sentence = details[:sentence]
@@ -194,17 +162,17 @@ module StringToNumber
           }
         end
 
-        extract_optimized(sentence, keys) + (factor * multiple_of_ten)
+        extract_optimized(sentence) + (factor * multiple_of_ten)
 
       # Quatre-vingt special handling
       elsif (m = QUATRE_VINGT_PATTERN.match(sentence))
-        normalize_str = m[1].tr(' ', '-')
+        normalize_str = m[:base].tr(' ', '-')
         normalize_str = normalize_str[0...-1] if normalize_str[-1] == 's'
 
         sentence = sentence.gsub(m[0], '')
 
-        extract_optimized(sentence, keys) +
-          WORD_VALUES[normalize_str] + (WORD_VALUES[m[8]] || 0)
+        extract_optimized(sentence) +
+          WORD_VALUES[normalize_str] + (WORD_VALUES[m[:suffix]] || 0)
       else
         match_optimized(sentence)
       end

data/lib/string_to_number/to_number.rb

@@ -199,12 +199,11 @@ module StringToNumber
       # - "quatre-vingt" / "quatre vingts" (with/without 's')
       # - "quatre-vingt-dix" / "quatre vingts dix" (90)
       # - Space vs hyphen variations
-      elsif (m = /(quatre(-|\s)vingt(s?)((-|\s)dix)?)((-|\s)?)(\w*)/.match(sentence))
+      elsif (m = /(?<base>quatre[-\s]vingt(?:s?)(?:[-\s]dix)?)(?:[-\s]?)(?<suffix>\w*)/.match(sentence))
         # Normalize spacing to hyphens for consistent lookup
-        normalize_str = m[1].tr(' ', '-')
+        normalize_str = m[:base].tr(' ', '-')
 
         # Remove trailing 's' from "quatre-vingts" if present
-        # Bug fix: use [-1] instead of [length] for last character
         normalize_str = normalize_str[0...-1] if normalize_str[-1] == 's'
 
         # Remove the matched portion from sentence
@@ -213,7 +212,7 @@ module StringToNumber
         # Return sum of: remaining sentence + normalized quatre-vingt value + any suffix
         # Example: "quatre-vingt-cinq" -> EXCEPTIONS["quatre-vingt"] + EXCEPTIONS["cinq"]
         extract(sentence, keys) +
-          EXCEPTIONS[normalize_str] + (EXCEPTIONS[m[8]] || 0)
+          EXCEPTIONS[normalize_str] + (EXCEPTIONS[m[:suffix]] || 0)
       else
         # Fallback: use match() method for simple word combinations
         match(sentence)

data/lib/string_to_number/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module StringToNumber
-  VERSION = '0.2.1'
+  VERSION = '0.3.0'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: string_to_number
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.3.0
 platform: ruby
 authors:
 - Fabien Piette
-autorequire: 
+autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-06-24 00:00:00.000000000 Z
+date: 2026-02-13 00:00:00.000000000 Z
 dependencies: []
 description: A ruby gem to convert French words into numbers.
 email:
@@ -18,26 +18,28 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".github/workflows/ci.yml"
+- ".github/workflows/release.yml"
 - ".gitignore"
 - ".rspec"
 - ".rubocop.yml"
 - ".tool-versions"
-- ".travis.yml"
 - CLAUDE.md
 - CODE_OF_CONDUCT.md
 - Gemfile
 - Gemfile.lock
-- LICENSE.txt
+- LICENSE
 - README.md
 - Rakefile
+- SECURITY.md
 - benchmark.rb
 - bin/console
 - bin/setup
+- docs/ARCHITECTURE.md
+- docs/demo.gif
 - lib/string_to_number.rb
 - lib/string_to_number/parser.rb
 - lib/string_to_number/to_number.rb
 - lib/string_to_number/version.rb
-- logo.png
 - microbenchmark.rb
 - performance_comparison.rb
 - profile.rb
@@ -48,7 +50,7 @@ licenses:
 metadata:
   allowed_push_host: https://rubygems.org
   rubygems_mfa_required: 'true'
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -63,8 +65,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.6
-signing_key: 
+rubygems_version: 3.5.22
+signing_key:
 specification_version: 4
 summary: A ruby gem to convert French words into numbers.
 test_files: []

data/.travis.yml

@@ -1,5 +0,0 @@
-sudo: false
-language: ruby
-rvm:
-  - 2.3.3
-before_install: gem install bundler -v 1.13.6