naturally 2.2.2 → 2.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: d6b9503d643f2bc2e137219f9572cff2e930a5565c55155d4204e2a77023f1b1
4
- data.tar.gz: 8ba1b7379a6a5b13dc4487d8c2946e46484cc46853acf792ae0502e2debba830
3
+ metadata.gz: f7b3438395c4df9f5c1470db59359c467abe79877204a11174b9a321ac2b4029
4
+ data.tar.gz: e3d200777e6d638c2e8b33386ec47366b5cc69f51fc61fb34f0c0aa38723eb6a
5
5
  SHA512:
6
- metadata.gz: e7a58a43c54c821703e9eedc9455a37433d7c80cca3ccb1eeaafed11f43e5095a48e11cebb0d421d1bf36116f73a336b3ad78b5ce904895becb739e36d8655a4
7
- data.tar.gz: a78a9c67ed7267bdb77eb2f7cb5fd5de79b22fe8297aaf634b2f30370ad00c401f22ea7ee4cc5949f3439995ea57aed86f69badfe7400731c78da27110005349
6
+ metadata.gz: 89629cc8ad213f9768a0125b485c634ef195c18a0f282153064dfa0e5009d37147b89ad8a7a156e89de7794389d0d8c3e6cdb12995e9b0bad5f9941133814f40
7
+ data.tar.gz: 7d159e939b9ed816d3af16841df1791cca2ad0e1a3b0feaf6372cde3bb41a819e6998a247ad1a95628cd6f648aac3d97ed3a3dba9515404dc612217b728b1cac
@@ -0,0 +1,37 @@
1
+ # This workflow uses actions that are not certified by GitHub.
2
+ # They are provided by a third-party and are governed by
3
+ # separate terms of service, privacy policy, and support
4
+ # documentation.
5
+ # This workflow will download a prebuilt Ruby version, install dependencies and run tests with Rake
6
+ # For more information see: https://github.com/marketplace/actions/setup-ruby-jruby-and-truffleruby
7
+
8
+ name: Ruby
9
+
10
+ on:
11
+ push:
12
+ branches: [ "master" ]
13
+ pull_request:
14
+ branches: [ "master" ]
15
+
16
+ permissions:
17
+ contents: read
18
+
19
+ jobs:
20
+ test:
21
+
22
+ runs-on: ubuntu-latest
23
+ strategy:
24
+ matrix:
25
+ ruby-version: ['3.2', '3.3', '3.4']
26
+
27
+ steps:
28
+ - uses: actions/checkout@v4
29
+ - name: Set up Ruby
30
+ # To automatically get bug fixes and new Ruby versions for ruby/setup-ruby,
31
+ # change this to (see https://github.com/ruby/setup-ruby#versioning):
32
+ uses: ruby/setup-ruby@v1
33
+ with:
34
+ ruby-version: ${{ matrix.ruby-version }}
35
+ bundler-cache: true # runs 'bundle install' and caches installed gems automatically
36
+ - name: Run tests
37
+ run: bundle exec rspec
data/CHANGELOG.md ADDED
@@ -0,0 +1,31 @@
1
+ # Changelog
2
+
3
+ All notable changes to this project will be documented in this file.
4
+
5
+ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
6
+ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7
+
8
+ ## [2.3.0] - 2025-06-11
9
+
10
+ ### Added
11
+ - New `#sort_filenames` method for sorting filenames with underscores and dots as separators
12
+ - Dots are given higher priority than underscores in filename sorting
13
+ - Comprehensive test coverage for filename sorting scenarios
14
+
15
+ ### Changed
16
+ - Updated README with documentation and examples for the new `#sort_filenames` method
17
+
18
+ ## [2.2.2] - Previous Release
19
+
20
+ ### Notes
21
+ - Previous stable release
22
+ - Included support for natural sorting with legal numbering, course codes, and Unicode
23
+ - Maintained compatibility with Ruby 2.0+
24
+
25
+ ## Historical Releases
26
+
27
+ For releases prior to 2.2.2, please refer to the git commit history.
28
+
29
+ ---
30
+
31
+ **Note**: This changelog was introduced in version 2.3.0. Future releases will document all changes here.
data/README.md CHANGED
@@ -3,11 +3,13 @@
3
3
 
