fat_core 1.0.3 → 1.2.0

data/lib/fat_core/range.rb

@@ -6,8 +6,6 @@ class Range
       Range.new(min, other.max)
     elsif right_contiguous?(other)
       Range.new(other.min, max)
-    else
-      nil
     end
   end
 
@@ -55,16 +53,16 @@ class Range
   end
 
   def intersection(other)
-    return nil unless self.overlaps?(other)
-    ([self.min, other.min].max..[self.max, other.max].min)
+    return nil unless overlaps?(other)
+    ([min, other.min].max..[max, other.max].min)
   end
-  alias_method :&, :intersection
+  alias & intersection
 
   def union(other)
-    return nil unless self.overlaps?(other) || self.contiguous?(other)
-    ([self.min, other.min].min..[self.max, other.max].max)
+    return nil unless overlaps?(other) || contiguous?(other)
+    ([min, other.min].min..[max, other.max].max)
   end
-  alias_method :+, :union
+  alias + union
 
   # The difference method, -, removes the overlapping part of the other
   # argument from self.  Because in the case where self is a superset of the
@@ -73,10 +71,9 @@ class Range
   # self is a subset of the other range, return an array of self
   def difference(other)
     unless max.respond_to?(:succ) && min.respond_to?(:pred) &&
-        other.max.respond_to?(:succ) && other.min.respond_to?(:pred)
-      raise "Range difference operation requires objects have pred and succ methods"
+           other.max.respond_to?(:succ) && other.min.respond_to?(:pred)
+      raise 'Range difference requires objects have pred and succ methods'
     end
-    # return [self] unless self.overlaps?(other)
     if subset_of?(other)
       # (4..7) - (0..10)
       []
@@ -85,15 +82,15 @@ class Range
       [(min..other.min.pred), (other.max.succ..max)]
     elsif overlaps?(other) && other.min <= min
       # (4..7) - (2..5) -> (6..7)
-      [(other.max.succ .. max)]
+      [(other.max.succ..max)]
     elsif overlaps?(other) && other.max >= max
       # (4..7) - (6..10) -> (4..5)
-      [(min .. other.min.pred)]
+      [(min..other.min.pred)]
     else
-      [ self ]
+      [self]
     end
   end
-  alias_method :-, :difference
+  alias - difference
 
   # Return whether any of the ranges that are within self overlap one
   # another
@@ -104,9 +101,9 @@ class Range
         next unless overlaps?(r1)
         result =
           ranges.any? do |r2|
-          r1.object_id != r2.object_id && overlaps?(r2) &&
-            r1.overlaps?(r2)
-        end
+            r1.object_id != r2.object_id && overlaps?(r2) &&
+              r1.overlaps?(r2)
+          end
         return true if result
       end
     end
@@ -117,7 +114,7 @@ class Range
   # without overlaps.
   def spanned_by?(ranges)
     joined_range = nil
-    ranges.sort_by {|r| r.min}.each do |r|
+    ranges.sort_by(&:min).each do |r|
       unless joined_range
         joined_range = r
         next
@@ -137,11 +134,11 @@ class Range
   # array.
   def gaps(ranges)
     if ranges.empty?
-      [self.clone]
+      [clone]
     elsif spanned_by?(ranges)
       []
     else
-      ranges = ranges.sort_by {|r| r.min}
+      ranges = ranges.sort_by(&:min)
       gaps = []
       cur_point = min
       ranges.each do |rr|
@@ -155,9 +152,7 @@ class Range
           cur_point = rr.max.succ
         end
       end
-      if cur_point <= max
-        gaps << (cur_point..max)
-      end
+      gaps << (cur_point..max) if cur_point <= max
       gaps
     end
   end
@@ -169,7 +164,7 @@ class Range
     if ranges.empty? || spanned_by?(ranges)
       []
     else
-      ranges = ranges.sort_by {|r| r.min}
+      ranges = ranges.sort_by(&:min)
       overlaps = []
       cur_point = nil
       ranges.each do |rr|

