map 6.6.0 → 8.0.0

data/specs/001-ordered-map-module/spec.md

@@ -0,0 +1,108 @@
+# Feature Specification: Conditional Ordered Map Module
+
+**Feature Branch**: `001-ordered-map-module`
+**Created**: 2025-11-10
+**Status**: Draft
+**Input**: User description: "we want to support all features of map in newer rubies, which have ordered maps.  we wish to extact the 'ordered' parts of map as a module, and only include it in Map for older/non-hash-ordered, rubies.  we want a KISS way to test this."
+
+## User Scenarios & Testing *(mandatory)*
+
+### User Story 1 - Legacy Ruby Support (Priority: P1)
+
+When developers use Map in Ruby 1.8.x (or other non-ordered hash implementations), they must receive the same ordered hash behavior that Map has always provided, with keys tracked in insertion order via the `@keys` array mechanism.
+
+**Why this priority**: This is the core value proposition - maintaining backward compatibility for users on older Ruby versions without breaking existing functionality. Without this, Map would lose its "works in all rubies" promise.
+
+**Independent Test**: Can be fully tested by running the existing test suite on Ruby 1.8.x or similar non-ordered hash implementations and verifying that all ordering-related tests pass.
+
+**Acceptance Scenarios**:
+
+1. **Given** Map running on Ruby 1.8.x, **When** a user creates a map with `Map[:a, 1, :b, 2, :c, 3]`, **Then** calling `keys` returns `['a', 'b', 'c']` in insertion order
+2. **Given** Map running on Ruby 1.8.x, **When** a user iterates with `each`, **Then** key-value pairs are yielded in insertion order
+3. **Given** Map running on Ruby 1.8.x, **When** a user calls `first` and `last`, **Then** they return the first and last inserted key-value pairs respectively
+
+---
+
+### User Story 2 - Modern Ruby Optimization (Priority: P2)
+
+When developers use Map in Ruby 1.9+ (where Hash is ordered by default), they must benefit from native Hash ordering performance without the overhead of maintaining a redundant `@keys` array.
+
+**Why this priority**: This improves performance and reduces memory overhead for the majority of current users, but doesn't break functionality since Ruby 1.9+ hashes are already ordered. This is secondary to maintaining backward compatibility.
+
+**Independent Test**: Can be fully tested by running the test suite on Ruby 1.9+ and verifying that: (1) all tests pass, (2) no `@keys` instance variable is present in Map instances, and (3) ordering behavior matches expected results.
+
+**Acceptance Scenarios**:
+
+1. **Given** Map running on Ruby 1.9+, **When** a user creates a map with `Map[:a, 1, :b, 2, :c, 3]`, **Then** calling `keys` returns `['a', 'b', 'c']` in insertion order without using `@keys` array
+2. **Given** Map running on Ruby 1.9+, **When** a user inspects a Map instance, **Then** no `@keys` instance variable is present
+3. **Given** Map running on Ruby 1.9+, **When** a user calls ordering-dependent methods (`first`, `last`, `values`, `each`), **Then** they work correctly using native Hash ordering
+
+---
+
+### User Story 3 - Simple Cross-Version Testing (Priority: P3)
+
+When developers or CI systems need to verify Map behavior across Ruby versions, they must have a simple, KISS (Keep It Simple, Stupid) way to run tests that validate both code paths (with and without the ordered module).
+
+**Why this priority**: Testing is important but can be implemented after the core functionality works. It's a development/maintenance concern rather than end-user functionality.
+
+**Independent Test**: Can be fully tested by running a test command that simulates both Ruby version scenarios and verifying that it produces clear pass/fail results for both paths.
+
+**Acceptance Scenarios**:
+
+1. **Given** a test runner configuration, **When** tests are executed, **Then** both "ordered module included" and "ordered module excluded" scenarios are tested
+2. **Given** test results, **When** reviewing output, **Then** it's clear which tests ran under which configuration (ordered module on/off)
+3. **Given** CI environment, **When** tests run, **Then** failures in either path are clearly reported with context about which Ruby version scenario failed
+
+---
+
+### Edge Cases
+
+- What happens when the Ruby version detection is ambiguous (e.g., alternative Ruby implementations like JRuby, Rubinius)?
+- How does the system handle Ruby versions with the ordering backport?
+- What happens during Marshal load/dump of Maps created on different Ruby versions?
+- How does the module inclusion affect class inheritance and subclassing of Map?
+
+## Requirements *(mandatory)*
+
+### Functional Requirements
+
+- **FR-001**: System MUST extract all ordering-related code (using `@keys` array) into a separate module
+- **FR-002**: System MUST conditionally include the ordering module only when Ruby Hash is not ordered by default (Ruby < 1.9)
+- **FR-003**: System MUST detect Ruby version at load time to determine whether Hash is ordered
+- **FR-004**: System MUST maintain identical external API behavior regardless of whether ordering module is included
+- **FR-005**: System MUST preserve Marshal compatibility for existing Map instances
+- **FR-006**: System MUST ensure all existing tests pass on both old and new Ruby versions without modification
+- **FR-007**: System MUST provide ordering module methods that override default Hash methods when included (e.g., `keys`, `values`, `each`, `first`, `last`, `delete`, `[]=`)
+- **FR-008**: Test framework MUST provide simple mechanism to test both code paths (with/without ordering module)
+- **FR-009**: System MUST handle `@keys` array initialization in `allocate` method conditionally based on Ruby version
+
+### Key Entities *(include if feature involves data)*
+
+- **OrderingModule**: A module containing all `@keys` array-dependent methods that maintain insertion order manually
+- **Map Class**: The main class that conditionally includes OrderingModule based on Ruby version detection
+- **Ruby Version Detector**: Logic that determines if native Hash ordering is available
+
+## Success Criteria *(mandatory)*
+
+### Measurable Outcomes
+
+- **SC-001**: All existing Map tests pass without modification on both Ruby 1.8.x and Ruby 1.9+ versions
+- **SC-002**: Map instances on Ruby 1.9+ do not contain `@keys` instance variable (verified via instance_variables inspection)
+- **SC-003**: Map maintains insertion order correctly in both Ruby version scenarios (100% of ordering-dependent operations return correct results)
+- **SC-004**: Developers can run a single test command that validates both code paths with clear pass/fail output
+- **SC-005**: Memory footprint per Map instance is reduced on Ruby 1.9+ due to absence of redundant `@keys` array
+- **SC-006**: Test execution time remains similar or improves (no more than 5% regression) across both Ruby versions
+
+### Assumptions
+
+- Ruby 1.9.0 is the cutoff version where Hash became ordered by default
+- The existing test suite adequately covers all ordering-dependent behavior
+- Marshal serialization format compatibility is acceptable to break across Ruby versions (Map objects serialized on old Ruby may not deserialize correctly on new Ruby if format changes)
+- Alternative Ruby implementations (JRuby, Rubinius, TruffleRuby) follow the same ordering behavior as MRI for their respective version numbers
+- The KISS testing approach means a simple flag or environment variable to force inclusion/exclusion of the ordering module, rather than complex test matrix infrastructure
+
+### Dependencies
+
+- Access to multiple Ruby version environments for testing (Ruby 1.8.x and Ruby 1.9+)
+- Existing test suite must be comprehensive enough to validate ordering behavior
+- No breaking changes to public API (all existing Map users' code must continue to work)

data/specs/001-ordered-map-module/tasks.md

@@ -0,0 +1,264 @@
+# Tasks: Conditional Ordered Map Module
+
+**Input**: Design documents from `/specs/001-ordered-map-module/`
+**Prerequisites**: plan.md, spec.md, research.md, data-model.md, quickstart.md
+
+**Tests**: No explicit TDD requirement in spec - using existing test suite for validation
+
+**Organization**: Tasks are grouped by user story to enable independent implementation and testing of each story.
+
+## Format: `[ID] [P?] [Story] Description`
+
+- **[P]**: Can run in parallel (different files, no dependencies)
+- **[Story]**: Which user story this task belongs to (e.g., US1, US2, US3)
+- Include exact file paths in descriptions
+
+## Path Conventions
+
+Ruby gem structure: `lib/` for source, `test/` for tests at repository root.
+
+---
+
+## Phase 1: Setup (Shared Infrastructure)
+
+**Purpose**: Prepare development environment and understand current codebase
+
+- [x] T001 Read and understand existing Map implementation in lib/map.rb
+- [x] T002 Identify all 11 ordering-dependent methods that use `@keys` array in lib/map.rb
+- [x] T003 [P] Document current `@keys` array usage patterns and synchronization points
+- [x] T004 [P] Run existing test suite to establish baseline (rake test)
+
+**Checkpoint**: Understanding of current implementation complete
+
+---
+
+## Phase 2: Foundational (Blocking Prerequisites)
+
+**Purpose**: Core module structure that MUST be complete before ANY user story can be implemented
+
+**⚠️ CRITICAL**: No user story work can begin until this phase is complete
+
+- [x] T005 Create new file lib/map/ordering.rb with module structure skeleton
+- [x] T006 Define Map::Ordering module with proper namespace in lib/map/ordering.rb
+- [x] T007 Implement module self.included hook for class method injection in lib/map/ordering.rb
+- [x] T008 Add conditional require and include logic in lib/map.rb (RUBY_VERSION < '1.9' || ENV['MAP_FORCE_ORDERING'])
+
+**Checkpoint**: Foundation ready - user story implementation can now begin in parallel
+
+---
+
+## Phase 3: User Story 1 - Legacy Ruby Support (Priority: P1) 🎯 MVP
+
+**Goal**: Extract all ordering-related code to Map::Ordering module so Ruby < 1.9 maintains insertion order via `@keys` array
+
+**Independent Test**: Run tests with `MAP_FORCE_ORDERING=1` to simulate Ruby < 1.9 behavior, verify all ordering tests pass and `@keys` variable exists
+
+### Implementation for User Story 1
+
+- [x] T009 [P] [US1] Move Map.allocate class method to Map::Ordering module (initializes `@keys = []`) in lib/map/ordering.rb
+- [x] T010 [P] [US1] Move keys instance method to Map::Ordering module (returns `@keys`) in lib/map/ordering.rb
+- [x] T011 [P] [US1] Move []= (store) method to Map::Ordering module (tracks keys in `@keys` array) in lib/map/ordering.rb
+- [x] T012 [P] [US1] Move values method to Map::Ordering module (iterates `@keys` to build array) in lib/map/ordering.rb
+- [x] T013 [P] [US1] Move first method to Map::Ordering module (uses `@keys.first`) in lib/map/ordering.rb
+- [x] T014 [P] [US1] Move last method to Map::Ordering module (uses `@keys.last`) in lib/map/ordering.rb
+- [x] T015 [P] [US1] Move each/each_pair method to Map::Ordering module (iterates `@keys`) in lib/map/ordering.rb
+- [x] T016 [P] [US1] Move each_key method to Map::Ordering module (iterates `@keys`) in lib/map/ordering.rb
+- [x] T017 [P] [US1] Move each_value method to Map::Ordering module (iterates `@keys` to access values) in lib/map/ordering.rb
+- [x] T018 [P] [US1] Move each_with_index method to Map::Ordering module (uses `@keys.each_with_index`) in lib/map/ordering.rb
+- [x] T019 [P] [US1] Move delete method to Map::Ordering module (removes from `@keys` array) in lib/map/ordering.rb
+- [x] T020 [US1] Remove or comment out the 11 extracted methods from lib/map.rb (module will provide them when included)
+- [x] T021 [US1] Verify Map::Ordering module is complete and syntactically correct (ruby -c lib/map/ordering.rb)
+- [x] T022 [US1] Test with MAP_FORCE_ORDERING=1 rake test - verify all tests pass
+- [x] T023 [US1] Verify @keys instance variable exists when module included (add inspection test)
+
+**Checkpoint**: At this point, User Story 1 should be fully functional - Ruby < 1.9 behavior simulated via MAP_FORCE_ORDERING=1
+
+---
+
+## Phase 4: User Story 2 - Modern Ruby Optimization (Priority: P2)
+
+**Goal**: Ensure Ruby 1.9+ uses native Hash ordering without `@keys` array overhead, achieving 25% memory savings
+
+**Independent Test**: Run tests normally (without MAP_FORCE_ORDERING) on Ruby 1.9+, verify all tests pass, no `@keys` variable exists, and ordering works correctly
+
+### Implementation for User Story 2
+
+- [x] T024 [US2] Verify conditional inclusion logic in lib/map.rb correctly excludes module on Ruby >= 1.9
+- [x] T025 [US2] Test normal execution (rake test) on current Ruby version (3.x) - verify all tests pass
+- [x] T026 [US2] Verify Map instances have no @keys instance variable (map.instance_variables inspection)
+- [x] T027 [US2] Verify ordering methods delegate to Hash superclass correctly (keys, values, each, first, last)
+- [x] T028 [US2] Add test case to verify memory optimization - Map instance should not have @keys in lib/map.rb comment or test
+- [x] T029 [US2] Verify Map::Options subclass inherits correct behavior (no @keys on Ruby 1.9+)
+- [x] T030 [US2] Performance verification - ensure no regression in iteration speed (optional benchmark)
+
+**Checkpoint**: At this point, User Stories 1 AND 2 should both work - Ruby 1.9+ optimized, legacy simulated via env var
+
+---
+
+## Phase 5: User Story 3 - Simple Cross-Version Testing (Priority: P3)
+
+**Goal**: Provide KISS testing mechanism via MAP_FORCE_ORDERING=1 environment variable to validate both code paths
+
+**Independent Test**: Run test suite both ways (with and without MAP_FORCE_ORDERING), verify clear output shows which path is active
+
+### Implementation for User Story 3
+
+- [ ] T031 [P] [US3] Add test helper to detect and report which mode is active in test/map_test.rb or test/lib/testing.rb
+- [ ] T032 [P] [US3] Create verification test that checks @keys presence matches expected mode in test/map_test.rb
+- [ ] T033 [US3] Document testing approach in README.md or TESTING.md file
+- [ ] T034 [US3] Add CI configuration example for testing both paths in .github/workflows or equivalent
+- [ ] T035 [US3] Create quick verification script (test/verify_ordering.rb) that demonstrates both modes per quickstart.md
+- [ ] T036 [US3] Update Rakefile to support `rake test:with_ordering` and `rake test:without_ordering` tasks
+- [ ] T037 [US3] Verify test output clearly indicates which configuration ran (module included/excluded)
+- [ ] T038 [US3] Run full test suite in both modes and verify identical pass/fail results
+
+**Checkpoint**: All user stories should now be independently functional - both code paths validated
+
+---
+
+## Phase 6: Polish & Cross-Cutting Concerns
+
+**Purpose**: Improvements that affect multiple user stories and finalize the feature
+
+- [ ] T039 [P] Update CHANGELOG with feature description and version notes
+- [ ] T040 [P] Update README.md with explanation of conditional ordering module (if needed)
+- [ ] T041 [P] Add code comments explaining module inclusion logic in lib/map.rb
+- [ ] T042 [P] Add module documentation comments in lib/map/ordering.rb
+- [ ] T043 [P] Document Marshal compatibility limitation in CHANGELOG or README
+- [ ] T044 [US3] Run quickstart.md validation - verify all examples work
+- [ ] T045 Verify Map::Options subclass works correctly in both modes
+- [ ] T046 Check for any Ruby 1.8 syntax issues in Map::Ordering module (if targeting old Ruby)
+- [ ] T047 Final regression test - run existing test suite 3 times (normal, forced ordering, different Ruby if available)
+- [ ] T048 Code review checklist - verify all 11 methods extracted, no duplicates, proper delegation
+
+---
+
+## Dependencies & Execution Order
+
+### Phase Dependencies
+
+- **Setup (Phase 1)**: No dependencies - can start immediately
+- **Foundational (Phase 2)**: Depends on Setup completion - BLOCKS all user stories
+- **User Stories (Phase 3-5)**: All depend on Foundational phase completion
+  - User Story 1 (P1): Can start after Foundational - No dependencies on other stories
+  - User Story 2 (P2): Depends on User Story 1 completion (needs module to verify exclusion works)
+  - User Story 3 (P3): Depends on User Stories 1 & 2 (needs both paths working to test)
+- **Polish (Phase 6)**: Depends on all user stories being complete
+
+### User Story Dependencies
+
+- **User Story 1 (P1)**: Can start after Foundational (Phase 2) - Core extraction work
+- **User Story 2 (P2)**: Depends on User Story 1 completion - Validates optimization path
+- **User Story 3 (P3)**: Depends on User Stories 1 & 2 - Validates testing mechanism across both
+
+**Note**: Unlike typical projects, these user stories are sequential because:
+- US2 requires US1 module to exist before verifying it's correctly excluded
+- US3 requires both code paths (US1 & US2) working before testing mechanism is meaningful
+
+### Within Each User Story
+
+- **User Story 1**: Tasks T009-T019 (method moves) are parallelizable [P]
+- **User Story 2**: Tasks T026-T027 are verification steps, run sequentially
+- **User Story 3**: Tasks T031-T032 (test helpers) are parallelizable [P]
+
+### Parallel Opportunities
+
+- Phase 1: Tasks T003-T004 can run in parallel
+- Phase 2: All tasks sequential (building foundation)
+- User Story 1: Tasks T009-T019 (11 method extractions) can be done in parallel
+- User Story 3: Tasks T031-T032, T033-T034, T039-T043 can run in parallel
+- Polish Phase: Documentation tasks T039-T043 can run in parallel
+
+---
+
+## Parallel Example: User Story 1 (Method Extraction)
+
+```bash
+# All 11 method extractions can happen simultaneously:
+Task: "Move Map.allocate to Map::Ordering (initializes @keys) in lib/map/ordering.rb"
+Task: "Move keys method to Map::Ordering (returns @keys) in lib/map/ordering.rb"
+Task: "Move []= method to Map::Ordering (tracks keys) in lib/map/ordering.rb"
+Task: "Move values method to Map::Ordering (iterates @keys) in lib/map/ordering.rb"
+Task: "Move first method to Map::Ordering (uses @keys.first) in lib/map/ordering.rb"
+Task: "Move last method to Map::Ordering (uses @keys.last) in lib/map/ordering.rb"
+Task: "Move each/each_pair to Map::Ordering (iterates @keys) in lib/map/ordering.rb"
+Task: "Move each_key method to Map::Ordering (iterates @keys) in lib/map/ordering.rb"
+Task: "Move each_value to Map::Ordering (iterates @keys) in lib/map/ordering.rb"
+Task: "Move each_with_index to Map::Ordering (uses @keys) in lib/map/ordering.rb"
+Task: "Move delete method to Map::Ordering (removes from @keys) in lib/map/ordering.rb"
+
+# These are all independent - different methods being moved to same new file
+```
+
+---
+
+## Implementation Strategy
+
+### MVP First (User Story 1 Only)
+
+1. Complete Phase 1: Setup (understand current code)
+2. Complete Phase 2: Foundational (create module structure)
+3. Complete Phase 3: User Story 1 (extract all ordering methods)
+4. **STOP and VALIDATE**: Test with MAP_FORCE_ORDERING=1, verify @keys exists and tests pass
+5. Ready for PR/review with backward compatibility proven
+
+### Incremental Delivery
+
+1. Complete Setup + Foundational → Module structure ready
+2. Add User Story 1 → Test with forced ordering → Backward compat proven (MVP!)
+3. Add User Story 2 → Test normal mode → Optimization verified
+4. Add User Story 3 → Test both modes → Testing mechanism validated
+5. Polish → Documentation complete → Feature done
+
+### Single Developer Strategy
+
+Since user stories are sequential:
+
+1. Complete Setup + Foundational (Phase 1-2)
+2. Extract all methods to module (Phase 3 / US1) - can parallelize the 11 method moves
+3. Verify optimization works (Phase 4 / US2)
+4. Add testing mechanism (Phase 5 / US3)
+5. Polish and document (Phase 6)
+
+---
+
+## Task Summary
+
+**Total Tasks**: 48 tasks
+
+**Task Count by Phase**:
+- Phase 1 (Setup): 4 tasks
+- Phase 2 (Foundational): 4 tasks
+- Phase 3 (User Story 1 - Legacy Support): 15 tasks
+- Phase 4 (User Story 2 - Optimization): 7 tasks
+- Phase 5 (User Story 3 - Testing): 8 tasks
+- Phase 6 (Polish): 10 tasks
+
+**Parallelizable Tasks**: 26 tasks marked with [P]
+
+**User Story Mapping**:
+- US1 (Legacy Ruby Support): 15 tasks - Module extraction
+- US2 (Modern Ruby Optimization): 7 tasks - Verification and optimization
+- US3 (Cross-Version Testing): 8 tasks - Testing mechanism
+
+**Suggested MVP Scope**:
+- Phase 1 + Phase 2 + Phase 3 (User Story 1)
+- Total: 23 tasks to achieve backward compatibility with module extraction
+- Deliverable: Map works with forced ordering mode, proving legacy Ruby support
+
+**Independent Testing**:
+- US1: Run with `MAP_FORCE_ORDERING=1 rake test`, verify @keys exists
+- US2: Run with `rake test`, verify no @keys, all tests pass
+- US3: Run both modes, verify test output clarity
+
+---
+
+## Notes
+
+- [P] tasks = can run in parallel (different methods, independent work)
+- [Story] label maps task to specific user story for traceability
+- This is an internal refactoring, so no external API contracts
+- Existing test suite is validation - no new tests required per spec
+- Module extraction enables clean separation without code duplication
+- Commit after each logical group (e.g., after all methods extracted)
+- Stop at any checkpoint to validate story independently

data/test/map_test.rb

@@ -173,18 +173,6 @@ Testing Map do
     assert{ a != b}
   end
 
-  testing 'simple struct usage' do
-    a = assert{ Map.new(:k => :v) }
-    s = assert{ a.struct }
-    assert{ s.k == :v }
-  end
-
-  testing 'nested struct usage' do
-    a = assert{ Map.new(:k => {:l => :v}) }
-    s = assert{ a.struct }
-    assert{ s.k.l == :v }
-  end
-
   testing 'that subclassing and clobbering initialize does not kill nested coersion' do
     c = Class.new(Map){ def initialize(arg) end }
     o = assert{ c.new(42) }
@@ -250,7 +238,6 @@ Testing Map do
   end
 
   testing 'that coercion is minimal' do
-    map = Map.new
     a = Class.new(Map) do
       def to_map() {:k => :a} end
     end
@@ -284,7 +271,6 @@ Testing Map do
     logic = proc do |method, args|
       before = args.dup
       opts = assert{ Map.send(method, args) }
-      after = args
 
       assert{ opts.is_a?(Map) }
       assert{ !args.last.is_a?(Hash) } if before.last.is_a?(Hash)
@@ -503,7 +489,7 @@ Testing Map do
     each = []
     array = %w( a b c )
     Map.each_pair(array){|k,v| each.push(k,v)}
-    assert{ each_pair = ['a', 'b', 'c', nil] }
+    assert{ each == ['a', 'b', 'c', nil] }
   end
 
   testing 'that maps support breath_first_each' do
@@ -517,6 +503,7 @@ Testing Map do
 
     accum = []
     Map.breadth_first_each(map){|k, v| accum.push([k, v])}
+
     expected =
       [[["hash"], {"x"=>"y"}],
        [["nested hash"], {"nested"=>{"a"=>"b"}}],
@@ -535,6 +522,8 @@ Testing Map do
        [["nested array", 0, 0], 3],
        [["nested array", 1, 0], 4],
        [["nested array", 2, 0], 5]]
+
+    assert{ expected == accum }
   end
 
   testing 'that maps have a needle-in-a-haystack like #contains? method' do
@@ -666,30 +655,6 @@ Testing Map do
     assert( m.A? )
   end
 
-  testing 'that maps have a clever little question method on Struct' do
-    m = Map.new
-    m.set(:a, :b, :c, 42)
-    m.set([:x, :y, :z] => 42.0, [:A, 2] => 'forty-two')
-    s = m.struct
-
-    assert( s.a.b.c == 42   )
-    assert( s.x.y.z == 42.0 )
-
-    assert( !s.b? )
-    assert( s.a? )
-    assert( s.a.b? )
-    assert( s.a.b.c? )
-    assert( !s.a.b.d? )
-
-    assert( s.x? )
-    assert( s.x.y? )
-    assert( s.x.y.z? )
-    assert( !s.y? )
-
-    assert( s.A? )
-
-  end
-
   testing 'that Map#default= blows up until a sane strategy for dealing with it is developed' do
     m = Map.new
 
@@ -745,24 +710,6 @@ Testing Map do
     assert{ map.list.class != Array }
   end
 
-  testing 'rack compatible params' do
-    m = Map.for(:a => [{}, {:b => 42}], :x => [ nil, [ nil, {:y => 42}] ], :A => {:B => {:C => 42}})
-
-    assert{ m.param_for(:a, 1, :b) == 'map[a][][b]=42' }
-    assert{ m.name_for(:a, 1, :b) == 'map[a][][b]' }
-
-    assert{ m.param_for(:x, 1, 1, :y) == 'map[x][][][y]=42' }
-    assert{ m.name_for(:x, 1, 1, :y) == 'map[x][][][y]' }
-
-    assert{ m.param_for(:A, :B, :C) == 'map[A][B][C]=42' }
-    assert{ m.name_for(:A, :B, :C) == 'map[A][B][C]' }
-
-    assert{ m.name_for(:A, :B, :C, :prefix => :foo) == 'foo[A][B][C]' }
-
-    m = Map.for({"a"=>{"b"=>42}, "x"=>{"y"=>42}, "foo"=>:bar, "array"=>[{"k"=>:v}]})
-    assert{ m.to_params == "map[a][b]=42&map[x][y]=42&map[foo]=bar&map[array][][k]=v"  }
-  end
-
   testing 'delete_if' do
     m = Map.for(:k => :v)
     assert{ m.delete_if{|k| k.to_s == 'k'} }
@@ -773,6 +720,23 @@ Testing Map do
     assert{ m.empty?}
   end
 
+  testing 'deep fetch' do
+    m = Map.for(:a => {:b => {:c => :v}})
+
+    assert{ m.fetch(:a, :b, :c) == :v }
+  end
+
+  testing 'fetch mapifys' do
+    m = Map.new
+    h = {:key => :value, :hash => {:a => :b}, :array => [0, {:a => :b}]}
+
+    missing = assert{ m.fetch(:missing){ h } }
+    assert{ missing.is_a?(Map) }
+    assert{ missing[:hash].is_a?(Map) }
+    assert{ not missing[:array][0].is_a?(Map) }
+    assert{ missing[:array][1].is_a?(Map) }
+  end
+
 protected
   def new_int_map(n = 1024)
     map = assert{ Map.new }

metadata

@@ -1,18 +1,29 @@
 --- !ruby/object:Gem::Specification
 name: map
 version: !ruby/object:Gem::Version
-  version: 6.6.0
-  prerelease: 
+  version: 8.0.0
 platform: ruby
 authors:
 - Ara T. Howard
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2016-01-12 00:00:00.000000000 Z
+date: 2025-11-13 00:00:00.000000000 Z
 dependencies: []
-description: ! 'the awesome ruby container you''ve always wanted: a string/symbol
-  indifferent ordered hash that works in all rubies'
+description: |-
+  map.rb is a string/symbol indifferent ordered hash that works in all rubies.
+
+  out of the over 200 ruby gems i have written, this is the one i use
+  every day, in all my projects.
+
+  some may be accustomed to using ActiveSupport::HashWithIndiffentAccess
+  and, although there are some similarities, map.rb is more complete,
+  works without requiring a mountain of code, and has been in production
+  usage for over 15 years.
+
+  it has no dependencies, and suports a myriad of other, 'tree-ish'
+  operators that will allow you to slice and dice data like a giraffee
+  with a giant weed whacker.
 email: ara.t.howard@gmail.com
 executables: []
 extensions: []
@@ -20,41 +31,46 @@ extra_rdoc_files: []
 files:
 - LICENSE
 - README
+- README.md
 - Rakefile
-- a.rb
+- images/giraffe.jpeg
+- images/map.png
 - lib/map.rb
-- lib/map/integrations/active_record.rb
+- lib/map/_lib.rb
 - lib/map/options.rb
-- lib/map/params.rb
-- lib/map/struct.rb
+- lib/map/ordering.rb
 - map.gemspec
+- specs/001-ordered-map-module/checklists/requirements.md
+- specs/001-ordered-map-module/data-model.md
+- specs/001-ordered-map-module/plan.md
+- specs/001-ordered-map-module/quickstart.md
+- specs/001-ordered-map-module/research.md
+- specs/001-ordered-map-module/spec.md
+- specs/001-ordered-map-module/tasks.md
 - test/leak.rb
 - test/lib/testing.rb
 - test/map_test.rb
 homepage: https://github.com/ahoward/map
 licenses:
-- same as ruby's
-post_install_message: 
+- Ruby
+metadata: {}
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
-  none: false
   requirements:
-  - - ! '>='
+  - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: '3.0'
 required_rubygems_version: !ruby/object:Gem::Requirement
-  none: false
   requirements:
-  - - ! '>='
+  - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: codeforpeople
-rubygems_version: 1.8.23.2
-signing_key: 
-specification_version: 3
-summary: map
+rubygems_version: 3.5.18
+signing_key:
+specification_version: 4
+summary: the perfect ruby data structure
 test_files: []
-has_rdoc: 

data/a.rb

@@ -1,10 +0,0 @@
-require './lib/map.rb'
-require 'yaml'
-
-a = Map.new
-a.set(:a, :b, "value")
-a.set(:a,0,:c, "value")
-
-p a
-puts a.to_hash.to_yaml # fine
-puts a.to_yaml # explode