4
4
  Natural ("version number") sorting with support for:
5
5
 
6
+ * **file names**,
6
7
  * **legal document numbering**,
7
8
  * **college course codes**, and
8
9
  * **Unicode**.
9
10
 
10
- See Jeff Atwood's [Sorting for Humans: Natural Sort Order](https://blog.codinghorror.com/sorting-for-humans-natural-sort-order/) and my post [Counting to 10 in Californian](https://blog.public.law/2012/08/07/counting-from-1-to-10-in-californian/).
11
+ See Jeff Atwood's [Sorting for Humans: Natural Sort Order](https://blog.codinghorror.com/sorting-for-humans-natural-sort-order/).
12
+
11
13
 
12
14
  ## Installation
13
15
 
@@ -17,18 +19,21 @@ $ gem install naturally
17
19
 
18
20
  ## Usage
19
21
 
22
+ ### `#sort`
23
+
20
24
  ```Ruby
21
25
  require 'naturally'
22
26
 
23
- # Sort a simple array of strings with legal numbering
24
- Naturally.sort(["336", "335a", "335", "335.1"]) # => ["335", "335.1", "335a", "336"]
25
-
26
27
  # Sort version numbers
27
- Naturally.sort(["13.10", "13.04", "10.10", "10.04.4"]) # => ["10.04.4", "10.10", "13.04", "13.10"]
28
- ```
28
+ Naturally.sort(["13.10", "13.04", "10.10", "10.04.4"])
29
+ # => ["10.04.4", "10.10", "13.04", "13.10"]
29
30
 
30
- Usually the library is used to sort an array of objects:
31
+ # Sort legal section numbers
32
+ Naturally.sort(["336", "335a", "335", "335.1"])
33
+ # => ["335", "335.1", "335a", "336"]
34
+ ```
31
35
 
36
+ The library can also sort an array of objects:
32
37
 
33
38
  ```Ruby
34
39
  # Define a new simple object for storing Ubuntu versions
@@ -44,23 +49,53 @@ releases = [
44
49
  UbuntuVersion.new('Lucid Lynx', '10.04.4')
45
50
  ]
46
51
 
