put 0.0.1 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 833121595321bacc22e213e447580f40bbbe1500670d5072c582ae54624b468f
-  data.tar.gz: 07dd91f2ae928542e6d4ed42d046ed628fd6a28ef13978cba7ab811796128d92
+  metadata.gz: 91d380401f71b040bc67875987d94a474c6075e28e25197acf9eeea15bfa7d24
+  data.tar.gz: 1f2c56fcb6258bb2d6762eff8aacebad67c83f405d0fc2bf9b863e8355daad8e
 SHA512:
-  metadata.gz: 37a54ae5099e675f9819d4f53e754b481d9ed7b8ad10623ca1978a0277f94e61b6acbc4eac6b0949f1a8dd9ea1e780571f4a6e5b655f493f6ecf11f1687c26f9
-  data.tar.gz: 568dcf85f64510b6b8d8fedc70adc1740339893413a2dfad8a9f42d4f512a2dbbdf2b344356d0fcd38b4b320dbd09bb939a471e1d384b92078d4a74f37a3d631
+  metadata.gz: a0048ac2c7ff377dc9f3944ff540786c8b352a6475e01c20db38839fe159ba109960e40c2ca6aa92b2d81b26097dc2c627d5270bdefa36f8f6d5858ed01493a1
+  data.tar.gz: c11d0add1538cf3457d29b8a9a6d03ad11e8107f0e910af80a82c6699553852abb4e43180370e768dda8e8fbcc60d2518e3c93e4760a55d7f492fe3b1adb43ff

data/CHANGELOG.md

@@ -1,5 +1,12 @@
-## [Unreleased]
+## [0.1.0] - 2022-09-22
 
-## [0.1.0] - 2022-09-21
+- Add Put.nils_first, Put.nils_last
+- Add Put.anywhere
+
+## [0.0.2] - 2022-09-21
+
+- Add support for Put.asc, Put.desc, and whether nils go first or last
+
+## [0.0.1] - 2022-09-21
 
 - Initial release

data/Gemfile

@@ -1,12 +1,8 @@
-# frozen_string_literal: true
-
 source "https://rubygems.org"
 
-# Specify your gem's dependencies in put.gemspec
 gemspec
 
-gem "rake", "~> 13.0"
-
-gem "minitest", "~> 5.0"
-
-gem "standard", "~> 1.3"
+gem "debug"
+gem "rake"
+gem "minitest"
+gem "standard"

data/Gemfile.lock

@@ -1,12 +1,18 @@
 PATH
   remote: .
   specs:
-    put (0.0.1)
+    put (0.1.0)
 
 GEM
   remote: https://rubygems.org/
   specs:
     ast (2.4.2)
+    debug (1.6.2)
+      irb (>= 1.3.6)
+      reline (>= 0.3.1)
+    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)
@@ -15,6 +21,8 @@ GEM
     rainbow (3.1.1)
     rake (13.0.6)
     regexp_parser (2.5.0)
+    reline (0.3.1)
+      io-console (~> 0.5)
     rexml (3.2.5)
     rubocop (1.35.1)
       json (~> 2.3)
@@ -39,12 +47,15 @@ GEM
 
 PLATFORMS
   arm64-darwin-21
+  arm64-darwin-22
+  x86_64-linux
 
 DEPENDENCIES
-  minitest (~> 5.0)
+  debug
+  minitest
   put!
-  rake (~> 13.0)
-  standard (~> 1.3)
+  rake
+  standard
 
 BUNDLED WITH
    2.3.22

data/README.md

@@ -1,33 +1,229 @@
-# Put
+# Put - put your things in order 💎
+
+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.
+
+# 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
+```
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/put`. To experiment with that code, run `bin/console` for an interactive prompt.
+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:
 
-TODO: Delete this and the text above, and describe your gem
+```ruby
+[1, 3, 4, 7, 8, 9].sort_by { |n|
+  [
+    (Put.first if n.even?),
+    Put.anywhere
+  ]
+} # => [8, 4, 1, 7, 9, 3]
+```
 
