fat_table 0.2.3 → 0.2.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 979f798ea068a4c78cefc05ad23e9bac937e1931
-  data.tar.gz: 0b9a6103449a3adc03e997702b2b7ba7eeb293f9
+  metadata.gz: 772c4f7d95d5af94968f650b4bc98ebad4756626
+  data.tar.gz: c15462e9a444de246690482da1a8acd3a46e0c60
 SHA512:
-  metadata.gz: 5bcc0327bf6438751e893c4ee8d3d286d13842fc92a72970c886f0857a215973bfec8baac98700f8f09f6da31fb4e0997916da8800e48411658055c94c43d8cb
-  data.tar.gz: fd50900aca39b031a7974069baf8abbbdf0a0a76853faa0c95033ae8fa3157b288e2fdc5d6dfe1b47241a18d84204878e0b19669d2f6be62fb153927c0846ad9
+  metadata.gz: 4f1177b1568ece2027849b102f2e7db84db99846e7291882f943fba5fd400b75032847df303c528fada0683afb2fb5b0bc97a2a91f2e52ed74cbd6960da07ac2
+  data.tar.gz: 813ddb4b57d893ce9bfb0ca17bb6d03d8807fa361b166396d0635fc5d23e70f4c1641fb69b0f3973678faa2e1bb87667de6bca4b8ff3c0033ceba38db0168658

data/.yardopts

@@ -0,0 +1 @@
+--no-private lib/**/*.rb --markup=markdown --main=README.rdoc - README.rdoc

data/README.org

@@ -148,8 +148,9 @@ the main features of ~FatTable~. See the detailed explanations further on down.
 
 When you install the fat_table gem, you have access to a program ~ft_console~
 which opens a ~pry~ session with ~fat_table~ loaded and the tables used in the
-examples in this README defined as local variables so you can experiment with
-them.
+examples in this README defined as instance variables so you can experiment with
+them.  Because they are defined as instance variables, you have to write ~tab1~
+as ~@tab1~ in ~ft_console~, but otherwise the examples should work.
 
 The examples in this ~README~ file are executed as code blocks within the
 ~README.org~ file, so they typically end with a call to ~.to_aoa~. That causes
@@ -162,21 +163,14 @@ To read in the table used in the Quick Start section above, you might do the
 following:
 
 #+BEGIN_EXAMPLE
-$ ft_console
-From: /home/ded/.rbenv/versions/2.3.0/lib/ruby/gems/2.3.0/gems/fat_table-0.2.1/bin/ft_console @ line 115 :
-
-    110:        [15, '2013-05-29', 'S', 15_900.00, 6685.95, 24.5802, 'YLEAC', 'T'],
-    111:        [16, '2013-05-30', 'S', 6_679.00, 2808.52, 25.0471, 'YLEAC', 'T']]
-    112: tt = FatTable.from_aoa(AOA)
-    113:
-    114: binding.pry
- => 115: instr <<-EOS
-    116: FatTable console sets up some sample tables you can play with (see ls)
-    117:
-    118:   For example, try 'puts tab1.to_term'
-    119: EOS
-
-[1] pry(main)> table = FatTable.from_aoa(data)
+$ ft_console[1] pry(main)> ls
+ActiveSupport::ToJsonWithActiveSupportEncoder#methods: to_json
+self.methods: inspect  to_s
+instance variables:
+  @aoa   @tab1      @tab2      @tab_a      @tab_b      @tt
+  @data  @tab1_str  @tab2_str  @tab_a_str  @tab_b_str
+locals: _  __  _dir_  _ex_  _file_  _in_  _out_  _pry_  lib  str  version
+[2] pry(main)> table = FatTable.from_aoa(@data)
 => #<FatTable::Table:0x0055b40e6cd870
  @boundaries=[],
  @columns=
@@ -197,7 +191,7 @@ From: /home/ded/.rbenv/versions/2.3.0/lib/ruby/gems/2.3.0/gems/fat_table-0.2.1/b
     @raw_header=:info,
     @type="String">,
    #<FatTable::Column:0x0055b40e6d2668 @header=:ok, @items=[false, true, false, true, true, true, true, true, true, true, true, false], @raw_header=:ok, @type="Boolean">]>
-[2] pry(main)> puts table.to_text
+[3] pry(main)> puts table.to_text
 +============+======+==========+==========+=========+=========+====+
 | Date       | Code | Raw      | Shares   | Price   | Info    | Ok |
 +------------+------+----------+----------+---------+---------+----+
@@ -215,7 +209,7 @@ From: /home/ded/.rbenv/versions/2.3.0/lib/ruby/gems/2.3.0/gems/fat_table-0.2.1/b
 | 2013-05-23 | S    | 23054.0  | 9694.21  | 26.8015 | ENTITY3 | F  |
 +============+======+==========+==========+=========+=========+====+
 => nil
-[3] pry(main)>
+[4] pry(main)>
 #+END_EXAMPLE
 
 And if you use ~.to_term~, you can see the effect of the color formatting
@@ -971,6 +965,8 @@ will raise an exception.
 - ~pdev~ :: for Numeric and DateTime columns, compute the population standard
      deviation of the non-nil values in the column, dates are converted to
      numbers as for the :avg aggregate,