47
- # Sort by version number
48
- sorted = Naturally.sort(releases, by: :version)
49
-
50
- # Check what we have
51
- expect(sorted.map(&:name)).to eq [
52
- 'Lucid Lynx',
53
- 'Maverick Meerkat',
54
- 'Precise Pangolin',
55
- 'Quantal Quetzal',
56
- 'Raring Ringtail',
57
- 'Saucy Salamander'
58
- ]
52
+ # Sort by the version attribute
53
+ Naturally.sort(releases, by: :version)
54
+
55
+ => [#<struct UbuntuVersion name="Lucid Lynx", version="10.04.4">,
56
+ #<struct UbuntuVersion name="Maverick Meerkat", version="10.10">,
57
+ #<struct UbuntuVersion name="Precise Pangolin", version="12.04.4">,
58
+ #<struct UbuntuVersion name="Quantal Quetzal", version="12.10">,
59
+ #<struct UbuntuVersion name="Raring Ringtail", version="13.04">,
60
+ #<struct UbuntuVersion name="Saucy Salamander", version="13.10">]
59
61
  ```
60
62
 
61
63
  [More examples are in the specs](https://github.com/public-law/naturally/blob/master/spec/naturally_spec.rb).
62
64
 
63
65
 
66
+ ### `#sort_filenames`
67
+
68
+ Sorts filenames naturally, treating underscores and dots as separators. Useful for sorting files like images or documents that use numbers, underscores, and dots in their names.
69
+
70
+ ```ruby
71
+ files = [
72
+ 'abc_2.tif',
73
+ 'abc_1_a.tif',
74
+ 'abc_1.zzz',
75
+ 'abc_1_xyz.abc',
76
+ 'abc_2a.tif',
77
+ 'abc.2.tif',
78
+ 'abc.1_a.tif',
79
+ 'abc_2.abc',
80
+ 'abc_1_xyz.abc'
81
+ ]
82
+ Naturally.sort_filenames(files)
83
+ # => [
84
+ # "abc.1_a.tif",
85
+ # "abc.2.tif",
86
+ # "abc_1.zzz",
87
+ # "abc_1_a.tif",
88
+ # "abc_1_xyz.abc",
89
+ # "abc_1_xyz.abc",
90
+ # "abc_2.abc",
91
+ # "abc_2.tif",
92
+ # "abc_2a.tif"
93
+ # ]
94
+ ```
95
+
96
+ This method gives higher priority to dots than underscores, so files like `abc.1_a.tif` will come before `abc.2.tif`.
97
+
98
+
64
99
  ## Implementation Notes
65
100
 
66
101
  The algorithm capitalizes on Ruby's array comparison behavior:
@@ -1,3 +1,5 @@
1
+ # frozen_string_literal: true
2
+
1
3
  module Naturally
2
4
  # An entity which can be compared to other like elements for
3
5
  # sorting. It's an object representing
@@ -6,8 +8,27 @@ module Naturally
6
8
  class Segment
7
9
  include Comparable
8
10
 
11
+ DIGITS_THEN_ALPHA = /^(\p{Digit}+)(\p{Alpha}+)$/
12
+ ALPHA_THEN_DIGITS = /^(\p{Alpha}+)(\p{Digit}+)$/
13
+ DIGITS = /^\p{Digit}+$/
14
+
15
+ # @return [Array] the sort key for a single token, computed without
16
+ # allocating a {Segment}.
17
+ def self.to_array(token)
18
+ if (m = DIGITS_THEN_ALPHA.match(token))
19
+ [:int, m[1].to_i, m[2]]
20
+ elsif (m = ALPHA_THEN_DIGITS.match(token))
21
+ [:str, m[1], m[2].to_i]
22
+ elsif DIGITS.match?(token)
23
+ [:int, token.to_i]
24
+ else
25
+ [:str, token]
26
+ end
27
+ end
28
+
9
29
  def initialize(v)
10
30
  @val = v
31
+ @array = Segment.to_array(v)
11
32
  end
12
33
 
13
34
  def <=>(other)
@@ -29,16 +50,7 @@ module Naturally
29
50
  # @example Section 633a of the U.S. Age Discrimination in Employment Act
30
51
  # Segment.new('633a').to_array #=> [:int, 633, "a"]
31
52
  def to_array
32
- # TODO: Refactor, probably via polymorphism
33
- if @val =~ /^(\p{Digit}+)(\p{Alpha}+)$/
34
- [:int, $1.to_i, $2]
35
- elsif @val =~ /^(\p{Alpha}+)(\p{Digit}+)$/
36
- [:str, $1, $2.to_i]
37
- elsif @val =~ /^\p{Digit}+$/
38
- [:int, @val.to_i]
39
- else
40
- [:str, @val]
41
- end
53
+ @array
42
54
  end
43
55
  end
44
56
  end
@@ -1,4 +1,4 @@
1
1
  module Naturally
2
2
  # Gem version
3
- VERSION = '2.2.2'
3
+ VERSION = '2.4.0'
4
4
  end
data/lib/naturally.rb CHANGED
@@ -1,8 +1,13 @@
1
+ # frozen_string_literal: true
2
+
1
3
  require 'naturally/segment'
2
4
 
3
5
  # A module which performs natural sorting on a variety of number
4
6
  # formats. (See the specs for examples.)
5
7
  module Naturally
8
+ WORD = /\p{Word}+/
9
+ private_constant :WORD
10
+
6
11
  # Perform a natural sort. Supports two syntaxes:
7
12
  #
8
13
  # 1. sort(objects) # Simple arrays
@@ -13,7 +18,7 @@ module Naturally
13
18
  # @return [Array<String>] the numbers sorted naturally.
14
19
  def self.sort(an_array, by:nil)
15
20
  if by.nil?
16
- an_array.sort_by { |x| normalize(x) }
21
+ an_array.sort_by { |x| sort_key(x) }
17
22
  else
18
23
  self.sort_by(an_array, by)
19
24
  end
@@ -30,7 +35,7 @@ module Naturally
30
35
  # @return [Array<Object>] the objects in natural sort order.
31
36
  def self.sort_by(an_array, an_attribute=nil, &block)
32
37
  return sort_by_block(an_array, &block) if block_given?
33
- an_array.sort_by { |obj| normalize(obj.send(an_attribute)) }
38
+ an_array.sort_by { |obj| sort_key(obj.public_send(an_attribute)) }
34
39
  end
35
40
 
36
41
  # Convert the given number to an array of {Segment}s.
@@ -45,8 +50,17 @@ module Naturally
45
50
  # @return [Array<Segment>] an array of Segments which
46
51
  # can be sorted naturally via a standard #sort.
47
52
  def self.normalize(complex_number)
48
- tokens = complex_number.to_s.gsub(/\_/,'').scan(/\p{Word}+/)
49
- tokens.map { |t| Segment.new(t) }
53
+ tokens(complex_number).map { |t| Segment.new(t) }
54
+ end
55
+
56
+ # Natural sort for filenames, treating underscores and dots as separators.
57
+ # Dots are given higher priority by inserting a '0' segment, as in user workaround.
58
+ # See Issue #24.
59
+ def self.sort_filenames(array)
60
+ array.sort_by do |filename|
61
+ # Replace '.' with '.0.' to give dot higher priority, then split on dot or underscore
62
+ filename.to_s.gsub('.', '.0.').split(/[\._]/).map { |t| Segment.new(t) }
63
+ end
50
64
  end
51
65
 
52
66
  private
@@ -58,6 +72,17 @@ module Naturally
58
72
  # sort key for the yielded object
59
73
  # @return [Array<Object>] the objects in natural sort order.
60
74
  def self.sort_by_block(an_array, &block)
61
- an_array.sort_by { |obj| normalize(yield(obj)) }
75
+ an_array.sort_by { |obj| sort_key(yield(obj)) }
76
+ end
77
+
78
+ # The same ordering as {normalize}, as plain arrays built once per
79
+ # element instead of {Segment}s that rebuild them on every comparison.
80
+ def self.sort_key(complex_number)
81
+ tokens(complex_number).map! { |t| Segment.to_array(t) }
82
+ end
83
+
84
+ def self.tokens(complex_number)
85
+ complex_number.to_s.delete('_').scan(WORD)
62
86
  end
87
+ private_class_method :sort_key, :tokens
63
88
  end
@@ -208,4 +208,29 @@ describe Naturally do
208
208
  ]
