fat_table 0.9.8 → 1.0.0

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

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: fat_table
 version: !ruby/object:Gem::Version
-  version: 0.9.8
+  version: 1.0.0
 platform: ruby
 authors:
 - Daniel E. Doherty
 bindir: bin
 cert_chain: []
-date: 2024-12-31 00:00:00.000000000 Z
+date: 2025-12-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: csv
@@ -116,6 +116,7 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".envrc"
+- ".github/workflows/ruby-with-dbs.yml"
 - ".gitignore"
 - ".rspec"
 - ".rubocop.yml"
@@ -123,25 +124,22 @@ files:
 - ".solargraph.yml"
 - ".travis.yml"
 - ".yardopts"
+- CHANGELOG.md
+- CHANGELOG.org
 - Gemfile
 - LICENSE.txt
+- README.md
 - README.org
 - README.rdoc
 - Rakefile
 - TODO.org
 - bin/ft_console
 - bin/setup
-- examples/create_trans.sql
-- examples/quick.pdf
-- examples/quick.png
-- examples/quick.ppm
-- examples/quick.tex
-- examples/quick_small.png
-- examples/quicktable.tex
-- examples/trades.db
-- examples/trans.csv
+- data/xcolors.txt
 - fat_table.gemspec
-- lib/ext/array.rb
+- lib/core_ext.rb
+- lib/core_ext/array.rb
+- lib/core_ext/numeric_string.rb
 - lib/fat_table.rb
 - lib/fat_table/column.rb
 - lib/fat_table/convert.rb
@@ -157,7 +155,6 @@ files:
 - lib/fat_table/formatters/org_formatter.rb
 - lib/fat_table/formatters/term_formatter.rb
 - lib/fat_table/formatters/text_formatter.rb
-- lib/fat_table/formatters/xcolors.txt
 - lib/fat_table/patches.rb
 - lib/fat_table/table.rb
 - lib/fat_table/version.rb

data/examples/create_trans.sql

@@ -1,14 +0,0 @@
-drop table trans;
-create table trans(date text, code text, raw, shares, price, info text, ok text);
-insert into trans values('2013-05-29', 'S', 15700.00, 6601.85, 24.7790, 'ENTITY3', 'F');
-insert into trans values('2013-05-02', 'P', 118186.40, 118186.4, 11.8500, 'ENTITY1', 'T');
-insert into trans values('2013-05-20', 'S', 12000.00, 5046.00, 28.2804, 'ENTITY3', 'F');
-insert into trans values('2013-05-23', 'S', 8000.00, 3364.00, 27.1083, 'ENTITY3', 'T');
-insert into trans values('2013-05-23', 'S', 39906.00, 16780.47, 25.1749, 'ENTITY3', 'T');
-insert into trans values('2013-05-20', 'S', 85000.00, 35742.50, 28.3224, 'ENTITY3', 'T');
-insert into trans values('2013-05-02', 'P', 795546.20, 795546.2, 1.1850, 'ENTITY1', 'T');
-insert into trans values('2013-05-29', 'S', 13459.00, 5659.51, 24.7464, 'ENTITY3', 'T');
-insert into trans values('2013-05-20', 'S', 33302.00, 14003.49, 28.6383, 'ENTITY3', 'T');
-insert into trans values('2013-05-29', 'S', 15900.00, 6685.95, 24.5802, 'ENTITY3', 'T');
-insert into trans values('2013-05-30', 'S', 6679.00, 2808.52, 25.0471, 'ENTITY3', 'T');
-insert into trans values('2013-05-23', 'S', 23054.00, 9694.21, 26.8015, 'ENTITY3', 'F');

data/examples/quick.tex

@@ -1,8 +0,0 @@
-\documentclass{article}
-
-\usepackage{longtable}
-\usepackage[pdftex,table,x11names]{xcolor}
-
-\begin{document}
-\include{quicktable.tex}
-\end{document}

data/examples/quicktable.tex

