fat_table 0.5.3 → 0.6.0

data/lib/fat_table/formatters/formatter.rb

@@ -181,41 +181,74 @@ module FatTable
     end
 
     # :category: Add Footers
-
-    # A simpler method for adding a footer to the formatted output having the
-    # label +label+ placed in the column with the header +label_col+ or in the
-    # first column if +label_col+ is ommitted.  The remaining hash arguments
-    # apply an aggregate to the values of the column, which can be:
-    #
-    # (1) a symbol representing one of the builtin aggregates, i.e., :first,
-    # :last, :range, :sum, :count, :min, :max, :avg, :var, :pvar, :dev, :pdev,
-    # :any?, :all?, :none?, and :one?,
     #
-    # (2) an arbitrary value of one of the four supported types: Boolean,
-    # DateTime, Numeric, or String: true, false, 3.14159, 'Total debits', or a
-    # string that is convertible into one of these types by the usual methods
-    # used in contructing a table,
+    # A keyword method for adding a footer to the formatted output having the
+    # label +label:+ (default 'Total') placed in the column with the header
+    # +label_col:+ or in the first column if +label_col+ is ommitted.
+    # This assigns a fixed group label to be placed in the :date column:
+    # #+begin_src ruby
+    #   fmtr.foot(label: "Year's Average", label_col: :date, temp: avg)
+    # #+end_src
+    #
+    # Besides being a fixed string, the +label:+ can also be a proc or lambda
+    # taking one argument, the foooter itself.
+    # Thus, a label such as:
+    #
+    # #+begin_src ruby
+    #     fmtr.foot(label: -> (f) { "Average (latest year #{f.column(:date).max.year})" },
+    #                temp: :avg)
+    # #+end_src
+    # And this would add the highest number to label, assuming the :date column
+    # of the footer's table had the year for each item.
+    #
+    # The remaining hash arguments apply an aggregate to the values of the
+    # column, which can be:
+    #
+    # 1. a symbol representing one of the builtin aggregates, i.e., :first,
+    #    :last, :range, :sum, :count, :min, :max, :avg, :var, :pvar, :dev,
+    #    :pdev, :any?, :all?, :none?, and :one?, or a symbol for your own
+    #    aggregate defined as an instance method on FatTable::Column.
+    # 2. a fixed string, but it the string can be converted into the Column's
+    #    type, it will be converted, so the string '3.14159' will be converted
+    #    to 3.14159 in a Numeric column.
+    # 3. a value of the Column's type, so Date.today would simply be evaluated
+    #    for a Numeric column.
+    # 4. most flexibly of all, a proc or lambda taking arguments: f, the
+    #    footer object itself; c, the column (or in the case of a group
+    #    footer, the sub-column) corresponding to the current header, and in
+    #    the case of a group footer, k, the number of the group (0-based).
+    # 5. Any other value is converted to a string with #to_s.
     #
     # Examples:
     #
     # Put the label in the :dickens column of the footer and the maximum value
     # from the :alpha column in the :alpha column of the footer.
     #
-    #   fmtr.foot('Best', :dickens, alpha: :max)
+    #   fmtr.foot(label: 'Best', label_col: :dickens, alpha: :max)
     #
     # Put the label 'Today' in the first column of the footer and today's date
     # in the :beta column.
     #
-    #   fmtr.foot('Today', beta: Date.today)
+    #   fmtr.foot(label: 'Today', beta: Date.today)
     #
     # Put the label 'Best' in the :dickens column of the footer and the string
     # 'Tale of Two Cities' in the :alpha column of the footer.  Since it can't
     # be interpreted as Boolean, Numeric, or DateTime, it is placed in the
     # footer literally.
     #
-    #   fmtr.foot('Best', :dickens, alpha: 'A Tale of Two Cities')
+    #   fmtr.foot(label: 'Best', label_col: :dickens, alpha: 'A Tale of Two
+    #   Cities')
+    #
+    # Use a lambda to calculate the value to be placed in the column :gamma.
+    #
+    #   fmtr.foot(label: 'Gamma', beta: :avg, gamma: ->(f, c) {
+    #     (Math.gamma(c.count) + f[:beta] } )
+    #
+    # Note that this way a footer can be made a function of the other footer
+    # values (using f[:other_col]) as well as the Column object corresponding
+    # to the lamda's column.
     #