data/lib/fat_core/string.rb

@@ -4,7 +4,7 @@ class String
   # Remove leading and trailing white space and compress internal runs of
   # white space to a single space.
   def clean
-    self.strip.squeeze(' ')
+    strip.squeeze(' ')
   end
 
   def distance(other, block_size: 1, max_distance: 10)
@@ -13,7 +13,7 @@ class String
     # will return max_distance+1 if the distance is bigger than that.
     # Here we subtract 1 so the max_distance also becomes the max
     # return value.
-    dl.distance(self, other, block_size, max_distance-1)
+    dl.distance(self, other, block_size, max_distance - 1)
   end
 
   # See if self contains colon- or space-separated words that include
@@ -22,18 +22,16 @@ class String
   def fuzzy_match(other)
     # Remove periods, commas, and apostrophes
     other = other.gsub(/[\*.,']/, '')
-    target = self.gsub(/[\*.,']/, '')
-    matched_text = nil
+    target = gsub(/[\*.,']/, '')
     matchers = other.split(/[: ]+/)
-    regexp_string = matchers.map {|m| ".*?#{Regexp.escape(m)}.*?"}.join('[: ]')
+    regexp_string = matchers.map { |m| ".*?#{Regexp.escape(m)}.*?" }.join('[: ]')
     regexp_string.sub!(/^\.\*\?/, '')
     regexp_string.sub!(/\.\*\?$/, '')
     regexp = /#{regexp_string}/i
-    if match = regexp.match(target)
-      matched_text = match[0]
-    else
-      matched_text = nil
-    end
+    matched_text =
+      if (match = regexp.match(target))
+        match[0]
+      end
     matched_text
   end
 
@@ -44,15 +42,11 @@ class String
   def matches_with(str)
     if str.nil?
       nil
-    elsif str =~ /^\s*\//
+    elsif str =~ %r{^\s*/}
       re = str.to_regexp
-      if self.to_s =~ re
-        $&
-      else
-        nil
-      end
+      $& if to_s =~ re
     else
-      self.to_s.fuzzy_match(str)
+      to_s.fuzzy_match(str)
     end
   end
 
@@ -60,7 +54,7 @@ class String
   # make the regular expression case-insensitive by default and extend the
   # modifier syntax to allow '/I' to indicate case-sensitive.
   def to_regexp
-    if self =~ /^\s*\/([^\/]*)\/([Iixm]*)\s*$/
+    if self =~ %r{^\s*/([^/]*)/([Iixm]*)\s*$}
       body = $1
       opts = $2
       flags = Regexp::IGNORECASE
@@ -70,7 +64,7 @@ class String
         flags |= Regexp::EXTENDED if opts.include?('x')
         flags |= Regexp::MULTILINE if opts.include?('m')
       end
-      flags = nil if flags == 0
+      flags = nil if flags.zero?
       Regexp.new(body, flags)
     else
       Regexp.new(self)
@@ -79,8 +73,8 @@ class String
 
   # Convert to symbol "Hello World" -> :hello_world
   def as_sym
-    strip.squeeze(' ').gsub(/\s+/, '_').
-      gsub(/[^_A-Za-z0-9]/, '').downcase.to_sym
+    strip.squeeze(' ').gsub(/\s+/, '_')
+      .gsub(/[^_A-Za-z0-9]/, '').downcase.to_sym
   end
 
   def as_string
@@ -94,7 +88,7 @@ class String
     return false
   end
 
-  def wrap(width=70, hang=0)
+  def wrap(width = 70, hang = 0)
     offset = 0
     trip = 1
     result = ''
@@ -113,7 +107,7 @@ class String
   end
 
   def tex_quote
-    r = self.dup
+    r = dup
     r = r.gsub(/[{]/, 'XzXzXobXzXzX')
     r = r.gsub(/[}]/, 'XzXzXcbXzXzX')
     r = r.gsub(/\\/, '\textbackslash{}')
@@ -124,7 +118,7 @@ class String
     r = r.gsub(/\>/, '\textgreater{}')
     r = r.gsub(/([_$&%#])/) { |m| '\\' + m }
     r = r.gsub('XzXzXobXzXzX', '\\{')
-    r = r.gsub('XzXzXcbXzXzX', '\\}')
+    r.gsub('XzXzXcbXzXzX', '\\}')
   end
 
   def self.random(size = 8)
@@ -134,48 +128,48 @@ class String
   # Convert a string with an all-digit date to an iso string
   # E.g., "20090923" -> "2009-09-23"
   def digdate2iso
-    self.sub(/(\d\d\d\d)(\d\d)(\d\d)/, '\1-\2-\3')
+    sub(/(\d\d\d\d)(\d\d)(\d\d)/, '\1-\2-\3')
   end
 
   def entitle!
-    little_words = %w[ a an the and or in on under of from as by to ]
+    little_words = %w(a an the and or in on under of from as by to)
     newwords = []
     words = split(/\s+/)
     first_word = true
     num_words = words.length
     words.each_with_index do |w, k|
       last_word = (k + 1 == num_words)
-      if w =~ %r[c/o]i
+      if w =~ %r{c/o}i
         # Care of
-        newwords.push("c/o")
-      elsif w =~ %r[^p\.?o\.?$]i
+        newwords.push('c/o')
+      elsif w =~ /^p\.?o\.?$/i
         # Post office
-        newwords.push("P.O.")
-      elsif w =~ %r[^[0-9]+(st|nd|rd|th)$]i
+        newwords.push('P.O.')
+      elsif w =~ /^[0-9]+(st|nd|rd|th)$/i
         # Ordinals
         newwords.push(w.downcase)
-      elsif w =~ %r[^(cr|dr|st|rd|ave|pk|cir)$]i
+      elsif w =~ /^(cr|dr|st|rd|ave|pk|cir)$/i
         # Common abbrs to capitalize
         newwords.push(w.capitalize)
-      elsif w =~ %r[^(us|ne|se|rr)$]i
+      elsif w =~ /^(us|ne|se|rr)$/i
         # Common 2-letter abbrs to upcase
         newwords.push(w.upcase)
-      elsif w =~ %r[^[0-9].*$]i
+      elsif w =~ /^[0-9].*$/i
         # Other runs starting with numbers,
         # like 3-A
         newwords.push(w.upcase)
-      elsif w =~ %r[^(N|S|E|W|NE|NW|SE|SW)$]i
+      elsif w =~ /^(N|S|E|W|NE|NW|SE|SW)$/i
         # Compass directions all caps
         newwords.push(w.upcase)
-      elsif w =~ %r[^[^aeiouy]*$]i && w.size > 2
+      elsif w =~ /^[^aeiouy]*$/i && w.size > 2
         # All consonants and at least 3 chars, probably abbr
         newwords.push(w.upcase)
-      elsif w =~ %r[^(\w+)-(\w+)$]i
-        # Hypenated double word
+      elsif w =~ /^(\w+)-(\w+)$/i
+        # Hyphenated double word
         newwords.push($1.capitalize + '-' + $2.capitalize)
       elsif little_words.include?(w.downcase)
         # Only capitalize at beginning or end
-        newwords.push((first_word or last_word) ? w.capitalize : w.downcase)
+        newwords.push(first_word || last_word ? w.capitalize : w.downcase)
       else
         # All else
         newwords.push(w.capitalize)
@@ -186,7 +180,17 @@ class String
   end
 
   def entitle
-    self.dup.entitle!
+    dup.entitle!
+  end
+
+  # Format the string according to the given sprintf format.
+  def format_by(fmt)
+    return self unless fmt
+    begin
+      format fmt, self
+    rescue ArgumentError
+      return self
+    end
   end
 
   # Thanks to Eugene at stackoverflow for the following.
@@ -194,19 +198,55 @@ class String
   #   colorized-output-breaks-linewrapping-with-readline
   # These color strings without confusing readline about the length of
   # the prompt string in the shell. (Unlike the rainbow routines)
-  def console_red;          colorize(self, "\001\e[1m\e[31m\002");  end
-  def console_dark_red;     colorize(self, "\001\e[31m\002");       end
-  def console_green;        colorize(self, "\001\e[1m\e[32m\002");  end
-  def console_dark_green;   colorize(self, "\001\e[32m\002");       end
-  def console_yellow;       colorize(self, "\001\e[1m\e[33m\002");  end
-  def console_dark_yellow;  colorize(self, "\001\e[33m\002");       end
-  def console_blue;         colorize(self, "\001\e[1m\e[34m\002");  end
-  def console_dark_blue;    colorize(self, "\001\e[34m\002");       end
-  def console_purple;       colorize(self, "\001\e[1m\e[35m\002");  end
-
-  def console_def;          colorize(self, "\001\e[1m\002");  end
-  def console_bold;         colorize(self, "\001\e[1m\002");  end
-  def console_blink;        colorize(self, "\001\e[5m\002");  end
-
-  def colorize(text, color_code)  "#{color_code}#{text}\001\e[0m\002" end
+  def console_red
+    colorize(self, "\001\e[1m\e[31m\002")
+  end
+
+  def console_dark_red
+    colorize(self, "\001\e[31m\002")
+  end
+
+  def console_green
+    colorize(self, "\001\e[1m\e[32m\002")
+  end
+
+  def console_dark_green
+    colorize(self, "\001\e[32m\002")
+  end
+
+  def console_yellow
+    colorize(self, "\001\e[1m\e[33m\002")
+  end
+
+  def console_dark_yellow
+    colorize(self, "\001\e[33m\002")
+  end
+
+  def console_blue
+    colorize(self, "\001\e[1m\e[34m\002")
+  end
+
+  def console_dark_blue
+    colorize(self, "\001\e[34m\002")
+  end
+
+  def console_purple
+    colorize(self, "\001\e[1m\e[35m\002")
+  end
+
+  def console_def
+    colorize(self, "\001\e[1m\002")
+  end
+
+  def console_bold
+    colorize(self, "\001\e[1m\002")
+  end
+
+  def console_blink
+    colorize(self, "\001\e[5m\002")
+  end
+
+  def colorize(text, color_code)
+    "#{color_code}#{text}\001\e[0m\002"
+  end
 end

data/lib/fat_core/symbol.rb

@@ -1,17 +1,15 @@
-  class Symbol
-    # Convert to capitalized string: :hello_world -> "Hello World"
-    def entitle
-      to_s.gsub('_', ' ').split(' ')
-        .join(' ')
-        .entitle
-    end
-    alias :to_string :entitle
+class Symbol
+  # Convert to capitalized string: :hello_world -> "Hello World"
+  def entitle
+    to_s.tr('_', ' ').split(' ').join(' ').entitle
+  end
+  alias to_string entitle
 
-    def as_sym
-      self
-    end
+  def as_sym
+    self
+  end
 
-    def tex_quote
-      to_s.tex_quote
-    end
+  def tex_quote
+    to_s.tex_quote
   end
+end

data/lib/fat_core/table.rb

@@ -0,0 +1,515 @@
+module FatCore
+  # A container for a two-dimensional table. All cells in the table must be a
+  # String, a Date, a DateTime, a Bignum (or Integer), a BigDecimal, or a
+  # boolean. All columns must be of one of those types or be a string
+  # convertible into one of the supported types. It is considered an error if a
+  # single column contains cells of different types. Any cell that cannot be
+  # parsed as one of the numeric, date, or boolean types will have to_s applied
+  #
+  # You can initialize a Table in several ways:
+  #
+  # 1. with a Nil, which will return an empty table to which rows or columns can
+  #    be added later,
+  # 2. with the name of a .csv file,
+  # 3. with the name of an .org file,
+  # 4. with an IO or StringIO object for either type of file, but in that case,
+  #    you need to specify 'csv' or 'org' as the second argument to tell it what
+  #    kind of file format to expect,
+  # 5. with an Array of Arrays,
+  # 6. with an Array of Hashes, all having the same keys, which become the names
+  #    of the column heads,
+  # 7. with an Array of any objects that respond to .keys and .values methods,
+  # 8. with another Table object.
+  #
+  # In the case of an array of arrays, if the second array's first element is a
+  # string that looks like a rule separator, '-----------', '+----------', etc.,
+  # the headers will be taken from the first array. In the case of an array of
+  # Hashes or Hash-lime objects, the keys of the hashes will be used as the
+  # headers. It is assumed that all the hashes have the same keys.
+  #
+  # In the resulting Table, the headers are converted into symbols, with all
+  # spaces converted to underscore and everything down-cased. So, the heading,
+  # 'Two Words' becomes the hash header :two_words.
+  #
+  # An entire column can be retrieved by header from a Table, thus,
+  # #+BEGIN_EXAMPLE
+  # tab = Table.new("example.org")
+  # tab[:age].avg
+  # #+END_EXAMPLE
+  # will extract the entire ~:age~ column and compute its average, since Column
+  # objects respond to aggregate methods, such as ~sum~, ~min~, ~max~, and ~avg~.
+  class Table
+    attr_reader :columns, :footers
+
+    TYPES = %w(NilClass TrueClass FalseClass Date DateTime Numeric String)
+
+    def initialize(input = nil, ext = '.csv')
+      @columns = []
+      @footers = {}
+      return self if input.nil?
+      case input
+      when IO, StringIO
+        case ext
+        when /csv/i
+          from_csv(input)
+        when /org/i
+          from_org(input)
+        else
+          raise "Don't know how to read a '#{ext}' file."
+        end
+      when String
+        ext = File.extname(input).downcase
+        File.open(input, 'r') do |io|
+          case ext
+          when '.csv'
+            from_csv(io)
+          when '.org'
+            from_org(io)
+          else
+            raise "Don't know how to read a '#{ext}' file."
+          end
+        end
+      when Array
+        case input[0]
+        when Array
+          from_array_of_arrays(input)
+        when Hash
+          from_array_of_hashes(input)
+        when Table
+          from_table(input)
+        else
+          if input[0].respond_to?(:to_hash)
+            from_array_of_hashes(input)
+          else
+            raise ArgumentError,
+                  "Cannot initialize Table with an array of #{input[0].class}"
+          end
+        end
+      else
+        raise ArgumentError,
+              "Cannot initialize Table with #{input.class}"
+      end
+    end
+
+    # Return the column with the given header.
+    def column(key)
+      columns.detect { |c| c.header == key.as_sym }
+    end
+
+    # Return the array of items of the column with the given header.
+    def [](key)
+      column(key)
+    end
+
+    def column?(key)
+      headers.include?(key.as_sym)
+    end
+
+    # Attr_reader as a plural
+    def types
+      columns.map(&:type)
+    end
+
+    # Return the headers for the table as an array of symbols.
+    def headers
+      columns.map(&:header)
+    end
+
+    # Return the rows of the table as an array of hashes, keyed by the headers.
+    def rows
+      rows = []
+      0.upto(columns.first.items.last_i) do |rnum|
+        row = {}
+        columns.each do |col|
+          row[col.header] = col[rnum]
+        end
+        rows << row
+      end
+      rows
+    end
+
+    def empty?
+      rows.empty?
+    end
+
+    ############################################################################
+    # SQL look-alikes. The following methods are based on SQL equivalents and
+    # all return a new Table object rather than modifying the table in place.
+    ############################################################################
+
+    # Return a new Table sorted on the rows of this Table on the possibly
+    # multiple keys given in the array of syms in headers. Append a ! to the
+    # symbol name to indicate reverse sorting on that column.
+    def order_by(*sort_heads)
+      sort_heads = [sort_heads].flatten
+      rev_heads = sort_heads.select { |h| h.to_s.ends_with?('!') }
+      sort_heads = sort_heads.map { |h| h.to_s.sub(/\!\z/, '').to_sym }
+      rev_heads = rev_heads.map { |h| h.to_s.sub(/\!\z/, '').to_sym }
+      new_rows = rows.sort do |r1, r2|
+        key1 = sort_heads.map { |h| rev_heads.include?(h) ? r2[h] : r1[h] }
+        key2 = sort_heads.map { |h| rev_heads.include?(h) ? r1[h] : r2[h] }
+        key1 <=> key2
+      end
+      new_tab = Table.new
+      new_rows.each do |nrow|
+        new_tab.add_row(nrow)
+      end
+      new_tab
+    end
+
+    # Return a Table having the selected column expression. Each expression can
+    # be either a (1) symbol, (2) a hash of symbol => symbol, or (3) a hash of
+    # symbol => 'string', though the bare symbol arguments (1) must precede any
+    # hash arguments. Each expression results in a column in the resulting Table
+    # in the order given. The expressions are evaluated in order as well.
+    def select(*exps)
+      new_cols = {}
+      new_heads = []
+      exps.each do |exp|
+        case exp
+        when Symbol, String
+          h = exp.as_sym
+          raise "Header #{h} does not exist" unless headers.include?(h)
+          new_heads << h
+          new_cols[h] = Column.new(header: h,
+                                   type: column(h).type,
+                                   items: column(h).items)
+        when Hash
+          exp.each_pair do |key, xp|
+            case xp
+            when Symbol
+              h = xp.as_sym
+              raise "Header #{key} does not exist" unless column?(key)
+              new_heads << h
+              new_cols[h] = Column.new(header: h,
+                                       type: column(key).type,
+                                       items: column(key).items)
+            when String
+              # Evaluate xp in the context of a binding including a local
+              # variable for each original column with the name as the head and
+              # the value for the current row as the value and a local variable
+              # for each new column with the new name and the new value.
+              h = key.as_sym
+              new_heads << h
+              new_cols[h] = Column.new(header: h)
+              ev = Evaluator.new(vars: { row: 0 }, before: '@row += 1')
+              rows.each_with_index do |old_row, row_num|
+                new_row ||= {}
+                # Gather the new values computed so far for this row
+                new_vars = new_heads.zip(new_cols.keys
+                                           .map { |k| new_cols[k] }
+                                           .map { |c| c[row_num] })
+                vars = old_row.merge(Hash[new_vars])
+                # Now we have a hash, vars, of all local variables we want to be
+                # defined while evaluating expression xp as the value of column
+                # key in the new column.
+                new_row[h] = ev.evaluate(xp, vars: vars)
+                new_cols[h] << new_row[h]
+              end
+            else
+              raise 'Hash parameters to select must be a symbol or string'
+            end
+          end
+        else
+          raise 'Parameters to select must be a symbol, string, or hash'
+        end
+      end
+      result = Table.new
+      new_heads.each do |h|
+        result.add_column(new_cols[h])
+      end
+      result
+    end
+
+    # Return a Table containing only rows matching the where expression.
+    def where(expr)
+      expr = expr.to_s
+      result = Table.new
+      ev = Evaluator.new(vars: { row: 0 }, before: '@row += 1')
+      rows.each do |row|
+        result.add_row(row) if ev.evaluate(expr, vars: row)
+      end
+      result
+    end
+
+    # Return a Table that combines this table with another table. The headers of
+    # this table are used in the result. There must be the same number of
+    # columns of the same type in the two tables, or an exception will be
+    # thrown. Unlike in SQL, no duplicates are eliminated from the result.
+    def union(other)
+      unless columns.size == other.columns.size
+        raise 'Cannot apply union to tables with a different number of columns.'
+      end
+      result = Table.new
+      columns.each_with_index do |col, k|
+        result.add_column(col + other.columns[k])
+      end
+      result
+    end
+
+    # Return a Table in which all rows of the table are divided into groups
+    # where the value of all columns named as simple symbols are equal. All
+    # other columns are set to the result of aggregating the values of that
+    # column within the group according to the Column aggregate function (:sum,
+    # :min, :max, etc.) set in a hash parameter with the non-aggregate column
+    # name as a key and the symbol for the aggregate function as a value. For
+    # example, consider the following call:
+    #
+    # #+BEGIN_EXAMPLE
+    # tab.group_by(:date, :code, :price, shares: :sum, ).
+    # #+END_EXAMPLE
+    #
+    # The first three parameters are simple symbols, so the table is divided
+    # into groups of rows in which the value of :date, :code, and :price are
+    # equal. The :shares parameter is set to the aggregate function :sum, so it
+    # will appear in the result as the sum of all the :shares values in each
+    # group. Any non-aggregate columns that have no aggregate function set
+    # default to using the aggregate function :first. Note that because of the
+    # way Ruby parses parameters to a method call, all the grouping symbols must
+    # appear first in the parameter list.
+    def group_by(*exprs)
+      group_cols = []
+      agg_cols = {}
+      exprs.each do |xp|
+        case xp
+        when Symbol
+          group_cols << xp
+        when Hash
+          agg_cols = xp
+        else
+          raise "Cannot group by parameter '#{xp}"
+        end
+      end
+      default_agg_func = :first
+      default_cols = headers - group_cols - agg_cols.keys
+      default_cols.each do |h|
+        agg_cols[h] = default_agg_func
+      end
+
+      sorted_tab = order_by(group_cols)
+      groups = sorted_tab.rows.group_by do |r|
+        group_cols.map { |k| r[k] }
+      end
+      result_rows = []
+      groups.each_pair do |_vals, grp_rows|
+        result_rows << row_from_group(grp_rows, group_cols, agg_cols)
+      end
+      result = Table.new
+      result_rows.each do |row|
+        result.add_row(row)
+      end
+      result
+    end
+
+    private
+
+    def row_from_group(rows, grp_cols, agg_cols)
+      new_row = {}
+      grp_cols.each do |h|
+        new_row[h] = rows.first[h]
+      end
+      agg_cols.each_pair do |h, agg_func|
+        items = rows.map { |r| r[h] }
+        new_h = "#{agg_func}_#{h}"
+        new_row[new_h] = Column.new(header: h,
+                                items: items,
+                                type: column(h).type).send(agg_func)
+      end
+      new_row
+    end
+
+    ############################################################################
+    # Table output methods.
+    ############################################################################
+
+    public
+
+    def add_footer(label: 'Total', aggregate: :sum, heads: [])
+      foot = {}
+      heads.each do |h|
+        foot[h] = column(h).send(aggregate)
+      end
+      @footers[label.as_sym] = foot
+      self
+    end
+
+    def add_sum_footer(cols, label = 'Total')
+      add_footer(heads: cols)
+    end
+
+    def add_avg_footer(cols, label = 'Average')
+      add_footer(label: label, aggregate: :avg, heads: cols)
+    end
+
+    def add_min_footer(cols, label = 'Minimum')
+      add_footer(label: label, aggregate: :min, heads: cols)
+    end
+
+    def add_max_footer(cols, label = 'Maximum')
+      add_footer(label: label, aggregate: :max, heads: cols)
+    end
+
+    # This returns the table as an Array of Arrays with formatting applied.
+    # This would normally called after all calculations on the table are done
+    # and you want to return the results.  The Array of Arrays structure is
+    # what org-mode src blocks will render as an org table in the buffer.
+    def to_org(formats: {})
+      result = []
+      header_row = []
+      headers.each do |hdr|
+        header_row << hdr.entitle
+      end
+      result << header_row
+      # This causes org to place an hline under the header row
+      result << nil unless header_row.empty?
+
+      rows.each do |row|
+        out_row = []
+        headers.each do |hdr|
+          out_row << row[hdr].format_by(formats[hdr])
+        end
+        result << out_row
+      end
+      footers.each_pair do |label, footer|
+        foot_row = []
+        columns.each do |hdr|
+          foot_row << footer[hdr].format_by(formats[hdr])
+        end
+        foot_row[0] = label.entitle
+        result << foot_row
+      end
+      result
+    end
+
+    # This returns the table as an Array of Arrays with formatting applied.
+    # This would normally called after all calculations on the table are done
+    # and you want to return the results.  The Array of Arrays structure is
+    # what org-mode src blocks will render as an org table in the buffer.
+    def to_org(include: headers, exclude: [], formats: {})
+      # Allow include and exclude to be a single symbol or an array of symbols
+      # and compute the displayed columns.
+      columns = [include].flatten
+      exclude = [exclude].flatten
+      columns = include - exclude
+
+      result = []
+
+      header_row = []
+      columns.each do |hdr|
+        header_row << hdr.entitle
+      end
+      result << header_row
+
+      result << nil unless header_row.empty?
+
+      rows.each do |row|
+        out_row = []
+        columns.each do |hdr|
+          out_row << row[hdr].format_by(formats[hdr])
+        end
+        result << out_row
+      end
+
+      footers.each_pair do |label, footer|
+        foot_row = []
+        columns.each do |hdr|
+          foot_row << footer[hdr].format_by(formats[hdr])
+        end
+        foot_row[0] = label.entitle
+        result << foot_row
+      end
+      result
+    end
+    ############################################################################
+    # Table construction methods.
+    ############################################################################
+
+    # Add a row represented by a Hash having the headers as keys. All tables
+    # should be built ultimately using this method as a primitive.
+    def add_row(row)
+      row.each_pair do |k, v|
+        key = k.as_sym
+        columns << Column.new(header: k) unless column?(k)
+        column(key) << v
+      end
+      self
+    end
+
+    def <<(row)
+      add_row(row)
+    end
+
+    def add_column(col)
+      raise "Table already has a column with header '#{col.header}'" if column?(col.header)
+      columns << col
+      self
+    end
+
+    private
+
+    # Construct table from an array of hashes or an array of any object that can
+    # respond to #to_hash.
+    def from_array_of_hashes(rows)
+      rows.each do |row|
+        add_row(row.to_hash)
+      end
+      self
+    end
+
+    def from_array_of_arrays(rows)
+      headers = []
+      if rows[0].any? { |itm| itm.to_s.number? }
+        headers = (1..rows[0].size).to_a.map { |k| "col#{k}".as_sym }
+        first_data_row = 0
+      else
+        # Use first row 0 as headers
+        headers = rows[0].map(&:as_sym)
+        first_data_row = 1
+      end
+      hrule_re = /\A\s*\|[-+]+/
+      rows[first_data_row..-1].each do |row|
+        next if row[0] =~ hrule_re
+        row = row.map { |s| s.to_s.strip }
+        hash_row = Hash[headers.zip(row)]
+        add_row(hash_row)
+      end
+      self
+    end
+
+    def from_csv(io)
+      ::CSV.new(io, headers: true, header_converters: :symbol,
+                skip_blanks: true).each do |row|
+        add_row(row.to_hash)
+      end
+      self
+    end
+
+    # Form rows of table by reading the first table found in the org file.
+    def from_org(io)
+      table_re = /\A\s*\|/
+      hrule_re = /\A\s*\|[-+]+/
+      rows = []
+      table_found = false
+      header_found = false
+      io.each do |line|
+        unless table_found
+          # Skip through the file until a table is found
+          next unless line =~ table_re
+          table_found = true
+        end
+        break unless line =~ table_re
+        if !header_found && line =~ hrule_re
+          header_found = true
+          next
+        elsif header_found && line =~ hrule_re
+          # Stop reading at the second hline
+          break
+        else
+          line = line.sub(/\A\s*\|/, '').sub(/\|\s*\z/, '')
+          rows << line.split('|')
+        end
+      end
+      from_array_of_arrays(rows)
+    end
+  end
+end