fat_table 0.5.5 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2f391d5e4ad9d7a4dcb303098b90f6fb42379d9df382192c4bacaf169523dab1
-  data.tar.gz: ea75f906fcd164752a3ca2220324ad10d8438562bb31c4846bc6575723e834fa
+  metadata.gz: f348d317c061becae08890ff02cc9c08789787d966f9ed88f3a4ef22b6eddb44
+  data.tar.gz: bf672b4f4f4ab07df465d06904ccebb9b48507177dc88a343eb09bfb0e98bc02
 SHA512:
-  metadata.gz: 2914c40a497cf24bcdba8868c4a4607ea1bdb0a94fba8caa3d6e31407ff6832621df2a0b4a8a2bb98c3b40080fed6d752f8e936f66a96270fe675e93d5a852d6
-  data.tar.gz: dbc43f4d2bac4a2a19bc7cc90d1fbfbf739a12f0f280a543670af588cfcf2bb0df74d50cfb7ded76b851f5470fd30d4f971659cead5131f9ea15e24b492e5823
+  metadata.gz: c721233a04cc1664e8d8acea3cf677190aa47da30b3db7e1b9f6c13ddd56028a8ecd8b0c71915d0a1703f46fc9a22a1c3a8a3f13d6c80fb07964a22fd864ab7e
+  data.tar.gz: 7877d4529d8a6f2a13ee0a1518730791b4e5ed7dbadd2030367593c95ccdbd5159e711f7ffe69b9b2fa9b4812a6f49d3d1a9fce46642e4454f54ff40d769a4cb

data/README.org

@@ -31,8 +31,9 @@ The following is for org.
   "Current version is: #{FatTable::VERSION}"
 #+end_src
 
+#+RESULTS:
 #+begin_EXAMPLE
-Current version is: 0.5.4
+Current version is: 0.6.0
 #+end_EXAMPLE
 
 * Introduction