-    def foot(label, label_col = nil, **agg_cols)
+    def foot(label: 'Total', label_col: nil, **agg_cols)
       foot = Footer.new(label, table, label_col: label_col)
       agg_cols.each_pair do |h, agg|
         foot.add_value(h, agg)
@@ -255,9 +288,92 @@ module FatTable
       foot
     end
 
-    # Add a group footer to the formatted output.  This method has the same
-    # usage as the #foot method, but it adds group footers.
-    def gfoot(label, label_col = nil, **agg_cols)
+    # :category: Add Footers
+    #
+    # A keyword method for adding a group footer to the formatted output
+    # having the label +label:+ (default 'Total') placed in the column with
+    # the header +label_col:+ or in the first column if +label_col+ is
+    # ommitted.
+    #
+    # This assigns a fixed group label to be placed in the :date column:
+    # #+begin_src ruby
+    #   fmtr.gfoot(label: "Year's Average", label_col: :date, temp: avg)
+    # #+end_src
+    #
+    # Besides being a fixed string, the +label:+ can also be a proc or lambda
+    # taking one or two arguments.  In the one argument form, the argument is
+    # the group number k.  If a second argument is specified, the foooter
+    # itself is passed as the argument.  Thus, a label such as:
+    #
+    # #+begin_src ruby
+    #   fmtr.gfoot(label: -> (k) { "Group #{(k+1).to_roman} Average" }, temp: :avg)
+    # #+end_src
+    # This would format the label with a roman numeral (assuming you defined a
+    # method to do so) for the group number.
+    #
+    # #+begin_src ruby
+    #     fmtr.gfoot(label: -> (k, f) { "Year #{f.column(:date, k).max.year} Group #{(k+1).to_roman} Average" },
+    #                temp: :avg)
+    # #+end_src
+    # And this would add the group's year to label, assuming the :date column
+    # of the footer's table had the same year for each item in the group.
+    #
+    #
+    # The remaining hash arguments apply an aggregate to the values
+    # of the column, which can be:
+    #
+    # 1. a symbol representing one of the builtin aggregates, i.e., :first,
+    #    :last, :range, :sum, :count, :min, :max, :avg, :var, :pvar, :dev,
+    #    :pdev, :any?, :all?, :none?, and :one?, or a symbol for your own
+    #    aggregate defined as an instance method on FatTable::Column.
+    # 2. a fixed string, but it the string can be converted into the Column's
+    #    type, it will be converted, so the string '3.14159' will be converted
+    #    to 3.14159 in a Numeric column.
+    # 3. a value of the Column's type, so Date.today would simply be evaluated
+    #    for a Numeric column.
+    # 4. most flexibly of all, a proc or lambda taking arguments: f, the
+    #    footer object itself; c, the column (or in the case of a group
+    #    footer, the sub-column) corresponding to the current header, and k,
+    #    this group's group number (0-based).
+    # 5. Any other value is converted to a string with #to_s.
+    #
+    # Examples:
+    #
+    # Put the label in the :dickens column of the footer and the maximum value
+    # from the :alpha column in the :alpha column of the footer.
+    #
+    # #+begin_src ruby
+    #   fmtr.gfoot(label: 'Best', label_col: :dickens, alpha: :max)
+    # #+end_src
+    #
+    # Put the label 'Today' in the first column of the footer and today's date
+    # in the :beta column.
+    #
+    # #+begin_src ruby
+    #   fmtr.gfoot(label: 'Today', beta: Date.today)
+    # #+end_src
+    #
+    # Put the label 'Best' in the :dickens column of the footer and the string
+    # 'Tale of Two Cities' in the :alpha column of the footer.  Since it can't
+    # be interpreted as Boolean, Numeric, or DateTime, it is placed in the
+    # footer literally.
+    #
+    # #+begin_src ruby
+    #   fmtr.gfoot(label: 'Best', label_col: :dickens, alpha: 'A Tale of Two
+    #   Cities')
+    # #+end_src
+    #
+    # Use a lambda to calculate the value to be placed in the column :gamma.
+    #
+    # #+begin_src ruby
+    #   fmtr.gfoot(label: 'Gamma', beta: :avg, gamma: ->(f, c) {
+    #     (Math.gamma(c.count) + f[:beta] } )
+    # #+end_src
+    #
+    # Note that this way a footer can be made a function of the other footer
+    # values (using f[:other_col]) as well as the Column object corresponding
+    # to the lamda's column.
+    def gfoot(label: 'Group Total', label_col: nil, **agg_cols)
       foot = Footer.new(label, table, label_col: label_col, group: true)
       agg_cols.each_pair do |h, agg|
         foot.add_value(h, agg)