@@ -1,123 +0,0 @@
-\begin{longtable}{clcrrc}
-\bfseries{Ref}&
-\multicolumn{1}{c}{\bfseries{Date}}&
-\bfseries{Code}&
-\multicolumn{1}{c}{\bfseries{Shares}}&
-\multicolumn{1}{c}{\bfseries{Price}}&
-\bfseries{Ok}\\
-\endhead
-\bfseries{1}&
-2013-05-02&
-P&
-\cellcolor{lightgray}{\textcolor{blue}{118,186.4}}&
-\$11.8500&
-Y\\
-\bfseries{2}&
-2013-05-02&
-P&
-\cellcolor{lightgray}{\textcolor{blue}{795,546.2}}&
-1.1850&
-Y\\
-\bfseries{Avg}&
-&
-\multicolumn{1}{l}{}&
-\bfseries{456,866.3}&
-\bfseries{6.5175}&
-\\
-\bfseries{3}&
-2013-05-20&
-S&
-\cellcolor{lightgray}{\textcolor{blue}{5,046.0}}&
-28.2804&
-N\\
-\bfseries{4}&
-2013-05-20&
-S&
-\cellcolor{lightgray}{\textcolor{blue}{35,742.5}}&
-28.3224&
-Y\\
-\bfseries{5}&
-2013-05-20&
-S&
-\cellcolor{lightgray}{\textcolor{blue}{14,003.5}}&
-28.6383&
-Y\\
-\bfseries{Avg}&
-&
-\multicolumn{1}{l}{}&
-\bfseries{18,264.0}&
-\bfseries{28.4137}&
-\\
-\bfseries{6}&
-2013-05-23&
-S&
-\cellcolor{lightgray}{\textcolor{blue}{3,364.0}}&
-27.1083&
-Y\\
-\bfseries{7}&
-2013-05-23&
-S&
-\cellcolor{lightgray}{\textcolor{blue}{16,780.5}}&
-25.1749&
-Y\\
-\bfseries{8}&
-2013-05-23&
-S&
-\cellcolor{lightgray}{\textcolor{blue}{9,694.2}}&
-26.8015&
-N\\
-\bfseries{Avg}&
-&
-\multicolumn{1}{l}{}&
-\bfseries{9,946.2}&
-\bfseries{26.3616}&
-\\
-\bfseries{9}&
-2013-05-29&
-S&
-\cellcolor{lightgray}{\textcolor{blue}{6,601.9}}&
-24.7790&
-N\\
-\bfseries{10}&
-2013-05-29&
-S&
-\cellcolor{lightgray}{\textcolor{blue}{5,659.5}}&
-24.7464&
-Y\\
-\bfseries{11}&
-2013-05-29&
-S&
-\cellcolor{lightgray}{\textcolor{blue}{6,686.0}}&
-24.5802&
-Y\\
-\bfseries{Avg}&
-&
-\multicolumn{1}{l}{}&
-\bfseries{6,315.8}&
-\bfseries{24.7019}&
-\\
-\bfseries{12}&
-2013-05-30&
-S&
-\cellcolor{lightgray}{\textcolor{blue}{2,808.5}}&
-25.0471&
-Y\\
-\bfseries{Avg}&
-&
-\multicolumn{1}{l}{}&
-\bfseries{2,808.5}&
-\bfseries{25.0471}&
-\\
-\bfseries{Average}&
-&
-\multicolumn{1}{l}{}&
-\bfseries{85,009.9}&
-\bfseries{23.0428}&
-\\
-\bfseries{Total}&
-&
-\multicolumn{1}{l}{}&
-\bfseries{1,020,119.1}&
-\bfseries{}&
-\\
-\end{longtable}

data/examples/trans.csv

@@ -1,13 +0,0 @@
-'Date', 'Code', 'Raw', 'Shares', 'Price', 'Info', 'Ok',
-'2013-05-29', 'S', 15700.00, 6601.85, 24.7790, 'ENTITY3', FALSE,
-'2013-05-02', 'P', 118186.40, 118186.4, 11.8500, 'ENTITY1', TRUE,
-'2013-05-20', 'S', 12000.00, 5046.00, 28.2804, 'ENTITY3', FALSE,
-'2013-05-23', 'S', 8000.00, 3364.00, 27.1083, 'ENTITY3', TRUE,
-'2013-05-23', 'S', 39906.00, 16780.47, 25.1749, 'ENTITY3', TRUE,
-'2013-05-20', 'S', 85000.00, 35742.50, 28.3224, 'ENTITY3', TRUE,
-'2013-05-02', 'P', 795546.20, 795546.2, 1.1850, 'ENTITY1', TRUE,
-'2013-05-29', 'S', 13459.00, 5659.51, 24.7464, 'ENTITY3', TRUE,
-'2013-05-20', 'S', 33302.00, 14003.49, 28.6383, 'ENTITY3', TRUE,
-'2013-05-29', 'S', 15900.00, 6685.95, 24.5802, 'ENTITY3', TRUE,
-'2013-05-30', 'S', 6679.00, 2808.52, 25.0471, 'ENTITY3', TRUE,
-'2013-05-23', 'S', 23054.00, 9694.21, 26.8015, 'ENTITY3', FALSE