fat_core 1.6.0 → 1.7.1

data/lib/fat_core/table.rb

@@ -1,49 +1,32 @@
 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
+  # String, a DateTime (or Date), a Numeric (Bignum, Integer, or BigDecimal), or
+  # a Boolean (TrueClass or FalseClass). All columns must be of one of those
+  # types or be a string convertible into one of them. 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, DateTime, or Boolean types will be treated
+  # as a String and have to_s applied.  Until the column type is determined, it
+  # will have the type NilClass.
   #
   # 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.
+  #    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 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,
-  #
-  # tab = Table.from_org_file("example.org")
-  # tab[:age].avg
-  #
-  # 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
+    attr_reader :columns
 
-    def initialize(input = nil, ext = '.csv')
+    def initialize
       @columns = []
-      @footers = {}
       @boundaries = []
     end
 
@@ -51,32 +34,49 @@ module FatCore
     # Constructors
     ###########################################################################
 
-    def self.from_csv_string(str)
-      from_csv_io(StringIO.new(str))
-    end
-
+    # Construct a Table from the contents of a CSV file.  Headers will be taken
+    # from the first row and converted to symbols.
     def self.from_csv_file(fname)
       File.open(fname, 'r') do |io|
         from_csv_io(io)
       end
     end
 
-    def self.from_org_string(str)
-      from_org_io(StringIO.new(str))
+    # Construct a Table from a string, treated as the input from a CSV file.
+    def self.from_csv_string(str)
+      from_csv_io(StringIO.new(str))
     end
 
+    # Construct a Table from the first table found in the given org-mode file.
+    # Headers are taken from the first row if the second row is an hrule.``
     def self.from_org_file(fname)
       File.open(fname, 'r') do |io|
         from_org_io(io)
       end
     end
 
+    # Construct a Table from a string, treated as the contents of an org-mode
+    # file.
+    def self.from_org_string(str)
+      from_org_io(StringIO.new(str))
+    end
+
+    # Construct a Table from an array of arrays.  If the second element is a nil
+    # or is an array whose first element is a string that looks like a rule
+    # separator, '|-----------', '+----------', etc., the headers will be taken
+    # from the first array converted to strings and then to symbols.  Any
+    # following such rows mark a group boundary.  Note that this is the form of
+    # a table used by org-mode src blocks, so it is useful for building Tables
+    # from the result of a src block.
     def self.from_aoa(aoa)
       from_array_of_arrays(aoa)
     end
 
+    # Construct a Table from an array of hashes, or any objects that respond to
+    # the #to_h method.  All hashes must have the same keys, which, when
+    # converted to symbols will become the headers for the Table.
     def self.from_aoh(aoh)
-      if aoh[0].respond_to?(:to_h)
+      if aoh.first.respond_to?(:to_h)
         from_array_of_hashes(aoh)
       else
         raise ArgumentError,
@@ -84,46 +84,192 @@ module FatCore
       end
     end
 
+    # Construct a Table from another Table.  Inherit any group boundaries from
+    # the input table.
     def self.from_table(table)
       from_aoh(table.rows)
+      @boundaries = table.boundaries
     end
 
