naturally 1.3.1 → 1.3.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: a36e33ade747d0c59b3788ba0bb22c1f6defb184
-  data.tar.gz: a81707fb161b155dc47bed22462cf8a9ed734fe5
+  metadata.gz: 11b862eddf78c3c623300fc93d643a1b0081f815
+  data.tar.gz: 576b16fec163a92e756c98c1df4f3b1af8ebab31
 SHA512:
-  metadata.gz: 7536fef931a0c593bc9918bff1e6407922a18cc339f8e0d96edf8e97db941232809238749fe6fd65f9fb9264cd8fa89d16d01cef8e64afe30301def32f6726f3
-  data.tar.gz: 00f5d433456e0516da7229ab2c64b9c5bbb448aa556e58252115a564d431078dfe19ca8fa1d28b5fd6cfaeee89e3e600db59f3c27d67f9f94e58fb5995a45888
+  metadata.gz: 08f910f8cd088cb92969c6f1d257cc53a2178e54894639bac1b361651c986f312e90c6cd42eacb202b89fc664dbf1108d76b474578a40e0a35462bb6ab4f23fe
+  data.tar.gz: 1f389ebe3746dc8d2f5c80cd35eb0dcdf4e408fd5f9116945e3355bdf2e037ecff46a60ca458bb3e02df5a701b3847460c184d4ba29012248aae2a09b32e26c9

data/.travis.yml

@@ -1,6 +1,4 @@
 language: ruby
 rvm:
-  - "1.9.3"
-  - "2.0.0"
-  - "2.1.0"
-  - "2.1.1"
+  - 2.1
+  - 2.2

data/Gemfile

@@ -1,7 +1,7 @@
 source 'https://rubygems.org'
 
 group :test do
-  gem 'rspec', '~> 2.0'
+  gem 'rspec', '~> 3.0'
   gem 'rake', '~> 10.0'
 end
 

data/README.md

@@ -1,29 +1,8 @@
 # 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)
 
-Natural (version number) sorting with added support for **legal document numbering** 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/).
-
-The core of the search is [from here](https://github.com/ahoward/version_sorter). It's since been extended to handle the particular types of numbers that come up in statutes, such
-as *335.1, 336, 336a*, etc.
-
-`Naturally` will also sort "numbers" in college course code format such as
-*MATH101, MATH102, ...*. See the specs for examples.
-
-
-## Installation
-
-Add this line to your application's Gemfile:
-
-    gem 'naturally'
-
-And then execute:
-
-    $ bundle
-
-Or install it outside of bundler with:
-
-    $ gem install naturally
+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/).
 
 
 ## Usage
