map 6.6.0 → 8.0.0

data/lib/map/_lib.rb

@@ -0,0 +1,85 @@
+class Map
+  VERSION = '8.0.0'
+
+  class << Map
+    def version
+      VERSION
+    end
+
+    def repo
+      'https://github.com/ahoward/map'
+    end
+
+    def summary
+      <<~____
+        the perfect ruby data structure
+      ____
+    end
+
+    def 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.
+      ____
+    end
+
+    def libs
+      %w[
+      ]
+    end
+
+    def dependencies
+      {
+      }
+    end
+
+    def libdir(*args, &block)
+      @libdir ||= File.dirname(File.expand_path(__FILE__))
+      args.empty? ? @libdir : File.join(@libdir, *args)
+    ensure
+      if block
+        begin
+          $LOAD_PATH.unshift(@libdir)
+          block.call
+        ensure
+          $LOAD_PATH.shift
+        end
+      end
+    end
+
+    def load(*libs)
+      libs = libs.join(' ').scan(/[^\s+]+/)
+      libdir { libs.each { |lib| Kernel.load(lib) } }
+    end
+
+    def load_dependencies!
+      libs.each do |lib|
+        require lib
+      end
+
+      begin
+        require 'rubygems'
+      rescue LoadError
+        nil
+      end
+
+      has_rubygems = defined?(gem)
+
+      dependencies.each do |lib, dependency|
+        gem(*dependency) if has_rubygems
+        require(lib)
+      end
+    end
+  end
+end

data/lib/map/ordering.rb

@@ -0,0 +1,126 @@
+# -*- encoding : utf-8 -*-
+
+# Map::Ordering
+#
+# This module contains all ordering-related methods that use the @keys array
+# to maintain insertion order. It is conditionally included in Map only when
+# Ruby's Hash class does not maintain insertion order (Ruby < 1.9), or when
+# explicitly forced via ENV['MAP_FORCE_ORDERING'].
+#
+# On Ruby 1.9+, Hash maintains insertion order natively, so these methods are
+# not needed and Map delegates to Hash's implementation for memory optimization.
+
+class Map < Hash
+  module Ordering
+    # Hook called when module is included into Map class
+    # This allows us to inject class methods into Map
+    def self.included(base)
+      base.class_eval do
+        # Override Map.allocate to initialize @keys array
+        def self.allocate
+          super.instance_eval do
+            @keys = []
+            self
+          end
+        end
+      end
+    end
+
+    # Instance methods that track ordering via @keys array
+
+    def keys
+      @keys ||= []
+    end
+
+    def []=(key, val)
+      key, val = convert(key, val)
+      keys.push(key) unless has_key?(key)
+      __set__(key, val)
+    end
+    alias_method 'store', '[]='
+
+    def values
+      array = []
+      keys.each{|key| array.push(self[key])}
+      array
+    end
+    alias_method 'vals', 'values'
+
+    def first
+      [keys.first, self[keys.first]]
+    end
+
+    def last
+      [keys.last, self[keys.last]]
+    end
+
+    def each_with_index
+      keys.each_with_index{|key, index| yield([key, self[key]], index)}
+      self
+    end
+
+    def each_key
+      keys.each{|key| yield(key)}
+      self
+    end
+
+    def each_value
+      keys.each{|key| yield self[key]}
+      self
+    end
+
+    def each
+      keys.each{|key| yield(key, self[key])}
+      self
+    end
+    alias_method 'each_pair', 'each'
+
+    def delete(key)
+      key = convert_key(key)
+      keys.delete(key)
+      super(key)
+    end
+
+    def clear
+      keys.clear
+      super
+    end
+
+    # Array-like ordered operations
+    def shift
+      unless empty?
+        key = keys.first
+        val = delete(key)
+        [key, val]
+      end
+    end
+
+    def unshift(*args)
+      Map.each_pair(*args) do |key, val|
+        key = convert_key(key)
+        delete(key)
+        keys.unshift(key)
+        __set__(key, val)
+      end
+      self
+    end
+
+    def push(*args)
+      Map.each_pair(*args) do |key, val|
+        key = convert_key(key)
+        delete(key)
+        keys.push(key)
+        __set__(key, val)
+      end
+      self
+    end
+
+    def pop
+      unless empty?
+        key = keys.last
+        val = delete(key)
+        [key, val]
+      end
+    end
+  end
+end

