naturally 1.4.0 → 2.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: a5b55ef725bab4abf9e87b176f86ab6c94d1ea4d
-  data.tar.gz: 2ca443c6027ed127aa570dceb2bdf63aeb060457
+SHA256:
+  metadata.gz: 71953ca154c0b7db095ccc5f8f877afed7142eb0bcf59a5118779ba2c8f79aa1
+  data.tar.gz: 302ae86df325c4e526e1b8158dc669c497b27ae9b5ffe60d32bdcb206285eb46
 SHA512:
-  metadata.gz: 85d8b14a18c0415b1360ce03a0eabad8e0cdfa07656648d71d251ac9556194aa705ff547b7cf5c6143762e876f425c4c05369047bef7368bdadaff24ce6d3705
-  data.tar.gz: df7f7705855241de8b0b1f4b26a4996398b90bfc5631088e5bcc9a141d2f98bc149a6192e9a19360b825839106ec06b3c12f586c327736b378eccb3f5c96694a
+  metadata.gz: c7f607e695090c2d12a67b1410960312fbc4d9b7d046f1dea91513653fd00da13e01ebf92c1405efdb498a32029baae4733ddd022cee78becf67db7b4988bedd
+  data.tar.gz: 3110d73168c9797628ad7490e1713785921abbce1651d54e9d8e1e2c6e2c65d9e5cbf77ad1c8b693ac49d2d4a7741ffb1198480f17a1f4b1fa9af2ca264d4c5f

data/.travis.yml

@@ -1,4 +1,4 @@
 language: ruby
 rvm:
-  - 2.1
-  - 2.2
+  - 2.4
+  - 2.5

data/Gemfile

@@ -2,7 +2,7 @@ source 'https://rubygems.org'
 
 group :test do
   gem 'rspec', '~> 3'
-  gem 'rake', '~> 10'
+  gem 'rake', '>= 12.3.3'
 end
 
 # Specify your gem's dependencies in naturally.gemspec

data/README.md

@@ -1,10 +1,11 @@
 # Naturally