@@ -532,7 +648,7 @@ module FatTable
       valid_keys = table.headers + %i[string numeric datetime boolean nil]
       invalid_keys = (fmts.keys - valid_keys).uniq
       unless invalid_keys.empty?
-        msg = "invalid #{location} column or type: #{invalid_keys.join(',')}"
+        msg = "invalid #{location} column or type: #{invalid_keys.join(', ')}"
         raise UserError, msg
       end
 
@@ -562,20 +678,21 @@ module FatTable
           end
         end
 
-        # Merge in formatting for column h based on the column type, or based
-        # on the string type for the header location.
+        # Merge in formatting instructions for column h based on the column
+        # name, or if there is no formatting instructions for the column by
+        # name, merge in the formatting instructions based on the column's
+        # type.  Insist on only the string type for the header location.
         typ = (location == :header ? :string : table.type(h).as_sym)
         parse_typ_method_name = 'parse_' + typ.to_s + '_fmt'
-        if fmts.key?(typ)
-          # Merge in type-based formatting
-          typ_fmt = send(parse_typ_method_name, fmts[typ]).first
-          format_h = format_h.merge(typ_fmt)
-        end
         if fmts[h]
           # Merge in column formatting
           col_fmt = send(parse_typ_method_name, fmts[h],
                          strict: location != :header).first
           format_h = format_h.merge(col_fmt)
+        elsif fmts.key?(typ)
+          # Merge in type-based formatting
+          typ_fmt = send(parse_typ_method_name, fmts[typ]).first
+          format_h = format_h.merge(typ_fmt)
         end
 
         # Copy :body formatting for column h to :bfirst and :gfirst if they
@@ -1003,9 +1120,14 @@ module FatTable
     # converted to strings formatted according to the Formatter's formatting
     # directives given in Formatter.format_for or Formatter.format.
     def output
-      # This results in a hash of two-element arrays. The key is the header and
-      # the value is an array of the header and formatted header. We do the
-      # latter so the structure parallels the structure for rows explained next.
+      # If there are neither headers nor any rows in the table, return an
+      # empty string.
+      return '' if table.empty? && table.headers.empty?
+
+      # This results in a hash of two-element arrays. The key
+      # is the header and the value is an array of the header and formatted
+      # header. We do the latter so the structure parallels the structure for
+      # rows explained next.
       formatted_headers = build_formatted_headers
 
       # These produce an array with each element representing a row of the

data/lib/fat_table/formatters/org_formatter.rb

@@ -20,7 +20,7 @@ module FatTable
     end
 
     def pre_header(widths)
-      result = '|'
+      result = +'|'
       widths.each_value do |w|
         result += '-' * (w + 2) + '+'
       end
@@ -53,7 +53,7 @@ module FatTable
     end
 
     def hline(widths)
-      result = '|'
+      result = +'|'
       widths.each_value do |w|
         result += '-' * (w + 2) + '+'
       end
@@ -62,7 +62,7 @@ module FatTable
     end
 
     def post_footers(widths)
-      result = '|'
+      result = +'|'
       widths.each_value do |w|
         result += '-' * (w + 2) + '+'
       end

data/lib/fat_table/formatters/term_formatter.rb

@@ -221,7 +221,7 @@ module FatTable
     end
 
     def pre_header(widths)