209
209
  end
210
210
  end
211
+
212
+
213
+ describe '#sort_filenames' do
214
+ it 'sorts filenames with underscores and dots as separators' do
215
+ expect(Naturally.sort_filenames(['abc_2.tif', 'abc_1_a.tif'])).to eq(["abc_1_a.tif", "abc_2.tif"])
216
+ expect(Naturally.sort_filenames(['abc_1.zzz', 'abc_1_xyz.abc'])).to eq(["abc_1.zzz", "abc_1_xyz.abc"])
217
+ expect(Naturally.sort_filenames(['abc_2a.tif', 'abc_1_a.tif'])).to eq(["abc_1_a.tif", "abc_2a.tif"])
218
+ expect(Naturally.sort_filenames(['abc.2.tif', 'abc.1_a.tif'])).to eq(["abc.1_a.tif", "abc.2.tif"])
219
+ expect(Naturally.sort_filenames(['abc_2.tif', 'abc_1.tif'])).to eq(["abc_1.tif", "abc_2.tif"])
220
+ expect(Naturally.sort_filenames(['abc_2.tif', 'abc_15_a.tif'])).to eq(["abc_2.tif", "abc_15_a.tif"])
221
+ expect(Naturally.sort_filenames(['abc_2.abc', 'abc_1_xyz.abc'])).to eq(["abc_1_xyz.abc", "abc_2.abc"])
222
+ end
223
+
224
+ it 'sorts an array that fails under both Array#sort and Naturally#sort' do
225
+ complex_array = ["abc_2.tif", "abc_1_a.tif", "abc_10_a.tif"]
226
+ correctly_sorted = ["abc_1_a.tif", "abc_2.tif", "abc_10_a.tif"]
227
+
228
+ # Should pass.
229
+ expect(Naturally.sort_filenames(complex_array)).to eq(correctly_sorted)
230
+
231
+ # Should fail.
232
+ expect(Naturally.sort(complex_array)).not_to eq(correctly_sorted)
233
+ expect(complex_array.sort).not_to eq(correctly_sorted)
234
+ end
235
+ end
211
236
  end