-## Installation
+### Put.nils_first(value)
 
-Install the gem and add to the application's Gemfile by executing:
+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!
 
-    $ bundle add put
+```ruby
+[:fun, :stuff, nil, :here].sort_by { |val|
+  [Put.nils_first(val)]
+} # => [nil, :fun, :stuff, :here]
+```
 
-If bundler is not being used to manage dependencies, install the gem by executing:
+### Put.nils_last(value)
 
-    $ gem install put
+As you might be able to guess, `Put.nils_last` puts the nils last:
 
-## Usage
+```ruby
+[:every, nil, :counts].sort_by { |val|
+  [Put.nils_last(val)]
+} # => [:every, :counts, nil]
+```
 
-TODO: Write usage instructions here
+### Put.debug(sorting_arrays)
 
-## Development
+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`.
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+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).
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+## Put your hands together! 👏
 
-## Contributing
+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.
+👏👏👏
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/searls/put.
+## Code of Conduct
 
-## License
-
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+This project follows Test Double's [code of
+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.

data/Rakefile

@@ -1,12 +1,10 @@
-# frozen_string_literal: true
-
 require "bundler/gem_tasks"
 require "rake/testtask"
 
 Rake::TestTask.new(:test) do |t|
   t.libs << "test"
   t.libs << "lib"
-  t.test_files = FileList["test/**/test_*.rb"]
+  t.test_files = FileList["test/**/*_test.rb"]
 end
 
 require "standard/rake"

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/nil_ext.rb

@@ -0,0 +1,12 @@
+module Put
+  module NilExtension
+    def <=>(other)
+      if ::Put::PutsThing === other
+        -(other <=> self)
+      else
+        super
+      end
+    end
+  end
+  ::NilClass.prepend(NilExtension)
+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

@@ -0,0 +1,27 @@
+module Put
+  class PutsThing
+    def <=>(other)
+      if value.nil? && (other.nil? || other&.value.nil?)
+        0
+      elsif value.nil?
+        nils_first? ? -1 : 1
+      elsif other.nil? || other&.value.nil?
+        nils_first? ? 1 : -1
+      elsif other && !other.reverse?
+        value <=> other.value
+      elsif other&.reverse?
+        other.value <=> value
+      else
+        value <=> 0
+      end
+    end
+
+    def reverse?
+      false
+    end
+
+    def nils_first?
+      false
+    end
+  end
+end

data/lib/put/version.rb

@@ -1,5 +1,3 @@
-# frozen_string_literal: true
-
-class Put
-  VERSION = "0.0.1"
+module Put
+  VERSION = "0.1.0"
 end

data/lib/put.rb

@@ -1,38 +1,47 @@
+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"
 
-class Put
+module Put
   def self.first
-    First
+    @@first ||= PutsThing::First.new.freeze
   end
 
   def self.last
-    Last
+    @@last ||= PutsThing::Last.new.freeze
   end
 
-  def initialize(value)
-    @value = value
+  def self.desc(value, nils_first: false)
+    PutsThing::Descending.new(value, nils_first: nils_first)
   end
 
-  First = new(-1).freeze
-  Last = new(1).freeze
+  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 <=>(other)
-    @value <=> if other
-      other.value
-    else
-      0
-    end
+  def self.nils_last(value)
+    PutsThing::NilsLast.new(value)
   end
 
-  module NilExtension
-    def <=>(other)
-      if ::Put === other
-        -(other <=> self)
-      else
-        super
-      end
-    end
+  def self.anywhere(seed: nil)
+    PutsThing::Anywhere.new(seed)
   end
 
-  ::NilClass.prepend(NilExtension)
+  def self.debug(sorting_arrays)
+    Debug.new.call(sorting_arrays)
+  end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: put
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.1.0
 platform: ruby
 authors:
 - Justin Searls
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2022-09-21 00:00:00.000000000 Z
+date: 2022-09-22 00:00:00.000000000 Z
 dependencies: []
 description:
 email:
@@ -25,6 +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