summaryse 1.0.0 → 1.1.0

data/CHANGELOG.md

@@ -1,4 +1,50 @@
-# 1.0.0 / FIX ME
+# 1.1.0 / FIX ME
+
+  * Added a way to register user-defined aggregation functions:
+
+        Summaryse.register(:comma_join) do |ary|
+          ary.join(', ')
+        end
+        [1, 4, 12, 7].summaryse(:comma_join) 
+        # => "1, 4, 12, 7"
+
+  * Added the ability to specify aggregations on hash keys that are not used at
+    all. In this case, the aggregator is called on an empty array.
+
+        [
+          { :size => 12 },
+          { :size => 17 }
+        ].summaryse(:size => :max, :hobbies => lambda{|a| a})
+        # => {:size => 17, :hobbies => []}
+
+  * Added the ability to use objects responding to to_summaryse as aggregator
+    functions:
+
+        class Foo
+          def to_summaryse; :sum; end
+        end
+        [1, 2, 3].summaryse(Foo.new)
+        # => 6
+
+  * Added the ability to explicitly bypass Hash entries as the result of a 
+    computation, by returning Summaryse::BYPASS
+
+        [
+          { :hobbies => [:ruby],  :size => 12 },
+          { :hobbies => [:music], :size => 17 }
+        ].summaryse(:size => :max, :hobbies => lambda{|a| Summaryse::BYPASS})
+        # => {:size => 17}
+
+  * The semantics of aggregating empty arrays is guaranteed. Due to duck typing, 
+    nil is returned in almost all cases except :count so far. This is specified
+    in README.
+
+  * Best-effort for yielding friendly hash ordering under ruby >= 1.9
+  
+  * Array#summaryse now raises an ArgumentError when it does not understand its
+    aggregator argument.
+
+# 1.0.0 / 2011.07.11
 
 * Enhancements
 

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    summaryse (1.0.0)
+    summaryse (1.1.0)
 
 GEM
   remote: http://rubygems.org/

data/README.md

@@ -1,4 +1,4 @@
-# Array#summaryse
+# Array#summaryse (version 1.1.0)
 
     [sudo] gem install summaryse
 