+    ############################################################################
+    # Class-level constructor helpers
+    ############################################################################
+
+    class << self
+      private
+
+      # Construct table from an array of hashes or an array of any object that can
+      # respond to #to_h.  If an array element is a nil, mark it as a group
+      # boundary in the Table.
+      def from_array_of_hashes(hashes)
+        result = new
+        hashes.each do |hsh|
+          if hsh.nil?
+            result.mark_boundary
+            next
+          end
+          result << hsh.to_h
+        end
+        result
+      end
+
+      # Construct a new table from an array of arrays. If the second element of
+      # the array is a nil, a string that looks like an hrule, or an array whose
+      # first element is a string that looks like an hrule, interpret the first
+      # element of the array as a row of headers. Otherwise, synthesize headers of
+      # the form "col1", "col2", ... and so forth. The remaining elements are
+      # taken as the body of the table, except that if an element of the outer
+      # array is a nil or a string that looks like an hrule, mark the preceding
+      # row as a boundary.
+      def from_array_of_arrays(rows)
+        result = new
+        headers = []
+        if looks_like_boundary?(rows[1])
+          # Take the first row as headers
+          # Use first row 0 as headers
+          headers = rows[0].map(&:as_sym)
+          first_data_row = 2
+        else
+          # Synthesize headers
+          headers = (1..rows[0].size).to_a.map { |k| "col#{k}".as_sym }
+          first_data_row = 0
+        end
+        rows[first_data_row..-1].each do |row|
+          if looks_like_boundary?(row)
+            result.mark_boundary
+            next
+          end
+          row = row.map { |s| s.to_s.strip }
+          hash_row = Hash[headers.zip(row)]
+          result << hash_row
+        end
+        result
+      end
+
+      # Return true if row is nil, a string that matches hrule_re, or is an
+      # array whose first element matches hrule_re.
+      def looks_like_boundary?(row)
+        hrule_re = /\A\s*[\|+][-]+/
+        return true if row.nil?
+        if row.respond_to?(:first) && row.first.respond_to?(:to_s)
+          return row.first.to_s =~ hrule_re
+        end
+        if row.respond_to?(:to_s)
+          return row.to_s =~ hrule_re
+        end
+        false
+      end
+
+      def from_csv_io(io)
+        result = new
+        ::CSV.new(io, headers: true, header_converters: :symbol,
+                  skip_blanks: true).each do |row|
+          result << row.to_h
+        end
+        result
+      end
+
+      # Form rows of table by reading the first table found in the org file.
+      def from_org_io(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
+            unless line =~ hrule_re
+              line = line.sub(/\A\s*\|/, '').sub(/\|\s*\z/, '')
+              rows << line.split('|').map(&:clean)
+            end
+            table_found = true
+            next
+          end
+          break unless line =~ table_re
+          if !header_found && line =~ hrule_re
+            rows << nil
+            header_found = true
+            next
+          elsif header_found && line =~ hrule_re
+            # Mark the boundary with a nil
+            rows << nil
+          elsif line !~ table_re
+            # Stop reading at the second hline
+            break
+          else
+            line = line.sub(/\A\s*\|/, '').sub(/\|\s*\z/, '')
+            rows << line.split('|').map(&:clean)
+          end
+        end
+        from_array_of_arrays(rows)
+      end
+    end
+
+    ###########################################################################
+    # Attributes
+    ###########################################################################
+
     # 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.
+    # Return the type of the column with the given header
+    def type(key)
+      column(key).type
+    end
+
+    # Return the array of items of the column with the given header, or if the
+    # index is an integer, return that row number.  So a table's rows can be
+    # accessed by number, and its columns can be accessed by column header.
+    # Also, double indexing works in either row-major or column-majoir order:
+    # tab[:id][8] returns the 8th item in the column headed :id and so does
+    # tab[8][:id].
     def [](key)
-      column(key)
+      case key
+      when Integer
+        raise "index '#{key}' out of range" unless (1..size).cover?(key)
+        rows[key - 1]
+      when String
+        raise "header '#{key}' not in table" unless headers.include?(key)
+        column(key).items
+      when Symbol
+        raise "header ':#{key}' not in table" unless headers.include?(key)
+        column(key).items
+      else
+        raise "cannot index table with a #{key.class}"
+      end
     end
 
+    # Return true if the table has a column with the given header.
     def column?(key)
       headers.include?(key.as_sym)
     end
 
-    # Attr_reader as a plural
+    # Return an array of the Table's column types.
     def types
       columns.map(&:type)
     end
 
-    # Return the headers for the table as an array of symbols.
+    # Return the headers for the Table as an array of symbols.
     def headers
       columns.map(&:header)
     end
 
-    # Return the number of rows in the table.
+    # Return the number of rows in the Table.
     def size
       return 0 if columns.empty?
       columns.first.size
     end
 
-    # Return whether this table is empty.
+    # Return whether this Table is empty.
     def empty?
       size.zero?
     end
 
-    # Return the rows of the table as an array of hashes, keyed by the headers.
+    # Return the rows of the Table as an array of hashes, keyed by the headers.
     def rows
       rows = []
       unless columns.empty?
@@ -277,9 +423,9 @@ module FatCore
 
     public
 
-    # 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.  Resets groups.
+    # Return a new Table sorting 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. Resets groups.
     def order_by(*sort_heads)
       sort_heads = [sort_heads].flatten
       rev_heads = sort_heads.select { |h| h.to_s.ends_with?('!') }
@@ -542,10 +688,12 @@ module FatCore
     #      have N and M rows respectively, the joined table will have N * M
     #      rows.
     # Resets groups.
-    JOIN_TYPES = [:inner, :left, :right, :full, :cross]
+    JOIN_TYPES = [:inner, :left, :right, :full, :cross].freeze
 
     def join(other, *exps, join_type: :inner)
-      raise ArgumentError, 'need other table as first argument to join' unless other.is_a?(Table)
+      unless other.is_a?(Table)
+        raise ArgumentError, 'need other table as first argument to join'
+      end
       unless JOIN_TYPES.include?(join_type)
         raise ArgumentError, "join_type may only be: #{JOIN_TYPES.join(', ')}"
       end
@@ -610,74 +758,6 @@ module FatCore
       join(other, join_type: :cross)
     end
 
-    # Return a Table with a single row for each group of rows in the input table
-    # 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 a aggregate function (:count, :sum,
-    # :min, :max, etc.), which defaults to the :first function, giving the value
-    # of that column for the first row in the group.  You can specify a
-    # different aggregate function for a column by adding a hash parameter with
-    # the column as the key and a symbol for the aggregate function as the
-    # value.  For example, consider the following call:
-    #
-    # tab.group_by(:date, :code, :price, shares: :sum, ).
-    #
-    # 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: hash 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. Because of the way Ruby
-    # parses parameters to a method call, all the grouping symbols must appear
-    # first in the parameter list before any hash parameters.
-    def group_by(*group_cols, **agg_cols)
-      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 = Table.new
-      groups.each_pair do |_vals, grp_rows|
-        result << row_from_group(grp_rows, group_cols, agg_cols)
-      end
-      result.normalize_boundaries
-      result
-    end
-
-    ############################################################################
-    # Footer methods
-    ############################################################################
-    def add_footer(label: 'Total', aggregate: :sum, heads: [])
-      foot = {}
-      heads.each do |h|
-        raise "No #{h} column in table to #{aggregate}" unless headers.include?(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
-
     private
 
     # Return an output row appropriate to the given join type, including all the
@@ -693,9 +773,9 @@ module FatCore
       # Translate any remaining row_b heads to append '_b' if they have the
       # same name as a row_a key.
       a_heads = row_a.keys
-      row_b = row_b.to_a.each.map do |k, v|
+      row_b = row_b.to_a.each.map { |k, v|
         [a_heads.include?(k) ? "#{k}_b".to_sym : k, v]
-      end.to_h
+      }.to_h
       row_a.merge(row_b)
     end
 
@@ -814,6 +894,53 @@ module FatCore
       self
     end
 
+    ###################################################################################
+    # Group By
+    ###################################################################################
+
+    public
+
+    # Return a Table with a single row for each group of rows in the input table
+    # 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 a aggregate function (:count, :sum,
+    # :min, :max, etc.), which defaults to the :first function, giving the value
+    # of that column for the first row in the group.  You can specify a
+    # different aggregate function for a column by adding a hash parameter with
+    # the column as the key and a symbol for the aggregate function as the
+    # value.  For example, consider the following call:
+    #
+    # tab.group_by(:date, :code, :price, shares: :sum, ).
+    #
+    # 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: hash 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. Because of the way Ruby
+    # parses parameters to a method call, all the grouping symbols must appear
+    # first in the parameter list before any hash parameters.
+    def group_by(*group_cols, **agg_cols)
+      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 = Table.new
+      groups.each_pair do |_vals, grp_rows|
+        result << row_from_group(grp_rows, group_cols, agg_cols)
+      end
+      result.normalize_boundaries
+      result
+    end
+
+    private
+
     def row_from_group(rows, grp_cols, agg_cols)
       new_row = {}
       grp_cols.each do |h|
@@ -821,7 +948,7 @@ module FatCore
       end
       agg_cols.each_pair do |h, agg_func|
         items = rows.map { |r| r[h] }
-        new_h = "#{agg_func}_#{h}"
+        new_h = "#{agg_func}_#{h}".as_sym
         new_row[new_h] = Column.new(header: h,
                                     items: items).send(agg_func)
       end
@@ -829,59 +956,16 @@ module FatCore
     end
 
     ############################################################################
-    # Table output methods.
+    # Table construction methods.
     ############################################################################
 
     public
 
-    # 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 = []
-
-      # Headers
-      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?
-
-      # Body
-      rows.each do |row|
-        out_row = []
-        headers.each do |hdr|
-          out_row << row[hdr].format_by(formats[hdr])
-        end
-        result << out_row
-      end
-
-      # Footers
-      footers.each_pair do |label, footer|
-        foot_row = []
-        columns.each do |col|
-          hdr = col.header
-          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. If mark is
     # true, mark this row as a boundary. All tables should be built ultimately
     # using this method as a primitive.
     def add_row(row, mark: false)
       row.each_pair do |k, v|
-        binding.pry if k.nil?
         key = k.as_sym
         columns << Column.new(header: k) unless column?(k)
         column(key) << v
@@ -900,104 +984,5 @@ module FatCore
       columns << col
       self
     end
-
-    class << self
-
-      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(hashes)
-        result = Table.new
-        hashes.each do |hsh|
-          if hsh.nil?
-            result.mark_boundary
-            next
-          end
-          result << hsh.to_h
-        end
-        result
-      end
-
-      # Construct a new table from an array of arrays. If the second element of
-      # the array is a nil, a string that looks like an hrule, or an array whose
-      # first element is a string that looks like an hrule, interpret the first
-      # element of the array as a row of headers. Otherwise, synthesize headers of
-      # the form "col1", "col2", ... and so forth. The remaining elements are
-      # taken as the body of the table, except that if an element of the outer
-      # array is a nil or a string that looks like an hrule, mark the preceding
-      # row as a boundary.
-      def from_array_of_arrays(rows)
-        result = Table.new
-        hrule_re = /\A\s*\|[-+]+/
-        headers = []
-        if rows[1].nil? || rows[1] =~ hrule_re || rows[1].first =~ hrule_re
-          # Take the first row as headers
-          # Use first row 0 as headers
-          headers = rows[0].map(&:as_sym)
-          first_data_row = 2
-        else
-          # Synthesize headers
-          headers = (1..rows[0].size).to_a.map { |k| "col#{k}".as_sym }
-          first_data_row = 0
-        end
-        rows[first_data_row..-1].each do |row|
-          if row.nil? || row[0] =~ hrule_re
-            result.mark_boundary
-            next
-          end
-          row = row.map { |s| s.to_s.strip }
-          hash_row = Hash[headers.zip(row)]
-          result << hash_row
-        end
-        result
-      end
-
-      def from_csv_io(io)
-        result = new
-        ::CSV.new(io, headers: true, header_converters: :symbol,
-                  skip_blanks: true).each do |row|
-          result << row.to_h
-        end
-        result
-      end
-
-      # Form rows of table by reading the first table found in the org file.
-      def from_org_io(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
-            unless line =~ hrule_re
-              line = line.sub(/\A\s*\|/, '').sub(/\|\s*\z/, '')
-              rows << line.split('|').map(&:clean)
-            end
-            table_found = true
-            next
-          end
-          break unless line =~ table_re
-          if !header_found && line =~ hrule_re
-            rows << nil
-            header_found = true
-            next
-          elsif header_found && line =~ hrule_re
-            # Mark the boundary with a nil
-            rows << nil
-          elsif line !~ table_re
-            # Stop reading at the second hline
-            break
-          else
-            line = line.sub(/\A\s*\|/, '').sub(/\|\s*\z/, '')
-            rows << line.split('|').map(&:clean)
-          end
-        end
-        from_array_of_arrays(rows)
-      end
-    end
   end
 end

data/lib/fat_core/version.rb

@@ -1,7 +1,7 @@
 module FatCore
   MAJOR = 1
-  MINOR = 6
-  PATCH = 0
+  MINOR = 7
+  PATCH = 1
 
   VERSION = [MAJOR, MINOR, PATCH].compact.join('.')
 end

data/lib/fat_core.rb

@@ -2,6 +2,7 @@
 require 'date'
 require 'active_support'
 require 'active_support/core_ext'
+require 'active_support/number_helper'
 require 'csv'
 
 require 'fat_core/version'
@@ -22,3 +23,4 @@ require 'fat_core/symbol'
 require 'fat_core/evaluator'
 require 'fat_core/column'
 require 'fat_core/table'
+require 'fat_core/formatters'