sorting 0.0.1 → 0.0.2

data/README.markdown

@@ -27,6 +27,14 @@ Sort a list of Person objects
       [Sorting.asc(person.first_name), Sorting.asc(person.last_name), Sorting.desc(person.age)]
     }
 
+    # Care about expensive comparison values which may not always be needed
+    # assume item.expensive_value takes a lot of time to compute, but since it's the second value,
+    # it might only be needed in a small number of cases.
+    require 'sorting/convenience'
+    items.sort_by { |item|
+      [asc(item.cheap_value), asc(:nils_last) { item.expensive_value }]
+    }
+
     # Care about nil values in your data
     require 'sorting/convenience'
     people.sort_by { |person|
@@ -36,14 +44,6 @@ Sort a list of Person objects
     # Only care about nil values in your data
     [5,3,nil,9].sort_by { |x| x || Sorting::Bigger } # Sorting::Smaller is available too
 
-    # Care about expensive comparison values which may not always be needed
-    # assume item.expensive_value takes a lot of time to compute, but since it's the second value,
-    # it might only be needed in a small number of cases.
-    require 'sorting/convenience'
-    items.sort_by { |item|
-      [asc(item.cheap_value), asc(:nils_last) { item.expensive_value }]
-    }
-
 Take a look at {file:documentation/examples.rb} for more examples.
 
 

data/documentation/examples.rb

@@ -0,0 +1,38 @@
+# encoding: utf-8
+
+begin
+  require 'sorting/convenience'
+rescue LoadError
+  $LOAD_PATH << (p File.expand_path('../../lib', __FILE__))
+  require 'sorting/convenience'
+  puts "Sorting gem is not installed, using relative lib"
+end
+
+
+require 'pp'
+Person = Struct.new(:first_name, :last_name, :age)
+people = [
+  Person.new('Peter', 'Pan', 15),
+  Person.new('Peter', 'Parker', 15),
+  Person.new('Peter', 'Pan', 23),
+]
+pp people.sort_by { |person| [asc(person.first_name), asc(person.last_name), desc(person.age)] }
+
+
+Foo  = Struct.new(:a, :b, :c)
+calc = proc { |s,x| sleep(s); x }
+foos = [
+  Foo.new(1,2,1),
+  Foo.new(1,2,2),
+  Foo.new(1,3,4),
+  Foo.new(2,3,4),
+]
+start = Time.now
+pp foos.sort_by { |x| [asc(x.a), desc(calc[0.1, x.b]), asc(calc[0.2, x.c])] }
+stop = Time.now
+printf "Elapsed: %.2fs\n", stop-start
+
+start = Time.now
+pp foos.sort_by { |x| [asc(x.a), desc { calc[0.1, x.b] }, asc { calc[0.2, x.c] }] }
+stop = Time.now
+printf "Elapsed: %.2fs\n", stop-start

data/lib/sorting.rb

@@ -14,6 +14,9 @@ require 'sorting/version'
 # Sorting
 # Helpful functionality for sorting and comparing.
 #
+# Requiring 'sorting' loads all functionality this gem provides, except for the
+# patches on Kernel. For those you must `require 'sorting/convenience'`.
+#
 # @example Convenient
 #     require 'sorting/convenience'
 #     people.sort_by { |person| [asc(person.first_name), asc(person.last_name), desc(person.age)] }
@@ -24,6 +27,14 @@ require 'sorting/version'
 #       [Sorting.asc(person.first_name), Sorting.asc(person.last_name), Sorting.desc(person.age)]
 #     }
 #
+# @example Care about expensive comparison values which may not always be needed
+#     # assume item.expensive_value takes a lot of time to compute, but since it's the second value,
+#     # it might only be needed in a small number of cases.
+#     require 'sorting/convenience'
+#     items.sort_by { |item|
+#       [asc(item.cheap_value), asc(:nils_last) { item.expensive_value }]
+#     }
+#
 # @example Care about nil values in your data
 #     require 'sorting/convenience'
 #     people.sort_by { |person|
@@ -33,15 +44,22 @@ require 'sorting/version'
 # @example Only care about nil values in your data
 #     [5,3,nil,9].sort_by { |x| x || Sorting::Bigger } # Sorting::Smaller is available too
 #
-# @example Care about expensive comparison values which may not always be needed
-#     # assume item.expensive_value takes a lot of time to compute, but since it's the second value,
-#     # it might only be needed in a small number of cases.
-#     require 'sorting/convenience'
-#     items.sort_by { |item|
-#       [asc(item.cheap_value), asc(:nils_last) { item.expensive_value }]
-#     }
-#
 module Sorting
-  class_eval(&Sorting::Helpers::MethodDefinitions)
-  module_function *Sorting::Helpers.private_instance_methods(false)
+  Sorting::Helpers.append_to(self) # can't use include, see Sorting::Helpers.append_to
+
+  # @!method asc(*args, &lazy)
+  #   @!scope class
+  #   @see Sorting::Helpers.asc
+  #
+  #   @note
+  #     This method is a module function, and as such also available as a
+  #     private instance method.
+
+  # @!method desc(*args, &lazy)
+  #   @!scope class
+  #   @see Sorting::Helpers.desc
+  #
+  #   @note
+  #     This method is a module function, and as such also available as a
+  #     private instance method.
 end

data/lib/sorting/ascending.rb

@@ -14,12 +14,16 @@ module Sorting
   #   Sorting::Helpers is a module which provides you with a convenient .asc
   #   forwarding method
   #
-  # @see Sorting#asc
-  #   Sorting#asc is the common way to create a Sorting::Ascending instance
+  # @see Sorting.asc
+  #   Sorting.asc is the common way to create a Sorting::Ascending instance,
+  #   or if you required 'sorting/convenience', then plain asc via Kernel#asc
   #
   # @see Sorting::Descending
   #   Sorting::Descending is the opposite of Sorting::Ascending
   #
+  # @note
+  #   require 'sorting' loads this class
+  #
   class Ascending
 
     # Valid values for the treat_nils parameter of Sorting::Ascending#initialize

data/lib/sorting/bigger.rb

@@ -12,6 +12,9 @@ module Sorting
   #
   # @see Sorting::Smaller
   #
+  # @note
+  #   require 'sorting' loads this module
+  #
   module Bigger
     extend Comparable
 
@@ -50,6 +53,8 @@ module Sorting
     #   (SR) Figure out why this ended up here. I (SR) think it was due to
     #   some comparison failing without it, but I don't remember which.
     #   The specific case should be documented.
+    #   It is not due to "somestring" <=> Sorting::Bigger, that inverts
+    #   the expression to Sorting::Bigger <=> "somestring"
     #
     def self.to_str
       self

data/lib/sorting/convenience.rb

@@ -11,8 +11,29 @@ require 'sorting'
 
 
 
-# @private
+# The 'sorting/convenience' file patches the Kernel module and adds global
+# `asc()` and `desc()` methods, which work like {Sorting::Helpers.asc} and
+# {Sorting::Helpers.desc}
+#
+# @note
+#   you have to require 'sorting/convenience' to load this
+#
 module Kernel
-  class_eval(&Sorting::Helpers::MethodDefinitions)
-  module_function *Sorting::Helpers.private_instance_methods(false)
+  Sorting::Helpers.append_to(self) # can't use include, see Sorting::Helpers.append_to
+
+  # @!method asc(*args, &lazy)
+  #   @!scope class
+  #   @see Sorting::Helpers.asc
+  #
+  #   @note
+  #     This method is a module function, and as such also available as a
+  #     private instance method.
+
+  # @!method desc(*args, &lazy)
+  #   @!scope class
+  #   @see Sorting::Helpers.desc
+  #
+  #   @note
+  #     This method is a module function, and as such also available as a
+  #     private instance method.
 end

data/lib/sorting/descending.rb

@@ -18,11 +18,15 @@ module Sorting
   #   Sorting::Helpers is a module which provides you with a convenient .desc
   #   forwarding method
   #
-  # @see Sorting#desc
-  #   Sorting#desc is the common way to create a Sorting::Ascending instance
+  # @see Sorting.desc
+  #   Sorting.desc is the common way to create a Sorting::Descending instance,
+  #   or if you required 'sorting/convenience', then plain asc via Kernel#desc
   #
-  # @see Sorting::Descending
-  #   Sorting::Descending is the opposite of Sorting::Ascending
+  # @see Sorting::Ascending
+  #   Sorting::Ascending is the opposite of Sorting::Descending
+  #
+  # @note
+  #   require 'sorting' loads this class
   #
   class Descending < Ascending
 

data/lib/sorting/helpers.rb

@@ -11,13 +11,17 @@ module Sorting
 
   # This module provides convenience methods to create Sorting::Ascending and
   # Sorting::Descending instances.
+  #
+  # Important: see {Sorting::Helpers.append_to} for how to properly use this
+  # module with other modules
+  #
+  # @note
+  #   require 'sorting' loads this module
+  #
   module Helpers
 
     # The proc with the method definitions of asc and desc.
-    # They are in a proc so the proc can be class_eval'ed in Sorting and Kernel
-    # to avoid an issue with methods of modules which are included in another
-    # module not being properly shared
-    #
+    # See {Sorting::Helpers.append_to} for an explanation.
     MethodDefinitions = proc {
 
       # Convenience method to create a Sorting::Ascending instance.
@@ -25,16 +29,53 @@ module Sorting
       def asc(*args, &lazy)
         Sorting::Ascending.new(*args, &lazy)
       end
-      private :asc
+      module_function :asc
 
       # Convenience method to create a Sorting::Descending instance.
-      # Works exactly the same as {Sorting::Ascending#initialize Descending#initialize}
+      # Works exactly the same as {Sorting::Descending#initialize Ascending#initialize}
       def desc(*args, &lazy)
         Sorting::Descending.new(*args, &lazy)
       end
-      private :desc
+      module_function :desc
     }
 
-    class_eval(&MethodDefinitions)
+    # Adds the Sorting::Helpers methods 'asc' and 'desc' to the given module.
+    # This method class_eval because modules included into modules don't
+    # properly share methods
+    #
+    # @param [Module] mod
+    #   The class or module on which to append the Sorting::Helpers methods
+    #
+    # @note
+    #   The methods are stored in the {Sorting::Helpers::MethodDefinitions}
+    #   proc. That proc is class_eval'ed in in the module given by the `mod`
+    #   parameter.
+    #   It is done that way to avoid an issue with methods of modules which are
+    #   included in another module not being properly shared
+    #
+    def self.append_to(mod)
+      mod.class_eval(&MethodDefinitions)
+    end
+
+    append_to(self)
+
+    # @!method asc(*args, &lazy)
+    #   @!scope class
+    #   Convenience method to create a Sorting::Ascending instance.
+    #   Works exactly the same as {Sorting::Ascending#initialize}.
+    #
+    #   @note
+    #     This method is a module function, and as such also available as a
+    #     private instance method.
+
+    # @!method desc(*args, &lazy)
+    #   @!scope class
+    #   Convenience method to create a Sorting::Descending instance.
+    #   Works exactly the same as {Sorting::Ascending#initialize
+    #   Descending#initialize}.
+    #
+    #   @note
+    #     This method is a module function, and as such also available as a
+    #     private instance method.
   end
 end

data/lib/sorting/smaller.rb

@@ -12,6 +12,9 @@ module Sorting
   #
   # @see Sorting::Bigger
   #
+  # @note
+  #   require 'sorting' loads this module
+  #
   module Smaller
     extend Comparable
 
@@ -43,6 +46,8 @@ module Sorting
     #   (SR) Figure out why this ended up here. I (SR) think it was due to
     #   some comparison failing without it, but I don't remember which.
     #   The specific case should be documented.
+    #   It is not due to "somestring" <=> Sorting::Smaller, that inverts
+    #   the expression to Sorting::Smaller <=> "somestring"
     #
     def self.to_str
       self

data/lib/sorting/version.rb

@@ -9,5 +9,8 @@ end
 module Sorting
 
   # The version of the sorting gem.
-  Version = Gem::Version.new("0.0.1")
+  # @note
+  #   require 'sorting' loads this module
+  #
+  Version = Gem::Version.new("0.0.2")
 end

data/sorting.gemspec

@@ -2,7 +2,7 @@
 
 Gem::Specification.new do |s|
   s.name                      = "sorting"
-  s.version                   = "0.0.1"
+  s.version                   = "0.0.2"
   s.authors                   = "Stefan Rusterholz"
   s.email                     = "stefan.rusterholz@gmail.com"
   s.homepage                  = "https://github.com/apeiros/sorting"
@@ -16,6 +16,7 @@ Gem::Specification.new do |s|
 
   s.files                     =
     Dir['bin/**/*'] +
+    Dir['documentation/**/*'] +
     Dir['lib/**/*'] +
     Dir['rake/**/*'] +
     Dir['test/**/*'] +
@@ -26,10 +27,9 @@ Gem::Specification.new do |s|
       Rakefile
       README.markdown
     ]
-  s.require_paths             = %w[lib]
+
   if File.directory?('bin') then
-    executables = Dir.chdir('bin') { Dir.glob('**/*').select { |f| File.executable?(f) } }
-    s.executables = executables unless executables.empty?
+    s.executables = Dir.chdir('bin') { Dir.glob('**/*').select { |f| File.executable?(f) } }
   end
 
   s.required_ruby_version     = ">= 1.9.2"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sorting
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-02-22 00:00:00.000000000 Z
+date: 2013-02-23 00:00:00.000000000 Z
 dependencies: []
 description: Helpful functionality for sorting and comparing.
 email: stefan.rusterholz@gmail.com
@@ -17,6 +17,7 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- documentation/examples.rb
 - lib/sorting/ascending.rb
 - lib/sorting/bigger.rb
 - lib/sorting/convenience.rb