sort_by_str 0.5.0

data/.document

@@ -0,0 +1,5 @@
+README.rdoc
+lib/**/*.rb
+bin/*
+features/**/*.feature
+LICENSE

data/.gitignore

@@ -0,0 +1,5 @@
+*.sw?
+.DS_Store
+coverage
+rdoc
+pkg

data/LICENSE

@@ -0,0 +1,13 @@
+Copyright (c) 2010 The New York Times Company
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this library except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

data/README.rdoc

@@ -0,0 +1,35 @@
+= sort_by_str
+
+SQL-like sorts on your Enumerables.
+
+== Getting Started
+ 
+  gem install sort_by_str
+  require 'sort_by_str'
+
+== Usage
+
+  a = Date.parse('2010-08-22')
+  b = Date.parse('2010-08-23)
+  
+  [a,b].sort_by_str('year ASC, day DESC')
+  => [b,a]
+
+Call sort_by_str on your Enumerable with a SQL-style sort expression containing a list of fields.
+
+A basic expression might look like like
+  'year, month, day'.
+
+Optional ASC (ascending) or DESC (descending) modifiers can also be used:
+  'year ASC, day DESC'
+
+<tt>send</tt> is used to extract values for comparison, so any valid method name
+can be used in the expression.
+
+== Author
+
+Ben Koski, bkoski@nytimes.com
+
+== Copyright
+
+Copyright (c) 2010 The New York Times Company. See LICENSE for details.

data/Rakefile

@@ -0,0 +1,56 @@
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "sort_by_str"
+    gem.summary = %Q{SQL-like sorts on your Enumerables}
+    gem.description = %Q{SQL-like sorts on your Enumerables}
+    gem.email = "bkoski@nytimes.com"
+    gem.homepage = "http://github.com/nytimes/sort_by_str"
+    gem.authors = ["Ben Koski"]
+    gem.add_development_dependency "thoughtbot-shoulda"
+    # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
+  end
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: sudo gem install jeweler"
+end
+
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test'
+  test.pattern = 'test/**/*_test.rb'
+  test.verbose = true
+end
+
+begin
+  require 'rcov/rcovtask'
+  Rcov::RcovTask.new do |test|
+    test.libs << 'test'
+    test.pattern = 'test/**/*_test.rb'
+    test.verbose = true
+  end
+rescue LoadError
+  task :rcov do
+    abort "RCov is not available. In order to run rcov, you must: sudo gem install spicycode-rcov"
+  end
+end
+
+task :test => :check_dependencies
+
+task :default => :test
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  if File.exist?('VERSION')
+    version = File.read('VERSION')
+  else
+    version = ""
+  end
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "sort_by_str #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/VERSION

@@ -0,0 +1 @@
+0.5.0

data/lib/sort_by_str.rb

@@ -0,0 +1,64 @@
+module Enumerable
+
+  # Similar to sort_by, sort_by_str accepts a string containing a SQL-style sort expression.
+  #
+  # The simplest sort expression is a comma separated list of fields: <tt>'month,day,year'</tt>
+  #
+  # But can also include optional ASC (ascending) or DESC (descending) order modifiers.
+  # For example: <tt>'year DESC, month ASC, day ASC'</tt>
+  # If an order modifier is omitted for a field, an ASC sort is assumed.
+  #
+  # Field values are checked for comparision using a <tt>send</tt>, so any method name can be used.
+  def sort_by_str str
+    sort_parts = str.split(',').collect { |p| p.split(' ') }
+    
+    # double-check structure of parsed data
+    raise ArgumentError,  "'#{str}' doesn't appear correctly formatted." if sort_parts.empty?
+    sort_parts.each { |p| raise ArgumentError, "'#{str}' doesn't appear correctly formatted." if p.length > 2 }
+    
+    # split into list of fields and sort directions for those fields
+    fields          = sort_parts.collect { |p| p.first }
+    sort_directions = sort_parts.collect { |p| p.last.upcase == 'DESC' ? :desc : :asc }  # if unspecified assumed to be an ASC sort
+
+    # From here we follow pattern of Schwartzian Transform used in sort_by (http://bit.ly/aPEsNO).
+    # This means that rather than doing a sort! directly on self, we cache values to be sorted into an array.
+    # So for example, given:
+    #  a = Date.today
+    #  b = Date.today + 1
+    #  [a,b].sort_by_str('year ASC, day DESC')
+    #
+    # we transform to
+    #   [[a, 2010, 22],[b,2010,23]]
+    # and then proceed with sort.
+    # Following sort, we collect list of first elements to produce final, sorted array.
+    # This prevents sort attrs from being called multiple times during sort
+    # which could be problematic if sort attr is an expensive calcuation.
+
+    # 1. collect data into intermediate arrays, data element first
+    sort_data = collect do |element|
+      data = [element]
+      fields.each { |f| data << element.send(f) }
+      data
+    end
+
+    # 2. actually sort the data -- a,b are limited to a[1..-1] so as to exclude first [data] element
+    sort_data.sort! do |a,b|
+      cmp = 0
+      sort_directions.zip(a[1..-1], b[1..-1]) do |field_data|
+        direction, a_val, b_val = field_data
+        if direction == :desc
+          cmp = b_val <=> a_val
+        else
+          cmp = a_val <=> b_val
+        end
+        break if cmp != 0
+      end
+
+      cmp
+    end
+    
+    # 3. now that data is sorted, reduce back to list of data elements
+    sort_data.collect { |element| element.first }
+  end
+  
+end

data/test/test_helper.rb

@@ -0,0 +1,11 @@
+require 'rubygems'
+require 'test/unit'
+require 'shoulda'
+require 'ostruct'
+
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+$LOAD_PATH.unshift(File.dirname(__FILE__))
+require 'sort_by_str'
+
+class Test::Unit::TestCase
+end

data/test/test_sort_by_str.rb

@@ -0,0 +1,55 @@
+require 'test_helper'
+
+class SortByStrTest < Test::Unit::TestCase
+
+  context "with valid sort expression" do
+    
+    setup do
+      @red_10 = OpenStruct.new(:color => 'red', :size => 10)
+      @blue_10 = OpenStruct.new(:color => 'blue', :size => 10)
+      @red_15 = OpenStruct.new(:color => 'red', :size => 15)
+      
+      @all_data = [@red_10, @blue_10, @red_15]
+    end
+    
+    should "sort correctly on a single-field sort" do
+      assert_equal [@blue_10, @red_15], [@red_15, @blue_10].sort_by_str('size')
+    end
+    
+    should "sort correctly on a multi-field sort" do
+      assert_equal [@blue_10, @red_10, @red_15], @all_data.sort_by_str('size, color')
+    end
+    
+    should "respect DESC modifier" do
+      assert_equal [@red_15, @blue_10, @red_10], @all_data.sort_by_str('size DESC, color')
+    end
+    
+    should "respect ASC modifier" do
+      assert_equal [@blue_10, @red_10, @red_15], @all_data.sort_by_str('size ASC, color')
+    end
+    
+    should "sort correctly even if extra spaces are supplied" do
+      assert_equal [@blue_10, @red_10, @red_15], @all_data.sort_by_str('size  ASC ,  color ')
+    end
+    
+  end
+  
+  context "with invalid sort expression" do
+    setup do
+      @data = [OpenStruct.new(:size => 10), OpenStruct.new(:size => 15)]
+    end
+
+    should "raise an ArgumentError if too many tokens are supplied for a field" do
+      assert_raises(ArgumentError) { @data.sort('size ASC DESC')}
+    end
+    
+    should "raise an ArgumentError if no fields are supplied" do
+      assert_raises(ArgumentError) { @data.sort('') }
+    end
+    
+    should "raise an ArgumentError if no tokens are supplied for a field" do
+      assert_raises(ArgumentError) { @data.sort('size ASC, ,size DESC')}
+    end
+  end
+
+end

metadata

@@ -0,0 +1,73 @@
+--- !ruby/object:Gem::Specification 
+name: sort_by_str
+version: !ruby/object:Gem::Version 
+  version: 0.5.0
+platform: ruby
+authors: 
+- Ben Koski
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-08-24 00:00:00 -04:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: thoughtbot-shoulda
+  type: :development
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+    version: 
+description: SQL-like sorts on your Enumerables
+email: bkoski@nytimes.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- LICENSE
+- README.rdoc
+files: 
+- .document
+- .gitignore
+- LICENSE
+- README.rdoc
+- Rakefile
+- VERSION
+- lib/sort_by_str.rb
+- test/test_helper.rb
+has_rdoc: true
+homepage: http://github.com/nytimes/sort_by_str
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.5
+signing_key: 
+specification_version: 3
+summary: SQL-like sorts on your Enumerables
+test_files: 
+- test/test_helper.rb
+- test/test_sort_by_str.rb