+- ~all?~ :: for Boolean columns only, return true if all of the non-nil values
+     in the column are true,
 - ~any?~ :: for Boolean columns only, return true if any non-nil value in the
      column is true,
 - ~none?~ :: for Boolean columns only, return true if no non-nil value in the

data/README.rdoc

@@ -135,8 +135,11 @@ the main features of +FatTable+. See the detailed explanations further on down.
 
 When you install the fat_table gem, you have access to a program +ft_console+
 which opens a +pry+ session with +fat_table+ loaded and the tables used in the
-examples in this README defined as local variables so you can experiment with
-them.
+examples in this README defined as instance variables so you can experiment with
+them. Because they are defined as instance variables, you have to write ~tab1~
+as ~@tab1~ in ~ft_console~, but otherwise the examples should work.
+
+
 
 The examples in this +README+ file are executed as code blocks within the
 +README.org+ file, so they typically end with a call to +.to_aoa+. That causes
@@ -148,21 +151,14 @@ the table to be inserted into the file and formatted as a table. With
 To read in the table used in the Quick Start section above, you might do the
 following:
 
-  $ ft_console
-  From: /home/ded/.rbenv/versions/2.3.0/lib/ruby/gems/2.3.0/gems/fat_table-0.2.1/bin/ft_console @ line 115 :
-
-      110:        [15, '2013-05-29', 'S', 15_900.00, 6685.95, 24.5802, 'YLEAC', 'T'],
-      111:        [16, '2013-05-30', 'S', 6_679.00, 2808.52, 25.0471, 'YLEAC', 'T']]
-      112: tt = FatTable.from_aoa(AOA)
-      113:
-      114: binding.pry
-  => 115: instr <<-EOS
-      116: FatTable console sets up some sample tables you can play with (see ls)
-      117:
-      118:   For example, try 'puts tab1.to_term'
-      119: EOS
-
-  [1] pry(main)> table = FatTable.from_aoa(data)
+  $ ft_console[1] pry(main)> ls
+  ActiveSupport::ToJsonWithActiveSupportEncoder#methods: to_json
+  self.methods: inspect  to_s
+  instance variables:
+    @aoa   @tab1      @tab2      @tab_a      @tab_b      @tt
+    @data  @tab1_str  @tab2_str  @tab_a_str  @tab_b_str
+  locals: _  __  _dir_  _ex_  _file_  _in_  _out_  _pry_  lib  str  version
+  [2] pry(main)> table = FatTable.from_aoa(@data)
   => #<FatTable::Table:0x0055b40e6cd870
   @boundaries=[],
   @columns=
@@ -183,7 +179,7 @@ following:
       @raw_header=:info,
       @type="String">,
     #<FatTable::Column:0x0055b40e6d2668 @header=:ok, @items=[false, true, false, true, true, true, true, true, true, true, true, false], @raw_header=:ok, @type="Boolean">]>
-  [2] pry(main)> puts table.to_text
+  [3] pry(main)> puts table.to_text
   +============+======+==========+==========+=========+=========+====+
   | Date       | Code | Raw      | Shares   | Price   | Info    | Ok |
   +------------+------+----------+----------+---------+---------+----+
@@ -201,7 +197,7 @@ following:
   | 2013-05-23 | S    | 23054.0  | 9694.21  | 26.8015 | ENTITY3 | F  |
   +============+======+==========+==========+=========+=========+====+
   => nil
-  [3] pry(main)>
+  [4] pry(main)>
 
 And if you use +.to_term+, you can see the effect of the color formatting
 directives.

data/bin/ft_console

@@ -4,7 +4,7 @@ require 'bundler/setup'
 require 'fat_table'
 require 'pry'
 
-data =
+@data =
   [['Date', 'Code', 'Raw', 'Shares', 'Price', 'Info', 'Ok'],
    ['2013-05-29', 'S', 15_700.00, 6601.85, 24.7790, 'ENTITY3', 'F'],
    ['2013-05-02', 'P', 118_186.40, 118_186.4, 11.8500, 'ENTITY1', 'T'],
@@ -19,7 +19,7 @@ data =
    ['2013-05-30', 'S', 6_679.00, 2808.52, 25.0471, 'ENTITY3', 'T'],
    ['2013-05-23', 'S', 23_054.00, 9694.21, 26.8015, 'ENTITY3', 'F']]
 
-tab_a_str = <<-EOS
+@tab_a_str = <<-EOS
   | Id | Name  | Age | Address    | Salary |  Join Date |
   |----+-------+-----+------------+--------+------------|
   |  1 | Paul  |  32 | California |  20000 | 2001-07-13 |
@@ -32,7 +32,7 @@ tab_a_str = <<-EOS
   | 10 | James |  45 | Texas      |   5000 |            |
   EOS
 
-tab_b_str = <<-EOS
+@tab_b_str = <<-EOS
   | Id | Dept        | Emp Id |
   |----+-------------+--------|
   |  1 | IT Billing  |      1 |
@@ -40,10 +40,10 @@ tab_b_str = <<-EOS
   |  3 | Finance     |      7 |
   EOS
 
-tab_a = FatTable.from_org_string(tab_a_str)
-tab_b = FatTable.from_org_string(tab_b_str)
+@tab_a = FatTable.from_org_string(@tab_a_str)
+@tab_b = FatTable.from_org_string(@tab_b_str)
 
