fat_table 0.9.9 → 1.0.0

data/Rakefile

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'bundler/gem_tasks'
 require 'rspec/core/rake_task'
 require 'rdoc/task'
@@ -13,4 +15,7 @@ end
 
 RSpec::Core::RakeTask.new(:spec)
 
+require "gem_docs"
+GemDocs.install
+
 task :default => [:spec, :rubocop]

data/bin/ft_console

@@ -1,4 +1,5 @@
 #!/usr/bin/env ruby
+# frozen_string_literal: true
 
 require 'bundler/setup'
 require 'fat_table'

data/fat_table.gemspec

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 lib = File.expand_path('../lib', __FILE__)
 $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 require 'fat_table/version'

data/lib/{ext → core_ext}/array.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 class Array
   # Map booleans true to 1 and false to 0 so they can be compared in a sort
   # with the <=> operator.

data/lib/core_ext/numeric_string.rb

@@ -0,0 +1,196 @@
+# frozen_string_literal: true
+
+require 'debug'
+
+# This refinement contains methods that extend the String class to massage
+# strings that represent numbers, such as adding commas, pre- and
+# post-padding, etc.
+module NumericString
+  # You can control how NumericString behaves by supplying a new
+  # NumericString::Config to the config: parameter of these methods.  Calling
+  # `NumericString::Config.build` gives you the deafult configuration with
+  # whatever overrides you give it.  You can also modify an existing config
+  # with some overrides. For example:
+  #
+  # #+begin_src ruby
+  #   cfg = NumericString::Config.build(group_size: 4)
+  #   cfg2 = cfg.with(group_char: '_')
+  #
+  #   "1234567.89".add_grouping(config: cfg)
+  #   => "123,4567.89"
+  #   "1234567.89".add_grouping(config: cfg2)
+  #   => '123_4567.89'
+  # #+end_src
+  Config = Struct.new(
+    :group_char,
+    :group_size,
+    :decimal_char,
+    :currency_symbol,
+    :pre_pad_char,
+    :post_pad_char,
+    keyword_init: true,
+  ) do
+    DEFAULTS = {
+      group_char: ',',
+      group_size: 3,
+      decimal_char: '.',
+      currency_symbol: '$',
+      pre_pad_char: '0',
+      post_pad_char: '0',
+    }.freeze
+
+    def self.default
+      @default ||= new(**DEFAULTS).freeze
+    end
+
+    # Build from defaults, overriding selectively
+    def self.build(**overrides)
+      new(**DEFAULTS.merge(overrides)).freeze
+    end
+
+    # Clone-with-changes (very Ruby, very nice)
+    def with(**overrides)
+      self.class.build(
+        group_char:      overrides.fetch(:group_char, group_char),
+        group_size:      overrides.fetch(:group_size, group_size),
+        decimal_char:    overrides.fetch(:decimal_char, decimal_char),
+        currency_symbol: overrides.fetch(:currency_symbol, currency_symbol),
+        pre_pad_char: overrides.fetch(:pre_pad_char, pre_pad_char),
+        post_pad_char: overrides.fetch(:post_pad_char, post_pad_char),
+      )
+    end
+  end
+
+  refine String do
+    # If self is a valid decimal number, add grouping commas to the whole
+    # part, retaining any fractional part and currency symbol undisturbed.
+    # The optional cond: parameter can contain a test to determine if the
+    # grouping ought to be performed.  If (1) self is not a valid decimal
+    # number string, (2) the whole part already contains grouping characters,
+    # or (3) cond: is falsey, return self.
+    def add_grouping(cond: true, config: Config.default)
+      return self unless cond
+      return self unless valid_num?(config:)
+
+      cur, whole, frac = cur_whole_frac(config:)
+      return self if whole.include?(config.group_char)
+
+      whole = whole.split('').reverse
+                .each_slice(config.group_size).to_a
+                .map { |a| a.reverse.join }
+                .reverse
+                .join(config.group_char)
+      cur + whole + frac
+    end
+
+    alias_method :add_commas, :add_grouping
+
+    # If self is a valid decimal number, add the currency symbol (per
+    # NumericString::Config.currency_symbol) to the front of the number
+    # string, retaining any grouping characters undisturbed.  The optional
+    # cond: parameter can contain a test to determine if the currency symbol
+    # ought to be pre-pended.  If (1) self is not a valid decimal number
+    # string, (2) the currency symbol is already present, or (3) cond: is
+    # falsey, return self.
+    def add_currency(cond: true, config: Config.default)
+      return self unless cond
+      return self unless valid_num?(config:)
+
+      md = match(num_re(config:))
+      return self unless md[:cur].blank?
+
+      config.currency_symbol + self
+    end
+
+    def add_pre_digits(n, cond: true, config: Config.default)
+      return self unless cond
+      return self if n <= 0
+      return self unless valid_num?(config:)
+
+      cur, whole, frac = cur_whole_frac(config:)
+      n_pads = [n - whole.delete(config.group_char).size, 0].max
+      padding = config.pre_pad_char * n_pads
+      "#{cur}#{padding}#{whole}#{frac}"
+    end
+
+    def add_post_digits(n, cond: true, config: Config.default)
+      return self unless cond
+      return self unless valid_num?(config:)
+
+      cur, whole, frac = cur_whole_frac(config:)
+      frac_digs = frac.size - 1 # frac includes the decimal character
+      if n >= frac_digs
+        n_pads = [n - frac_digs, 0].max
+        padding = config.post_pad_char * n_pads
+        "#{cur}#{whole}#{frac}#{padding}"
+      elsif n.zero?
+        # Round up last digit of whole if first digit of frac >= 5
+        if frac[1].to_i >= 5
+          whole = whole[0..-2] + (whole[-1].to_i + 1).to_s
+        end
+        # No fractional part
+        "#{cur}#{whole}"
+      elsif n.negative?
+        # This calls for rounding the whole part to nearest 10^n.abs and
+        # dropping the frac part.
+        ndigs_in_whole = whole.delete(config.group_char).size
+        nplaces = [ndigs_in_whole - 1, n.abs].min
+        # Replace the right-most nplaces digs with the pre-pad character.
+        replace_count = 0
+        new_whole = +''
+        round_char = whole.delete(config.group_char)[-1]
+        rounded = false
+        whole.split('').reverse_each do |c|
+          if c == config.group_char
+            new_whole << c
+          elsif replace_count < nplaces
+            new_whole << config.pre_pad_char
+            round_char = c
+            replace_count += 1
+          elsif !rounded
+            new_whole <<
+              if round_char.to_i >= 5
+                (c.to_i + 1).to_s
+              else
+                c
+              end
+            rounded = true
+          else
+            new_whole << c
+          end
+        end
+        "#{cur}#{new_whole.reverse}"
+      else
+        # We have to shorten the fractional part, which required rounding.
+        last_frac_dig = frac[n]
+        following_frac_dig = frac[n + 1]
+        if following_frac_dig.to_i >= 5
+          last_frac_dig = (last_frac_dig.to_i + 1).to_s
+        end
+        frac = frac[0..(n - 1)] + last_frac_dig
+        padding = ''
+        "#{cur}#{whole}#{frac}#{padding}"
+      end
+    end
+
+    private
+
+    def num_re(config: Config.default)
+      cur_sym = Regexp.quote(config.currency_symbol)
+      grp_char = Regexp.quote(config.group_char)
+      dec_char = Regexp.quote(config.decimal_char)
+      /\A(?<cur>#{cur_sym})?(?<whole>[0-9#{grp_char}]+)(?<frac>#{dec_char}[0-9]*)?\z/
+    end
+
+    # Return the currency, whole and fractional parts of a string with a possible
+    # decimal point attached to the frac part if present.
+    def cur_whole_frac(config: Config.default)
+      match = match(num_re(config:))
+      [match[:cur].to_s, match[:whole].to_s, match[:frac].to_s]
+    end
+
+    def valid_num?(config: Config.default)
+      match?(num_re(config:))
+    end
+  end
+end

data/lib/core_ext.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+require_relative 'core_ext/array'
+require_relative 'core_ext/numeric_string'

data/lib/fat_table/column.rb

@@ -86,7 +86,11 @@ module FatTable
     #   col.header #=> :prices
     #   col.sum #=> 18376.75
     #
-    # @param
+    # @param header [String, Symbol] the name of the column header
+    # @param items [Array<String>, Array<DateTime>, Array<Numeric>, Array<Boolean>] the initial data items in column
+    # @param type [String] the column type: 'String', 'Numeric', 'DateTime', 'Boolean', or 'NilClass'
+    # @param tolerant [Boolean] whether the column accepts unconvertable items not of its type as Strings
+    # @return [Column] the new Column
     def initialize(header:, items: [], type: 'NilClass', tolerant: false)
       @raw_header = header
       @header =

data/lib/fat_table/convert.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module FatTable
   module Convert
     # Convert val to the type of key, a ruby class constant, such as Date,

data/lib/fat_table/footer.rb

@@ -213,7 +213,7 @@ module FatTable
     end
 
     # Insert a possibly calculated value for the label in the appropriate
-    # @values column.
+    # `@values` column.
     def insert_labels_in_label_col
       if group
         @values[@label_col] = []

data/lib/fat_table/formatters/formatter.rb

@@ -67,7 +67,7 @@ module FatTable
         bgcolor: 'none',
         hms: false,
         pre_digits: 0,
-        post_digits: 0,
+        post_digits: 4,
         commas: false,
         currency: false,
         datetime_fmt: '%F %H:%M:%S',
@@ -1026,63 +1026,37 @@ module FatTable
     # above. Only device-independent formatting is done here. Device dependent
     # formatting (e.g., color) can be done in a subclass of Formatter by
     # specializing this method.
+
+    using NumericString
+
     def format_numeric(val, istruct)
       return istruct[:nil_text] if val.nil?
       return val.secs_to_hms if istruct[:hms]
 
-      if istruct[:commas]
-        # Commify the whole number part if not done already.
-        result = val.commas(istruct[:post_digits])
-      else
-        result = val.round(istruct[:post_digits]).to_s
-        match = result.match(/\.(\d+)\z/)
-        if match && (match[1]&.size&.< istruct[:post_digits])
-          # Add trailing zeros to pad out post_digits
-          n_zeros = [istruct[:post_digits] - match[1].size, 0].max
-          zeros = '0' * n_zeros
-          result += zeros
-        end
-        result
-      end
-
-      if istruct[:pre_digits].positive?
-        match = result.match(/\A([\d,]+)(\.\d+)?\z/)
-        whole_part = match[1]
-        frac_part = match[2]
-        n_zeros = [istruct[:pre_digits] - whole_part.delete(',').size, 0].max
-        result =
-          if n_zeros.positive?
-            if istruct[:commas]
-              # Insert leading zeros with commas
-              pre_comma_match = whole_part.match(/\A(\d+),/)
-              if pre_comma_match
-                n_partial_zeros = 3 - pre_comma_match[1].size
-                whole_part = "0" * n_partial_zeros + whole_part
-                n_zeros -= n_partial_zeros
-              end
-              zeros = ''
-              if n_zeros.positive?
-                zeros = "0" * n_zeros
-                if n_zeros > 3 && istruct[:commas]
-                  zeros = zeros.reverse.gsub!(/([0-9]{3})/, "\\1,").reverse
-                end
-              end
-              "#{zeros},#{whole_part}#{frac_part}"
-            else
-              # Insert leading zeros without commas
-              zeros = "0" * n_zeros
-              "#{zeros}#{whole_part}#{frac_part}"
-            end
-          else
-            "#{whole_part}#{frac_part}"
-          end
+      case val
+      when Integer
+        val.to_s
+          .add_pre_digits(istruct[:pre_digits], cond: istruct[:pre_digits].positive?)
+          .add_commas(cond: istruct[:commas])
+          .add_currency(cond: istruct[:currency])
+      when Rational
+        num = val.numerator.to_s
+                .add_pre_digits(istruct[:pre_digits], cond: istruct[:pre_digits].positive?)
+                .add_commas(cond: istruct[:commas])
+                .add_currency(cond: istruct[:currency])
+        den = val.denominator.to_s
+                .add_pre_digits(istruct[:pre_digits], cond: istruct[:pre_digits].positive?)
+                .add_commas(cond: istruct[:commas])
+        "#{num}/#{den}"
+      when Float, BigDecimal
+        val.to_s
+          .add_pre_digits(istruct[:pre_digits], cond: istruct[:pre_digits].positive?)
+          .add_post_digits(istruct[:post_digits])
+          .add_commas(cond: istruct[:commas])
+          .add_currency(cond: istruct[:currency])
       else
-        result
-      end
-      if istruct[:currency]
-        result = "#{FatTable.currency_symbol}#{result}"
+        raise ArgumentError, "cannot apply format_numeric to #{val} of class #{val.class}"
       end
-      result
     end
 
     # Apply non-device-dependent string formatting instructions.

data/lib/fat_table/formatters/latex_formatter.rb

@@ -26,8 +26,8 @@ module FatTable
     end
 
     # Taken from the Rainbow gem's list of valid colors.
-
-    self.valid_colors = File.readlines(File.join(__dir__, 'xcolors.txt'), chomp: true)
+    color_path = File.expand_path("../../../data/xcolors.txt", __dir__)
+    self.valid_colors = File.readlines(color_path, chomp: true)
 
     # LaTeX commands to load the needed packages based on the :environement
     # option.  For now, just handles the default 'longtable' :environment.  The

data/lib/fat_table/table.rb

@@ -721,7 +721,7 @@ module FatTable
     # row in the table as a group boundary.  An attempt to add a boundary to
     # an empty table has no effect.  We adopt the convention that the last row
     # of the table always marks an implicit boundary even if it is not in the
-    # @explicit_boundaries array.  When we "mark" a boundary, we intend it to
+    # `@explicit_boundaries` array.  When we "mark" a boundary, we intend it to
     # be an explicit boundary, even if it marks the last row of the table.
     def mark_boundary(row_num = nil)
       return self if empty?
@@ -774,7 +774,7 @@ module FatTable
     # user's point of view are indexed starting at 0.
     def row_index_to_group_index(row_num)
       boundaries.each_with_index do |b_last, g_num|
-        return (g_num + 1) if row_num <= b_last
+        return g_num + 1 if row_num <= b_last
       end
       0
     end
@@ -918,8 +918,8 @@ module FatTable
     #    access the instance variable @row, as the row number of the row being
     #    evaluated, and @group, as the group number of the row being evaluated.
     #
-    # 4. a hash in +new_cols+ with one of the special keys, +ivars: {literal
-    #    hash}+, +before_hook: 'ruby-code'+, or +after_hook: 'ruby-code'+ for
+    # 4. a hash in +new_cols+ with one of the special keys, `+ivars: {literal
+    #    hash}+`, +before_hook: 'ruby-code'+, or +after_hook: 'ruby-code'+ for
     #    defining custom instance variables to be used during evaluation of
     #    parameters described in point 3 and hooks of ruby code snippets to be
     #    evaluated before and after processing each row.
@@ -1150,7 +1150,7 @@ module FatTable
     # exception will be thrown. Duplicates are eliminated from the result. Any
     # groups present in either Table are eliminated in the output Table.
     def intersect(other)
-      set_operation(other, :intersect, distinct: true)
+      set_operation(other, :&, distinct: true)
     end
 
     # :category: Operators
@@ -1163,7 +1163,7 @@ module FatTable
     # will be thrown. Duplicates are not eliminated from the result. Resets
     # groups.
     def intersect_all(other)
-      set_operation(other, :intersect, distinct: false)
+      set_operation(other, :&, distinct: false)
     end
 
     # :category: Operators
@@ -1176,7 +1176,7 @@ module FatTable
     # are eliminated from the result. Any groups present in either Table are
     # eliminated in the output Table.
     def except(other)
-      set_operation(other, :difference, distinct: true)
+      set_operation(other, :-, distinct: true)
     end
 
     # :category: Operators
@@ -1189,7 +1189,7 @@ module FatTable
     # are /not/ eliminated from the result. Any groups present in either Table
     # are eliminated in the output Table.
     def except_all(other)
-      set_operation(other, :difference, distinct: false)
+      set_operation(other, :-, distinct: false)
     end
 
     # An Array of symbols for the valid join types.

data/lib/fat_table/version.rb

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

data/lib/fat_table.rb

@@ -1,11 +1,36 @@
 # frozen_string_literal: true
 
-# This module provides objects for treating tables as a data type on which you
-# can (1) perform operations, such as select, where, join, and others and (2)
-# output the tables in several formats, including text, ANSI terminal, LaTeX,
-# and others.  It also provides several constructors for building tables from a
-# variety of input sources.  See, e.g., .from_csv_file,
-# FatTable.from_org_file, and FatTable.from_sql, for more details.
+# Gem Overview (extracted from README.org by gem_docs)
+#
+# * Introduction
+# ~FatTable~ is a gem that treats tables as a data type. It provides methods for
+# constructing tables from a variety of sources, building them row-by-row,
+# extracting rows, columns, and cells, and performing aggregate operations on
+# columns. It also provides a set of SQL-esque methods for manipulating table
+# objects: ~select~ for filtering by columns or for creating new columns, ~where~
+# for filtering by rows, ~order_by~ for sorting rows, ~distinct~ for eliminating
+# duplicate rows, ~group_by~ for aggregating multiple rows into single rows and
+# applying column aggregate methods to ungrouped columns, a collection of ~join~
+# methods for combining tables, and more.
+#
+# Furthermore, ~FatTable~ provides methods for formatting tables and producing
+# output that targets various output media: text, ANSI terminals, ruby data
+# structures, LaTeX tables, Emacs org-mode tables, and more. The formatting
+# methods can specify cell formatting in a way that is uniform across all the
+# output methods and can also decorate the output with any number of footers,
+# including group footers. ~FatTable~ applies formatting directives to the extent
+# they makes sense for the output medium and treats other formatting directives as
+# no-ops.
+#
+# ~FatTable~ can be used to perform operations on data that are naturally best
+# conceived of as tables, which in my experience is quite often. It can also
+# serve as a foundation for providing reporting functions where flexibility
+# about the output medium can be useful. Finally ~FatTable~ can be used within
+# Emacs ~org-mode~ files in code blocks targeting the Ruby language. Org mode
+# tables are presented to a ruby code block as an array of arrays, so ~FatTable~
+# can read them in with its ~.from_aoa~ constructor. A ~FatTable~ table output as an
+# array of arrays with its ~.to_aoa~ output function will be rendered in an
+# org-mode buffer as an org-table, ready for processing by other code blocks.
 module FatTable
   require 'fat_core/symbol'
   require 'fat_core/array'
@@ -18,9 +43,9 @@ module FatTable
   require 'active_support/core_ext'
   require 'active_support/number_helper'
 
+  require 'core_ext'
   require 'fat_table/version'
   require 'fat_table/patches'
-  require 'ext/array'
   require 'fat_table/evaluator'
   require 'fat_table/convert'
   require 'fat_table/column'
@@ -145,11 +170,11 @@ module FatTable
   # methods can be called. If no block is given, the default format for the type
   # will be used. The +options+ are passed along to the FatTable::Formatter
   # created to process the output.
-  def self.to_format(table, options = {}) # :yields: formatter
+  def self.to_format(table, **options) # :yields: formatter
     if block_given?
-      to_any(format, table, options, &Proc.new)
+      to_any(format, table, **options, &Proc.new)
     else
-      to_any(format, table, options)
+      to_any(format, table, **options)
     end
   end
 
@@ -159,15 +184,15 @@ module FatTable
   # +FatTable::Formatter+ of the appropriate type on which formatting and footer
   # methods can be called. If no block is given, the default format for the
   # +fmt+ type will be used.
-  def self.to_any(fmt, table, options = {})
+  def self.to_any(fmt, table, **options)
     fmt = fmt.as_sym
     raise UserError, "unknown format '#{fmt}'" unless FORMATS.include?(fmt)
 
     method = "to_#{fmt}"
     if block_given?
-      send(method, table, options, &Proc.new)
+      send(method, table, **options, &Proc.new)
     else
-      send(method, table, options)
+      send(method, table, **options)
     end
   end
 
@@ -176,7 +201,7 @@ module FatTable
   # default formatting is applied to the +table+'s cells. If a block is given,
   # it yields the +FatTable::Formatter+ to the block on which formatting
   # and footer methods can be called.
-  def self.to_psv(table, options = {})
+  def self.to_psv(table, **options)
     fmt = Formatter.new(table, options)
     yield fmt if block_given?
     fmt.output
@@ -186,8 +211,8 @@ module FatTable
   # default formatting is applies to the table's cells. If a block is given, it
   # yields an AoaFormatter to the block to which formatting instructions and
   # footers can be added by calling methods on it.
-  def self.to_aoa(table, options = {})
-    fmt = AoaFormatter.new(table, options)
+  def self.to_aoa(table, **options)
+    fmt = AoaFormatter.new(table, **options)
     yield fmt if block_given?
     fmt.output
   end
@@ -197,8 +222,8 @@ module FatTable
   # table. If no block is given, default formatting is applies to the table's
   # cells. If a block is given, it yields an AohFormatter to the block to which
   # formatting instructions and footers can be added by calling methods on it.
-  def self.to_aoh(table, options = {})
-    fmt = AohFormatter.new(table, options)
+  def self.to_aoh(table, **options)
+    fmt = AohFormatter.new(table, **options)
     yield fmt if block_given?
     fmt.output
   end
@@ -207,8 +232,8 @@ module FatTable
   # default formatting applies to the table's cells. If a block is given, it
   # yields a LaTeXFormatter to the block to which formatting instructions and
   # footers can be added by calling methods on it.
-  def self.to_latex(table, options = {})
-    fmt = LaTeXFormatter.new(table, options)
+  def self.to_latex(table, **options)
+    fmt = LaTeXFormatter.new(table, **options)
     yield fmt if block_given?
     fmt.output
   end
@@ -217,8 +242,8 @@ module FatTable
   # is given, default formatting applies to the table's cells. If a block is
   # given, it yields a OrgFormatter to the block to which formatting
   # instructions and footers can be added by calling methods on it.
-  def self.to_org(table, options = {})
-    fmt = OrgFormatter.new(table, options)
+  def self.to_org(table, **options)
+    fmt = OrgFormatter.new(table, **options)
     yield fmt if block_given?
     fmt.output
   end
@@ -227,8 +252,8 @@ module FatTable
   # table. If no block is given, default formatting applies to the table's
   # cells. If a block is given, it yields a TermFormatter to the block to which
   # formatting instructions and footers can be added by calling methods on it.
-  def self.to_term(table, options = {})
-    fmt = TermFormatter.new(table, options)
+  def self.to_term(table, **options)
+    fmt = TermFormatter.new(table, **options)
     yield fmt if block_given?
     fmt.output
   end
@@ -237,8 +262,8 @@ module FatTable
   # no block is given, default formatting applies to the table's cells. If a
   # block is given, it yields a TextFormatter to the block to which formatting
   # instructions and footers can be added by calling methods on it.
-  def self.to_text(table, options = {})
-    fmt = TextFormatter.new(table, options)
+  def self.to_text(table, **options)
+    fmt = TextFormatter.new(table, **options)
     yield fmt if block_given?
     fmt.output
   end