put 0.0.2 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 946be21b2839e39c50fccfc55683ec69b8aa1d888a4030cd93aa3ff59f17ff18
-  data.tar.gz: 9cd544f2130f11a1285eaeeaff6b695ac3ca80513b721783836a4d7526b70178
+  metadata.gz: 535145ee17f2f25a68d80ed7afa1e58cb2edd1d261c2b0f976cd9706c4304049
+  data.tar.gz: 4551a7ac241dc9d0b6fc7b975ae0a7d10c87b1dadf35c3832128ecaf563b1b2d
 SHA512:
-  metadata.gz: 057e1c3b3b7bcb4b8b79e9a98ec132f1c9d6faa03defb3095ae0d2fa5eaeed7b74e3d39d8bda3ab280d8b594e492b493008d1711349d1a11ddea6c1e95802eee
-  data.tar.gz: 2d093be68e236968499608dbd183ffbd99e7664cb6d3a929e0f15bbc904a0f86905a187f2f0046902bab0b055c5dd29399d1cf53a684e36f12a2e19e4bbcdf4b
+  metadata.gz: 7cd640fd7da59ca4ad28472284addf6df5db063dba76a1e98f9de4c44e6a243818f8366f1b79ebc345010e0cfc454c5a03c7030449710967f945f9504419937c
+  data.tar.gz: e8217fdfbe3fb805bd31bc5632c227c2b9265fc176004a94b41943c33a8b24b06399868026fdb8e8098e4c32162db4a4ff03006a9db7668675af8ac04615bde5

data/CHANGELOG.md

@@ -1,4 +1,11 @@
-## [Unreleased]
+## [0.2.0] - 2026-09-22
+
+- **[Breaking]** Drop support for Ruby 2.6; require Ruby >= 3.1
+
+## [0.1.0] - 2022-09-22
+
+- Add Put.nils_first, Put.nils_last
+- Add Put.anywhere
 
 ## [0.0.2] - 2022-09-21
 

data/Gemfile

@@ -4,5 +4,10 @@ gemspec
 
 gem "debug"
 gem "rake"
-gem "minitest"
+gem "minitest", "< 6"
+gem "parallel", "< 2"
 gem "standard"
+gem "ostruct"
+gem "fiddle"
+gem "racc"
+gem "base64"

data/Gemfile.lock

@@ -1,58 +1,85 @@
 PATH
   remote: .
   specs:
-    put (0.0.2)
+    put (0.2.0)
 
 GEM
   remote: https://rubygems.org/
   specs:
-    ast (2.4.2)
+    ast (2.4.3)
+    base64 (0.3.0)
     debug (1.6.2)
       irb (>= 1.3.6)
       reline (>= 0.3.1)
+    fiddle (1.1.8)
     io-console (0.5.11)
     irb (1.4.1)
       reline (>= 0.3.0)
-    json (2.6.2)
-    minitest (5.16.3)
-    parallel (1.22.1)
-    parser (3.1.2.1)
+    json (2.21.2)
+    language_server-protocol (3.17.0.6)
+    lint_roller (1.1.0)
+    minitest (5.27.0)
+    ostruct (0.6.3)
+    parallel (1.28.0)
+    parser (3.3.12.0)
       ast (~> 2.4.1)
+      racc
+    prism (1.9.0)
+    racc (1.8.1)
     rainbow (3.1.1)
     rake (13.0.6)
-    regexp_parser (2.5.0)
+    regexp_parser (2.13.0)
     reline (0.3.1)
       io-console (~> 0.5)
-    rexml (3.2.5)
-    rubocop (1.35.1)
+    rubocop (1.88.2)
       json (~> 2.3)
-      parallel (~> 1.10)
-      parser (>= 3.1.2.1)
+      language_server-protocol (~> 3.17.0.2)
+      lint_roller (~> 1.1.0)
+      parallel (>= 1.10)
+      parser (>= 3.3.0.2)
       rainbow (>= 2.2.2, < 4.0)
