put 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 91d380401f71b040bc67875987d94a474c6075e28e25197acf9eeea15bfa7d24
-  data.tar.gz: 1f2c56fcb6258bb2d6762eff8aacebad67c83f405d0fc2bf9b863e8355daad8e
+  metadata.gz: ed8c542e17e5ecbc293a508843be66ab105238b761ed40e585980a2402ec6124
+  data.tar.gz: f7fef7196819fe61112639c965a4f5eca999dc0c72c94f6360574f02c94242f1
 SHA512:
-  metadata.gz: a0048ac2c7ff377dc9f3944ff540786c8b352a6475e01c20db38839fe159ba109960e40c2ca6aa92b2d81b26097dc2c627d5270bdefa36f8f6d5858ed01493a1
-  data.tar.gz: c11d0add1538cf3457d29b8a9a6d03ad11e8107f0e910af80a82c6699553852abb4e43180370e768dda8e8fbcc60d2518e3c93e4760a55d7f492fe3b1adb43ff
+  metadata.gz: 1b19851583cc9248409052e468a9bd913731eb04fe93ba16358965634740bbba5260626478fc6f7b5c7f4e2180c46e9fd6bdebbb6b6b19722a67209bfa020d23
+  data.tar.gz: 8c6216e264c6abe21db898b59c880f5aaa7276032a2f9b5c0db623f2496268f632b81e041b9e9fff2cd970c3158104f3b36881ae432de79088fb2c5f4ccbbffb

data/CHANGELOG.md

@@ -1,3 +1,11 @@
+## [0.3.0] - 2026-09-22
+
+- Add Put.enum [#2](https://github.com/testdouble/put/issues/2)
+
+## [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

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,49 +1,70 @@
 PATH
   remote: .
   specs:
-    put (0.1.0)
+    put (0.3.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
@@ -51,9 +72,14 @@ PLATFORMS
   x86_64-linux
 
 DEPENDENCIES
+  base64
   debug
-  minitest
+  fiddle
+  minitest (< 6)
+  ostruct
+  parallel (< 2)
   put!
+  racc
   rake
   standard
 

data/README.md

@@ -1,11 +1,13 @@
-# Put - put your things in order 💎
+# Put puts your objects 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.
+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.
 
-# First, put Put in your Gemfile
+## Put "put" in your Gemfile
 
 You've probably already put a few gems in there, so why not put Put, too:
 
@@ -20,8 +22,8 @@ Of course after you push Put, your colleagues will wonder why you put Put there.
 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.
+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:
 
@@ -68,8 +70,8 @@ is almost begging for a code comment above it to explain its intent
 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
+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_"
 
@@ -95,8 +97,8 @@ The Put gem solves every one of the above issues:
   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.
+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
 
@@ -116,8 +118,8 @@ either `Put.first` or `nil`, like this:
 
 ### 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`:
+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|
@@ -203,6 +205,31 @@ As you might be able to guess, `Put.nils_last` puts the nils last:
 } # => [:every, :counts, nil]
 ```
 
+### Put.enum(value, order:, nils_first: false)
+
+When you're sorting by a discrete attribute — a role, a status, a tier — that
+doesn't have a natural order of its own, `Put.enum` sorts a value by its
+position in a list you provide, instead of you writing a `case`/`when`
+translation table by hand:
+
+```ruby
+[:director, :staff, :manager].sort_by { |role|
+  [Put.enum(role, order: [:staff, :manager, :director])]
+} # => [:staff, :manager, :director]
+```
+
+A value that isn't in `order` sorts after every value that is, rather than
+raising:
+
+```ruby
+[:manager, :contractor, :staff].sort_by { |role|
+  [Put.enum(role, order: [:staff, :manager, :director])]
+} # => [:staff, :manager, :contractor]
+```
+
+Like `Put.asc` and `Put.desc`, `Put.enum` also takes a `nils_first` keyword
+argument (defaulting to `false`) for where `nil` values should sort.
+
 ### Put.debug(sorting_arrays)
 
 If you see "comparison of Array with Array failed" and you don't have any idea
@@ -226,4 +253,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/puts_thing/enum.rb

@@ -0,0 +1,10 @@
+module Put
+  class PutsThing
+    class Enum < InOrder
+      def initialize(value, order:, nils_first: false)
+        rank = value.nil? ? nil : (order.index(value) || Float::INFINITY)
+        super(rank, nils_first: nils_first)
+      end
+    end
+  end
+end

data/lib/put/version.rb

@@ -1,3 +1,3 @@
 module Put
-  VERSION = "0.1.0"
+  VERSION = "0.3.0"
 end

data/lib/put.rb

@@ -6,6 +6,7 @@ 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/enum"
 require_relative "put/puts_thing/ascending"
 require_relative "put/puts_thing/descending"
 require_relative "put/puts_thing/nil_order"
@@ -29,6 +30,10 @@ module Put
     PutsThing::Ascending.new(value, nils_first: nils_first)
   end
 
+  def self.enum(value, order:, nils_first: false)
+    PutsThing::Enum.new(value, order: order, nils_first: nils_first)
+  end
+
   def self.nils_first(value)
     PutsThing::NilsFirst.new(value)
   end

metadata

@@ -1,16 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: put
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.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: []
@@ -31,6 +29,7 @@ files:
 - lib/put/puts_thing/anywhere.rb
 - lib/put/puts_thing/ascending.rb
 - lib/put/puts_thing/descending.rb
+- lib/put/puts_thing/enum.rb
 - lib/put/puts_thing/first.rb
 - lib/put/puts_thing/in_order.rb
 - lib/put/puts_thing/last.rb
@@ -38,7 +37,6 @@ files:
 - 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:
@@ -47,7 +45,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
@@ -55,15 +52,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.20
-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