summaryse 1.0.0

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+# 1.0.0 / FIX ME
+
+* Enhancements
+
+  * Birthday!

data/Gemfile

@@ -0,0 +1,2 @@
+source 'http://rubygems.org'
+gemspec :name => "summaryse"

data/Gemfile.lock

@@ -0,0 +1,34 @@
+PATH
+  remote: .
+  specs:
+    summaryse (1.0.0)
+
+GEM
+  remote: http://rubygems.org/
+  specs:
+    bluecloth (2.0.11)
+    diff-lcs (1.1.2)
+    rake (0.9.2)
+    rspec (2.4.0)
+      rspec-core (~> 2.4.0)
+      rspec-expectations (~> 2.4.0)
+      rspec-mocks (~> 2.4.0)
+    rspec-core (2.4.0)
+    rspec-expectations (2.4.0)
+      diff-lcs (~> 1.1.2)
+    rspec-mocks (2.4.0)
+    wlang (0.10.2)
+    yard (0.7.2)
+
+PLATFORMS
+  java
+  ruby
+
+DEPENDENCIES
+  bluecloth (~> 2.0.9)
+  bundler (~> 1.0)
+  rake (~> 0.9.2)
+  rspec (~> 2.4.0)
+  summaryse!
+  wlang (~> 0.10.1)
+  yard (~> 0.7.2)

data/LICENCE.md

@@ -0,0 +1,22 @@
+# The MIT Licence
+
+    Copyright (c) 2011 - Bernard Lambeau
+
+    Permission is hereby granted, free of charge, to any person obtaining
+    a copy of this software and associated documentation files (the
+    "Software"), to deal in the Software without restriction, including
+    without limitation the rights to use, copy, modify, merge, publish,
+    distribute, sublicense, and/or sell copies of the Software, and to
+    permit persons to whom the Software is furnished to do so, subject to
+    the following conditions:
+
+    The above copyright notice and this permission notice shall be
+    included in all copies or substantial portions of the Software.
+
+    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+    EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+    MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+    NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+    LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+    OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+    WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/Manifest.txt

@@ -0,0 +1,14 @@
+summaryse.gemspec
+summaryse.noespec
+CHANGELOG.md
+Gemfile
+Gemfile.lock
+bin/**/*
+examples/**/*
+lib/**/*
+LICENCE.md
+Manifest.txt
+Rakefile
+README.md
+spec/**/*
+tasks/**/*

data/README.md