@@ -24,9 +24,9 @@ used to merge YAML files. Simpler examples are given a bit later.
 In many projects of mine including 
 {https://github.com/blambeau/noe noe}, 
 {https://github.com/blambeau/agora agora} or 
-{https://github.com/blambeau/dbagile dbagile}, a common need is merge YAML files. 
-Merging YAML files is complex because you need full control of how merging applies 
-on specific tree nodes. Summaryse solves this very effectively.
+{https://github.com/blambeau/dbagile dbagile}, a common need is to merge YAML 
+files. Merging YAML files is difficult because you need full control of how 
+merging applies on specific tree nodes. Summaryse solves this very effectively.
 
     # This is left.yaml
     left = YAML.load ...      # syntactically wrong, but to avoid Yard's rewriting
@@ -142,18 +142,16 @@ behavior to use on others:
     ].summaryse(:hobbies => :union, nil => :first)
     # => {:hobbies => [:ruby, :music], :size => 12}
 
-### Specifying with lambdas
+### Unexisting keys
 
-When no default summarization function fit your needs, just pass a lambda. It 
-will be called with the array of values on which aggregation must be done:
+Specifying unexisting keys is also permitted. In this case, the evaluation is 
+done on an empty array:
 
     [
       { :hobbies => [:ruby],  :size => 12 },
       { :hobbies => [:music], :size => 17 }
-    ].summaryse(:hobbies => :union, :size => lambda{|a|
-      a.join(', ')
-    })
-    # => {:hobbies => [:ruby, :music], :size => "12, 17"}
+    ].summaryse(:hello => lambda{|a| a})
+    # => {:hello => []}
 
 ## On Arrays of Hash-es
 
@@ -177,18 +175,85 @@ returned hashes are in order of encountered 'by key' values. That is, in the
 example above, yard comes before summaryse that comes before treetop because 
 this is the order in which they have been seen initially.
 
-# By the way, why this stupid name?
+# Some extra goodness
 
-Just because summarize was already an {https://rubygems.org/gems/summarize existing gem}. 
-Summaryse is also much less likely to cause a name clash on the Array class. And
-I'm a french-speaking developer :-)
+## On empty arrays
 
-And where does 'summarize' come from? The name is inspired by (yet not equivalent 
-to) {http://en.wikipedia.org/wiki/D_(data_language_specification)#Tutorial_D 
-TUTORIAL D}'s summarization operator on relations. 
-See my {https://github.com/blambeau/alf alf} project. Array#summaryse is
-rubyiesque in mind and does not conform to a purely relational vision of 
-summarization, though.
+For now, no special support is provided for the corner cases. One could argue 
+that the sum of an empty array should be 0, but this is wrong because of duck
+typing (maybe you try to sum something else)... A nil value is returned in 
+almost all empty cases unless the semantics is very clear:
+
+    [].summaryse(:count)  # => 0
+    [].summaryse(:sum)    # => nil
+    [].summaryse(:avg)    # => nil
+
+    [].summaryse(:min)    # => nil
+    [].summaryse(:max)    # => nil
+    [].summaryse(:first)  # => nil
+    [].summaryse(:last)   # => nil
+
+    [].summaryse(:intersection)  # => nil
+    [].summaryse(:union)         # => nil
+
+Special support for specifying a default value to use on empty arrays should
+be provided around 2.0. Don't hesitate too contribute a patch if you need it 
+earlier.
+
+## Specifying with lambdas
+
+When no default summarization function fit your needs, just pass a lambda. It 
+will be called with the array of values on which aggregation must be done:
+
+    [
+      { :hobbies => [:ruby],  :size => 12 },
+      { :hobbies => [:music], :size => 17 }
+    ].summaryse(:hobbies => :union, :size => lambda{|a|
+      a.join(', ')
+    })
+    # => {:hobbies => [:ruby, :music], :size => "12, 17"}
+
+## Registering your own aggregators
+
+Since 1.1, you can register your own aggregation functions. Such function simply
+takes a single argument which is an array of values to aggregate. This is 
+especially useful to install new and/or override existing aggregation functions.
+This also allows handling parameters:
+
+    Summaryse.register(:comma_join) do |ary|
+      ary.join(', ')
+    end
+    [1, 4, 12, 7].summaryse(:comma_join) # => "1, 4, 12, 7"
+
+## Aggregator objects
+
+Sometimes it is useful to use your own objects as aggregators. For this, simply
+provide them a to_summaryse function that returns an aggregation function:
+
+    class Foo
+      def to_summaryse; :sum; end
+    end
+    [1, 2, 3].summaryse(Foo.new).should eq(6)
+
+Returned object is anything that can be seen as an aggregation function: a 
+Symbol, a Proc, a Hash, an Array, or even another such object:
+
+    class Bar
+      def to_summaryse; Foo.new; end
+    end
+    [1, 2, 3].summaryse(Bar.new).should eq(6)
+
+## Bypassing Hash entries
+
+It is sometimes useful to explicit bypass specific Hash entries as the result of 
+the computation. Entries for which the aggregator returns Summaryse::BYPASS will
+be simply removed from the result:
+
+    [
+      { :hobbies => [:ruby],  :size => 12 },
+      { :hobbies => [:music], :size => 17 }
+    ].summaryse(:size => :max, :hobbies => lambda{|a| Summaryse::BYPASS})
+    # => {:size => "17"}
 
 # Contribute, Versioning and so on.
 
@@ -197,8 +262,14 @@ As usual: the code is on {http://github.com/blambeau/summaryse github}, I follow
 implementation details, that is, the method name, its recognized arguments and 
 the semantics of the returned value), etc.
 
-Now, frankly, you can also copy/paste the source code of this simple array 
-extension in your own project. This tend to be much friendly and much simpler 
-than using a gem, IMHO. Reuse by copy-pasting even has a name:
-{http://revision-zero.org/reuse code scavenging}. 
- 
+## By the way, why this stupid name?
+
+Just because summarize was already an {https://rubygems.org/gems/summarize existing gem}. 
+Summaryse is also much less likely to cause a name clash on the Array class. And
+I'm a french-speaking developer :-)
+
+And where does 'summarize' come from? The name is inspired by (yet not equivalent 
+to) {http://en.wikipedia.org/wiki/D_(data_language_specification)#Tutorial_D TUTORIAL D}'s 
+summarization operator on relations. See my {https://github.com/blambeau/alf alf} 
+project. Array#summaryse is rubyiesque in mind and does not conform to a purely 
+relational vision of summarization, though.

data/lib/summaryse.rb

@@ -1,3 +1,48 @@
 require "summaryse/version"
 require "summaryse/loader"
+module Summaryse
+
+  # Bypass marker
+  BYPASS = Object.new
+
+  #
+  # Registers a aggregation function under a given name.
+  #
+  # The lambda function is converted as a Proc from the supplied block.
+  # It takes one array argument, on which the aggregation must be done
+  # and returned.
+  #
+  # @param [Symbol] name a aggregation function name
+  # @param [lambda] the function itself
+  # 
+  def self.register(name, &lambda)
+    @aggregators ||= {}
+    @aggregators[name] = lambda
+  end
+
+  #
+  # Returns an aggregator by name, nil if no such aggregator as been
+  # previously registered.
+  #
+  def self.aggregator(name)
+    @aggregators && @aggregators[name]
+  end
+
+  #
+  register(:count)       {|a| a.size                     }
+  register(:sum)         {|a| a.inject(:+)               }
+  register(:avg)         {|a| a.inject(:+)/a.size.to_f   }
+
+  # 
+  register(:first)       {|a| a.first                    }
+  register(:last)        {|a| a.last                     }
+  register(:min)         {|a| a.min                      }
+  register(:max)         {|a| a.max                      }
+
+  #
+  register(:intersection){|a| a.inject(:&)               }
+  register(:union)       {|a| a.inject(:|)               }
+
+end # module Summaryse
 require "summaryse/core_ext/array"
+

data/lib/summaryse/core_ext/array.rb

@@ -62,24 +62,22 @@ class Array
     case agg
     when Proc
       agg.call(self)
-    when :avg
-      inject(:+).to_f/size
-    when :count
-      size
-    when :intersection
-      inject(:&)
-    when :sum
-      inject(:+)
-    when :union
-      inject(:|)
     when Symbol
-      self.send(agg)
+      if fn = Summaryse.aggregator(agg)
+        fn.call(self)
+      elsif self.respond_to?(agg)
+        self.send(agg)
+      else
+        raise ArgumentError, "No such aggregation function #{agg}"
+      end
     when Hash
       big = Hash.new{|h,k| h[k] = []}
+      agg.each_key{|k| big[k] = [] unless k.nil?}
       each{|t| t.each_pair{|k,v| big[k] << v}}
       Hash[big.collect{|k,v|
         if summ = (agg[k] || agg[nil])
-          [k,v.summaryse(summ)]
+          res = v.summaryse(summ)
+          res == Summaryse::BYPASS ? nil : [k, res]
         end
       }.compact]
     when Array
@@ -91,8 +89,14 @@ class Array
         keys << key
         grouped[key] << t
       }
-      agg = agg.merge(Hash[by.collect{|k| [k, :first]}])
+      agg = Hash[by.collect{|k| [k, :first]}].merge(agg)
       keys.uniq.collect{|key| grouped[key].summaryse(agg)}
+    else
+      if agg.respond_to?(:to_summaryse)
+        summaryse(agg.to_summaryse)
+      else
+        raise ArgumentError, "Unable to convert #{agg} to an aggregation function"
+      end
     end
   end
 

data/lib/summaryse/version.rb

@@ -2,7 +2,7 @@ module Summaryse
   module Version
   
     MAJOR = 1
-    MINOR = 0
+    MINOR = 1
     TINY  = 0
   
     def self.to_s

data/spec/readme_spec.rb

@@ -58,6 +58,11 @@ describe "README file" do
       a.join(', ')
     }).should eq(:hobbies => [:ruby, :music], :size => "12, 17")
 
+    [
+      { :hobbies => [:ruby],  :size => 12 },
+      { :hobbies => [:music], :size => 17 }
+    ].summaryse(:hello => lambda{|a| a}).should eq(:hello => [])
+
     [ 
       { :hobbies => {:day => [:ruby], :night => [:ruby] } },
       { :hobbies => {:day => [],      :night => [:sleep]} }
@@ -109,4 +114,33 @@ describe "README file" do
     [ left, right ].summaryse(merge).should eq(exp)
   end
 
+  describe "Extra goodness" do
+
+    specify "On empty arrays" do
+      [].summaryse(:count).should eq(0)
+      [].summaryse(:first).should be_nil
+      [].summaryse(:intersection).should be_nil
+      [].summaryse(:last).should be_nil
+      [].summaryse(:min).should be_nil
+      [].summaryse(:sum).should be_nil
+      [].summaryse(:union).should be_nil
+    end
+
+    specify "Installing your own aggregators" do
+      Summaryse.register(:comma_join) do |ary|
+       ary.join(', ')
+      end
+      [1, 4, 12, 7].summaryse(:comma_join).should eq("1, 4, 12, 7")
+    end
+
+    specify "bypassing entries" do
+      agg = {:size => :max, :hobbies => lambda{|a| Summaryse::BYPASS}}
+      [
+        { :hobbies => [:ruby],  :size => 12 },
+        { :hobbies => [:music], :size => 17 }
+      ].summaryse(agg).should eq({:size => 17})
+    end
+
+  end
+
 end

data/spec/summaryse_spec.rb

@@ -46,18 +46,27 @@ describe Summaryse do
     end
 
     it "should recognize max" do
+      [].summaryse(:max).should be_nil
       numbers.summaryse(:max).should eq(17)
     end
 
     it "should recognize sum" do
       numbers.summaryse(:sum).should eq(15 + 3 + 17 + 4 + 12)
-      arrays.summaryse(:sum).should eq([ 15, 3, 12, 17, 4, 12])
+      arrays.summaryse(:sum).should eq([15, 3, 12, 17, 4, 12])
     end
 
     it "should recognize union" do
       arrays.summaryse(:union).should eq([15, 3, 12, 17, 4])
     end
 
+    it "should delegate to existing method otherwise" do
+      [1, 2, 2].summaryse(:uniq).should == [1, 2]
+    end
+
+    it "should raise when not found" do
+      lambda{ [1, 2, 2].summaryse(:no_such_one) }.should raise_error(ArgumentError)
+    end
+
   end # Symbol argument
 
   describe "when called with a Hash argument" do
@@ -87,6 +96,16 @@ describe Summaryse do
       rel.summaryse(control).should eq(:size => "hello")
     end
 
+    it "should allow specifying unexisting keys" do
+      control = {:no_such => lambda{|a| a}}
+      rel.summaryse(control).should eq(:no_such => [])
+    end
+
+    it "should allow specifying bypassed keys" do
+      control = {:size => :max, :hobbies => lambda{|a| Summaryse::BYPASS}}
+      rel.summaryse(control).should eq(:size => 12)
+    end
+
   end # Hash argument
 
   describe "when called with an Array argument" do
@@ -105,7 +124,30 @@ describe Summaryse do
         {:version => "2.0", :size => 99}
       ])
     end
+  end
+
+  describe "when called with a to_summarysable argument" do
+
+    it "should summarize as defined by the method" do
+      class Foo
+        def to_summaryse; :sum; end
+      end
+      [1, 2, 3].summaryse(Foo.new).should eq(6)
+
+      class Bar
+        def to_summaryse; Foo.new; end
+      end
+      [1, 2, 3].summaryse(Bar.new).should eq(6)
+    end
 
   end
+
+  describe "when called with something unconvertible" do
   
+    specify do
+      lambda{ [1,2,3].summaryse(Object.new).should raise_error(ArgumentError) }
+    end
+
+  end
+
 end

data/summaryse.gemspec

@@ -27,7 +27,7 @@ Gem::Specification.new do |s|
   #
   # The description should be more detailed than the summary.  For example,
   # you might wish to copy the entire README into the description.
-  s.description = "summaryse arrays with full power. Among others, this gem allows merging YAML\nconfiguration files,... "
+  s.description = "Summarize arrays with full power. As a side effect, this gem allows merging \nmultiple YAML configuration files with power, without sacrifying simplicity... "
   
   # The URL of this gem home page (optional)
   s.homepage = "http://github.com/blambeau/summaryse"

data/summaryse.noespec

@@ -7,18 +7,19 @@ variables:
   lower: 
     summaryse
   upper:
-    summaryse
+    Summaryse
   version:
-    1.0.0
+    1.1.0
   summary: |-
     Array#summaryse
   description: |-
-    summaryse arrays with full power. Among others, this gem allows merging YAML
-    configuration files,... 
+    Summarize arrays with full power. As a side effect, this gem allows merging 
+    multiple YAML configuration files with power, without sacrifying simplicity... 
   authors: 
     - { name: "Bernard Lambeau", email: blambeau@gmail.com }
   links:
     - http://github.com/blambeau/summaryse
+    - http://rubydoc.info/github/blambeau/summaryse/master/frames
   dependencies: 
     - {name: rake,      version: "~> 0.9.2", groups: [development]}
     - {name: bundler,   version: "~> 1.0",   groups: [development]}

metadata

@@ -1,95 +1,130 @@
---- !ruby/object:Gem::Specification
+--- !ruby/object:Gem::Specification 
 name: summaryse
-version: !ruby/object:Gem::Version
-  version: 1.0.0
+version: !ruby/object:Gem::Version 
+  hash: 19
   prerelease: 
+  segments: 
+  - 1
+  - 1
+  - 0
+  version: 1.1.0
 platform: ruby
-authors:
+authors: 
 - Bernard Lambeau
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2011-07-11 00:00:00.000000000Z
-dependencies:
-- !ruby/object:Gem::Dependency
-  name: rake
-  requirement: &74647200 !ruby/object:Gem::Requirement
+
+date: 2011-07-12 00:00:00 Z
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  version_requirements: &id001 !ruby/object:Gem::Requirement 
     none: false
-    requirements:
+    requirements: 
     - - ~>
-      - !ruby/object:Gem::Version
+      - !ruby/object:Gem::Version 
+        hash: 63
+        segments: 
+        - 0
+        - 9
+        - 2
         version: 0.9.2
   type: :development
+  requirement: *id001
   prerelease: false
-  version_requirements: *74647200
-- !ruby/object:Gem::Dependency
-  name: bundler
-  requirement: &74646950 !ruby/object:Gem::Requirement
+  name: rake
+- !ruby/object:Gem::Dependency 
+  version_requirements: &id002 !ruby/object:Gem::Requirement 
     none: false
-    requirements:
+    requirements: 
     - - ~>
-      - !ruby/object:Gem::Version
-        version: '1.0'
+      - !ruby/object:Gem::Version 
+        hash: 15
+        segments: 
+        - 1
+        - 0
+        version: "1.0"
   type: :development
+  requirement: *id002
   prerelease: false
-  version_requirements: *74646950
-- !ruby/object:Gem::Dependency
-  name: rspec
-  requirement: &74646720 !ruby/object:Gem::Requirement
+  name: bundler
+- !ruby/object:Gem::Dependency 
+  version_requirements: &id003 !ruby/object:Gem::Requirement 
     none: false
-    requirements:
+    requirements: 
     - - ~>
-      - !ruby/object:Gem::Version
+      - !ruby/object:Gem::Version 
+        hash: 31
+        segments: 
+        - 2
+        - 4
+        - 0
         version: 2.4.0
   type: :development
+  requirement: *id003
   prerelease: false
-  version_requirements: *74646720
-- !ruby/object:Gem::Dependency
-  name: yard
-  requirement: &74646490 !ruby/object:Gem::Requirement
+  name: rspec
+- !ruby/object:Gem::Dependency 
+  version_requirements: &id004 !ruby/object:Gem::Requirement 
     none: false
-    requirements:
+    requirements: 
     - - ~>
-      - !ruby/object:Gem::Version
+      - !ruby/object:Gem::Version 
+        hash: 7
+        segments: 
+        - 0
+        - 7
+        - 2
         version: 0.7.2
   type: :development
+  requirement: *id004
   prerelease: false
-  version_requirements: *74646490
-- !ruby/object:Gem::Dependency
-  name: bluecloth
-  requirement: &74646260 !ruby/object:Gem::Requirement
+  name: yard
+- !ruby/object:Gem::Dependency 
+  version_requirements: &id005 !ruby/object:Gem::Requirement 
     none: false
-    requirements:
+    requirements: 
     - - ~>
-      - !ruby/object:Gem::Version
+      - !ruby/object:Gem::Version 
+        hash: 29
+        segments: 
+        - 2
+        - 0
+        - 9
         version: 2.0.9
   type: :development
+  requirement: *id005
   prerelease: false
-  version_requirements: *74646260
-- !ruby/object:Gem::Dependency
-  name: wlang
-  requirement: &74646030 !ruby/object:Gem::Requirement
+  name: bluecloth
+- !ruby/object:Gem::Dependency 
+  version_requirements: &id006 !ruby/object:Gem::Requirement 
     none: false
-    requirements:
+    requirements: 
     - - ~>
-      - !ruby/object:Gem::Version
+      - !ruby/object:Gem::Version 
+        hash: 53
+        segments: 
+        - 0
+        - 10
+        - 1
         version: 0.10.1
   type: :development
+  requirement: *id006
   prerelease: false
-  version_requirements: *74646030
-description: ! 'summaryse arrays with full power. Among others, this gem allows merging
-  YAML
-
-  configuration files,... '
-email:
+  name: wlang
+description: "Summarize arrays with full power. As a side effect, this gem allows merging \n\
+  multiple YAML configuration files with power, without sacrifying simplicity... "
+email: 
 - blambeau@gmail.com
 executables: []
+
 extensions: []
-extra_rdoc_files:
+
+extra_rdoc_files: 
 - README.md
 - CHANGELOG.md
 - LICENCE.md
-files:
+files: 
 - summaryse.gemspec
 - summaryse.noespec
 - CHANGELOG.md
@@ -115,35 +150,38 @@ files:
 - tasks/debug_mail.txt
 homepage: http://github.com/blambeau/summaryse
 licenses: []
+
 post_install_message: 
 rdoc_options: []
-require_paths:
+
+require_paths: 
 - lib
-required_ruby_version: !ruby/object:Gem::Requirement
+required_ruby_version: !ruby/object:Gem::Requirement 
   none: false
-  requirements:
-  - - ! '>='
-    - !ruby/object:Gem::Version
-      version: '0'
-      segments:
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
       - 0
-      hash: 872999347
-required_rubygems_version: !ruby/object:Gem::Requirement
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
   none: false
-  requirements:
-  - - ! '>='
-    - !ruby/object:Gem::Version
-      version: '0'
-      segments:
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
       - 0
-      hash: 872999347
+      version: "0"
 requirements: []
+
 rubyforge_project: 
 rubygems_version: 1.8.5
 signing_key: 
 specification_version: 3
 summary: Array#summaryse
-test_files:
+test_files: 
 - spec/spec_helper.rb
 - spec/readme_spec.rb
 - spec/summaryse_spec.rb