data/lib/map.rb

@@ -1,41 +1,10 @@
 # -*- encoding : utf-8 -*-
 class Map < Hash
-  Version = '6.6.0' unless defined?(Version)
-  Load = Kernel.method(:load) unless defined?(Load)
+  require_relative 'map/_lib.rb'
 
   class << Map
-    def version
-      Map::Version
-    end
-
-    def description
-      "the awesome ruby container you've always wanted: a string/symbol indifferent ordered hash that works in all rubies"
-    end
-
-    def libdir(*args, &block)
-      @libdir ||= File.expand_path(__FILE__).sub(/\.rb$/,'')
-      libdir = args.empty? ? @libdir : File.join(@libdir, *args.map{|arg| arg.to_s})
-    ensure
-      if block
-        begin
-          $LOAD_PATH.unshift(libdir) unless $LOAD_PATH.first==libdir
-          module_eval(&block)
-        ensure
-          $LOAD_PATH.shift() if $LOAD_PATH.first==libdir
-        end
-      end
-    end
-
-    def load(*args, &block)
-      libdir{ Load.call(*args, &block) }
-    end
-
-    def allocate
-      super.instance_eval do
-        @keys = []
-        self
-      end
-    end
+    # allocate method moved to Map::Ordering module (conditionally included)
+    # When ordering module is not included (Ruby 1.9+), Hash.allocate is used
 
     def new(*args, &block)
       allocate.instance_eval do
@@ -195,11 +164,10 @@ class Map < Hash
     end
   end
 
-# instance constructor 
+# instance constructor
 #
-  def keys
-    @keys ||= []
-  end
+  # keys method moved to Map::Ordering module (conditionally included)
+  # When ordering module is not included (Ruby 1.9+), Hash#keys is used
 
   def initialize(*args, &block)
     case args.size
@@ -258,6 +226,17 @@ class Map < Hash
     key.kind_of?(Symbol) ? key.to_s : key
   end
 
+  def Map.mapify(object)
+    case
+      when object.is_a?(Array)
+        object.each{|it| Map.mapify(it)}
+      when object.is_a?(Hash)
+        Map.for(object)
+      else
+        object
+    end
+  end
+
   def convert_key(key)
     if klass.respond_to?(:convert_key)
       klass.convert_key(key)
@@ -332,21 +311,32 @@ class Map < Hash
   alias_method '__get__', '[]' unless method_defined?('__get__')
   alias_method '__update__', 'update' unless method_defined?('__update__')
 
-  def []=(key, val)
-    key, val = convert(key, val)
-    keys.push(key) unless has_key?(key)
-    __set__(key, val)
+  # []= method:
+  # - With ordering module (Ruby < 1.9 or forced): tracks keys in @keys array
+  # - Without module (Ruby >= 1.9, not forced): just converts and stores
+  #
+  # Only define for Ruby >= 1.9 without forced ordering (module provides it otherwise)
+  unless RUBY_VERSION < '1.9' || ENV['MAP_FORCE_ORDERING']
+    def []=(key, val)
+      key, val = convert(key, val)
+      __set__(key, val)
+    end
+    alias_method 'store', '[]='
   end
-  alias_method 'store', '[]='
 
   def [](key)
     key = convert_key(key)
     __get__(key)
   end
 
-  def fetch(key, *args, &block)
-    key = convert_key(key)
-    super(key, *args, &block)
+  def fetch(key, *keys, &block)
+    keys.unshift(key)
+
+    if has?(*keys)
+      get(*keys)
+    else
+      Map.mapify(yield)
+    end
   end
 
   def key?(key)
@@ -377,59 +367,67 @@ class Map < Hash
     replace(reverse_merge(hash))
   end
 
-  def values
-    array = []
-    keys.each{|key| array.push(self[key])}
-    array
-  end
-  alias_method 'vals', 'values'
+  # Ordering-dependent methods moved to Map::Ordering module (conditionally included):
+  # - values, each_with_index, each_key, each_value, each/each_pair (iterate via @keys)
+  # - clear (maintain @keys synchronization)
+  # When ordering module is not included (Ruby 1.9+), Hash methods are used
 