@@ -148,6 +149,7 @@ org-mode buffer as an org-table, ready for processing by other code blocks.
       - [[#type-and-column-priority][Type and Column priority]]
     - [[#footers][Footers]]
       - [[#adding-footers][Adding Footers]]
+      - [[#dynamic-labels][Dynamic Labels]]
       - [[#aggregators][Aggregators]]
       - [[#footer-objects][Footer objects]]
       - [[#footer-examples][Footer Examples]]
@@ -534,6 +536,7 @@ You can create an empty table with ~FatTable::Table.new~ or, the shorter form,
 in the added rows determine the names of the headers:
 
 #+BEGIN_SRC ruby :results silent
+  require 'fat_table'
   tab = FatTable.new
   tab << { a: 1, b: 2, c: "<2017-01-21>", d: 'f', e: '' }
   tab << { a: 3.14, b: 2.17, c: '[2016-01-21 Thu]', d: 'Y', e: nil }
@@ -1754,8 +1757,6 @@ available in ~ft_console~ as ~@tab_a~ and ~@tab_b~:
     |  2 | Engineering |      2 |
     |  3 | Finance     |      7 |
     EOS
-
-  tab_b = FatTable.from_org_string(tab_b_str)
 #+END_SRC
 
 Here is ~tab_a~:
@@ -2465,7 +2466,6 @@ Finance&
  {:id=>"3", :dept=>"Finance", :emp_id=>"7"}]
 #+end_EXAMPLE
 
-
 *** Formatting Directives
 The formatting methods explained in the next section all take formatting
 directives as strings in which letters and other characters signify what
@@ -2706,12 +2706,27 @@ but not for other nils, such as in the last row of the ~:join_date~ column.
 
 *** Footers
 **** Adding Footers
-You can call the ~footer,~ ~gfooter, foot, and gfoot~ methods on ~Formatter~
-objects to add footers and group footers. Note that all of these methods
-return a ~Footer~ object that can be accessed to extract the computed values.
-All of these methods return the ~FatTable::Footer~ object so constructed. It
-can be used to access the values and other attributes of the footer
-computed. Their signatures are:
+You can call the ~foot~, ~gfoot~, ~footer,~ or ~gfooter~, methods on
+~Formatter~ objects to add footers and group footers. Note that all of these
+methods return a ~Footer~ object that can be accessed to extract the computed
+values.  All of these methods return the ~FatTable::Footer~ object so
+constructed. It can be used to access the values and other attributes of the
+footer computed. Their signatures are:
+
+- ~foot(label: label, label_col: nil, **agg_cols)~ :: where ~label~ is a label
+  to be placed in the column with header ~label_col~, or, if ommitted, in the
+  first cell of the footer (unless that column is named as one of the
+  ~agg_cols~, in which case the label is ignored), and ~**agg_cols~ is zero or
+  more hash-like parameters with a column symbol as a key and a valid
+  aggregate as the value. This causes a table-wide header to be added at the
+  bottom of the table applying ~agg~, to the ~agg_cols~. A table can have any
+  number of footers attached, and they will appear at the bottom of the output
+  table in the order they are given.
+
+- ~gfoot(label: 'Group Total', label_col: nil, **agg_cols)~ :: where the
+  parameters have the same meaning as for the ~foot~ method, but results in a
+  footer for each group in the table rather than the table as a whole. These
+  will appear in the output table just below each group.
 
 - ~footer(label, *sum_cols, **agg_cols)~ :: where ~label~ is a label to be
   placed in the first cell of the footer (unless that column is named as one
@@ -2724,26 +2739,11 @@ computed. Their signatures are:
   number of footers attached, and they will appear at the bottom of the output
   table in the order they are given.
 
-- ~foot(label, label_col, **agg_cols)~ :: where ~label~ is a label to be
-  placed in the column with header ~label_col~, or, if ommitted, in the first
-  cell of the footer (unless that column is named as one of the ~agg_cols~, in
-  which case the label is ignored), and ~**agg_cols~ is zero or more hash-like
-  parameters with a column symbol as a key and a valid aggregate as the
-  value. This causes a table-wide header to be added at the bottom of the
-  table applying ~agg~, to the ~agg_cols~. A table can have any number of
-  footers attached, and they will appear at the bottom of the output table in
-  the order they are given.
-
 - ~gfooter(label, *sum_cols, **agg_cols)~ :: where the parameters have the
   same meaning as for the ~footer~ method, but results in a footer for each
   group in the table rather than the table as a whole. These will appear in
   the output table just below each group.
 
-- ~gfoot(label, label_col, **agg_cols)~ :: where the parameters have the same
-  meaning as for the ~foot~ method, but results in a footer for each group in
-  the table rather than the table as a whole. These will appear in the output
-  table just below each group.
-
 There are also a number of convenience methods for adding common footers:
 - ~sum_footer(*cols)~ :: Add a footer summing the given columns with the label
      'Total'.
@@ -2762,6 +2762,39 @@ There are also a number of convenience methods for adding common footers:
 - ~max_gfooter(*cols)~ :: Add a group footer showing the maximum for the given
      columns with the label 'Group Maximum'.
 
+**** Dynamic Labels
+Most of the time, you will want a fixed string as the label.  However,
+especially in the case of a group footer, you might want a dynamically
+contructed label.  You can use a proc or lambda for a label, and it will be
+computed for you.  In the case of non-group footers, the proc takes a single
+parameter, the footer object itself.  This allows you to make the label a
+function of other footer values, for example, you could make the label
+include the most recent year from the date column:
+
+#+begin_src ruby
+  fmtr.foot(label: -> (f) { "Average (latest year #{f.column(:date).max.year})" },
+  temp: :avg)
+#+end_src
+
+In the case of a group footer, the lambda or proc may take either one or qtwo parameters.
+If it takes one, the parameter is simply the 0-based number of the group:
+
+#+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.
+
+If it takes two arguments, the second argument is the footer itself, as with
+non-group footers:
+
+#+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
+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.
+
 **** Aggregators
 When adding a footer with the above methods, you can specify an aggregator for
 each column named in the ~agg_cols~ parameter.  There are several candidates
@@ -2778,6 +2811,9 @@ for what you can use for an aggregator:
     In the case of datetime columns, these aggrgators convert the dates to
     julian date numbers, perform the calculation, then convert the result back
     to a datetime object.
+    Apart from the built-in aggrgators, you could define your own by opening the
+    FatTable::Column class and adding a suitable instance method.  In that
+    case, the symbol could also refer to the method you defined.
 - String :: using a string as an aggrgegator can result in:
   + the string being converted to an object matching the type of the column
     (for example, using '$1,888' in a numeric column puts the constant number
@@ -2792,11 +2828,16 @@ for what you can use for an aggregator:
 - A Lambda :: finally, you can provide a lambda for performing arbitrary
   calculations and placing the result in the footer field.  The number of
   arguments the lambda takes can vary:
-  * If the lambda is used in a group footer, it must take a single integer
-    argument that is set to the group number being calculated and /can/ take a
-    second argument for the column symbol in which it appears, or
-  * If the lambda is used in an ordinary footer, it either takes no arguments,
-    or a single argument for the column symbol in which it appears.
+  * If the lambda is used in an ordinary footer column, it can take 0, 1, or 2
+    arguments: (1) the first argument, if given, will be set to the
+    FatTable::Column object for that column and (2) the second argument, if
+    given, will be set to the Footer object itself.
+  * If the lambda is used in a group footer column, it can 0, 1, 2, or 3
+    arguments: (1) the first argument, if given, will be set to the group's
+    0-based index number, (2) the second argument, if given, will be set to a
+    FatTable::Column object consisting of those items in the group's column,
+    and (3) the third argument, if given, will be set to the Footer object
+    itself.
 
 **** Footer objects
 Each of the methods for adding a footer to a ~Formatter~ returns a ~Footer~ object
@@ -2820,7 +2861,6 @@ their computed values.  Here are the accessors available on a
   to the footer value for that column, nil for unused columns.  Use the index
   ~k~ to specify which group to access in the case of a group footer.
 
-
 **** Footer Examples
 As a reminder, here is the table, ~tab_a~ defined earlier:
 
@@ -2981,18 +3021,20 @@ But it can be any type.  Here we pick a lottery winner from the employee ids.
 #+end_EXAMPLE
 
 ***** Lambdas
-Perhaps the most flexible form of aggregator is a lambda form.  They require 2
-or 3 parameters in non-group and group footers, respectively:
-
-- ~->(f, c) {...}~ :: in a normal, non-group footer, you must provide for two
-  paramters: the first, ~f~, will be bound to the footer in which the lambda
-  appears and the second, ~c~, will be bound to the column header to which the
-  lambda is attached.
-- ~->(f, c, k)~ :: in a group footer, you must provide for three paramters:
-  the first, ~f~, will be bound to the footer in which the lambda appears, the
-  second, ~c~, will be bound to the column header to which the lambda is
-  attached, and the third, ~k~ will be bound to the group number of the group
-  being evaluated.
+Perhaps the most flexible form of aggregator is a lambda form.  They can take
+up to 2 or up to 3 parameters in non-group and group footers, respectively:
+
+- ~->(c, f) {...}~ :: in a normal, non-group footer, you may provide for up to
+  two paramters: the first, ~c~, if given, will be bound to the column header
+  to which the lambda is attached and and the second, ~f~, if given will be
+  bound to the footer in which the lambda appears.  A lambda with no
+  parameters can be provided as well if none are needed.
+- ~->(k, c, f)~ :: in a group footer, you may provide for up to three
+  paramters: the the first, ~k~, if provided, will be bound to the group
+  number of the group being evaluated, the second, ~c~, if provided, will be
+  bound to the column header to which the lambda is attached, and the third,
+  ~f~, will be bound to the footer in which the lambda appears. A lambda with
+  no parameters can be provided as well if none are needed.
 
 With the first argument, the footer itself becomes available and with it all
 the things accessible with the footers, including the items in the current
@@ -3003,7 +3045,7 @@ Compute the summ of the squares if the items in the ~:age~ column:
   tab_a.to_text do |f|
     f.format(numeric: '0.0R,', datetime: 'd[%v]D[%v]')
     f.footer('Average', age: :avg, salary: :avg, join_date: :avg)
-    f.footer('SSQ', age: ->(f, c) { sa = f.items(c).map {|x| x * x}.sum; Math.sqrt(sa) })
+    f.footer('SSQ', age: ->(c) { sa = c.items.map {|x| x * x}.sum; Math.sqrt(sa) })
   end
 #+END_SRC
 
@@ -3032,8 +3074,8 @@ summ of the squares if the ages in each group:
   tab_a.order_with('join_date.year').to_text do |f|
     f.format(numeric: '0.0R,', datetime: 'd[%v]D[%v]', sort_key: '0.0~,')
     f.footer('Average', age: :avg, salary: :avg, join_date: :avg)
-    f.gfooter('Group SSQ', age: ->(f, c, k) { sa = f.items(c, k).map {|x| x * x}.sum; Math.sqrt(sa) })
-    f.footer('Total SSQ', age: ->(f, c) { sa = f.items(c).map {|x| x * x}.sum; Math.sqrt(sa) })
+    f.gfooter('Group SSQ', age: ->(k, c, f) { sa = c.items.map {|x| x * x}.sum; Math.sqrt(sa) })
+    f.footer('Total SSQ', age: ->(c, f) { sa = c.items.map {|x| x * x}.sum; Math.sqrt(sa) })
   end
 #+END_SRC
 
@@ -3045,19 +3087,19 @@ summ of the squares if the ages in each group:
 +-----------+-------+-----+------------+--------+-------------+----------+
 | Group SSQ |       |  45 |            |        |             |          |
 +-----------+-------+-----+------------+--------+-------------+----------+
-|         1 | Paul  |  32 | California | 20,000 | 13-JUL-2001 |     2001 |
+|         1 | Paul  |  32 | California | 20,000 | 13-JUL-2001 | 2001     |
 +-----------+-------+-----+------------+--------+-------------+----------+
 | Group SSQ |       |  32 |            |        |             |          |
 +-----------+-------+-----+------------+--------+-------------+----------+
-|         2 | Allen |  25 | Texas      |        | 13-JUL-2005 |     2005 |
-|         8 | Paul  |  24 | Houston    | 20,000 | 13-JUL-2005 |     2005 |
-|         9 | James |  44 | Norway     |  5,000 | 13-JUL-2005 |     2005 |
+|         2 | Allen |  25 | Texas      |        | 13-JUL-2005 | 2005     |
+|         8 | Paul  |  24 | Houston    | 20,000 | 13-JUL-2005 | 2005     |
+|         9 | James |  44 | Norway     |  5,000 | 13-JUL-2005 | 2005     |
 +-----------+-------+-----+------------+--------+-------------+----------+
 | Group SSQ |       |  56 |            |        |             |          |
 +-----------+-------+-----+------------+--------+-------------+----------+
-|         3 | Teddy |  23 | Norway     | 20,000 | 13-DEC-2007 |     2007 |
-|         4 | Mark  |  25 | Rich-Mond  | 65,000 | 13-DEC-2007 |     2007 |
-|         5 | David |  27 | Texas      | 85,000 | 13-DEC-2007 |     2007 |
+|         3 | Teddy |  23 | Norway     | 20,000 | 13-DEC-2007 | 2007     |
+|         4 | Mark  |  25 | Rich-Mond  | 65,000 | 13-DEC-2007 | 2007     |
+|         5 | David |  27 | Texas      | 85,000 | 13-DEC-2007 | 2007     |
 +-----------+-------+-----+------------+--------+-------------+----------+
 | Group SSQ |       |  43 |            |        |             |          |
 +-----------+-------+-----+------------+--------+-------------+----------+

data/lib/fat_table/footer.rb

@@ -2,7 +2,7 @@
 
 module FatTable
   class Footer
-    attr_reader :table, :label, :label_col, :values, :group
+    attr_reader :table, :label_col, :values, :group
 
     ###########################################################################
     # Constructors
@@ -15,6 +15,7 @@ module FatTable
     # for the footer are added later with the #add_value method.
     def initialize(label = 'Total', table, label_col: nil, group: false)
       @label = label
+
       unless table.is_a?(Table)
         raise ArgumentError, 'Footer.new needs a table argument'
       end
@@ -30,14 +31,7 @@ module FatTable
       @group = group
       @group_cols = {}
       @values = {}
-      if group
-        @values[@label_col] = []
-        table.number_of_groups.times do
-          @values[@label_col] << @label
-        end
-      else
-        @values[@label_col] = [@label]
-      end
+      insert_labels_in_label_col
       make_accessor_methods
     end
 
@@ -71,6 +65,11 @@ module FatTable
       end
     end
 
+    # Return the value of the label, for the kth group if grouped.
+    def label(k = 0)
+      calc_label(k)
+    end
+
     # :category: Accessors
 
     # Return the value of under the +key+ header, or if this is a group
@@ -108,8 +107,10 @@ module FatTable
       if group && k.nil?
         raise ArgumentError, 'Footer#column(h, k) missing the group number argument k'
       end
+
       if group
-        k.nil? ? @group_cols[h] : @group_cols[h][k]
+        @group_cols[h] ||= table.group_cols(h)
+        @group_cols[h][k]
       else
         table.column(h)
       end
@@ -151,14 +152,13 @@ module FatTable
 
     # Evaluate the given agg for the header col and, in the case of a group
     # footer, the group k.
-    def calc_val(agg, col, k = nil)
-      column =
-        if group
-          @group_cols[col] ||= table.group_cols(col)
-          @group_cols[col][k]
-        else
-          table.column(col)
-        end
+    def calc_val(agg, h, k = nil)
+      column = column(h, k)
+
+      # Convert Date and Time objects to DateTime
+      if [Date, Time].include?(agg.class)
+        agg = agg.to_datetime
+      end
 
       case agg
       when Symbol
@@ -179,29 +179,69 @@ module FatTable
       when Proc
         result =
           if group
-            unless agg.arity == 3
-              msg = 'a lambda used in a group footer must have three arguments: (f, c, k)'
+            case agg.arity
+            when 0
+              agg.call
+            when 1
+              agg.call(k)
+            when 2
+              agg.call(k, column)
+            when 3
+              agg.call(k, column, self)
+            else
+              msg = 'a lambda used in a group footer may have 0 to 3  three arguments: (k, c, f)'
               raise ArgumentError, msg
             end
-            agg.call(self, col, k)
           else
-            unless agg.arity == 2
-              msg = 'a lambda used in a non-group footer must have two arguments: (f, c)'
+            case agg.arity
+            when 0
+              agg.call
+            when 1
+              agg.call(column)
+            when 2
+              agg.call(column, self)
+            else
+              msg = 'a lambda used in a non-group footer may have 0 to 2 arguments: (c, f)'
               raise ArgumentError, msg
             end
-            agg.call(self, col)
           end
-        # Make sure the result returned can be inserted into footer field.
-        case result
-        when Symbol, String
-          calc_val(result, col, k)
-        when column.type.constantize
-          result
+        # Pass the result back into this method as the new agg
+        calc_val(result, h, k)
+      else
+        agg.to_s
+      end
+    end
+
+    # Insert a possibly calculated value for the label in the appropriate
+    # @values column.
+    def insert_labels_in_label_col
+      if group
+        @values[@label_col] = []
+        table.number_of_groups.times do |k|
+          @values[@label_col] << calc_label(k)
+        end
+      else
+        @values[@label_col] = [calc_label(0)]
+      end
+    end
+
+    # Calculate the label for the kth group, using k = 0 for non-group
+    # footers.  If the label is a proc, call it with the group number.
+    def calc_label(k)
+      case @label
+      when Proc
+        case @label.arity
+        when 0
+          @label.call
+        when 1
+          @label.call(k)
+        when 2
+          @label.call(k, self)
         else
-          raise ArgumentError, "lambda cannot return an object of class #{result.class}"
+          raise ArgumentError, "footer label proc may only have 1 argument for group number k"
         end
       else
-        agg
+        @label.to_s
       end
     end
 

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] } )
     #
-    def foot(label, label_col = nil, **agg_cols)
+    # 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: '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)

data/lib/fat_table/version.rb

@@ -2,5 +2,5 @@
 
 module FatTable
   # The current version of FatTable
-  VERSION = '0.5.5'
+  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.5
+  version: 0.6.0
 platform: ruby
 authors:
 - Daniel E. Doherty
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2022-03-25 00:00:00.000000000 Z
+date: 2022-03-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler