put 0.0.2 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 946be21b2839e39c50fccfc55683ec69b8aa1d888a4030cd93aa3ff59f17ff18
-  data.tar.gz: 9cd544f2130f11a1285eaeeaff6b695ac3ca80513b721783836a4d7526b70178
+  metadata.gz: 91d380401f71b040bc67875987d94a474c6075e28e25197acf9eeea15bfa7d24
+  data.tar.gz: 1f2c56fcb6258bb2d6762eff8aacebad67c83f405d0fc2bf9b863e8355daad8e
 SHA512:
-  metadata.gz: 057e1c3b3b7bcb4b8b79e9a98ec132f1c9d6faa03defb3095ae0d2fa5eaeed7b74e3d39d8bda3ab280d8b594e492b493008d1711349d1a11ddea6c1e95802eee
-  data.tar.gz: 2d093be68e236968499608dbd183ffbd99e7664cb6d3a929e0f15bbc904a0f86905a187f2f0046902bab0b055c5dd29399d1cf53a684e36f12a2e19e4bbcdf4b
+  metadata.gz: a0048ac2c7ff377dc9f3944ff540786c8b352a6475e01c20db38839fe159ba109960e40c2ca6aa92b2d81b26097dc2c627d5270bdefa36f8f6d5858ed01493a1
+  data.tar.gz: c11d0add1538cf3457d29b8a9a6d03ad11e8107f0e910af80a82c6699553852abb4e43180370e768dda8e8fbcc60d2518e3c93e4760a55d7f492fe3b1adb43ff

data/CHANGELOG.md

@@ -1,4 +1,7 @@
-## [Unreleased]
+## [0.1.0] - 2022-09-22
+
+- Add Put.nils_first, Put.nils_last
+- Add Put.anywhere
 
 ## [0.0.2] - 2022-09-21
 

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    put (0.0.2)
+    put (0.1.0)
 
 GEM
   remote: https://rubygems.org/
@@ -48,6 +48,7 @@ GEM
 PLATFORMS
   arm64-darwin-21
   arm64-darwin-22
+  x86_64-linux
 
 DEPENDENCIES
   debug

data/README.md

@@ -1,11 +1,223 @@
-# Put
+# Put - put your things 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.
 
-A neat trick when implementing complex sorting rules is to map them to an
-array of arrays of comparable elements in priority-order.
+# First, 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 this
+pattern doesn't have an 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 (e.g. `<=>` 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 are sure be glad they put you in charge of
+putting little 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 items that meet a certain condition 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
 

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.1.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,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: put
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.1.0
 platform: ruby
 authors:
 - Justin Searls
@@ -25,8 +25,18 @@ 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
@@ -52,7 +62,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.7
+rubygems_version: 3.3.20
 signing_key:
 specification_version: 4
 summary: Put helps you write prioritized, multi-variate sort_by blocks