-      result = upper_left
+      result = +upper_left
       widths.each_value do |w|
         result += double_rule * (w + 2) + upper_tee
       end
@@ -255,7 +255,7 @@ module FatTable
     end
 
     def hline(widths)
-      result = left_tee
+      result = +left_tee
       widths.each_value do |w|
         result += horizontal_rule * (w + 2) + single_cross
       end
@@ -289,7 +289,7 @@ module FatTable
     end
 
     def post_footers(widths)
-      result = lower_left
+      result = +lower_left
       widths.each_value do |w|
         result += double_rule * (w + 2) + lower_tee
       end

data/lib/fat_table/formatters/text_formatter.rb

@@ -16,7 +16,7 @@ module FatTable
     end
 
     def pre_header(widths)
-      result = '+'
+      result = +'+'
       widths.each_value do |w|
         result += '=' * (w + 2) + '+'
       end
@@ -49,7 +49,7 @@ module FatTable
     end
 
     def hline(widths)
-      result = '+'
+      result = +'+'
       widths.each_value do |w|
         result += '-' * (w + 2) + '+'
       end
@@ -82,7 +82,7 @@ module FatTable
     end
 
     def post_footers(widths)
-      result = '+'
+      result = +'+'
       widths.each_value do |w|
         result += '=' * (w + 2) + '+'
       end

data/lib/fat_table/table.rb

@@ -105,7 +105,7 @@ module FatTable
       unless heads.empty?
         heads.each do |h|
           if h.to_s.end_with?('!') || @tolerant_columns.include?(h)
-            @columns << Column.new(header: h.to_s.sub(/!\s*\z/, ''), tolerant: true)
+            @columns << Column.new(header: h.to_s.sub(/!\s*\z/, ''), type: 'String')
           else
             @columns << Column.new(header: h)
           end
@@ -120,7 +120,7 @@ module FatTable
     # though FatTable::Table objects have no instance variables, a class that
     # inherits from it might.
     def empty_dup
-      self.dup.__empty!
+      dup.__empty!
     end
 
     def __empty!
@@ -779,7 +779,6 @@ module FatTable
       last_key = nil
       new_rows.each_with_index do |nrow, k|
         new_tab << nrow
-        # key = nrow.fetch_values(*sort_heads)
         key = nrow.fetch_values(*key_hash.keys)
         new_tab.mark_boundary(k - 1) if last_key && key != last_key
         last_key = key
@@ -1712,11 +1711,19 @@ module FatTable
     end
 
     # The <=> operator cannot handle nils without some help.  Treat a nil as
-    # smaller than any other value, but equal to other nils.  The two keys are assumed to be arrays of values to be
-    # compared with <=>.
+    # smaller than any other value, but equal to other nils.  The two keys are
+    # assumed to be arrays of values to be compared with <=>.  Since
+    # tolerant_columns permit strings to be mixed in with columns of type
+    # Numeric, DateTime, and Boolean, treat strings mixed with another type
+    # the same as nils.
     def compare_with_nils(key1, key2)
       result = nil
       key1.zip(key2) do |k1, k2|
+        if k1.is_a?(String) && !k2.is_a?(String)
+          k1 = nil
+        elsif !k1.is_a?(String) && k2.is_a?(String)
+          k2 = nil
+        end
         if k1.nil? && k2.nil?
           result = 0
           next

data/lib/fat_table/version.rb

@@ -2,5 +2,5 @@
 
 module FatTable
   # The current version of FatTable
-  VERSION = '0.5.3'
+  VERSION = '0.6.0'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: fat_table
 version: !ruby/object:Gem::Version
-  version: 0.5.3
+  version: 0.6.0
 platform: ruby
 authors:
 - Daniel E. Doherty
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2022-01-24 00:00:00.000000000 Z
+date: 2022-03-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -332,7 +332,7 @@ licenses: []
 metadata:
   allowed_push_host: https://rubygems.org
   yard.run: yri
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -348,7 +348,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubygems_version: 3.3.3
-signing_key: 
+signing_key:
 specification_version: 4
 summary: Provides tools for working with tables as a data type.
 test_files: []