-      regexp_parser (>= 1.8, < 3.0)
-      rexml (>= 3.2.5, < 4.0)
-      rubocop-ast (>= 1.20.1, < 2.0)
+      regexp_parser (>= 2.9.3, < 3.0)
+      rubocop-ast (>= 1.49.0, < 2.0)
       ruby-progressbar (~> 1.7)
-      unicode-display_width (>= 1.4.0, < 3.0)
-    rubocop-ast (1.21.0)
-      parser (>= 3.1.1.0)
-    rubocop-performance (1.14.3)
-      rubocop (>= 1.7.0, < 2.0)
-      rubocop-ast (>= 0.4.0)
-    ruby-progressbar (1.11.0)
-    standard (1.16.1)
-      rubocop (= 1.35.1)
-      rubocop-performance (= 1.14.3)
-    unicode-display_width (2.3.0)
+      unicode-display_width (>= 2.4.0, < 4.0)
+    rubocop-ast (1.50.0)
+      parser (>= 3.3.7.2)
+      prism (~> 1.7)
+    rubocop-performance (1.26.1)
+      lint_roller (~> 1.1)
+      rubocop (>= 1.75.0, < 2.0)
+      rubocop-ast (>= 1.47.1, < 2.0)
+    ruby-progressbar (1.13.0)
+    standard (1.56.0)
+      language_server-protocol (~> 3.17.0.2)
+      lint_roller (~> 1.0)
+      rubocop (~> 1.88.0)
+      standard-custom (~> 1.0.0)
+      standard-performance (~> 1.8)
+    standard-custom (1.0.2)
+      lint_roller (~> 1.0)
+      rubocop (~> 1.50)
+    standard-performance (1.9.0)
+      lint_roller (~> 1.1)
+      rubocop-performance (~> 1.26.0)
+    unicode-display_width (3.3.0)
+      unicode-emoji (~> 4.3)
+    unicode-emoji (4.3.0)
 
 PLATFORMS
   arm64-darwin-21
   arm64-darwin-22
+  x86_64-linux
 
 DEPENDENCIES
+  base64
   debug
-  minitest
+  fiddle
+  minitest (< 6)
+  ostruct
+  parallel (< 2)
   put!
+  racc
   rake
   standard
 

data/README.md

@@ -1,11 +1,225 @@
-# Put
+# Put puts your objects in order 💎
 