-  def values_at(*keys)
-    keys.map{|key| self[key]}
-  end
+  # For Ruby >= 1.9 without ordering module, provide optimized implementations
+  # These methods are only defined when the ordering module is NOT included
+  unless RUBY_VERSION < '1.9' || ENV['MAP_FORCE_ORDERING']
+    # delete needs key conversion
+    def delete(key)
+      key = convert_key(key)
+      super(key)
+    end
 
-  def first
-    [keys.first, self[keys.first]]
-  end
+    # first and last return [key, value] pairs
+    # Use keys array since Hash#first/Hash#last don't exist in all Ruby versions
+    def first
+      key = keys.first
+      [key, self[key]] if key
+    end
 
-  def last
-    [keys.last, self[keys.last]]
-  end
+    def last
+      key = keys.last
+      [key, self[key]] if key
+    end
 
-# iterator methods
-#
-  def each_with_index
-    keys.each_with_index{|key, index| yield([key, self[key]], index)}
-    self
-  end
+    # values uses Hash#values (ordered in 1.9+)
+    def values
+      Hash.instance_method(:values).bind(self).call
+    end
 
-  def each_key
-    keys.each{|key| yield(key)}
-    self
-  end
+    # Iterator methods delegate to Hash (ordered in 1.9+)
+    def each
+      Hash.instance_method(:each).bind(self).call{|k, v| yield(k, v)}
+    end
+    alias_method 'each_pair', 'each'
 
-  def each_value
-    keys.each{|key| yield self[key]}
-    self
-  end
+    def each_key
+      Hash.instance_method(:each_key).bind(self).call{|k| yield(k)}
+    end
 
-  def each
-    keys.each{|key| yield(key, self[key])}
-    self
-  end
-  alias_method 'each_pair', 'each'
+    def each_value
+      Hash.instance_method(:each_value).bind(self).call{|v| yield(v)}
+    end
 
-# mutators
-#
-  def delete(key)
-    key = convert_key(key)
-    keys.delete(key)
-    super(key)
+    def each_with_index
+      i = 0
+      each do |k, v|
+        yield([k, v], i)
+        i += 1
+      end
+      self
+    end
+
+    def clear
+      Hash.instance_method(:clear).bind(self).call
+    end
   end
 
-  def clear
-    keys.clear
-    super
+  def values_at(*keys)
+    keys.map{|key| self[key]}
   end
 
   def delete_if(&block)
@@ -460,39 +458,51 @@ class Map < Hash
 
 # ordered container specific methods
 #
-  def shift
-    unless empty?
-      key = keys.first
-      val = delete(key)
-      [key, val]
+  # When Map::Ordering module is included (Ruby < 1.9 or forced):
+  #   These methods use @keys array for efficient order manipulation
+  # When module is NOT included (Ruby 1.9+):
+  #   These methods are defined below and work with Hash's native ordering
+  #
+  # Only define for Ruby >= 1.9 without forced ordering (module provides them otherwise)
+  unless RUBY_VERSION < '1.9' || ENV['MAP_FORCE_ORDERING']
+    def shift
+      unless empty?
+        key = keys.first
+        val = delete(key)
+        [key, val]
+      end
     end
-  end
 
-  def unshift(*args)
-    Map.each_pair(*args) do |key, val|
-      key = convert_key(key)
-      delete(key)
-      keys.unshift(key)
-      __set__(key, val)
+    def unshift(*args)
+      # For Ruby 1.9+: process each pair in order, unshifting sequentially
+      # This matches the @keys array behavior
+      Map.each_pair(*args) do |key, val|
+        key = convert_key(key)
+        val = convert_value(val)
+        # Rebuild hash with this key at front
+        temp = {key => val}
+        each do |k, v|
+          temp[k] = v unless k == key
+        end
+        clear
+        temp.each{|k, v| __set__(k, v)}
+      end
+      self
     end
-    self
-  end
 
-  def push(*args)
-    Map.each_pair(*args) do |key, val|
-      key = convert_key(key)
-      delete(key)
-      keys.push(key)
-      __set__(key, val)
+    def push(*args)
+      Map.each_pair(*args) do |key, val|
+        self[key] = val  # This naturally appends in Ruby 1.9+
+      end
+      self
     end
-    self
-  end
 
-  def pop
-    unless empty?
-      key = keys.last
-      val = delete(key)
-      [key, val]
+    def pop
+      unless empty?
+        key = keys.last
+        val = delete(key)
+        [key, val]
+      end
     end
   end
 
@@ -636,21 +646,26 @@ class Map < Hash
 # a sane method missing that only supports writing values or reading
 # *previously set* values
 #
-  def method_missing(*args, &block)
+  def method_missing(*args, **kws, &block)
     method = args.first.to_s
+
     case method
       when /=$/
         key = args.shift.to_s.chomp('=')
         value = args.shift
         self[key] = value
+
       when /\?$/
         key = args.shift.to_s.chomp('?')
         self.has?( key )
+
       else
         key = method
+
         unless has_key?(key)
           return(block ? fetch(key, &block) : super(*args))
         end
+
         self[key]
     end
   end
@@ -1172,6 +1187,24 @@ class Map < Hash
   def mongoize
     self
   end
+
+  # Conditionally include ordering module based on Ruby version
+  #
+  # Ruby 1.9+ maintains Hash insertion order natively, so the @keys array
+  # and associated methods are not needed. This provides memory optimization
+  # (25% reduction per Map instance) and delegates to Hash's efficient ordering.
+  #
+  # For Ruby < 1.9, the ordering module provides manual insertion order tracking
+  # via @keys array for backward compatibility.
+  if RUBY_VERSION < '1.9'
+    # Ruby < 1.9: MUST use ordering module (Hash is unordered)
+    require_relative 'map/ordering'
+    include Ordering
+  elsif ENV['MAP_FORCE_ORDERING']
+    # Ruby >= 1.9 ONLY: Optionally force module inclusion for testing legacy code path
+    require_relative 'map/ordering'
+    include Ordering
+  end
 end
 
 module Kernel
@@ -1181,7 +1214,4 @@ private
   end
 end
 
-Map.load('struct.rb')
-Map.load('options.rb')
-Map.load('params.rb')
-
+require_relative 'map/options.rb'

data/map.gemspec

@@ -3,26 +3,38 @@
 
 Gem::Specification::new do |spec|
   spec.name = "map"
-  spec.version = "6.6.0"
+  spec.version = "8.0.0"
+  spec.required_ruby_version = '>= 3.0'
   spec.platform = Gem::Platform::RUBY
-  spec.summary = "map"
-  spec.description = "the awesome ruby container you've always wanted: a string/symbol indifferent ordered hash that works in all rubies"
-  spec.license = "same as ruby's"
+  spec.summary = "the perfect ruby data structure"
+  spec.description = "map.rb is a string/symbol indifferent ordered hash that works in all rubies.\n\nout of the over 200 ruby gems i have written, this is the one i use\nevery day, in all my projects.\n\nsome may be accustomed to using ActiveSupport::HashWithIndiffentAccess\nand, although there are some similarities, map.rb is more complete,\nworks without requiring a mountain of code, and has been in production\nusage for over 15 years.\n\nit has no dependencies, and suports a myriad of other, 'tree-ish'\noperators that will allow you to slice and dice data like a giraffee\nwith a giant weed whacker."
+  spec.license = "Ruby"
 
   spec.files =
 ["LICENSE",
  "README",
+ "README.md",
  "Rakefile",
- "a.rb",
+ "images",
+ "images/giraffe.jpeg",
+ "images/map.png",
  "lib",
  "lib/map",
  "lib/map.rb",
- "lib/map/integrations",
- "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",
+ "specs/001-ordered-map-module",
+ "specs/001-ordered-map-module/checklists",
+ "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",
  "test/leak.rb",
  "test/lib",
@@ -33,13 +45,10 @@ Gem::Specification::new do |spec|
   
   spec.require_path = "lib"
 
-  spec.test_files = nil
-
   
 
   spec.extensions.push(*[])
 
-  spec.rubyforge_project = "codeforpeople"
   spec.author = "Ara T. Howard"
   spec.email = "ara.t.howard@gmail.com"
   spec.homepage = "https://github.com/ahoward/map"