-tab1_str = <<-EOS
+@tab1_str = <<-EOS
 | Ref  | Date             | Code |  Price | G10 | QP10 | Shares |   LP |    QP |   IPLP |   IPQP |
 |------+------------------+------+--------+-----+------+--------+------+-------+--------+--------|
 | T001 | [2016-11-01 Tue] | P    | 7.7000 | T   | F    |    100 |   14 |    86 | 0.2453 | 0.1924 |
@@ -70,7 +70,7 @@ tab1_str = <<-EOS
 | T016 | [2016-11-02 Wed] | P    | 8.2500 | T   | T    |    100 |   14 |    86 | 0.2453 | 0.1924 |
 EOS
 
-tab2_str = <<-EOS
+@tab2_str = <<-EOS
 | Ref  | Date             | Code |  Price | G10 | QP10 | Shares |    LP |   QP |   IPLP |   IPQP |
 |------+------------------+------+--------+-----+------+--------+-------+------+--------+--------|
 | T003 | [2016-11-01 Tue] | P    | 7.5000 | F   | T    |    800 |   112 |  688 | 0.2453 | 0.1924 |
@@ -93,10 +93,10 @@ tab2_str = <<-EOS
 | T021 | [2017-01-23 Mon] | P    |   7.16 | T   | T    |  12100 | 11050 | 1050 | 0.2453 | 0.1924 |
 EOS
 
-tab1 = FatTable.from_org_string(tab1_str)
-tab2 = FatTable.from_org_string(tab2_str)
+@tab1 = FatTable.from_org_string(@tab1_str)
+@tab2 = FatTable.from_org_string(@tab2_str)
 