-Put helps you put stuff in order when using
-[Enumerable#sort_by](https://ruby-doc.org/core-3.1.2/Enumerable.html#method-i-sort_by).
+Put pairs with
+[Enumerable#sort_by](https://ruby-doc.org/core-3.1.2/Enumerable.html#method-i-sort_by)
+to provide a more expressive, fault-tolerant, and configurable approach to
+sorting Ruby objects with multiple criteria. [Here's a screencast & short blog 
+post](https://blog.testdouble.com/talks/2022-09-28-a-better-way-to-sort-ruby-objects/)
+that we put out, in case you're interested.
 
-A neat trick when implementing complex sorting rules is to map them to an
-array of arrays of comparable elements in priority-order.
+## Put "put" in your Gemfile
 
+You've probably already put a few gems in there, so why not put Put, too:
+
+```ruby
+gem "put"
+```
+
+Of course after you push Put, your colleagues will wonder why you put Put there.
+
+## Before you tell me where to put it
+
+A neat trick when applying complex sorting rules to a collection is to map them
+to an array of arrays of comparable values in priority order. It's a common
+approach (and a special subtype of what's called a [Schwartzian
+transform](https://en.wikipedia.org/wiki/Schwartzian_transform)), but the
+pattern doesn't have a widely-accepted name yet, so let's use code to explain.
+
+Suppose you have some people:
+
+```ruby
+Person = Struct.new(:name, :age, :rubyist?, keyword_init: true)
+
+people = [
+  Person.new(name: "Tam", age: 22),
+  Person.new(name: "Zak", age: 33),
+  Person.new(name: "Axe", age: 33),
+  Person.new(name: "Qin", age: 18, rubyist?: true),
+  Person.new(name: "Zoe", age: 28, rubyist?: true)
+]
+```
+
+And you want to sort these people in the following priority order:
+
+1. Put any Rubyists at the _top_ of the list, as is right and good
+2. If both are (or are not) Rubyists, break the tie by sorting by age descending
+3. Finally, break any remaining ties by sorting by name ascending
+
+Here's what the aforementioned pattern to accomplish this usually looks like
+using
+[Enumerable#sort_by](https://ruby-doc.org/core-3.1.2/Enumerable.html#method-i-sort_by):
+
+```ruby
+people.sort_by { |person|
+  [
+    person.rubyist? ? 0 : 1,
+    person.age * -1,
+    person.name
+  ]
+} # => Zoe, Qin, Axe, Zak, Tam
+```
+
+The above will return everyone in the right order. This has a few drawbacks,
+though:
+
+* Unless you're already familiar with this pattern that nobody's bothered to
+give a name before, this code isn't very expressive. As a result, each line
+is almost begging for a code comment above it to explain its intent
+* Ternary operators are confusing, especially with predicate methods like
+`rubyist?` and especially when returning [magic
+number](https://en.wikipedia.org/wiki/Magic_number_(programming))'s like `1` and
+`0`.
+* Any `nil` values will result in a bad time. If a person's `age` is nil, you'll
+get "_undefined method '*' for nil:NilClass_" `NoMethodError`
+* Relatedly, if any two items aren't comparable (i.e. `<=>` returns nil), you'll
+  be greeted with an inscrutable `ArgumentError` that just says "_comparison of
+  Array with Array failed_"
+
+Here's the same code example if you put Put in there:
+
+```ruby
+people.sort_by { |person|
+  [
+    (Put.first if person.rubyist?),
+    Put.desc(person.age),
+    Put.asc(person.name)
+  ]
+} # => Zoe, Qin, Axe, Zak, Tam
+```
+
+The Put gem solves every one of the above issues:
+
+* Put's methods have actual names. In fact, let's just call this the "Put
+  pattern" while we're at it
+* No ternaries necessary
+* It's quite `nil` friendly
+* It ships with a `Put.debug` method that helps you introspect those
+  impenetrable `ArgumentError` messages whenever any two values turn out not to
+  be comparable
+
+After reading this, your teammates will be glad they put you in charge of
+putting gems like Put in the Gemfile.
+
+## When you Put it that way
+
+Put's API is short and sweet. In fact, you've already put up with most of it.
+
+### Put.first
+
+When a particular condition indicates an item should go to the top of a list,
+you'll want to designate a position in your mapped `sort_by` arrays to return
+either `Put.first` or `nil`, like this:
+
+```ruby
+[42, 12, 65, 99, 49].sort_by { |n|
+  [(Put.first if n.odd?)]
+} # => 65, 99, 49, 42, 12
+```
+
+### Put.last
+
+When a sort criteria should go to the bottom of the list, you can do the same
+sort of conditional expression with `Put.last`:
+
+```ruby
+%w[Jin drinks Gin on Gym day].sort_by { |s|
+  [(Put.last unless s.match?(/[A-Z]/))]
+} # => ["Jin", "Gin", "Gym", "drinks", "on", "day"]
+```
+
+### Put.asc(value, nils_first: false)
+
+The `Put.asc` method provides a nil-safe way to sort a value in ascending order:
+
+```ruby
+%w[The quick brown fox].sort_by { |s|
+  [Put.asc(s)]
+} # => ["The", "brown", "fox", "quick"]
+```
+
+It also supports an optional `nils_first` keyword argument that defaults to
+false (translation: nils are sorted last by default), which looks like this:
+
+```ruby
+[3, nil, 1, 5].sort_by { |n|
+  [Put.asc(n, nils_first: true)]
+} # => [nil, 1, 3, 5]
+```
+
+### Put.desc(value, nils_first: false)
+
+The opposite of `Put.asc` is `Put.desc`, and it works as you might suspect:
+
+```ruby
+%w[Aardvark Zebra].sort_by { |s|
+  [Put.desc(s)]
+} # => ["Zebra", "Aardvark"]
+```
+
+And also like `Put.asc`, `Put.desc` has an optional `nils_first` keyword
+argument when you want nils on top:
+
+```ruby
+[1, nil, 2, 3].sort_by { |n|
+  [Put.desc(n, nils_first: true)]
+} # => [nil, 3, 2, 1]
+```
+
+### Put.anywhere
+
+You're sorting stuff, so naturally _order matters_. But when building a compound
+`sort_by` expression, order matters less as you add more and more tiebreaking
+criteria. In fact, sometimes shuffling items is the more appropriate than
+leaving things in their original order. Enter `Put.anywhere`, which can be
+called without any argument at any index in the mapped sorting array:
+
+```ruby
+[1, 3, 4, 7, 8, 9].sort_by { |n|
+  [
+    (Put.first if n.even?),
+    Put.anywhere
+  ]
+} # => [8, 4, 1, 7, 9, 3]
+```
+
+### Put.nils_first(value)
+
+If you're sorting items and you know some not-comparable `nil` values are going
+to appear, you can put all the nils on top with `Put.nil_first(value)`. Note
+that _unlike_ `Put.asc` and `Put.desc`, it won't actually sort the values—it'll
+just pull all the nils up!
+
+```ruby
+[:fun, :stuff, nil, :here].sort_by { |val|
+  [Put.nils_first(val)]
+} # => [nil, :fun, :stuff, :here]
+```
+
+### Put.nils_last(value)
+
+As you might be able to guess, `Put.nils_last` puts the nils last:
+
+```ruby
+[:every, nil, :counts].sort_by { |val|
+  [Put.nils_last(val)]
+} # => [:every, :counts, nil]
+```
+
+### Put.debug(sorting_arrays)
+
+If you see "comparison of Array with Array failed" and you don't have any idea
+what is going on, try debugging by changing `sort_by` to `map` and passing it
+to `Put.debug`.
+
+For an interactive example of how to debug this issue with `Put.debug`, take a
+look [at this test case](/test/put_test.rb#L53-L98).
+
+## Put your hands together! 👏
+
+Many thanks to [Matt Jones](https://github.com/al2o3cr) and [Matthew
+Draper](https://github.com/matthewd) for answering a bunch of obscure questions
+about comparisons in Ruby and implementing the initial prototype, respectively.
+👏👏👏
 
 ## Code of Conduct
 
@@ -14,4 +228,4 @@ conduct](https://testdouble.com/code-of-conduct) for all community interactions,
 including (but not limited to) one-on-one communications, public posts/comments,
 code reviews, pull requests, and GitHub issues. If violations occur, Test Double
 will take any action they deem appropriate for the infraction, up to and
-including blocking a user from the organization's repositories.
+including blocking a user from the organization's repositories.

data/lib/put/debug.rb

@@ -0,0 +1,45 @@
+module Put
+  class Debug
+    Result = Struct.new(:success?, :incomparables, keyword_init: true)
+    Incomparable = Struct.new(
+      :sorting_index, :left, :left_index, :left_value,
+      :right, :right_index, :right_value, keyword_init: true
+    ) {
+      def inspect
+        both_puts_things = left.is_a?(PutsThing) && right.is_a?(PutsThing)
+        left_desc = (both_puts_things ? left_value : left).inspect
+        right_desc = (both_puts_things ? right_value : right).inspect
+        "Sorting comparator at index #{sorting_index} failed, because items at indices #{left_index} and #{right_index} were not comparable. Their values were `#{left_desc}' and `#{right_desc}', respectively."
+      end
+    }
+
+    def call(sorting_arrays)
+      sorting_arrays.sort
+      Result.new(success?: true, incomparables: [])
+    rescue ArgumentError
+      # TODO this is O(n^lol)
+      incomparables = sorting_arrays.transpose.map.with_index { |comparables, sorting_index|
+        comparables.map.with_index { |comparable, comparable_index|
+          comparables.map.with_index { |other, other_index|
+            next if comparable_index == other_index
+            if (comparable <=> other).nil?
+              Incomparable.new(
+                sorting_index: sorting_index,
+                left: comparable,
+                left_index: comparable_index,
+                left_value: (comparable.value if comparable.is_a?(PutsThing)),
+                right: other,
+                right_index: other_index,
+                right_value: (other.value if other.is_a?(PutsThing))
+              )
+            end
+          }
+        }
+      }.flatten.compact.uniq { |inc|
+        # Remove dupes where two items are incomparable in both <=> directions:
+        [inc.sorting_index] + [inc.left_index, inc.right_index].sort
+      }
+      Result.new(success?: false, incomparables: incomparables)
+    end
+  end
+end

data/lib/put/puts_thing/anywhere.rb

@@ -0,0 +1,13 @@
+module Put
+  class PutsThing
+    class Anywhere < PutsThing
+      def initialize(seed)
+        @random = seed.nil? ? Random.new : Random.new(seed)
+      end
+
+      def value
+        @random.rand
+      end
+    end
+  end
+end

data/lib/put/puts_thing/ascending.rb

@@ -0,0 +1,6 @@
+module Put
+  class PutsThing
+    class Ascending < InOrder
+    end
+  end
+end

data/lib/put/puts_thing/descending.rb

@@ -0,0 +1,9 @@
+module Put
+  class PutsThing
+    class Descending < InOrder
+      def reverse?
+        true
+      end
+    end
+  end
+end

data/lib/put/puts_thing/first.rb

@@ -0,0 +1,9 @@
+module Put
+  class PutsThing
+    class First < PutsThing
+      def value
+        -Float::INFINITY
+      end
+    end
+  end
+end

data/lib/put/puts_thing/in_order.rb

@@ -0,0 +1,16 @@
+module Put
+  class PutsThing
+    class InOrder < PutsThing
+      def initialize(value, nils_first:)
+        @value = value
+        @nils_first = nils_first
+      end
+
+      attr_reader :value
+
+      def nils_first?
+        @nils_first
+      end
+    end
+  end
+end

data/lib/put/puts_thing/last.rb

@@ -0,0 +1,13 @@
+module Put
+  class PutsThing
+    class Last < PutsThing
+      def value
+        Float::INFINITY
+      end
+
+      def nils_first?
+        true
+      end
+    end
+  end
+end

data/lib/put/puts_thing/nil_order.rb

@@ -0,0 +1,17 @@
+module Put
+  class PutsThing
+    class NilOrder < PutsThing
+      def initialize(value)
+        @value = value
+      end
+
+      def value
+        if @value.nil?
+          nil
+        else
+          0
+        end
+      end
+    end
+  end
+end

data/lib/put/puts_thing/nils_first.rb

@@ -0,0 +1,9 @@
+module Put
+  class PutsThing
+    class NilsFirst < NilOrder
+      def nils_first?
+        true
+      end
+    end
+  end
+end

data/lib/put/puts_thing/nils_last.rb

@@ -0,0 +1,9 @@
+module Put
+  class PutsThing
+    class NilsLast < NilOrder
+      def nils_first?
+        false
+      end
+    end
+  end
+end

data/lib/put/puts_thing.rb

@@ -23,43 +23,5 @@ module Put
     def nils_first?
       false
     end
-
-    class First < PutsThing
-      def value
-        -Float::INFINITY
-      end
-    end
-
-    class Last < PutsThing
-      def value
-        Float::INFINITY
-      end
-
-      def nils_first?
-        true
-      end
-    end
-
-    class InOrder < PutsThing
-      def initialize(value, nils_first:)
-        @value = value
-        @nils_first = nils_first
-      end
-
-      attr_reader :value
-
-      def nils_first?
-        @nils_first
-      end
-    end
-
-    class Ascending < InOrder
-    end
-
-    class Descending < InOrder
-      def reverse?
-        true
-      end
-    end
   end
 end

data/lib/put/version.rb

@@ -1,3 +1,3 @@
 module Put
-  VERSION = "0.0.2"
+  VERSION = "0.2.0"
 end

data/lib/put.rb

@@ -1,6 +1,16 @@
+require_relative "put/debug"
 require_relative "put/version"
 require_relative "put/nil_ext"
 require_relative "put/puts_thing"
+require_relative "put/puts_thing/anywhere"
+require_relative "put/puts_thing/first"
+require_relative "put/puts_thing/last"
+require_relative "put/puts_thing/in_order"
+require_relative "put/puts_thing/ascending"
+require_relative "put/puts_thing/descending"
+require_relative "put/puts_thing/nil_order"
+require_relative "put/puts_thing/nils_first"
+require_relative "put/puts_thing/nils_last"
 
 module Put
   def self.first
@@ -18,4 +28,20 @@ module Put
   def self.asc(value, nils_first: false)
     PutsThing::Ascending.new(value, nils_first: nils_first)
   end
+
+  def self.nils_first(value)
+    PutsThing::NilsFirst.new(value)
+  end
+
+  def self.nils_last(value)
+    PutsThing::NilsLast.new(value)
+  end
+
+  def self.anywhere(seed: nil)
+    PutsThing::Anywhere.new(seed)
+  end
+
+  def self.debug(sorting_arrays)
+    Debug.new.call(sorting_arrays)
+  end
 end

metadata

@@ -1,16 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: put
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.2.0
 platform: ruby
 authors:
 - Justin Searls
-autorequire:
 bindir: exe
 cert_chain: []
-date: 2022-09-22 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies: []
-description:
 email:
 - searls@gmail.com
 executables: []
@@ -25,10 +23,19 @@ files:
 - README.md
 - Rakefile
 - lib/put.rb
+- lib/put/debug.rb
 - lib/put/nil_ext.rb
 - lib/put/puts_thing.rb
+- lib/put/puts_thing/anywhere.rb
+- lib/put/puts_thing/ascending.rb
+- lib/put/puts_thing/descending.rb
+- lib/put/puts_thing/first.rb
+- lib/put/puts_thing/in_order.rb
+- lib/put/puts_thing/last.rb
+- lib/put/puts_thing/nil_order.rb
+- lib/put/puts_thing/nils_first.rb
+- lib/put/puts_thing/nils_last.rb
 - lib/put/version.rb
-- put.gemspec
 - sig/put.rbs
 homepage: https://github.com/testdouble/put
 licenses:
@@ -37,7 +44,6 @@ metadata:
   homepage_uri: https://github.com/testdouble/put
   source_code_uri: https://github.com/testdouble/put
   changelog_uri: https://github.com/testdouble/put/blob/main/CHANGELOG.md
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -45,15 +51,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.6.0
+      version: 3.1.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.7
-signing_key:
+rubygems_version: 4.0.21
 specification_version: 4
 summary: Put helps you write prioritized, multi-variate sort_by blocks
 test_files: []

data/put.gemspec

@@ -1,28 +0,0 @@
-require_relative "lib/put/version"
-
-Gem::Specification.new do |spec|
-  spec.name = "put"
-  spec.version = Put::VERSION
-  spec.authors = ["Justin Searls"]
-  spec.email = ["searls@gmail.com"]
-
-  spec.summary = "Put helps you write prioritized, multi-variate sort_by blocks"
-  spec.homepage = "https://github.com/testdouble/put"
-  spec.license = "MIT"
-  spec.required_ruby_version = ">= 2.6.0"
-
-  spec.metadata["homepage_uri"] = spec.homepage
-  spec.metadata["source_code_uri"] = spec.homepage
-  spec.metadata["changelog_uri"] = "#{spec.homepage}/blob/main/CHANGELOG.md"
-
-  # Specify which files should be added to the gem when it is released.
-  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
-  spec.files = Dir.chdir(__dir__) do
-    `git ls-files -z`.split("\x0").reject do |f|
-      (f == __FILE__) || f.match(%r{\A(?:(?:bin|test|spec|features)/|\.(?:git|travis|circleci)|appveyor)})
-    end
-  end
-  spec.bindir = "exe"
-  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
-  spec.require_paths = ["lib"]
-end