metadata CHANGED
@@ -1,53 +1,56 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: naturally
3
3
  version: !ruby/object:Gem::Version
4
- version: 2.2.2
4
+ version: 2.4.0
5
5
  platform: ruby
6
6
  authors:
7
- - Robb Shecter
7
+ - Robb Shecter
8
8
  bindir: bin
9
9
  cert_chain: []
10
10
  date: 1980-01-02 00:00:00.000000000 Z
11
11
  dependencies: []
12
- description: Natural Sorting with support for legal numbering, course numbers, and
13
- other number/letter mixes.
12
+ description: "Natural Sorting with support for legal numbering, course numbers, and other number/letter mixes."
14
13
  email:
15
- - robb@public.law
14
+ - robb@public.law
16
15
  executables: []
17
16
  extensions: []
18
17
  extra_rdoc_files: []
19
18
  files:
20
- - ".gitignore"
21
- - ".travis.yml"
22
- - Gemfile
23
- - LICENSE.txt
24
- - README.md
25
- - Rakefile
26
- - lib/naturally.rb
27
- - lib/naturally/segment.rb
28
- - lib/naturally/version.rb
29
- - naturally.gemspec
30
- - spec/naturally_spec.rb
31
- homepage: http://github.com/public-law/naturally
19
+ - .github/workflows/ruby.yml
20
+ - .gitignore
21
+ - .travis.yml
22
+ - CHANGELOG.md
23
+ - Gemfile
24
+ - LICENSE.txt
25
+ - README.md
26
+ - Rakefile
27
+ - lib/naturally.rb
28
+ - lib/naturally/segment.rb
29
+ - lib/naturally/version.rb
30
+ - naturally.gemspec
31
+ - spec/naturally_spec.rb
32
+ homepage: "http://github.com/public-law/naturally"
32
33
  licenses:
33
- - MIT
34
+ - MIT
34
35
  metadata: {}
35
36
  rdoc_options: []
36
37
  require_paths:
37
- - lib
38
+ - lib
38
39
  required_ruby_version: !ruby/object:Gem::Requirement
39
40
  requirements:
40
- - - ">="
41
- - !ruby/object:Gem::Version
42
- version: '2.0'
41
+ -
42
+ - ">="
43
+ - !ruby/object:Gem::Version
44
+ version: "2.0"
43
45
  required_rubygems_version: !ruby/object:Gem::Requirement
44
46
  requirements:
45
- - - ">="
46
- - !ruby/object:Gem::Version
47
- version: '0'
47
+ -
48
+ - ">="
49
+ - !ruby/object:Gem::Version
50
+ version: "0"
48
51
  requirements: []
49
- rubygems_version: 3.6.9
52
+ rubygems_version: 4.1.0
50
53
  specification_version: 4
51
54
  summary: Sorts numbers according to the way people are used to seeing them.
52
55
  test_files:
53
- - spec/naturally_spec.rb
56
+ - spec/naturally_spec.rb