-[![Gem Version](https://badge.fury.io/rb/naturally.png)](http://badge.fury.io/rb/naturally) [![Build Status](https://travis-ci.org/dogweather/naturally.png)](https://travis-ci.org/dogweather/naturally) [![Code Climate](https://codeclimate.com/github/dogweather/naturally.png)](https://codeclimate.com/github/dogweather/naturally)
+[![Gem Version](https://badge.fury.io/rb/naturally.png)](http://badge.fury.io/rb/naturally) [![Build Status](https://travis-ci.org/public-law/naturally.png)](https://travis-ci.org/public-law/naturally) 
+[![Maintainability](https://api.codeclimate.com/v1/badges/0ebf4ef97723f2622105/maintainability)](https://codeclimate.com/github/dogweather/naturally/maintainability)
 
-Natural (version number) sorting with support for **legal document numbering**, **college course codes**, and **Unicode**.
-See Jeff Atwood's [Sorting for Humans: Natural Sort Order](http://www.codinghorror.com/blog/2007/12/sorting-for-humans-natural-sort-order.html) and the WebLaws.org post [Counting to 10 in Californian](http://www.weblaws.org/blog/2012/08/counting-from-1-to-10-in-californian/).
+Natural ("version number") sorting with support for **legal document numbering**, **college course codes**, and **Unicode**.
+See Jeff Atwood's [Sorting for Humans: Natural Sort Order](http://www.codinghorror.com/blog/2007/12/sorting-for-humans-natural-sort-order.html) and the Public.Law post [Counting to 10 in Californian](https://blog.public.law/2012/08/07/counting-from-1-to-10-in-californian/).
 
-##Installation
+## Installation
 
 ```Shell
 $ gem install naturally
@@ -15,8 +16,11 @@ $ gem install naturally
 ```Ruby
 require 'naturally'
 
-# Sort a simple array of strings
+# Sort a simple array of strings with legal numbering
 Naturally.sort(["336", "335a", "335", "335.1"])  # => ["335", "335.1", "335a", "336"]
+
+# Sort version numbers
+Naturally.sort(["13.10", "13.04", "10.10", "10.04.4"])  # => ["10.04.4", "10.10", "13.04", "13.10"]
 ```
 
 Usually the library is used to sort an array of objects:
@@ -37,7 +41,7 @@ releases = [
 ]
 
 # Sort by version number
-sorted = Naturally.sort_by(releases, :version)
+sorted = Naturally.sort releases, by: :version
 
 # Check what we have
 expect(sorted.map(&:name)).to eq [

data/lib/naturally.rb

@@ -3,26 +3,39 @@ require 'naturally/segment'
 # A module which performs natural sorting on a variety of number
 # formats. (See the specs for examples.)
 module Naturally
-  # Perform a natural sort.
+  # Perform a natural sort. Supports two syntaxes:
+  #
+  # 1. sort(objects)  # Simple arrays
+  # 2. sort(objects, by: some_attribute)  # Complex objects
   #
   # @param [Array<String>] an_array the list of numbers to sort.
+  # @param [by] (optional) an attribute of the array by which to sort.
   # @return [Array<String>] the numbers sorted naturally.
-  def self.sort(an_array)
-    an_array.sort_by { |x| normalize(x) }
+  def self.sort(an_array, by:nil)
+    if by.nil?
+      an_array.sort_by { |x| normalize(x) }
+    else
+      self.sort_by(an_array, by)
+    end
   end
 
   # Sort an array of objects "naturally" by a given attribute.
+  # If block is given, attribute is ignored and each object
+  # is yielded to the block to obtain the sort key.
   #
   # @param [Array<Object>] an_array the list of objects to sort.
   # @param [Symbol] an_attribute the attribute by which to sort.
+  # @param [Block] &block a block that should evaluate to the
+  #        sort key for the yielded object
   # @return [Array<Object>] the objects in natural sort order.
-  def self.sort_by(an_array, an_attribute)
+  def self.sort_by(an_array, an_attribute=nil, &block)
+    return sort_by_block(an_array, &block) if block_given?
     an_array.sort_by { |obj| normalize(obj.send(an_attribute)) }
   end
 
-  # Convert the given number an array of {Segment}s.
+  # Convert the given number to an array of {Segment}s.
   # This enables it to be sorted against other arrays
-  # by the standard #sort method.
+  # by the built-in #sort method.
   #
   # For example, '1.2a.3' becomes
   # [Segment<'1'>, Segment<'2a'>, Segment<'3'>]
@@ -32,7 +45,19 @@ module Naturally
   # @return [Array<Segment>] an array of Segments which
   #         can be sorted naturally via a standard #sort.
   def self.normalize(complex_number)
-    tokens = complex_number.to_s.scan(/\p{Word}+/)
+    tokens = complex_number.to_s.gsub(/\_/,'').scan(/\p{Word}+/)
     tokens.map { |t| Segment.new(t) }
   end
+
+  private
+  # Sort an array of objects "naturally", yielding each object
+  # to the block to obtain the sort key.
+  #
+  # @param [Array<Object>] an_array the list of objects to sort.
+  # @param [Block] &block a block that should evaluate to the
+  #        sort key for the yielded object
+  # @return [Array<Object>] the objects in natural sort order.
+  def self.sort_by_block(an_array, &block)
+    an_array.sort_by { |obj| normalize(yield(obj)) }
+  end
 end

data/lib/naturally/segment.rb

@@ -1,7 +1,8 @@
 module Naturally
   # An entity which can be compared to other like elements for
   # sorting. It's an object representing
-  # a value which implements the {Comparable} interface.
+  # a value which implements the {Comparable} interface which can
+  # convert itself to an array.
   class Segment
     include Comparable
 
@@ -25,7 +26,7 @@ module Naturally
     # @example a college course code
     #   Segment.new('MATH101').to_array #=> [:str, "MATH", 101]
     #
-    # @example Section 633a of the ADEA
+    # @example Section 633a of the U.S. Age Discrimination in Employment Act
     #   Segment.new('633a').to_array #=> [:int, 633, "a"]
     def to_array
       # TODO: Refactor, probably via polymorphism

data/lib/naturally/version.rb

@@ -1,4 +1,4 @@
 module Naturally
   # Gem version
-  VERSION = '1.4.0'
+  VERSION = '2.2.1'
 end

data/naturally.gemspec

@@ -7,11 +7,11 @@ Gem::Specification.new do |gem|
   gem.version       = Naturally::VERSION
   gem.license       = 'MIT'
   gem.authors       = ["Robb Shecter"]
-  gem.email         = ["robb@weblaws.org"]
+  gem.email         = ["robb@public.law"]
   gem.summary       = %q{Sorts numbers according to the way people are used to seeing them.}
   gem.description   = %q{Natural Sorting with support for legal numbering, course numbers, and other number/letter mixes.}
   gem.homepage      = "http://github.com/dogweather/naturally"
-  gem.required_ruby_version = '>= 2.1'
+  gem.required_ruby_version = '>= 2.0'
 
   gem.files         = `git ls-files`.split($/)
   gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }

data/spec/naturally_spec.rb

@@ -1,92 +1,128 @@
+# coding: utf-8
 require 'naturally'
 
 describe Naturally do
-  def it_sorts(this:, to_this:)
+  # Just a helper for these tests
+  def it_sorts(opts = {})
+    this = opts[:this]
+    to_this = opts[:to_this]
     actual = Naturally.sort(this)
     expect(actual).to eq(to_this)
   end
 
+
   describe '#sort' do
+    it 'supports a nicer by: syntax' do
+      UbuntuVersion ||= Struct.new(:name, :version)
+      releases = [
+        UbuntuVersion.new('Saucy Salamander', '13.10'),
+        UbuntuVersion.new('Raring Ringtail',  '13.04'),
+        UbuntuVersion.new('Precise Pangolin', '12.04.4'),
+        UbuntuVersion.new('Maverick Meerkat', '10.10'),
+        UbuntuVersion.new('Quantal Quetzal',  '12.10'),
+        UbuntuVersion.new('Lucid Lynx',       '10.04.4')
+      ]
+
+      actual = Naturally.sort releases, by: :version
+
+      expect(actual.map(&:name)).to eq [
+                                      'Lucid Lynx',
+                                      'Maverick Meerkat',
+                                      'Precise Pangolin',
+                                      'Quantal Quetzal',
+                                      'Raring Ringtail',
+                                      'Saucy Salamander'
+                                    ]
+    end
+
+
     it 'sorts an array of strings nicely as if they were legal numbers' do
       it_sorts(
-        this: %w(676 676.1 676.11 676.12 676.2 676.3 676.9 676.10),
+        this:    %w(676 676.1 676.11 676.12 676.2 676.3 676.9 676.10),
         to_this: %w(676 676.1 676.2 676.3 676.9 676.10 676.11 676.12)
       )
     end
 
     it 'sorts a more complex list of strings' do
       it_sorts(
-        this: %w(350 351 352 352.1 352.5 353.1 354 354.3 354.4 354.45 354.5),
+        this:    %w(350 351 352 352.1 352.5 353.1 354 354.3 354.4 354.45 354.5),
         to_this: %w(350 351 352 352.1 352.5 353.1 354 354.3 354.4 354.5 354.45)
       )
     end
 
     it 'sorts when numbers have letters in them' do
       it_sorts(
-        this: %w(335 335.1 336a 336 337 337a 337.1 337.15 337.2),
+        this:    %w(335 335.1 336a 336 337 337a 337.1 337.15 337.2),
         to_this: %w(335 335.1 336 336a 337 337.1 337.2 337.15 337a)
       )
     end
 
     it 'sorts when numbers have unicode letters in them' do
       it_sorts(
-        this: %w(335 335.1 336a 336 337 337я 337.1 337.15 337.2),
+        this:    %w(335 335.1 336a 336 337 337я 337.1 337.15 337.2),
         to_this: %w(335 335.1 336 336a 337 337.1 337.2 337.15 337я)
       )
     end
 
     it 'sorts when letters have numbers in them' do
       it_sorts(
-        this: %w(PC1, PC3, PC5, PC7, PC9, PC10, PC11, PC12, PC13, PC14, PROF2, PBLI, SBP1, SBP3),
+        this:    %w(PC1, PC3, PC5, PC7, PC9, PC10, PC11, PC12, PC13, PC14, PROF2, PBLI, SBP1, SBP3),
         to_this: %w(PBLI, PC1, PC3, PC5, PC7, PC9, PC10, PC11, PC12, PC13, PC14, PROF2, SBP1, SBP3)
       )
     end
 
     it 'sorts when letters have numbers and unicode characters in them' do
       it_sorts(
-        this: %w(АБ4, АБ2, АБ10, АБ12, АБ1, АБ3, АД8, АД5, АЩФ12, АЩФ8, ЫВА1),
+        this:    %w(АБ4, АБ2, АБ10, АБ12, АБ1, АБ3, АД8, АД5, АЩФ12, АЩФ8, ЫВА1),
         to_this: %w(АБ1, АБ2, АБ3, АБ4, АБ10, АБ12, АД5, АД8, АЩФ8, АЩФ12, ЫВА1)
       )
     end
 
     it 'sorts double digits with letters correctly' do
       it_sorts(
-        this: %w(12a 12b 12c 13a 13b 2 3 4 5 10 11 12),
+        this:    %w(12a 12b 12c 13a 13b 2 3 4 5 10 11 12),
         to_this: %w(2 3 4 5 10 11 12 12a 12b 12c 13a 13b)
       )
     end
 
     it 'sorts double digits with unicode letters correctly' do
       it_sorts(
-        this: %w(12а 12б 12в 13а 13б 2 3 4 5 10 11 12),
+        this:    %w(12а 12б 12в 13а 13б 2 3 4 5 10 11 12),
         to_this: %w(2 3 4 5 10 11 12 12а 12б 12в 13а 13б)
       )
     end
 
+    it 'sorts strings suffixed with underscore and numbers correctly' do
+      it_sorts(
+        this:    %w(item_10 item_11 item_1 item_7 item_5 item_3 item_4 item_6 item_2),
+        to_this: %w(item_1 item_2 item_3 item_4 item_5 item_6 item_7 item_10 item_11)
+      )
+    end
+
     it 'sorts letters with digits correctly' do
       it_sorts(
-        this: %w(1 a 2 b 3 c),
+        this:    %w(1 a 2 b 3 c),
         to_this: %w(1 2 3 a b c)
       )
     end
 
     it 'sorts complex numbers with digits correctly' do
       it_sorts(
-        this: %w(1 a 2 b 3 c 1.1 a.1 1.2 a.2 1.3 a.3 b.1 ),
+        this:    %w(1 a 2 b 3 c 1.1 a.1 1.2 a.2 1.3 a.3 b.1 ),
         to_this: %w(1 1.1 1.2 1.3 2 3 a a.1 a.2 a.3 b b.1 c)
       )
     end
 
     it 'sorts complex mixes of numbers and digits correctly' do
       it_sorts(
-        this: %w( 1.a.1 1.1 ),
+        this:    %w( 1.a.1 1.1 ),
         to_this: %w( 1.1 1.a.1 )
       )
     end
 
     it 'sorts complex mixes of numbers and digits correctly' do
       it_sorts(
-        this: %w( 1a1 1aa aaa ),
+        this:    %w( 1a1 1aa aaa ),
         to_this: %w( 1aa 1a1 aaa )
       )
     end
@@ -94,7 +130,7 @@ describe Naturally do
 
   describe '#sort_naturally_by' do
     it 'sorts by an attribute' do
-      UbuntuVersion = Struct.new(:name, :version)
+      UbuntuVersion ||= Struct.new(:name, :version)
       releases = [
         UbuntuVersion.new('Saucy Salamander', '13.10'),
         UbuntuVersion.new('Raring Ringtail',  '13.04'),
@@ -150,4 +186,26 @@ describe Naturally do
       ]
     end
   end
+
+  describe '#sort_naturally_by_block' do
+    it 'sorts using a block' do
+      releases = [
+        {:name => 'Saucy Salamander', :version => '13.10'},
+        {:name => 'Raring Ringtail',  :version => '13.04'},
+        {:name => 'Precise Pangolin', :version => '12.04.4'},
+        {:name => 'Maverick Meerkat', :version => '10.10'},
+        {:name => 'Quantal Quetzal',  :version => '12.10'},
+        {:name => 'Lucid Lynx',       :version => '10.04.4'}
+      ]
+      actual = Naturally.sort_by(releases){|r| r[:version]}
+      expect(actual.map{|r| r[:name]}).to eq [
+        'Lucid Lynx',
+        'Maverick Meerkat',
+        'Precise Pangolin',
+        'Quantal Quetzal',
+        'Raring Ringtail',
+        'Saucy Salamander'
+      ]
+    end
+  end
 end

metadata

@@ -1,19 +1,19 @@
 --- !ruby/object:Gem::Specification
 name: naturally
 version: !ruby/object:Gem::Version
-  version: 1.4.0
+  version: 2.2.1
 platform: ruby
 authors:
 - Robb Shecter
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2015-08-04 00:00:00.000000000 Z
+date: 2021-01-18 00:00:00.000000000 Z
 dependencies: []
 description: Natural Sorting with support for legal numbering, course numbers, and
   other number/letter mixes.
 email:
-- robb@weblaws.org
+- robb@public.law
 executables: []
 extensions: []
 extra_rdoc_files: []
@@ -33,7 +33,7 @@ homepage: http://github.com/dogweather/naturally
 licenses:
 - MIT
 metadata: {}
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -41,16 +41,15 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '2.1'
+      version: '2.0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 2.4.8
-signing_key: 
+rubygems_version: 3.2.5
+signing_key:
 specification_version: 4
 summary: Sorts numbers according to the way people are used to seeing them.
 test_files: