string_to_number 0.2.0 → 0.3.0

data/README.md

@@ -1,54 +1,53 @@
 # 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)
+<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>
 
-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.
+Convert French written numbers into their numeric equivalents in Ruby.
 
-## ✨ Features
+<p align="center">
+  <img src="docs/demo.gif" alt="goscribe demo" width="800">
+</p>
 
-- **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
+## Quick Start
 
-## 🚀 Performance
+```ruby
+gem 'string_to_number'  # Add to your Gemfile, then: bundle install
+```
 
-| Input Size | Original | Optimized | Improvement |
-|------------|----------|-----------|-------------|
-| Short      | 0.5ms    | 0.035ms   | **14x**     |
-| Medium     | 2.1ms    | 0.045ms   | **47x**     |
-| Long       | 23ms     | 0.05ms    | **460x**    |
+```ruby
+require 'string_to_number'
 
-## 📦 Installation
+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
+```
 
-Add this line to your application's Gemfile:
+## Features
 
-```ruby
-gem 'string_to_number'
-```
+- **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
 
-And then execute:
+**Prerequisites:** Ruby 2.7+
 
 ```bash
-$ bundle install
+gem install string_to_number
 ```
 
-Or install it yourself as:
+Or in your Gemfile:
 
-```bash
-$ gem install string_to_number
+```ruby
+gem 'string_to_number'
 ```
 
-## 🔧 Usage
-
-### Basic Usage
+## Usage
 
 ```ruby
 require 'string_to_number'
@@ -59,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
+StringToNumber.cache_stats    # inspect cache hit ratios
+StringToNumber.clear_caches!  # free cached data
 ```
 
-### 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
-```
-
-### 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/Rakefile

@@ -1,9 +1,13 @@
+# frozen_string_literal: true
+
 require 'bundler/gem_tasks'
 require 'rspec/core/rake_task'
+require 'rubocop/rake_task'
 
 RSpec::Core::RakeTask.new(:spec)
+RuboCop::RakeTask.new
 
-task default: :spec
+task default: %i[rubocop spec]
 
 task :env, [:env] do |_t, _args|
   require 'string_to_number'

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/benchmark.rb