@@ -0,0 +1,204 @@
+# Array#summaryse
+
+    [sudo] gem install summaryse
+
+## Links
+
+* {http://rubydoc.info/github/blambeau/summaryse/master/frames} (read this file there!)
+* {http://github.com/blambeau/summaryse} (source code)
+
+## Summaryse's summary
+
+Summaryse provides a core extension, namely Array#summaryse. Oh, sorry, I must 
+add: "OMG, a core extension :-/ If you are aware of any compatibility issue, 
+let me know!". 
+
+So, what is Array#summaryse? Roughly, a way to computate aggregations. This goes
+from simple aggregations on simple values (summing integers), to complex aggregations 
+on complex values (merging arrays of hashes that contain hashes and array of 
+hashes that...). Below is a typical use case showing how Array#summaryse can be
+used to merge YAML files. Simpler examples are given a bit later.
+
+## An opinionated use-case -- YAML merging
+
+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.
+
+    # This is left.yaml
+    left = YAML.load ...      # syntactically wrong, but to avoid Yard's rewriting
+      hobbies:
+        - ruby
+        - rails
+      dependencies:
+        - {name: rspec, version: '2.6.4', for: [ runtime ]}
+    ...
+
+    # This is right.yaml
+    right = YAML.load ...
+      hobbies:
+        - ruby
+        - music
+      dependencies:
+        - {name: rails, version: '3.0',   for: [ runtime ]}
+        - {name: rspec, version: '2.6.4', for: [ test    ]}
+    ...
+
+    # This is merge.yaml
+    merge = YAML.load ...
+      hobbies:                # on hobbies, we simply make a set-based union
+        :union
+      dependencies:           # on dependencies, we apply recursively
+        - [name, version]     #   - 'aggregate by name and version'
+        - for: :union         #   - compute the union of 'for' usage
+    ...
+    
+    # Merge and re-dump
+    [ left, right ].summaryse(merge).to_yaml
+    
+    # This is the (pretty-printed) result 
+    hobbies:
+      - ruby
+      - rails
+      - music
+    dependencies:
+      - {name: rspec, version: '2.6.4', for: [ runtime, test ]}
+      - {name: rails, version: '3.0',   for: [ runtime       ]}
+
+This is a very opinionated, yet already complex, case-study. Let me go back to 
+a more general explanation now.
+
+## On simple values (integers, floats, ...)
+
+Summarizing an array of simple values yields -> a simple value... Below are some
+examples on integers. We are in ruby, so duck-typing applies everywhere. 
+
+### Arithmetics & Algebra
+
+    # :count, same as #size
+    [1, 4, 12, 7].summaryse(:count) # => 4
+
+    # :sum, same as #inject(:+)
+    [1, 4, 12, 7].summaryse(:sum)   # => 24
+
+    # :avg, same as #inject(:+)/size
+    [1, 4, 12, 7].summaryse(:avg)   # => 6.0
+
+### Array theory
+
+    # :min, same as #min
+    [1, 4, 12, 7].summaryse(:min)   # => 1
+
+    # :max, same as #max
+    [1, 4, 12, 7].summaryse(:max)   # => 12
+
+    # :first, same as #first
+    [1, 4, 12, 7].summaryse(:first) # => 1
+
+    # :last, same as #last
+    [1, 4, 12, 7].summaryse(:last)  # => 7
+
+### Set theory
+
+    # :union, same as #inject(:|)
+    [ [1, 4], [12, 1, 7], [1] ].summaryse(:union)        # => [1, 4, 12, 7]
+
+    # :intersection, same as #inject(:&)
+    [ [1, 4], [12, 1, 7], [1] ].summaryse(:intersection) # => [1]
+
+## On Hash-es
+
+Summarizing an Array of Hash-es yields -> a Hash.
+
+Previous section provided the base cases. You can use them on elements of hashes
+by passing a ... Hash of course:
+
+    [
+      { :hobbies => [:ruby],  :size => 12 },
+      { :hobbies => [:music], :size => 17 }
+    ].summaryse(:hobbies => :union, :size => :max)   
+    # => {:hobbies => [:ruby, :music], :size => 17}
+
+And it works recursively, of course:
+
+    [ 
+      { :hobbies => {:day => [:ruby], :night => [:ruby] } },
+      { :hobbies => {:day => [],      :night => [:sleep]} }
+    ].summaryse(:hobbies => {:day => :union, :night => :union})
+    # => {:hobbies => {:day => [:ruby], :night => [:ruby, :sleep]}}
+
+### Specifying default behavior
+
+By default, the returned hash only contains elements for which you have provided
+a summarization heuristic. However, you can use a nil key to specify the default
+behavior to use on others:
+
+    [
+      { :hobbies => [:ruby],  :size => 12 },
+      { :hobbies => [:music], :size => 17 }
+    ].summaryse(:hobbies => :union, nil => :first)
+    # => {:hobbies => [:ruby, :music], :size => 12}
+
+### 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"}
+
+## On Arrays of Hash-es
+
+Summarizing an Array of Array-s of Hash-es yields -> an Array of Hash-es
+
+There is a subtelty here, as you have to specify the "by key", that is, what
+hash elements form the summarization grouping terms.
+
+    [ 
+      [ { :name => :yard,      :for => [ :devel   ] },
+        { :name => :summaryse, :for => [ :runtime ] } ],
+      [ { :name => :summaryse, :for => [ :devel   ] }, 
+        { :name => :treetop,   :for => [ :runtime ] } ]
+    ].summaryse([ [:name], {:for => :union} ])
+    # => [ {:name => :yard,      :for => [:devel]           },
+    #      {:name => :summaryse, :for => [:devel, :runtime] },
+    #      {:name => :treetop,   :for => [:runtime]         } ]
+
+A quick remark: when merging arrays of hashes, #summaryse guarantees that the 
+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?
+
+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.
+
+# Contribute, Versioning and so on.
+
+As usual: the code is on {http://github.com/blambeau/summaryse github}, I follow
+{http://semver.org/ semantic versioning} (the public API is almost everything but 
+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}. 
+ 

data/Rakefile

@@ -0,0 +1,23 @@
+begin
+  gem "bundler", "~> 1.0"
+  require "bundler/setup"
+rescue LoadError => ex
+  puts ex.message
+  abort "Bundler failed to load, (did you run 'gem install bundler' ?)"
+end
+
+# Dynamically load the gem spec
+$gemspec_file = File.expand_path('../summaryse.gemspec', __FILE__)
+$gemspec      = Kernel.eval(File.read($gemspec_file))
+
+# We run tests by default
+task :default => :test
+
+#
+# Install all tasks found in tasks folder
+#
+# See .rake files there for complete documentation.
+#
+Dir["tasks/*.rake"].each do |taskfile|
+  instance_eval File.read(taskfile), taskfile
+end

data/examples/yaml_merge.rb

@@ -0,0 +1,33 @@
+$LOAD_PATH.unshift File.expand_path('../../lib', __FILE__)
+require 'summaryse'
+require 'yaml'
+
+# This is left.yaml
+left = YAML.load <<-Y
+  hobbies:
+    - ruby
+    - rails
+  dependencies:
+    - {name: rspec, version: '2.6.4', for: [ runtime ]}
+Y
+
+# This is right.yaml
+right = YAML.load <<-Y
+  hobbies:
+    - ruby
+    - music
+  dependencies:
+    - {name: rails, version: '3.0',   for: [ runtime ]}
+    - {name: rspec, version: '2.6.4', for: [ test    ]}
+Y
+
+# This is merge.yaml
+merge = YAML.load <<-M
+  hobbies: 
+    :union
+  dependencies: 
+    - [name, version]
+    - for: :union
+M
+
+puts [ left, right ].summaryse(merge).to_yaml

data/lib/summaryse.rb

@@ -0,0 +1,3 @@
+require "summaryse/version"
+require "summaryse/loader"
+require "summaryse/core_ext/array"

data/lib/summaryse/core_ext/array.rb

@@ -0,0 +1,99 @@
+class Array
+
+  #
+  # Apply a summarization to self
+  #
+  # == Base
+  #
+  # Basic summarization operators are 
+  #   * :avg, :count, :sum
+  #   * :mix, :max, :first, :last
+  #   * :union, :intersection
+  #
+  # They suppose the existence of the corresponding dyadic operators like 
+  # '+' (i.e. sum, avg), '|' (union), '&' (intersection) on the array values.
+  #
+  # Example:
+  #     [1, 4, 12, 7].summaryse(:sum)   # => 24
+  #
+  # == Hashes
+  #
+  # Summarizing arrays of hashes may be done by passing an hash of summarization
+  # expressions. Calls will be made recursively in this case:
+  #
+  # Example: 
+  #     [
+  #       { :hobbies => [:ruby],  :size => 12 },
+  #       { :hobbies => [:music], :size => 17 }
+  #     ].summaryse(:hobbies => :union, :size => :max)
+  #     # => {:hobbies => [:ruby, :music], :size => 17}
+  #
+  # Use the nil key to specify the default aggregation to apply if not explcitely
+  # specified. A Proc object can also be passed as aggregation operator. In this
+  # case, it will be called with the array of values on which the aggregation
+  # must be done:
+  #
+  #     # In the example below, hobbies are summarized through default behavior
+  #     # provided by the nil key. Sizes are summarized by the lambda. 
+  #     [
+  #       { :hobbies => [:ruby],  :size => 12 },
+  #       { :hobbies => [:music], :size => 17 }
+  #     ].summaryse(nil => :union, :size => lambda{|a| a.join(',')})
+  #     # => {:hobbies => [:ruby, :music], :size => "12,17"}
+  # 
+  # == Arrays of Hashes
+  #
+  # Summarizing arrays of arrays of hashes may be done by passing an array of 
+  # two values. The first one is a 'by key', the second is the summarization 
+  # hash to apply.
+  #
+  # Example:
+  #     [ 
+  #       [ { :name => :yard,      :for => [ :devel   ] },
+  #         { :name => :summaryse, :for => [ :runtime ] } ],
+  #       [ { :name => :summaryse, :for => [ :devel   ] }, 
+  #         { :name => :treetop,   :for => [ :runtime ] } ]
+  #     ].summaryse([ [:name], {:for => :union} ])
+  #     # => [ {:name => :yard,      :for => [:devel]           },
+  #     #      {:name => :summaryse, :for => [:devel, :runtime] },
+  #     #      {:name => :treetop,   :for => [:runtime]         } ]
+  #
+  def summaryse(agg)
+    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)
+    when Hash
+      big = Hash.new{|h,k| h[k] = []}
+      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)]
+        end
+      }.compact]
+    when Array
+      by, agg = agg
+      keys = []
+      grouped = Hash.new{|h,k| h[k] = []}
+      flatten.each{|t|
+        key = Hash[by.collect{|k| [k, t[k]] }]
+        keys << key
+        grouped[key] << t
+      }
+      agg = agg.merge(Hash[by.collect{|k| [k, :first]}])
+      keys.uniq.collect{|key| grouped[key].summaryse(agg)}
+    end
+  end
+
+end