@@ -68,6 +47,11 @@ expect(sorted.map(&:name)).to eq [
 
 See [the spec for more examples](https://github.com/dogweather/naturally/blob/master/spec/naturally_spec.rb) of what Naturally can sort.
 
+## Related Work
+
+* [ahoward/version_sorter](https://github.com/ahoward/version_sorter), the starting point for the `naturally` gem.
+* [GitHub's Version sorter](https://github.com/github/version_sorter)
+
 
 ## Contributing
 

data/lib/naturally.rb

@@ -1,98 +1,43 @@
-# encoding: utf-8
-
-require 'naturally/version'
-
+require 'naturally/segment'
+
+# A module which performs natural sorting on a variety of number
+# formats. (See the specs for examples.)
+#
+# It achieves this by capitalizing on Ruby's behavior when
+# comparing arrays: The module sorts arrays of segmented numbers such as
+# ['1.9', '1.9a', '1.10'] by comparing them in their array forms.
+# I.e., approximately [['1', '9'], ['1, '9a'], ['1', '10']]
 module Naturally
   # Perform a natural sort.
   #
   # @param [Array<String>] an_array the list of numbers to sort.
   # @return [Array<String>] the numbers sorted naturally.
   def self.sort(an_array)
-    return an_array.sort_by { |x| normalize(x) }
+    an_array.sort_by { |x| normalize(x) }
   end
 
+  # Sort an array of objects "naturally" by a given attribute.
+  #
+  # @param [Array<Object>] an_array the list of objects to sort.
+  # @param [Symbol] an_attribute the attribute by which to sort.
+  # @return [Array<Object>] the objects in natural sort order.
   def self.sort_by(an_array, an_attribute)
-    an_array.sort_by{|i| Naturally.normalize(i.send(an_attribute))}
+    an_array.sort_by { |obj| normalize(obj.send(an_attribute)) }
   end
 
-  # Convert the given number into an object that can be sorted
-  # naturally. This object is an array of {NumberElement} instances.
+  # Convert the given number an array of {Segment}s.
+  # This enables it to be sorted against other arrays
+  # by the standard #sort method.
   #
-  # @param [String] number the number in complex form such as 1.2a.3.
-  # @return [Array<NumberElement>] an array of NumberElements which is
-  #         able to be sorted naturally via a normal 'sort'.
-  def self.normalize(number)
-    number.to_s.scan(%r/\p{Word}+/o).map { |i| NumberElement.new(i) }
-  end
-
-  private
-
-  # An entity which can be compared to other like elements for
-  # sorting in an array. It's an object representing
-  # a value which implements the {Comparable} interface.
-  class NumberElement
-    include Comparable
-    attr_accessor :val
-
-    def initialize(v)
-      @val = v
-    end
-
-    def <=>(other)
-      if both_are_integers_without_letters(other)
-        return @val.to_i <=> other.val.to_i
-      end
-
-      if either_is_numbers_followed_by_letters(other)
-        return simple_normalize(@val) <=> simple_normalize(other.val)
-      end
-
-      if either_is_letters_followed_by_numbers(other)
-        return reverse_simple_normalize(@val) <=> reverse_simple_normalize(other.val)
-      end
-
-      @val <=> other.val
-    end
-
-    def either_is_letters_followed_by_numbers(other)
-      letters_with_numbers? || other.letters_with_numbers?
-    end
-
-    def either_is_numbers_followed_by_letters(other)
-      numbers_with_letters? || other.numbers_with_letters?
-    end
-
-    def both_are_integers_without_letters(other)
-      pure_integer? && other.pure_integer?
-    end
-
-    def pure_integer?
-      @val =~ /^\d+$/
-    end
-
-    def numbers_with_letters?
-      val =~ /^\d+\p{Alpha}+$/
-    end
-
-    def letters_with_numbers?
-      val =~ /^\p{Alpha}+\d+$/
-    end
-
-    def simple_normalize(n)
-      if n =~ /^(\d+)(\p{Alpha}+)$/
-        [$1.to_i, $2]
-      else 
-        [n.to_i]
-      end
-    end
-
-    def reverse_simple_normalize(n)
-      if n =~ /^(\p{Alpha}+)(\d+)$/
-        [$1, $2.to_i]
-      else
-        [n.to_s]
-      end
-    end
-
+  # For example:
+  # '1.2a.3' becomes [Segment<'1'>, Segment<'2a'>, Segment<'3'>]
+  #
+  # @param [String] complex_number the number in a hierarchical form
+  #                 such as 1.2a.3.
+  # @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.map { |t| Segment.new(t) }
   end
 end

data/lib/naturally/segment.rb

@@ -0,0 +1,28 @@
+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.
+  class Segment
+    include Comparable
+
+    def initialize(v)
+      @val = v
+    end
+
+    def <=>(other)
+      to_array <=> other.to_array
+    end
+
+    def to_array
+      if @val =~ /^(\p{Digit}+)(\p{Alpha}+)$/
+        [$1.to_i, $2]
+      elsif @val =~ /^(\p{Alpha}+)(\p{Digit}+)$/
+        [$1, $2.to_i]
+      elsif @val =~ /^\p{Digit}+$/
+        [@val.to_i]
+      else
+        [@val]
+      end
+    end
+  end
+end

data/lib/naturally/version.rb

@@ -1,3 +1,3 @@
 module Naturally
-  VERSION = '1.3.1'
+  VERSION = '1.3.2'
 end

data/naturally.gemspec

@@ -6,10 +6,11 @@ require 'naturally/version'
 Gem::Specification.new do |gem|
   gem.name          = "naturally"
   gem.version       = Naturally::VERSION
+  gem.license       = 'MIT'
   gem.authors       = ["Robb Shecter"]
   gem.email         = ["robb@weblaws.org"]
   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}
+  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.files         = `git ls-files`.split($/)

data/spec/naturally_spec.rb

@@ -1,55 +1,67 @@
 # encoding: utf-8
-
 require 'naturally'
 
 describe Naturally do
+  def it_sorts(this:, to_this:)
+    actual = Naturally.sort(this)
+    expect(actual).to eq(to_this)
+  end
+
   describe '#sort' do
     it 'sorts an array of strings nicely as if they were legal numbers' do
-      a = %w[676 676.1 676.11 676.12 676.2 676.3 676.9 676.10]
-      b = %w[676 676.1 676.2 676.3 676.9 676.10 676.11 676.12]
-      Naturally.sort(a).should == b
+      it_sorts(
+        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
-      a = %w[350 351 352 352.1 352.5 353.1 354 354.3 354.4 354.45 354.5]
-      b = %w[350 351 352 352.1 352.5 353.1 354 354.3 354.4 354.5 354.45]
-      Naturally.sort(a).should == b
+      it_sorts(
+        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
-      a = %w[335 335.1 336a 336 337 337a 337.1 337.15 337.2]
-      b = %w[335 335.1 336 336a 337 337.1 337.2 337.15 337a]
-      Naturally.sort(a).should == b
+      it_sorts(
+        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
-      a = %w[335 335.1 336a 336 337 337я 337.1 337.15 337.2]
-      b = %w[335 335.1 336 336a 337 337.1 337.2 337.15 337я]
-      Naturally.sort(a).should == b
+      it_sorts(
+        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
-      a = %w[PC1, PC3, PC5, PC7, PC9, PC10, PC11, PC12, PC13, PC14, PROF2, PBLI, SBP1, SBP3]
-      b = %w[PBLI, PC1, PC3, PC5, PC7, PC9, PC10, PC11, PC12, PC13, PC14, PROF2, SBP1, SBP3]
-      Naturally.sort(a).should == b
+      it_sorts(
+        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
-      a = %w[АБ4, АБ2, АБ10, АБ12, АБ1, АБ3, АД8, АД5, АЩФ12, АЩФ8, ЫВА1]
-      b = %w[АБ1, АБ2, АБ3, АБ4, АБ10, АБ12, АД5, АД8, АЩФ8, АЩФ12, ЫВА1]
-      Naturally.sort(a).should == b
+      it_sorts(
+        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
-      a = %w[12a 12b 12c 13a 13b 2 3 4 5 10 11 12]
-      b = %w[2 3 4 5 10 11 12 12a 12b 12c 13a 13b]
-      Naturally.sort(a).should == b
+      it_sorts(
+        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
-      a = %w[12а 12б 12в 13а 13б 2 3 4 5 10 11 12]
-      b = %w[2 3 4 5 10 11 12 12а 12б 12в 13а 13б]
-      Naturally.sort(a).should == b
+      it_sorts(
+        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
   end
 
@@ -64,8 +76,8 @@ describe Naturally do
         UbuntuVersion.new('Quantal Quetzal',  '12.10'),
         UbuntuVersion.new('Lucid Lynx',       '10.04.4')
       ]
-      sorted = Naturally.sort_by(releases, :version)
-      expect(sorted.map(&:name)).to eq [
+      actual = Naturally.sort_by(releases, :version)
+      expect(actual.map(&:name)).to eq [
         'Lucid Lynx',
         'Maverick Meerkat',
         'Precise Pangolin',
@@ -86,8 +98,8 @@ describe Naturally do
         Thing.new('2.1', 'Калуга'),
         Thing.new('1.3', 'Васюки')
       ]
-      sorted = objects.sort_by{ |o| Naturally.normalize(o.name) }
-      sorted.map{|o| o.name}.should == %w[
+      actual = objects.sort_by { |o| Naturally.normalize(o.name) }
+      expect(actual.map(&:name)).to eq %w(
         Брест
         Будапешт
         Васюки
@@ -95,7 +107,7 @@ describe Naturally do
         Киев
         Москва
         Париж
-      ]
+      )
     end
   end
 end

metadata

@@ -1,16 +1,17 @@
 --- !ruby/object:Gem::Specification
 name: naturally
 version: !ruby/object:Gem::Version
-  version: 1.3.1
+  version: 1.3.2
 platform: ruby
 authors:
 - Robb Shecter
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-05-07 00:00:00.000000000 Z
+date: 2015-03-11 00:00:00.000000000 Z
 dependencies: []
-description: Natural Sorting with support for legal numbering
+description: Natural Sorting with support for legal numbering, course numbers, and
+  other number/letter mixes.
 email:
 - robb@weblaws.org
 executables: []
@@ -24,11 +25,13 @@ files:
 - README.md
 - Rakefile
 - lib/naturally.rb
+- lib/naturally/segment.rb
 - lib/naturally/version.rb
 - naturally.gemspec
 - spec/naturally_spec.rb
 homepage: http://github.com/dogweather/naturally
-licenses: []
+licenses:
+- MIT
 metadata: {}
 post_install_message: 
 rdoc_options: []
@@ -46,10 +49,9 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.2.2
+rubygems_version: 2.4.6
 signing_key: 
 specification_version: 4
 summary: Sorts numbers according to the way people are used to seeing them.
 test_files:
 - spec/naturally_spec.rb
-has_rdoc: