map 6.6.0 → 8.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 6943612f809404a5d3045cefd7c293970fc2926053bef6b86c732f984eb10fee
+  data.tar.gz: b3c701393f2d1064897b3f9b26da0314d15e9131e26d16027bbf84f92b2039d8
+SHA512:
+  metadata.gz: a1b125e4b5bc8cbdd56c059dd5f34421701989503ff435535d032eca5bff4239dd9faea22597e9dd5209bd5db02348a3288a91a7c4a2d68e67dbec26f20d2904
+  data.tar.gz: 46037e4bc03b517dff6ddb936784b7400c403977391b87911fc6481482d6049fe2fafefb29331a25026ddfa739fa05df804fe820243ea47ada4cee8045bc2725

data/LICENSE

@@ -1 +1 @@
-same as ruby's
+Ruby

data/README.md

@@ -0,0 +1,268 @@
+NAME
+----
+  map.rb
+
+
+LOGO
+----
+  ![weed whacking giraffe]('https://github.com/ahoward/map/blob/master/images/map.png')
+
+
+SYNOPSIS
+--------
+  the awesome ruby container you've always wanted: a string/symbol indifferent
+  ordered hash that works in all rubies.
+
+  maps are bitchin ordered hashes that are both ordered, string/symbol
+  indifferent, and have all sorts of sweetness like recursive conversion, more
+  robust, not to mention dependency-less, implementation than
+  HashWithIndifferentAccess.
+
+  bestiest of all, maps support some very powerful tree-like iterators that
+  make working with structured data, like json, insanely simple.
+
+  map.rb has been in production usage for 14 years and is commensurately
+  hardened.  if you process json, you will love map.rb
+
+
+INSTALL
+-------
+  gem install map
+
+
+URI
+---
+  http://github.com/ahoward/map
+
+
+DESCRIPTION
+-----------
+
+> maps are always ordered.  constructing them in an ordered fashion builds
+> them that way, although the normal hash contructor is also supported
+>
+```ruby
+
+  m = Map[:k, :v, :key, :val]
+  m = Map(:k, :v, :key, :val)
+  m = Map.new(:k, :v, :key, :val)
+
+  m = Map[[:k, :v], [:key, :val]]
+  m = Map(:k => :v, :key => :val)  # ruh-oh, the input hash loses order!
+  m = Map.new(:k => :v, :key => :val)  # ruh-oh, the input hash loses order!
+
+  m = Map.new
+  m[:a] = 0
+  m[:b] = 1
+  m[:c] = 2
+
+  p m.keys   #=> ['a','b','c']  ### always ordered!
+  p m.values #=> [0,1,2]        ### always ordered!
+
+```
+
+> maps don't care about symbol vs.string keys
+>
+```ruby
+
+  p m[:a]  #=> 0
+  p m["a"] #=> 0
+
+```
+
+> even via deep nesting 
+>
+```ruby
+
+  p m[:foo]['bar'][:baz]  #=> 42
+
+```
+
+> many functions operate in a way one would expect from an ordered container
+>
+```ruby
+
+  m.update(:k2 => :v2)
+  m.update(:k2, :v2)
+
+  key_val_pair = m.shift
+  key_val_pair = m.pop
+
+```
+
+> maps keep mapiness for even deep operations
+>
+```ruby
+
+  m.update :nested => {:hashes => {:are => :converted}}
+
+```
+
+> maps can give back clever little struct objects
+>
+```ruby
+
+  m = Map(:foo => {:bar => 42})
+  s = m.struct
+  p s.foo.bar #=> 42
+
+```
+
+> because option parsing is such a common use case for needing string/symbol
+> indifference map.rb comes out of the box loaded with option support
+>
+```ruby
+
+  def foo(*args, &block)
+    opts = Map.options(args)
+    a = opts.getopt(:a)
+    b = opts.getopt(:b, :default => false)
+  end
+
+
+  opts = Map.options(:a => 42, :b => nil, :c => false)
+  opts.getopt(:a)                    #=> 42
+  opts.getopt(:b)                    #=> nil
+  opts.getopt(:b, :default => 42)    #=> 42 
+  opts.getopt(:c)                    #=> false
+  opts.getopt(:d, :default => false) #=> false
+
+```
+
+> this avoids such bugs as
+>
+```ruby
+
+  options = {:read_only => false}
+  read_only = options[:read_only] || true  # should be false but is true
+
+```
+
+> with options this becomes
+>
+```ruby
+
+  options = Map.options(:read_only => true)
+  read_only = options.getopt(:read_only, :default => false) #=> true
+
+```
+
+> maps support some really nice operators that hashes/orderedhashes do not
+>
+```ruby
+
+  m = Map.new
+  m.set(:h, :a, 0, 42)
+  m.has?(:h, :a)         #=> true
+  p m                    #=> {'h' => {'a' => [42]}} 
+  m.set(:h, :a, 1, 42.0)
+  p m                    #=> {'h' => {'a' => [42, 42.0]}} 
+
+  m.get(:h, :a, 1)       #=> 42.0
+  m.get(:x, :y, :z)      #=> nil
+  m[:x][:y][:z]          #=> raises exception!
+
+  m = Map.new(:array => [0,1])
+  defaults = {:array => [nil, nil, 2]}
+  m.apply(defaults)
+  p m[:array]            #=> [0,1,2]
+
+```
+
+> they also support some *powerful* tree-ish iteration styles
+>
+```ruby
+
+  m = Map.new
+
+  m.set(
+    [:a, :b, :c, 0] => 0,
+    [:a, :b, :c, 1] => 10,
+    [:a, :b, :c, 2] => 20,
+    [:a, :b, :c, 3] => 30
+  )
+
+  m.set(:x, :y, 42)
+  m.set(:x, :z, 42.0)
+
+  m.depth_first_each do |key, val|
+    p key => val
+  end
+
+  #=> [:a, :b, :c, 0] => 0
+  #=> [:a, :b, :c, 1] => 10
+  #=> [:a, :b, :c, 2] => 20
+  #=> [:a, :b, :c, 3] => 30
+  #=> [:x, :y] => 42
+  #=> [:x, :z] => 42.0
+
+```
+
+
+TESTING
+-------
+
+map.rb supports two ordering implementations:
+
+1. **Ruby 1.9+**: Uses native Hash ordering (memory optimized, no @keys array)
+2. **Ruby < 1.9**: Uses Map::Ordering module with explicit @keys array
+
+### Testing Both Code Paths
+
+The `MAP_FORCE_ORDERING=1` environment variable forces inclusion of the Map::Ordering
+module **on Ruby >= 1.9 only**, allowing you to test the legacy ordering code path on
+modern Ruby versions. (On Ruby < 1.9, the module is always included regardless of this
+setting, since it's required for Hash ordering.)
+
+```sh
+# Test with native Hash ordering (Ruby 1.9+ default)
+rake test
+rake test:without_ordering
+
+# Test with Map::Ordering module (simulates Ruby < 1.9)
+MAP_FORCE_ORDERING=1 rake test
+rake test:with_ordering
+
+# Quick verification of both modes
+ruby test/verify_ordering.rb
+MAP_FORCE_ORDERING=1 ruby test/verify_ordering.rb
+```
+
+Both modes pass the same 56 tests with 4940 assertions, proving functional equivalence.
+
+### Testing Across Ruby Versions
+
+**Quick validation (RECOMMENDED):**
+
+```sh
+# Test both code paths on your current Ruby
+./test_hash_ordering.sh
+
+# Summary output shows:
+#   - Native mode: no @keys (optimized)
+#   - Forced mode: has @keys (simulates Ruby < 1.9)
+#   - Both: 56 tests, 4940 assertions pass
+```
+
+**Test across multiple Ruby versions:**
+
+```sh
+# Test all installed Ruby versions automatically
+./test_all_rubies.sh
+
+# Or manually test with specific Ruby versions
+RBENV_VERSION=3.2.8 ./test_hash_ordering.sh
+RBENV_VERSION=3.3.4 rake test
+RBENV_VERSION=3.3.4 MAP_FORCE_ORDERING=1 rake test
+```
+
+**Note**: Old Ruby Docker images (< 2.0) are no longer available. Use `MAP_FORCE_ORDERING=1`
+to test the Ruby < 1.9 code path on modern Ruby - it uses the exact same `Map::Ordering`
+module with the same `@keys` array logic and behavior.
+
+**CI/CD testing:**
+
+The `.github/workflows/test.yml` workflow automatically tests across Ruby 2.7, 3.0,
+3.1, 3.2, 3.3, and head on every push and pull request, running both with and without
+the ordering module.
+

data/Rakefile

@@ -1,10 +1,11 @@
-This.rubyforge_project = 'codeforpeople'
 This.author = "Ara T. Howard"
 This.email = "ara.t.howard@gmail.com"
-This.homepage = "https://github.com/ahoward/#{ This.lib }"
+This.github = "ahoward"
+This.homepage = "https://github.com/#{ This.github }/#{ This.basename }"
+This.repo = "https://github.com/#{ This.github }/#{ This.basename }"
 
 task :license do
-  open('LICENSE', 'w'){|fd| fd.puts "same as ruby's"}
+  open('LICENSE', 'w'){|fd| fd.puts "Ruby"}
 end
 
 task :default do
@@ -19,6 +20,24 @@ namespace :test do
   task(:unit){ run_tests!(:unit) }
   task(:functional){ run_tests!(:functional) }
   task(:integration){ run_tests!(:integration) }
+
+  # Test with Map::Ordering module forced (simulates Ruby < 1.9)
+  task(:with_ordering) do
+    ENV['MAP_FORCE_ORDERING'] = '1'
+    puts "\n#{ '=' * 60 }"
+    puts "Running tests WITH Map::Ordering module (MAP_FORCE_ORDERING=1)"
+    puts "#{ '=' * 60 }\n\n"
+    run_tests!
+  end
+
+  # Test without Map::Ordering module (Ruby 1.9+ native Hash ordering)
+  task(:without_ordering) do
+    ENV.delete('MAP_FORCE_ORDERING')
+    puts "\n#{ '=' * 60 }"
+    puts "Running tests WITHOUT Map::Ordering module (Ruby 1.9+ mode)"
+    puts "#{ '=' * 60 }\n\n"
+    run_tests!
+  end
 end
 
 def run_tests!(which = nil)
@@ -72,11 +91,13 @@ task :gemspec do
         extension = File.basename(entry).split(%r/[.]/).last
         ignore_extensions.any?{|ext| ext === extension}
       end
+
       list.delete_if do |entry|
         next unless test(?d, entry)
         dirname = File.expand_path(entry)
         ignore_directories.any?{|dir| File.expand_path(dir) == dirname}
       end
+
       list.delete_if do |entry|
         next unless test(?f, entry)
         filename = File.expand_path(entry)
@@ -84,22 +105,20 @@ task :gemspec do
       end
     end
 
-  lib         = This.lib
+  name        = This.basename
   object      = This.object
   version     = This.version
   files       = shiteless[Dir::glob("**/**")]
   executables = shiteless[Dir::glob("bin/*")].map{|exe| File.basename(exe)}
-  #has_rdoc    = true #File.exist?('doc')
-  test_files  = "test/#{ lib }.rb" if File.file?("test/#{ lib }.rb")
-  summary     = object.respond_to?(:summary) ? object.summary : "summary: #{ lib } kicks the ass"
-  description = object.respond_to?(:description) ? object.description : "description: #{ lib } kicks the ass"
-  license     = object.respond_to?(:license) ? object.license : "same as ruby's"
+  summary     = Util.unindent(This.summary).strip
+  description = Util.unindent(This.description).strip
+  license     = This.license.strip
 
   if This.extensions.nil?
     This.extensions = []
     extensions = This.extensions
     %w( Makefile configure extconf.rb ).each do |ext|
-      extensions << ext if File.exists?(ext)
+      extensions << ext if File.exist?(ext)
     end
   end
   extensions = [extensions].flatten.compact
@@ -121,14 +140,15 @@ task :gemspec do
     else
       Template {
         <<-__
-          ## <%= lib %>.gemspec
+          ## <%= name %>.gemspec
           #
 
           Gem::Specification::new do |spec|
-            spec.name = <%= lib.inspect %>
+            spec.name = <%= name.inspect %>
             spec.version = <%= version.inspect %>
+            spec.required_ruby_version = '>= 3.0'
             spec.platform = Gem::Platform::RUBY
-            spec.summary = <%= lib.inspect %>
+            spec.summary = <%= summary.inspect %>
             spec.description = <%= description.inspect %>
             spec.license = <%= license.inspect %>
 
@@ -137,15 +157,12 @@ task :gemspec do
             
             spec.require_path = "lib"
 
-            spec.test_files = <%= test_files.inspect %>
-
             <% dependencies.each do |lib_version| %>
               spec.add_dependency(*<%= Array(lib_version).flatten.inspect %>)
             <% end %>
 
             spec.extensions.push(*<%= extensions.inspect %>)
 
-            spec.rubyforge_project = <%= This.rubyforge_project.inspect %>
             spec.author = <%= This.author.inspect %>
             spec.email = <%= This.email.inspect %>
             spec.homepage = <%= This.homepage.inspect %>
@@ -155,7 +172,7 @@ task :gemspec do
     end
 
   Fu.mkdir_p(This.pkgdir)
-  gemspec = "#{ lib }.gemspec"
+  gemspec = "#{ name }.gemspec"
   open(gemspec, "w"){|fd| fd.puts(template)}
   This.gemspec = gemspec
 end
@@ -171,28 +188,49 @@ task :gem => [:clean, :gemspec] do
   This.gem = File.join(This.pkgdir, File.basename(gem))
 end
 
+task :README => [:readme]
+
 task :readme do
   samples = ''
   prompt = '~ > '
   lib = This.lib
   version = This.version
 
-  Dir['sample*/*'].sort.each do |sample|
-    samples << "\n" << "  <========< #{ sample } >========>" << "\n\n"
+  Dir['sample*/**/**.rb'].sort.each do |sample|
+    link = "[#{ sample }](#{ This.repo }/blob/main/#{ sample })"
+    samples << "  #### <========< #{ link } >========>\n"
 
     cmd = "cat #{ sample }"
-    samples << Util.indent(prompt + cmd, 2) << "\n\n"
-    samples << Util.indent(`#{ cmd }`, 4) << "\n"
+    samples << "```sh\n"
+    samples << Util.indent(prompt + cmd, 2) << "\n"
+    samples << "```\n"
+    samples << "```ruby\n"
+    samples << Util.indent(IO.binread(sample), 4) << "\n"
+    samples << "```\n"
+
+    samples << "\n"
 
     cmd = "ruby #{ sample }"
-    samples << Util.indent(prompt + cmd, 2) << "\n\n"
+    samples << "```sh\n"
+    samples << Util.indent(prompt + cmd, 2) << "\n"
+    samples << "```\n"
 
     cmd = "ruby -e'STDOUT.sync=true; exec %(ruby -I ./lib #{ sample })'"
-    samples << Util.indent(`#{ cmd } 2>&1`, 4) << "\n"
+    oe = `#{ cmd } 2>&1`
+    samples << "```txt\n"
+    samples << Util.indent(oe, 4) << "\n"
+    samples << "```\n"
+
+    samples << "\n"
   end
 
+  This.samples = samples
+
   template = 
-    if test(?e, 'README.erb')
+    case
+    when test(?e, 'README.md.erb')
+      Template{ IO.read('README.md.erb') }
+    when test(?e, 'README.erb')
       Template{ IO.read('README.erb') }
     else
       Template {
@@ -211,31 +249,23 @@ task :readme do
       }
     end
 
-  open("README", "w"){|fd| fd.puts template}
+  IO.binwrite('README.md', template)
 end
 
-
 task :clean do
   Dir[File.join(This.pkgdir, '**/**')].each{|entry| Fu.rm_rf(entry)}
 end
 
-
-task :release => [:clean, :gemspec, :gem] do
+task :release => [:dist, :gem] do
   gems = Dir[File.join(This.pkgdir, '*.gem')].flatten
-  raise "which one? : #{ gems.inspect }" if gems.size > 1
-  raise "no gems?" if gems.size < 1
+  abort "which one? : #{ gems.inspect }" if gems.size > 1
+  abort "no gems?" if gems.size < 1
 
   cmd = "gem push #{ This.gem }"
   puts cmd
   puts
   system(cmd)
   abort("cmd(#{ cmd }) failed with (#{ $?.inspect })") unless $?.exitstatus.zero?
-
-  cmd = "rubyforge login && rubyforge add_release #{ This.rubyforge_project } #{ This.lib } #{ This.version } #{ This.gem }"
-  puts cmd
-  puts
-  system(cmd)
-  abort("cmd(#{ cmd }) failed with (#{ $?.inspect })") unless $?.exitstatus.zero?
 end
 
 
@@ -253,58 +283,66 @@ BEGIN {
   require 'rbconfig'
   require 'pp'
 
-# fu shortcut
+# fu shortcut!
 #
   Fu = FileUtils
 
-# cache a bunch of stuff about this rakefile/environment
+# guess a bunch of stuff about this rakefile/environment based on the
 #
   This = OpenStruct.new
 
   This.file = File.expand_path(__FILE__)
   This.dir = File.dirname(This.file)
   This.pkgdir = File.join(This.dir, 'pkg')
+  This.basename = File.basename(This.dir)
 
-# grok lib
+# load actual shit _lib
 #
-  lib = ENV['LIB']
-  unless lib
-    lib = File.basename(Dir.pwd).sub(/[-].*$/, '')
-  end
-  This.lib = lib
+  _libpath = ["./lib/#{ This.basename }/_lib.rb", "./lib/#{ This.basename }.rb"]
+  _lib = _libpath.detect{|l| test(?s, l)}
 
-# grok version
-#
-  version = ENV['VERSION']
-  unless version
-    require "./lib/#{ This.lib }"
-    This.name = lib.capitalize
-    This.object = eval(This.name)
-    version = This.object.send(:version)
-  end
-  This.version = version
+  abort "could not find a _lib in ./lib/ via #{ _libpath.join(':') }" unless _lib
+
+  This._lib = _lib
+  require This._lib
 
-# see if dependencies are export by the module
+# extract the name from the _lib
 #
-  if This.object.respond_to?(:dependencies)
-    This.dependencies = This.object.dependencies
+  lines = IO.binread(This._lib).split("\n")
+  re = %r`\A \s* (module|class) \s+ ([^\s]+) \s* \z`iomx
+  name = nil
+  lines.each do |line|
+    match = line.match(re)
+    if match
+      name = match.to_a.last
+      break
+    end
   end
+  unless name
+    abort "could not extract `name` from #{ This._lib }"
+  end
+  This.name = name
+  This.basename = This.name.downcase
 
-# we need to know the name of the lib an it's version
+# now, fully grok This 
 #
-  abort('no lib') unless This.lib
-  abort('no version') unless This.version
+  This.object       = eval(This.name)
+  This.version      = This.object.version
+  This.dependencies = This.object.dependencies
+  This.summary      = This.object.summary
+  This.description  = This.object.respond_to?(:description) ? This.object.description : This.summary
+  This.license      = This.object.respond_to?(:license) ? This.object.license : IO.binread('LICENSE').strip
 
 # discover full path to this ruby executable
 #
-  c = Config::CONFIG
+  c = RbConfig::CONFIG
   bindir = c["bindir"] || c['BINDIR']
   ruby_install_name = c['ruby_install_name'] || c['RUBY_INSTALL_NAME'] || 'ruby'
   ruby_ext = c['EXEEXT'] || ''
   ruby = File.join(bindir, (ruby_install_name + ruby_ext))
   This.ruby = ruby
 
-# some utils
+# some utils, alwayze teh utils...
 #
   module Util
     def indent(s, n = 2)
@@ -319,7 +357,8 @@ BEGIN {
       next if line =~ %r/^\s*$/
       indent = line[%r/^\s*/] and break
     end
-    indent ? s.gsub(%r/^#{ indent }/, "") : s
+    unindented = indent ? s.gsub(%r/^#{ indent }/, "") : s
+    unindented.strip
   end
     extend self
   end
@@ -327,17 +366,54 @@ BEGIN {
 # template support
 #
   class Template
+    def Template.indent(string, n = 2)
+      string = string.to_s
+      n = n.to_i
+      padding = (42 - 10).chr * n
+      initial = %r/^#{ Regexp.escape(padding) }/
+      #require 'debug'
+      #binding.break
+      Util.indent(string, n).sub(initial, '')
+    end
     def initialize(&block)
       @block = block
       @template = block.call.to_s
     end
     def expand(b=nil)
-      ERB.new(Util.unindent(@template)).result((b||@block).binding)
+      ERB.new(Util.unindent(@template), trim_mode: '%<>-').result((b||@block).binding)
     end
     alias_method 'to_s', 'expand'
   end
   def Template(*args, &block) Template.new(*args, &block) end
 
+# os / platform support 
+#
+  module Platform
+    def Platform.windows?
+      (/cygwin|mswin|mingw|bccwin|wince|emx/ =~ RUBY_PLATFORM) != nil
+    end
+
+    def Platform.darwin?
+     (/darwin/ =~ RUBY_PLATFORM) != nil
+    end
+
+    def Platform.mac?
+      Platform.darwin?
+    end
+
+    def Platform.unix?
+      !Platform.windows?
+    end
+
+    def Platform.linux?
+      Platform.unix? and not Platform.darwin?
+    end
+
+    def Platform.jruby?
+      RUBY_ENGINE == 'jruby'
+    end
+  end
+
 # colored console output support
 #
   This.ansi = {