-AOA = [['Ref', 'Date', 'Code', 'Raw', 'Shares', 'Price', 'Info', 'Bool'],
+@aoa = [['Ref', 'Date', 'Code', 'Raw', 'Shares', 'Price', 'Info', 'Bool'],
        [1, '2013-05-02', 'P', 795_546.20, 795_546.2, 1.1850, 'YLPEF1', 'T'],
        [2, '2013-05-02', 'P', 118_186.40, 118_186.4, 11.8500, 'YLPEF1', 'T'],
        [7, '2013-05-20', 'S', 12_000.00, 5046.00, 28.2804, 'YLEAC', 'F'],
@@ -109,11 +109,6 @@ AOA = [['Ref', 'Date', 'Code', 'Raw', 'Shares', 'Price', 'Info', 'Bool'],
        [14, '2013-05-29', 'S', 15_700.00, 6601.85, 24.7790, 'YLEAC', 'F'],
        [15, '2013-05-29', 'S', 15_900.00, 6685.95, 24.5802, 'YLEAC', 'T'],
        [16, '2013-05-30', 'S', 6_679.00, 2808.52, 25.0471, 'YLEAC', 'T']]
-tt = FatTable.from_aoa(AOA)
+@tt = FatTable.from_aoa(@aoa)
 
-binding.pry
-instr <<-EOS
-FatTable console sets up some sample tables you can play with (see ls)
-
-  For example, try 'puts tab1.to_term'
-EOS
+Pry.start

data/fat_table.gemspec

@@ -59,6 +59,7 @@ org-mode buffer as an org-table, ready for processing by other code blocks.
   spec.bindir        = 'bin'
   spec.executables   = ['ft_console']
   spec.require_paths = ['lib']
+  spec.metadata['yard.run'] = 'yri' # use "yard" to build full HTML docs.
 
   spec.add_development_dependency 'simplecov'
   spec.add_development_dependency 'bundler', '~> 1.14'
@@ -68,9 +69,9 @@ org-mode buffer as an org-table, ready for processing by other code blocks.
   spec.add_development_dependency 'pry'
   spec.add_development_dependency 'pry-doc'
   spec.add_development_dependency 'pry-byebug'
-  spec.add_development_dependency 'rcodetools'
+  spec.add_development_dependency 'redcarpet'
 
-  spec.add_runtime_dependency 'fat_core', '~> 2.0', '>= 2.0.1'
+  spec.add_runtime_dependency 'fat_core', '~> 4.0', '>= 4.1'
   spec.add_runtime_dependency 'activesupport'
   spec.add_runtime_dependency 'rainbow'
   spec.add_runtime_dependency 'dbi'

data/lib/fat_table.rb

@@ -1,5 +1,3 @@
-require "fat_table/version"
-
 # 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,
@@ -7,12 +5,17 @@ require "fat_table/version"
 # variety of input sources.  See, e.g., .from_csv_file,
 # FatTable.from_org_file, and FatTable.from_sql, for more details.
 module FatTable
-  require 'fat_core'
+  require 'fat_core/symbol'
+  require 'fat_core/array'
+  require 'fat_core/hash'
+  require 'fat_core/numeric'
+  require 'csv'
   require 'dbi'
   require 'active_support'
   require 'active_support/core_ext'
   require 'active_support/number_helper'
 
+  require 'fat_table/version'
   require 'fat_table/evaluator'
   require 'fat_table/column'
   require 'fat_table/table'

data/lib/fat_table/formatters/aoa_formatter.rb

@@ -1,8 +1,8 @@
 module FatTable
   # A subclass of Formatter for rendering the table as a Ruby Array of Arrays.
-  # Each cell is an element of the inner Array is formatted as a string in
-  # accordance with the formatting directives. All footers are included as extra
-  # Arrays of the output. AoaFormatter supports no +options+
+  # Each cell is formatted as a string in accordance with the formatting
+  # directives. All footers are included as extra Arrays of the output.
+  # AoaFormatter supports no +options+
   class AoaFormatter < Formatter
 
     private

data/lib/fat_table/formatters/formatter.rb

@@ -2,14 +2,14 @@ module FatTable
   # A Formatter is for use in Table output routines, and provides methods for
   # adding group and table footers to the output and instructions for how the
   # table's cells ought to be formatted. The goal is to make subclasses of this
-  # class handle different output targets, such as aoa for org tables, ANSI
-  # terminals, LaTeX, plain text, org mode table text, and so forth. Many of
-  # the formatting options, such as color, will be no-ops for some output
-  # targets, such as text, but will be valid nonetheless. Thus, the Formatter
-  # subclass should provide the best implementation for each formatting request
-  # available for the target. This base class will consist largely of methods
-  # that format output as pipe-separated values, but implementations provided
-  # by subclasses will override these for different output targets.
+  # class handle different output targets, such as aoa for an Array of Arrays
+  # (useful in Emacs org-mode code blocks), ANSI terminals, LaTeX, plain text,
+  # org mode table text, and so forth. Many of the formatting options, such as
+  # color, will be no-ops for some output targets, such as text, but will be
+  # valid nonetheless. Thus, a Formatter subclass should provide the best
+  # implementation for each formatting request available for the target. This
+  # base class will format output as pipe-separated values, but implementations
+  # provided by subclasses will override these for different output targets.
   class Formatter
     # Valid locations in a Table as an array of symbols.
     LOCATIONS = [:header, :body, :bfirst, :gfirst, :gfooter, :footer].freeze
@@ -156,12 +156,12 @@ module FatTable
     #   tab.footer('Grand Total', :shares, :price)
     #
     # Average then show standard deviation of several columns
-    #   tab.footer.('Average', date: avg, shares: :avg, price: avg)
-    #   tab.footer.('Sigma', date: dev, shares: :dev, price: :dev)
+    #   tab.footer.('Average', date: :avg, shares: :avg, price: :avg)
+    #   tab.footer.('Sigma', date: :dev, shares: :dev, price: :dev)
     #
     # Do some sums and some other aggregates: sum shares, average date and
     # price.
-    #   tab.footer.('Summary', :shares, date: avg, price: avg)
+    #   tab.footer.('Summary', :shares, date: :avg, price: :avg)
     def footer(label, *sum_cols, **agg_cols)
       label = label.to_s
       foot = {}
@@ -195,11 +195,11 @@ module FatTable
     #   :shares, :price)
     #
     # Average then show standard deviation of several columns
-    #   tab.gfooter.('Average', date: avg, shares: :avg, price: avg)
+    #   tab.gfooter.('Average', date: :avg, shares: :avg, price: :avg)
     #   tab.gfooter.('Sigma', date: dev, shares: :dev, price: :dev)
     #
     # Do some sums and some other aggregates: sum shares, average date and
-    # price. tab.gfooter.('Summary', :shares, date: avg, price: avg)
+    # price. tab.gfooter.('Summary', :shares, date: :avg, price: :avg)
     def gfooter(label, *sum_cols, **agg_cols)
       label = label.to_s
       foot = {}
@@ -303,12 +303,11 @@ module FatTable
       gfooter('Group Maximum', hsh)
     end
 
+    # :category: Formatting
+
     ############################################################################
     # Formatting methods
     #
-    #
-    # :category: Formatting
-    #
     # A Formatter can specify a hash to hold the formatting instructions for
     # columns by using the column head as a key and the value as the format
     # instructions. In addition, the keys, :numeric, :string, :datetime,
@@ -419,7 +418,7 @@ module FatTable
     end
 
     # :category: Formatting
-    #
+
     # Define a formatting directives for the given location. The following are
     # the valid +location+ symbols.
     #
@@ -865,7 +864,7 @@ module FatTable
       end
       if istruct.commas
         # Commify the whole number part if not done already.
-        result = result.commify
+        result = result.commas
       end
       result
     end
@@ -880,7 +879,8 @@ module FatTable
         when :upper
           val.upcase
         when :title
-          val.entitle
+          # Note: fat_core entitle keeps all uppercase words as upper case,
+          val.downcase.entitle
         when :none
           val
         end

data/lib/fat_table/table.rb

@@ -58,6 +58,7 @@ module FatTable
     ###########################################################################
 
     # :category: Constructors
+
     # Return an empty FatTable::Table object.
     def initialize
       @columns = []
@@ -65,8 +66,9 @@ module FatTable
     end
 
     # :category: Constructors
-    # Construct a Table from the contents of a CSV file.  Headers will be taken
-    # from the first row and converted to symbols.
+
+    # Construct a Table from the contents of a CSV file named +fname+. Headers
+    # will be taken from the first CSV row and converted to symbols.
     def self.from_csv_file(fname)
       File.open(fname, 'r') do |io|
         from_csv_io(io)
@@ -74,7 +76,9 @@ module FatTable
     end
 
     # :category: Constructors
-    # Construct a Table from a string, treated as the input from a CSV file.
+
+    # Construct a Table from a CSV string +str+, treated in the same manner as
+    # the input from a CSV file in ::from_org_file.
     def self.from_csv_string(str)
       from_csv_io(StringIO.new(str))
     end
@@ -82,9 +86,9 @@ module FatTable
     # :category: Constructors
 
     # Construct a Table from the first table found in the given Emacs org-mode
-    # file. Headers are taken from the first row if the second row is an hrule.
-    # Otherwise, synthetic headers of the form +:col_1+, +:col_2+, etc. are
-    # created.
+    # file named +fname+. Headers are taken from the first row if the second row
+    # is an hrule. Otherwise, synthetic headers of the form +:col_1+, +:col_2+,
+    # etc. are created.
     def self.from_org_file(fname)
       File.open(fname, 'r') do |io|
         from_org_io(io)
@@ -92,36 +96,39 @@ module FatTable
     end
 
     # :category: Constructors
-    # Construct a Table from a string, treated as the contents of an org-mode
-    # file.
+
+    # Construct a Table from a string +str+, treated in the same manner as the
+    # contents of an org-mode file in ::from_org_file.
     def self.from_org_string(str)
       from_org_io(StringIO.new(str))
     end
 
     # :category: Constructors
 
-    # Construct a new table from an array of arrays. By default, with +hlines+
-    # false, do not look for separators, i.e. nil or a string of dashes, just
-    # treat the first row as headers. With +hlines+ true, expect separators to
-    # mark the header row and any boundaries. If the second element of the array
-    # is a +nil+, interpret the first element of the array as a row of headers.
-    # Otherwise, synthesize headers of the form +:col_1+, +:col_2+, ... 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+, mark the preceding row
-    # as a boundary. Note: In org mode code blocks, by default (+:hlines no+)
-    # all hlines are stripped from the table, otherwise (+:hlines yes+) they are
-    # indicated with nil elements in the outer array.
+    # Construct a new table from an Array of Arrays +aoa+. By default, with
+    # +hlines+ set to false, do not look for separators, i.e. +nils+, just treat
+    # the first row as headers. With +hlines+ set true, expect +nil+ separators
+    # to mark the header row and any boundaries. If the second element of the
+    # array is a +nil+, interpret the first element of the array as a row of
+    # headers. Otherwise, synthesize headers of the form +:col_1+, +:col_2+, ...
+    # 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+, mark the
+    # preceding row as a group boundary. Note for Emacs users: In org mode code
+    # blocks when an org-mode table is passed in as a variable it is passed in
+    # as an Array of Arrays. By default (+ HEADER: :hlines no +) org-mode strips
+    # all from the table; otherwise (+ HEADER: :hlines yes +) they are indicated
+    # with nil elements in the outer array.
     def self.from_aoa(aoa, hlines: false)
       from_array_of_arrays(aoa, hlines: hlines)
     end
 
     # :category: Constructors
 
-    # 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.  If hlines is
-    # set true, mark a group boundary whenever a nil, rather than a hash
-    # appears in the outer array.
+    # Construct a Table from +aoh+, an Array of Hashes or an Array of 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. If hlines is set true, mark a group boundary whenever a nil, rather
+    # than a hash appears in the outer array.
     def self.from_aoh(aoh, hlines: false)
       if aoh.first.respond_to?(:to_h)
         from_array_of_hashes(aoh, hlines: hlines)
@@ -133,16 +140,16 @@ module FatTable
 
     # :category: Constructors
 
-    # Construct a Table from another Table.  Inherit any group boundaries from
-    # the input table.
+    # Construct a new table from another FatTable::Table object +table+. Inherit any
+    # group boundaries from the input table.
     def self.from_table(table)
       table.deep_dup
     end
 
     # :category: Constructors
 
-    # Construct a Table by running a SQL query against the database set up with
-    # FatTable.set_db.  Return the Table with the query results as rows.
+    # Construct a Table by running a SQL +query+ against the database set up
+    # with FatTable.set_db, with the rows of the query result as rows.
     def self.from_sql(query)
       raise UserError, 'FatTable.db must be set with FatTable.set_db' if FatTable.db.nil?
       result = Table.new
@@ -281,13 +288,16 @@ module FatTable
     ###########################################################################
 
     # :category: Attributes
-    # Return the Column with the given header.
+
+    # Return the table's Column with the given +key+ as its header.
     def column(key)
       columns.detect { |c| c.header == key.as_sym }
     end
 
     # :category: Attributes
-    # Return the type of the Column with the given header
+
+    # Return the type of the Column with the given +key+ as its
+    # header as a String.
     def type(key)
       column(key).type
     end
@@ -295,11 +305,11 @@ module FatTable
     # :category: Attributes
 
     # Return the array of items of the column with the given header symbol
-    # +key+, or if +key+ 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-major
-    # order: \tab\[:id\]\[8\] returns the 9th item in the column headed :id and
-    # so does \tab\[8\]\[:id\].
+    # +key+, or if +key+ is an Integer, return that row at that index. 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-major order: \tab\[:id\]\[8\] returns the 9th item in the column
+    # headed :id and so does \tab\[8\]\[:id\].
     def [](key)
       case key
       when Integer
@@ -325,7 +335,7 @@ module FatTable
 
     # :category: Attributes
 
-    # Return a Hash of the Table's Column header symbols to types.
+    # Return a Hash of the Table's Column header symbols to type strings.
     def types
       result = {}
       columns.each do |c|
@@ -336,7 +346,7 @@ module FatTable
 
     # :category: Attributes
 
-    # 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
@@ -461,7 +471,7 @@ module FatTable
     # boundaries would make no sense anyway. Likewise, #union, #intersection,
     # #except, and #join reset the boundaries to their default.
     #
-    # Return an array of an array of row hashes for the groups in this Table.
+    # Return an array of an Array of row Hashes for the groups in this Table.
     def groups
       normalize_boundaries
       groups = []
@@ -482,8 +492,9 @@ module FatTable
       self
     end
 
-    # Mark a boundary at k, and if k is nil, mark the last row in the table as a
-    # group boundary.  This is used for internal purposes.
+    # Mark a group boundary at row +k+, and if +k+ is +nil+, mark the last row
+    # in the table as a group boundary. This is mainly used for internal
+    # purposes.
     def mark_boundary(k = nil) # :nodoc:
       if k
         boundaries.push(k)
@@ -551,11 +562,11 @@ module FatTable
     # :category: Operators
 
     # 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.
+    # keys given in +sort_heads+ as an Array of Symbols. Append a ! to the
+    # symbol name to indicate reverse sorting on that column.
     #
     #   tab.order_by(:ref, :date) => sorted table
-    #   tab.order_by(:date!)  => reverse sort on :date
+    #   tab.order_by(:date!) => reverse sort on :date
     #
     # After sorting, the output Table will have group boundaries added after
     # each row where the sort key changes.
@@ -588,23 +599,25 @@ module FatTable
     # Return a Table having the selected column expressions. Each expression can
     # be either a
     #
-    # 1. a symbol, +:old_col+, representing a column in the current table,
+    # 1. in +cols+, a symbol, +:old_col+, representing a column in the current
+    #    table,
     #
-    # 2. a hash of +new_col: :old_col+ to rename an existing +:old_col+ column as
-    #    +:new_col+, or
+    # 2. a hash in +new_cols+ of the form +new_col: :old_col+ to rename an
+    #    existing +:old_col+ column as +:new_col+, or
     #
-    # 3. a hash of +new_col: 'expression'+, to add a new column that is computed
-    #    as an arbitrary ruby expression of the existing columns (whether
-    #    selected for the output table or not) or any new_col defined earlier in
-    #    the argument list defined as local variables in the expression. The
-    #    expression string can also 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.
+    # 3. a hash in +new_cols+ of the form +new_col: 'expression'+, to add a new
+    #    column +new_col+ that is computed as an arbitrary ruby expression in
+    #    which there are local variables bound to the names of existing columns
+    #    (whether selected for the output table or not) as well as any +new_col+
+    #    defined earlier in the argument list. The expression string can also
+    #    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.
     #
-    # The bare symbol arguments (1) must precede any hash arguments (2) or (3).
-    # Each expression results in a column in the resulting Table in the order
-    # given. The expressions are evaluated in left-to-right order as well. The
-    # output table preserves any groups present in the input table.
+    # The bare symbol arguments +cols+ (1) must precede any hash arguments
+    # +new_cols+ (2 or 3). Each expression results in a column in the resulting
+    # Table in the order given in the argument list. The expressions are
+    # evaluated in left-to-right order as well. The output table preserves any
+    # groups present in the input table.
     #
     #   tab.select(:ref, :date, :shares) => table with only 3 columns selected
     #   tab.select(:ref, :date, shares: :quantity) => rename :shares->:quantity
@@ -676,7 +689,7 @@ module FatTable
 
     # :category: Operators
 
-    # Return this table with all duplicate rows eliminated. Resets groups. Same
+    # Return a new table with all duplicate rows eliminated. Resets groups. Same
     # as #uniq.
     def distinct
       result = Table.new
@@ -697,12 +710,12 @@ module FatTable
 
     # :category: Operators
 
-    # Return a Table that combines this table with +other+ table. In other
-    # words, return the union of this table with the other. The headers of this
-    # table are used in the result. There must be the same number of columns of
-    # the same type in the two tables, or an exception will be thrown.
-    # Duplicates are eliminated from the result.  Any groups present in either
-    # Table are eliminated in the output Table.
+    # Return a Table that combines this table with +other+ table, i.e., return
+    # the union of this table with the other. The headers of this table are used
+    # in the result. There must be the same number of columns of the same type
+    # in the two tables, otherwise an exception will be raised. Duplicates are
+    # eliminated from the result. Any groups present in either Table are
+    # eliminated in the output Table.
     def union(other)
       set_operation(other, :+,
                     distinct: true,
@@ -753,10 +766,10 @@ module FatTable
     # :category: Operators
 
     # Return a Table that includes the rows of this table except for any rows
-    # that are the same as those in another table. In other words, return the
-    # set difference between this table an the other. The headers of this table
+    # that are the same as those in Table +other+. In other words, return the
+    # set difference between this table and +other+. The headers of this table
     # are used in the result. There must be the same number of columns of the
-    # same type in the two tables, or an exception will be thrown. Duplicates
+    # same type in the two tables, or an exception will be raised. Duplicates
     # are eliminated from the result. Any groups present in either Table are
     # eliminated in the output Table.
     def except(other)
@@ -766,12 +779,12 @@ module FatTable
     # :category: Operators
 
     # Return a Table that includes the rows of this table except for any rows
-    # that are the same as those in +other+ Table. In other words, return the
+    # that are the same as those in Table +other+. In other words, return the
     # set difference between this table an the other. The headers of this table
     # are used in the result. There must be the same number of columns of the
     # same type in the two tables, or an exception will be thrown. Duplicates
-    # are not eliminated from the result. Any groups present in either Table are
-    # eliminated in the output Table.
+    # 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)
     end
@@ -814,8 +827,10 @@ module FatTable
 
     # :category: Operators
     #
-    # Return a table that joins this table to another based on one or more join
-    # expressions. There are several possibilities for the join expressions:
+    # Return a table that joins this Table to +other+ based on one or more join
+    # expressions +exps+ using the +join_type+ in determining the rows of the
+    # result table. There are several possible forms for the join expressions
+    # +exps+:
     #
     # 1. If no join expressions are given, the tables will be joined when all
     #    values with the same name in both tables have the same value, a
@@ -876,8 +891,8 @@ module FatTable
     #          the tables have N and M rows respectively, the joined table will
     #          have N * M rows.
     #
-    # Any groups present in either Table are eliminated in the output Table.
-    # See the README for examples.
+    # Any groups present in either Table are eliminated in the output Table. See
+    # the README for examples.
     def join(other, *exps, join_type: :inner)
       unless other.is_a?(Table)
         raise UserError, 'need other table as first argument to join'
@@ -927,31 +942,36 @@ module FatTable
     end
 
     # :category: Operators
-    # Perform an inner join as described in FatTable::Table.join.
+
+    # Perform an inner join as described in FatTable::Table#join.
     def inner_join(other, *exps)
       join(other, *exps)
     end
 
     # :category: Operators
-    # Perform a left join as described in FatTable::Table.join.
+
+    # Perform a left join as described in FatTable::Table#join.
     def left_join(other, *exps)
       join(other, *exps, join_type: :left)
     end
 
     # :category: Operators
-    # Perform a right join as described in FatTable::Table.join.
+
+    # Perform a right join as described in FatTable::Table#join.
     def right_join(other, *exps)
       join(other, *exps, join_type: :right)
     end
 
     # :category: Operators
-    # Perform a full join as described in FatTable::Table.join.
+
+    # Perform a full join as described in FatTable::Table#join.
     def full_join(other, *exps)
       join(other, *exps, join_type: :full)
     end
 
     # :category: Operators
-    # Perform a cross join as described in FatTable::Table.join.
+
+    # Perform a cross join as described in FatTable::Table#join.
     def cross_join(other)
       join(other, join_type: :cross)
     end
@@ -1099,23 +1119,24 @@ module FatTable
     public
 
     # :category: Operators
+
     # 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.) that you can specify 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:
+    # where the value of all columns +group_cols+ named as simple symbols are
+    # equal. All other columns, +agg_cols+, 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.) that you can specify 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. 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.
+    # The first three parameters are simple symbols and count as +group_cols+,
+    # 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 an +agg_col+
+    # parameter set to the aggregate function :sum, so it will appear in the
+    # result as the sum of all the :shares values in each group. 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)
       sorted_tab = order_by(group_cols)
       groups = sorted_tab.rows.group_by do |r|
@@ -1152,9 +1173,10 @@ module FatTable
     public
 
     # :category: Constructors
-    # 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.
+
+    # Add a +row+ represented by a Hash having the headers as keys. If +mark:+
+    # is set 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|
         key = k.as_sym
@@ -1166,12 +1188,14 @@ module FatTable
     end
 
     # :category: Constructors
-    # Add a row without marking.
+
+    # Add a +row+ without marking it as a group boundary.
     def <<(row)
       add_row(row)
     end
 
     # :category: Constructors
+
     # Add a FatTable::Column object +col+ to the table.
     def add_column(col)
       raise "Table already has a column with header '#{col.header}'" if column?(col.header)
@@ -1193,12 +1217,12 @@ module FatTable
     # :category: Output
 
     # Return a string or ruby object according to the format specified in
-    # FatTable.format.  If a block is given, it will yield a Formatter of the
-    # appropriate type to which format and footers can be applied. Otherwise, the
-    # default format for the type will be used.
+    # FatTable.format, passing the +options+ on to the Formatter. If a block is
+    # given, it will yield a Formatter of the appropriate type to which format
+    # and footers can be applied. Otherwise, the default format for the type
+    # will be used.
     #
-    # :call-seq:
-    # to_format(options = {}) { |fmt| ... }
+    # :call-seq: to_format(options = {}) { |fmt| ... }
     #
     def to_format(options = {})
       if block_given?
@@ -1211,11 +1235,11 @@ module FatTable
     # :category: Output
 
     # Return a string or ruby object according to the format type +fmt_type+
-    # given in the first argument. Valid format types are :psv, :aoa, :aoh,
-    # :latex, :org, :term, :text, or their string equivalents. If a block is
-    # given, it will yield a Formatter of the appropriate type to which format
-    # and footers can be applied. Otherwise, the default format for the type
-    # will be used.
+    # given in the first argument, passing the +options+ on to the Formatter.
+    # Valid format types are :psv, :aoa, :aoh, :latex, :org, :term, :text, or
+    # their string equivalents. If a block is given, it will yield a Formatter
+    # of the appropriate type to which format and footers can be applied.
+    # Otherwise, the default format for the type will be used.
     #
     # :call-seq: to_any(fmt_type, options = {}) { |fmt| ... }
     #
@@ -1232,12 +1256,13 @@ module FatTable
 
     # :category: Output
 
-    # Return the table as a string formatted as a pipe-separated values. If no
-    # block is given, default formatting is applies to the table's cells. If a
-    # block is given, it yields a Formatter to the block to which formatting
-    # instructions and footers can be added by calling methods on it.  Since the
-    # pipe-separated format is the default format for Formatter, there is no
-    # class PsvFormatter as you might expect.
+    # Return the table as a string formatted as a pipe-separated values, passing
+    # the +options+ on to the Formatter. If no block is given, default
+    # formatting is applies to the table's cells. If a block is given, it yields
+    # a Formatter to the block to which formatting instructions and footers can
+    # be added by calling methods on it. Since the pipe-separated format is the
+    # default format for Formatter, there is no class PsvFormatter as you might
+    # expect.
     def to_psv(options = {})
       fmt = Formatter.new(self, options)
       yield fmt if block_given?
@@ -1246,10 +1271,11 @@ module FatTable
 
     # :category: Output
 
-    # Return the table as an Array of Array of Strings. If no block is given,
-    # 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.
+    # Return the table as an Array of Array of Strings, passing the +options+ on
+    # to the AoaFormatter. If no block is given, 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 to_aoa(options = {})
       fmt = FatTable::AoaFormatter.new(self, options)
       yield fmt if block_given?
@@ -1258,12 +1284,12 @@ module FatTable
 
     # :category: Output
 
-    # Return the table as an Array of Hashes. Each inner hash uses the Table's
-    # columns as keys and it values are strings representing the cells of the
-    # 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.
+    # Return the table as an Array of Hashes, passing the +options+ on to the
+    # AohFormatter. Each inner hash uses the Table's columns as keys and it
+    # values are strings representing the cells of the 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 to_aoh(options = {})
       fmt = AohFormatter.new(self, options)
       yield fmt if block_given?
@@ -1272,10 +1298,11 @@ module FatTable
 
     # :category: Output
 
-    # Return the table as a string containing a LaTeX table. If no block is
-    # given, 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.
+    # Return the table as a string containing a LaTeX table, passing the
+    # +options+ on to the LaTeXFormatter. If no block is given, 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 to_latex(options = {})
       fmt = LaTeXFormatter.new(self, options)
       yield fmt if block_given?
@@ -1284,10 +1311,11 @@ module FatTable
 
     # :category: Output
 
-    # Return the table as a string containing an Emacs org-mode table. If no
-    # block 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.
+    # Return the table as a string containing an Emacs org-mode table, passing
+    # the +options+ on to the OrgFormatter. If no block 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 to_org(options = {})
       fmt = OrgFormatter.new(self, options)
       yield fmt if block_given?
@@ -1297,10 +1325,10 @@ module FatTable
     # :category: Output
 
     # Return the table as a string containing ANSI terminal text representing
-    # 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.
+    # table, passing the +options+ on to the TermFormatter. 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 to_term(options = {})
       fmt = TermFormatter.new(self, options)
       yield fmt if block_given?
@@ -1309,10 +1337,12 @@ module FatTable
 
     # :category: Output
 
-    # Return the table as a string containing ordinary text representing table.
-    # If 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.
+    # Return the table as a string containing ordinary text representing table,
+    # passing the +options+ on to the TextFormatter. If 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.
+    # @return [String]
     def to_text(options = {})
       fmt = TextFormatter.new(self, options)
       yield fmt if block_given?

data/lib/fat_table/version.rb

@@ -1,4 +1,4 @@
 module FatTable
   # The current version of FatTable
-  VERSION = '0.2.3'.freeze
+  VERSION = '0.2.4'.freeze
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: fat_table
 version: !ruby/object:Gem::Version
-  version: 0.2.3
+  version: 0.2.4
 platform: ruby
 authors:
 - Daniel E. Doherty
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-05-08 00:00:00.000000000 Z
+date: 2017-05-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: simplecov
@@ -123,7 +123,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: rcodetools
+  name: redcarpet
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -142,20 +142,20 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.0'
+        version: '4.0'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 2.0.1
+        version: '4.1'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.0'
+        version: '4.0'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 2.0.1
+        version: '4.1'
 - !ruby/object:Gem::Dependency
   name: activesupport
   requirement: !ruby/object:Gem::Requirement
@@ -280,6 +280,7 @@ files:
 - ".gitignore"
 - ".rspec"
 - ".travis.yml"
+- ".yardopts"
 - Gemfile
 - LICENSE.txt
 - README.org
@@ -308,6 +309,7 @@ homepage: https://github.com/ddoherty03/fat_table
 licenses: []
 metadata:
   allowed_push_host: https://rubygems.org
+  yard.run: yri
 post_install_message: 
 rdoc_options: []
 require_paths:
@@ -324,7 +326,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.5.1
+rubygems_version: 2.5.2
 signing_key: 
 specification_version: 4
 summary: Provides tools for working with tables as a data type.