@@ -10,8 +10,8 @@ require 'benchmark'
 class StringToNumberBenchmark
   # Test data organized by complexity
   TEST_CASES = {
-    simple: [
-      'un', 'vingt', 'cent', 'mille'
+    simple: %w[
+      un vingt cent mille
     ],
     medium: [
       'vingt et un', 'deux cent cinquante', 'mille deux cent'
@@ -20,20 +20,20 @@ class StringToNumberBenchmark
       'trois milliards cinq cents millions',
       'soixante-quinze million trois cent quarante six mille sept cent quatre-vingt-dix neuf'
     ],
-    edge_cases: [
-      'VINGT', 'une', 'septante', 'quatre-vingts'
+    edge_cases: %w[
+      VINGT une septante quatre-vingts
     ]
   }.freeze
 
   def self.run_benchmark
-    puts "StringToNumber Performance Benchmark"
-    puts "=" * 50
+    puts 'StringToNumber Performance Benchmark'
+    puts '=' * 50
     puts "Ruby version: #{RUBY_VERSION}"
     puts "Platform: #{RUBY_PLATFORM}"
     puts
 
     # Warm up
-    puts "Warming up..."
+    puts 'Warming up...'
     TEST_CASES.values.flatten.each { |text| StringToNumber.in_numbers(text) }
     puts
 
@@ -41,7 +41,7 @@ class StringToNumberBenchmark
 
     TEST_CASES.each do |category, test_cases|
       puts "#{category.to_s.capitalize} Numbers:"
-      puts "-" * 30
+      puts '-' * 30
 
       results = benchmark_category(test_cases)
       total_results[category] = results
@@ -53,46 +53,44 @@ class StringToNumberBenchmark
       puts
 
       # Show individual case performance for complex numbers
-      if category == :complex
-        puts "Individual case breakdown:"
-        test_cases.each_with_index do |text, index|
-          individual_time = Benchmark.realtime do
-            1000.times { StringToNumber.in_numbers(text) }
-          end
-          avg_ms = (individual_time / 1000) * 1000
-          puts "  #{index + 1}. #{avg_ms.round(4)}ms - '#{text[0..50]}#{text.length > 50 ? '...' : ''}'"
+      next unless category == :complex
+
+      puts 'Individual case breakdown:'
+      test_cases.each_with_index do |text, index|
+        individual_time = Benchmark.realtime do
+          1000.times { StringToNumber.in_numbers(text) }
         end
-        puts
+        avg_ms = (individual_time / 1000) * 1000
+        puts "  #{index + 1}. #{avg_ms.round(4)}ms - '#{text[0..50]}#{'...' if text.length > 50}'"
       end
+      puts
     end
 
     # Summary
-    puts "=" * 50
-    puts "PERFORMANCE SUMMARY"
-    puts "=" * 50
+    puts '=' * 50
+    puts 'PERFORMANCE SUMMARY'
+    puts '=' * 50
 
     total_results.each do |category, results|
       status = case results[:avg_time_ms]
-               when 0..0.1 then "🟢 Excellent"
-               when 0.1..0.5 then "🟡 Good"
-               when 0.5..1.0 then "🟠 Acceptable"
-               else "🔴 Needs optimization"
+               when 0..0.1 then '🟢 Excellent'
+               when 0.1..0.5 then '🟡 Good'
+               when 0.5..1.0 then '🟠 Acceptable'
+               else '🔴 Needs optimization'
                end
-      
+
       puts "#{category.to_s.capitalize.ljust(12)} #{status.ljust(15)} #{results[:avg_time_ms].round(4)}ms avg"
     end
 
     puts
-    puts "Memory efficiency test..."
+    puts 'Memory efficiency test...'
     test_memory_usage
 
     puts
-    puts "Scalability test..."
+    puts 'Scalability test...'
     test_scalability
   end
 
-  private
-
   def self.benchmark_category(test_cases, iterations = 2000)
     total_time = Benchmark.realtime do
       test_cases.each do |text|
@@ -130,7 +128,7 @@ class StringToNumberBenchmark
 
       puts "Object creation: #{object_growth} new objects (#{object_growth > 1000 ? '🔴 High' : '🟢 Low'})"
     else
-      puts "Memory tracking not available on this platform"
+      puts 'Memory tracking not available on this platform'
     end
   end
 
@@ -138,27 +136,32 @@ class StringToNumberBenchmark
     # Test how performance scales with input complexity
     inputs = [
       'un',                                                           # 2 chars
-      'vingt et un',                                                  # 11 chars  
+      'vingt et un',                                                  # 11 chars
       'mille deux cent trente-quatre',                               # 29 chars
       'trois milliards cinq cents millions deux cent mille et une'   # 58 chars
     ]
 
-    puts "Input length vs. performance:"
-    
+    puts 'Input length vs. performance:'
+
     results = inputs.map do |input|
       time = Benchmark.realtime do
         1000.times { StringToNumber.in_numbers(input) }
       end
       avg_ms = (time / 1000) * 1000
-      
+
       { length: input.length, time: avg_ms, input: input }
     end
 
     results.each do |result|
       complexity_ratio = result[:time] / results.first[:time]
-      status = complexity_ratio < 5 ? "🟢" : complexity_ratio < 10 ? "🟡" : "🔴"
-      
-      puts "  #{result[:length].to_s.rjust(2)} chars: #{result[:time].round(4)}ms #{status} (#{complexity_ratio.round(1)}x baseline)"
+      status = if complexity_ratio < 5
+                 '🟢'
+               else
+                 complexity_ratio < 10 ? '🟡' : '🔴'
+               end
+
+      puts "  #{result[:length].to_s.rjust(2)} chars: #{result[:time].round(4)}ms #{status} " \
+           "(#{complexity_ratio.round(1)}x baseline)"
     end
 
     # Check if performance degrades reasonably
@@ -172,6 +175,4 @@ class StringToNumberBenchmark
 end
 
 # Run the benchmark
-if __FILE__ == $0
-  StringToNumberBenchmark.run_benchmark
-end
+StringToNumberBenchmark.run_benchmark if __FILE__ == $PROGRAM_NAME

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.