tabulo 2.2.0 → 2.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 295d0e4161611edd684ef1f65143767b418af24f0e630e83bb6554cf25636e44
-  data.tar.gz: e4a0e0fcc8a2efdedb251d413f65f2627b7706136af55026728d6c906f0bc311
+  metadata.gz: 87e2e8bb108886b594c80a32396ab586c90792ae6e5efeb5769e457b13d6c96d
+  data.tar.gz: 03c93ac0d5419fb654244ab574d9e7aa43263f40ca71e008f6d43772a76ffece
 SHA512:
-  metadata.gz: 8cc23cce74adbe70451dc387007baa32339ac8d0942d55594e8516ac871880c4ef8176a69db5da7dad2dcfa122d83ae838cb9129e3df8212f3a1ae4ab337c92a
-  data.tar.gz: dfa4e051e1f45a41e3611b8c22422ee9f043671d4d7f432318fab6465c6b888c5a3e67302a3950e241d73dc17e99d3b26e2d2738b3eacc162f5a4e07b628acaa
+  metadata.gz: ae04026433b44638cd777f483fb0e8b0494370cc71fb84c5bc91cc38c65c92aa4e68183b48db1e92e53b3e3ede6b680975190d2626510f0ad31b6f651bb9538d
+  data.tar.gz: 5a543577d7d678ccee445789d588147a778fa45899876872749ad1ced9119e99369b43b1e7b642d2f9eae27c41d2e904de9d7765513b9b813824deac5e8d958c

data/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+### v2.3.0
+
+* Provide `#remove_column` method.
+* Provide `before` option to `#add_column`, to allow insertion of column into non-final position.
+* Provide `styler` and `header_styler` options in table initializer, to enable default stylers
+  to be set for all columns.
+* Documentation improvements and code tidy-ups.
+
 ### v2.2.0
 
 * New `column_formatter` option on `Tabulo::Table` initializer, enabling the table's default column
@@ -15,7 +23,7 @@
 
 ### v2.1.0
 
-* New `:reduced_ascii` and `:reduced_modern` border options
+* New `reduced_ascii` and `reduced_modern` border options
 * Fix `column_width` option not properly inherited from original table by the new table created
   by calling #transpose.
 

data/README.md

@@ -7,13 +7,9 @@
 [![Code Climate][CC img]][Code Climate]
 [![Awesome][AR img]][Awesome Ruby]
 
-Tabulo is a terminal table generator for Ruby.
+Tabulo is a terminal table generator for Ruby. It is both highly configurable and very easy to use.
 
-It offers a DRY, "column-centric" interface, and is designed to make it very easy to produce highly
-readable tables, even from large and unwieldy data sets and streams.
-
-Tabulo is both easy to use and feature rich, allowing you to quickly tabulate any enumerable
-collection, with options for automatic column sizing, a variety of border styles, and more.
+_Quick API:_
 
 ```
 > puts Tabulo::Table.new(User.all, :id, :first_name, :last_name, border: :modern).pack
@@ -25,12 +21,35 @@ collection, with options for automatic column sizing, a variety of border styles
 └────┴────────────┴───────────┘
 ```
 
+_Full API:_
+
+```
+table = Tabulo::Table.new(User.all, border: :modern) do |t|
+  t.add_column("ID", &:id)
+  t.add_column("First name", &:first_name)
+  t.add_column("Last name") { |user| user.last_name.upcase }
+end
+```
+
+```
+> puts table.pack
+┌────┬────────────┬───────────┐
+│ ID │ First name │ Last name │
+├────┼────────────┼───────────┤
+│  1 │ John       │ CITIZEN   │
+│  2 │ Jane       │ DOE       │
+└────┴────────────┴───────────┘
+```
+
 ## Features
 
+* Presents a [DRY initialization interface](#configuring-columns): by being “column based” rather than
+  “row based”, it spares the developer the burden of syncing the ordering within the header row
+  with that of the body rows.
 * Lets you set [fixed column widths](#fixed-column-widths), then either [wrap](#overflow-handling)
   or [truncate](#overflow-handling) the overflow.
-* Alternatively, ["pack"](#pack) the table so that each column is automatically just wide enough for
-  its contents, but [without overflowing the terminal horizontally](#max-table-width).
+* Alternatively, you can [“pack”](#pack) the table so that each column is automatically just
+  wide enough for its contents, but [without overflowing the terminal horizontally](#max-table-width).
 * Alignment of cell content is [configurable](#cell-alignment), but has helpful content-based
   defaults (numbers right, strings left).
 * Tabulate any `Enumerable`: the underlying collection need not be an array.
@@ -44,9 +63,8 @@ collection, with options for automatic column sizing, a variety of border styles
 * Multibyte Unicode characters are correctly handled.
 * Apply [colours](#colours-and-styling) and other styling to table content and borders, without breaking the table.
 * Easily [transpose](#transposition) the table, so that rows are swapped with columns.
-* Choose from multiple [border configurations](#borders), including Markdown, "ASCII", and smoothly joined Unicode border characters.
-* Use a [DRY initialization interface](#configuring-columns): by being "column based", it is
-  designed to spare the developer the burden of syncing the ordering within the header row with that of the body rows.
+* Choose from multiple [border configurations](#borders), including Markdown, “ASCII”, and smoothly
+  joined Unicode border characters.
 
 Tabulo has also been ported to Crystal (with some modifications): see [Tablo](https://github.com/hutou/tablo).
 
@@ -65,7 +83,11 @@ Tabulo has also been ported to Crystal (with some modifications): see [Tablo](ht
         * [Automating column widths](#automating-column-widths)
         * [Overflow handling](#overflow-handling)
      * [Formatting cell values](#formatting-cell-values)
-     * [Colours and styling](#colours-and-styling)
+     * [Colours and other styling](#colours-and-styling)
+        * [Styling cell content](#styling-cell-content)
+        * [Styling column headers](#styling-column-headers)
+        * [Setting default styles](#default-styles)
+        * [Styling borders](#border-styling)
      * [Repeating headers](#repeating-headers)
      * [Using a Table Enumerator](#using-a-table-enumerator)
      * [Accessing cell values](#accessing-cell-values)
@@ -73,13 +95,14 @@ Tabulo has also been ported to Crystal (with some modifications): see [Tablo](ht
      * [Transposing rows and columns](#transposition)
      * [Border configuration](#borders)
      * [Row dividers](#dividers)
+     * [Using a table as a snapshot rather than as a dynamic view](#freezing-a-table)
   * [Comparison with other libraries](#motivation)
   * [Contributing](#contributing)
   * [License](#license)
 
 ## Installation
 
-Add this line to your application's Gemfile:
+Add this line to your application’s Gemfile:
 
 ```ruby
 gem 'tabulo'
@@ -126,7 +149,7 @@ table = Tabulo::Table.new([1, 2, 5]) do |t|
 end
 ```
 
-When the columns correspond to methods, you can also use the "quick API", by passing a symbol
+When the columns correspond to methods, you can also use the “quick API”, by passing a symbol
 directly to `new` for each column:
 
 ```ruby
@@ -167,6 +190,30 @@ end
 +--------------+--------------+--------------+
 ```
 
+By default, each new column is added to the right of all the other columns so far added to the
+table. However, if you want to insert a new column into some other position, you can use the
+`before` option, passing the label of the column to the left of which you want the new column to be added:
+
+```ruby
+table = Table::Table.new([1, 2, 3], :itself, :odd?)
+table.add_column(:even?, before: :odd?)
+```
+
+```
+> puts table
++--------------+--------------+--------------+
+|    itself    |     even?    |     odd?     |
++--------------+--------------+--------------+
+|            1 |     false    |     true     |
+|            2 |     true     |     false    |
+|            5 |     false    |     true     |
++--------------+--------------+--------------+
+```
+
+There is also a `#remove_column` method, for deleting an existing column from a table; see the
+[documentation](https://www.rubydoc.info/gems/tabulo/2.3.0/Tabulo/Table#remove_column-instance_method)
+for details.
+
 <a name="cell-alignment"></a>
 ### Cell alignment
 
@@ -278,7 +325,7 @@ table = Tabulo::Table.new([1, 2, 5], :itself, :even?, :odd?, column_padding: [0,
 <a name="pack"></a>
 #### Automating column widths
 
-Instead of setting column widths "manually", you can tell the table to sort out the widths
+Instead of setting column widths &ldquo;manually&rdquo;, you can tell the table to sort out the widths
 itself, so that each column is just wide enough for its header and contents (plus a character
 of padding):
 
@@ -297,7 +344,7 @@ table.pack
 +--------+-------+
 ```
 
-The `pack` method returns the table itself, so you can "pack-and-print" in one go:
+The `pack` method returns the table itself, so you can &ldquo;pack-and-print&rdquo; in one go:
 
 ```ruby
 puts Tabulo::Table.new([1, 2], :itself, :even?).pack
@@ -334,12 +381,15 @@ the table will fit.
 
 Note that `pack`ing the table necessarily involves traversing the entire collection up front as
 the maximum cell width needs to be calculated for each column. You may not want to do this
-if the collection is very large. Note also the effect of `pack` is to fix the column widths
-as appropriate to the formatted cell contents given the state of the underlying collection
-_at the point of packing_. If the underlying collection changes between that point, and when
-the table is printed, then the columns will _not_ be resized yet again on printing. This is a
-consequence of the table always being essentially a "live view" on the underlying collection:
-formatted contents are never cached within the table itself.
+if the collection is very large.
+
+Note also the effect of `pack` is to fix the column widths as appropriate to the formatted cell
+contents given the state of the underlying collection _at the point of packing_. If the underlying
+collection changes between that point, and when the table is printed, then the columns will _not_ be
+resized yet again on printing. This is a consequence of the table always being essentially a
+&ldquo;live view&rdquo; on the underlying collection: formatted contents are never cached within the
+table itself. There are [ways around this](#freezing-a-table), however, if this is not the desired
+behaviour&mdash;see [below](#freezing-a-table).
 
 <a name="overflow-handling"></a>
 #### Overflow handling
@@ -397,10 +447,10 @@ The character used to indicate truncation, which defaults to `~`, can be configu
 ### Formatting cell values
 
 While the callable passed to `add_column` determines the underyling, calculated value in each
-cell of the column, there is a separate concept, of a "formatter", that determines how that value will
-be visually displayed. By default, `.to_s` is called on the underlying cell value to "format"
-it; however, you can format it differently by passing another callable to the `formatter` option
-of `add_column`:
+cell of the column, there is a separate concept, of a &ldquo;formatter&rdquo;, that determines how
+that value will be visually displayed. By default, `.to_s` is called on the underlying cell value to
+&ldquo;format&rdquo; it; however, you can format it differently by passing another callable to the
+`formatter` option of `add_column`:
 
 ```ruby
 table = Tabulo::Table.new(1..3) do |t|
@@ -422,7 +472,7 @@ end
 +--------------+--------------+
 ```
 
-Note the numbers in the "Reciprocal" column in this example are still right-aligned, even though
+Note the numbers in the &ldquo;Reciprocal&rdquo; column in this example are still right-aligned, even though
 the callable passed to `formatter` returns a String. Default cell alignment is determined by the type
 of the underlying cell value, not the way it is formatted. This is usually the desired result.
 
@@ -452,7 +502,10 @@ Formatters set for individual columns on calling `#add_column` always override t
 the table.
 
 <a name="colours-and-styling"></a>
-### Colours and styling
+### Colours and other styling
+
+<a name="styling-cell-content"></a>
+#### Styling cell content
 
 In most terminals, if you want to print text that is coloured, or has certain other styles such as
 underlining, you need to use ANSI escape sequences, either directly, or by means of a library such
@@ -485,13 +538,19 @@ table.add_column(
 )
 ```
 
-The `styler` option should be passed a callable that takes two parameters: the
-first represents the content of the cell (in this case a boolean indicating whether the
-number is even); and the second represents the formatted string value of that cell, i.e. the
-cell content after any processing by the [formatter](#formatting-cell-values).
-If the content of a cell is wrapped over multiple lines, then the `styler` will be called
-once per line, so that each line of the cell will have the escape sequence applied to it
-separately (ensuring the styling doesn't bleed into neighbouring cells).
+The `styler` option should be passed a callable that takes two parameters: the first represents
+the underlying value of the cell (in this case a boolean indicating whether the number is even);
+and the second represents the formatted string value of that cell, i.e. the cell content after
+any processing by the [formatter](#formatting-cell-values). If the content of a cell is wrapped
+over multiple lines, then the `styler` will be called once per line, so that each line of the
+cell will have the escape sequence applied to it separately (ensuring the styling doesn&#8217;t bleed
+into neighbouring cells).
+
+If the content of a cell has been [truncated](#overflow-handling), then whatever colours or other styling
+apply to the cell content will also be applied the truncation indicator character.
+
+<a name="styling-column-headers"></a>
+#### Styling column headers
 
 If you want to apply colours or other styling to the content of a column header, as opposed
 to cells in the table body, use the `header_styler` option, e.g.:
@@ -500,23 +559,39 @@ to cells in the table body, use the `header_styler` option, e.g.:
 table.add_column(:even?, header_styler: -> (s) { "\033[32m#{s}\033[0m" })
 ```
 
-To apply colours or other styling to the row divider, column divider, corner and border
-characters of the table, use the `border_styler` option when initializing the table, e.g.:
+<a name="default-styles"></a>
+#### Setting default styles
+
+By default, no styling is applied to the headers or body content of a column unless configured to do
+so via the `header_styler` or `styler` option when calling `add_column` for that particular column.
+It is possible to apply styling by default to _all_ columns in a table, however, as the table initializer
+also accepts both a `header_styler` and a `styler` option. For example, if you want all the header text
+in the table to be green, you could do:
 
 ```ruby
-table = Tabulo::Table.new(1..5, :itself, :even?, :odd?, border_styler: -> (s) { "\033[32m#{s}\033[0m" })
+table = Tabulo::Table.new(1..5, :itself, :even?, :odd?, header_styler: -> (s) { "\033[32m#{s}\033[0m" })
 ```
 
-If the content of a cell has been [truncated](#overflow-handling), then whatever colours or other styling
-apply to the cell content will also be applied the truncation indicator character.
+Now, all columns in the table will have automatically have green header text, unless overridden
+by another header styler being passed to `#add_column`.
+
+<a name="border-styling"></a>
+#### Styling borders
+
+Styling can also be applied to borders and dividing lines, using the `border_styler` option when
+initializing the table, e.g.:
+
+```ruby
+table = Tabulo::Table.new(1..5, :itself, :even?, :odd?, border_styler: -> (s) { "\033[32m#{s}\033[0m" })
+```
 
 <a name="repeating-headers"></a>
 ### Repeating headers
 
 By default, headers are only shown once, at the top of the table (`header_frequency: :start`). If
 `header_frequency` is passed `nil`, headers are not shown at all; or, if passed an `Integer` N,
-headers are shown at the top and then repeated every N rows. This can be handy when you're looking
-at table that's taller than your terminal.
+headers are shown at the top and then repeated every N rows. This can be handy when you&#8217;re looking
+at table that&#8217;s taller than your terminal.
 
 E.g.:
 
@@ -548,7 +623,7 @@ table = Tabulo::Table.new(1..10, :itself, :even?, header_frequency: 5)
 <a name="enumerator"></a>
 ### Using a Table Enumerator
 
-Because it's an `Enumerable`, a `Tabulo::Table` can also give you an `Enumerator`,
+Because it&#8217;s an `Enumerable`, a `Tabulo::Table` can also give you an `Enumerator`,
 which is useful when you want to step through rows one at a time. In a Rails console,
 for example, you might do this:
 
@@ -596,8 +671,8 @@ end
 
 The first argument to `add_column` always provides the key for the purpose of accessing the `Hash`
 form of a `Tabulo::Row`. (If the provided argument was a `String`, it will be converted to a
-`Symbol` for purposes of accessing this `Hash`.) This key serves as a sort of "logical label" for
-the column; and it need not be the same as the column header. If we want the header to be different
+`Symbol` for purposes of accessing this `Hash`.) This key serves as a sort of &ldquo;logical label&rdquo;
+for the column; and it need not be the same as the column header. If we want the header to be different
 to the label, we can achieve this using the `header` option to `add_column`:
 
 ```ruby
@@ -676,8 +751,8 @@ a new table in which the rows and columns are swapped:
 
 By default, a header row is added to the new table, showing the string value of the element
 represented in that column. This can be configured, however, along with other aspects of
-`transpose`'s behaviour. For details, see the
-[documentation](https://www.rubydoc.info/gems/tabulo/2.2.0/Tabulo/Table#transpose-instance_method).
+`transpose`&#8217;s behaviour. For details, see the
+[documentation](https://www.rubydoc.info/gems/tabulo/2.3.0/Tabulo/Table#transpose-instance_method).
 
 <a name="borders"></a>
 ### Configuring borders
@@ -813,6 +888,76 @@ If you want a line before every row, pass `1` to `row_divider_frequency`. For ex
 └──────────────┴──────────────┴──────────────┘
 ```
 
+<a name="freezing-a-table"></a>
+### Using a table as a snapshot rather than as a dynamic view
+
+The nature of a `Tabulo::Table` is that of a dynamic view onto the underlying `sources` enumerable
+from which it was initialized (or which was subsequently assigned to its `sources` attribute). That
+is, if the contents of the `sources` enumerable change subsequent to initialization of or assignment to
+`sources`, then the table when printed will show the `sources` as they are at the time of printing,
+not as they were at the time of initialization or assignment. For example:
+
+```ruby
+arr = [1, 2]
+table = Tabulo::Table.new(arr, :itself, :even?, :odd?)
+```
+
+```
+> puts table
++--------------+--------------+--------------+
+|    itself    |     even?    |     odd?     |
++--------------+--------------+--------------+
+|            1 |     false    |     true     |
+|            2 |     true     |     false    |
++--------------+--------------+--------------+
+```
+
+```ruby
+arr << 3
+```
+
+```
+> puts table
++--------------+--------------+--------------+
+|    itself    |     even?    |     odd?     |
++--------------+--------------+--------------+
+|            1 |     false    |     true     |
+|            2 |     true     |     false    |
+|            3 |     false    |     true     |
++--------------+--------------+--------------+
+```
+
+In this example, even though no direct mutations have been made to `table`, the result
+of calling `puts table` has changed, in virtue of a mutation on the underyling enumerable `arr`.
+
+A similar behaviour can be seen when `sources` is an ActiveRecord query, and there
+are changes to the relevant database table(s) such that the result of the query changes. This is
+worth bearing in mind when calling [`pack`](#pack) on a table, since if the `sources` enumerable
+changes between `pack`ing and printing, then the column widths calculated by the `pack` method
+may no longer be &ldquo;just right&rdquo; given the changed `sources`.
+
+If this is not the desired behaviour, there are ways around this. For example, if dealing with an
+ActiveRecord relation, you can convert the query to a plain array before initializing the table:
+
+```ruby
+sources = User.all.to_a
+table = Tabulo::Table.new(sources, :id, :first_name, :last_name)
+table.pack
+puts table
+```
+
+Passing an `Array` rather than the ActiveRecord query directly means that if there are changes to
+the content of the `users` database table, these will not be reflected in the rendered content of
+the `Tabulo::Table` (unless some of the `Tabulo::Table` columns are based on callables that perform
+further database queries when called&hellip;).
+
+Note that it is also possible simply to store the string value of a table for later use,
+rather than the table itself:
+
+```ruby
+rendered_table = Tabulo::Table.new(1..10, :itself, :even?, :odd?).pack.to_s
+```
+
 <a name="motivation"></a>
 ## Comparison with other libraries
 
@@ -826,7 +971,7 @@ There are other libraries for generating plain text tables in Ruby. Popular amon
 *DISCLAIMER: My comments regarding these other libraries are based only on my own, possibly flawed
 reading of the documentation for, and experimentation with, these libraries at the time of my
 writing this. Their APIs, features or documentation may well change between when I write this, and
-when you read it. Please consult the libraries' own documentation for yourself, rather than relying
+when you read it. Please consult the libraries&#8217; own documentation for yourself, rather than relying
 on these comments.*
 
 While these libraries have their strengths, I have personally found that, for the common use case of
@@ -835,7 +980,7 @@ query result), using these libraries feels more cumbersome than it could be.
 
 For example, suppose we have called `User.all` from the Rails console, and want to print
 a table showing the email, first name, last name and ID of each user,
-with column headings. Also, we want the ID column to be right-aligned, because it's a number.
+with column headings. Also, we want the ID column to be right-aligned, because it&#8217;s a number.
 
 In **terminal-table**, we could achieve this as follows:
 
@@ -848,7 +993,7 @@ puts table
 ```
 
 The problem here is that there is no single source of knowledge about which columns
-appear, and in which order. If we want to add another column to the left of "email",
+appear, and in which order. If we want to add another column to the left of &ldquo;email&rdquo;,
 we need to amend the rows array, and the headings array, and the index passed to `align_column`.
 We bear the burden of keeping these three in sync. This is not be a big deal for small one-off
 tables, but for tables that have many columns, or that are constructed
@@ -856,9 +1001,9 @@ dynamically based on user input or other runtime factors determining the columns
 to be included, this can be a hassle and a source of brittleness.
 
 **tty-table** has a somewhat different API to `terminal-table`. It offers both a
-"row-based" and a "column-based" method of initializing a table. The row-based method
-is similar to `terminal-table`'s in that it burdens the developer with syncing the
-column ordering across multiple code locations. The "column-based" API for `tty-table`, on
+&ldquo;row-based&rdquo; and a &ldquo;column-based&rdquo; method of initializing a table. The row-based method
+is similar to `terminal-table`&#8217;s in that it burdens the developer with syncing the
+column ordering across multiple code locations. The &ldquo;column-based&rdquo; API for `tty-table`, on
 the other hand, seems to avoid this problem. One way of using it is like this:
 
 ```ruby
@@ -874,26 +1019,27 @@ table = TTY::Table.new [
 puts table
 ```
 
-While this doesn't seem too bad, it does mean that the underlying collection (`users`) has to
+While this doesn&#8217;t seem too bad, it does mean that the underlying collection (`users`) has to
 be traversed multiple times, once for each column, which is inefficient, particularly
-if the underlying collection is large. In addition, it's not clear how to pass separate
+if the underlying collection is large. In addition, it&#8217;s not clear how to pass separate
 formatting information for each column when initializing in this way. (Perhaps there is a way to do
-this, but if there is, it doesn't seem to be documented.) So it seems we still have to use
+this, but if there is, it doesn&#8217;t seem to be documented.) So it seems we still have to use
 `table.align_column(3, :right)`, which again burdens us with keeping the column index
 passed to `align_column` in sync.
 
 As for **table\_print**, this is a handy gem for quickly tabulating ActiveRecord
 collections from the Rails console. `table_print` is similar to `tabulo` in that it has a
-column-based API, so it doesn't suffer from the multiple-source-of-knowledge issue in regards to
+column-based API, so it doesn&#8217;t suffer from the multiple-source-of-knowledge issue in regards to
 column orderings. However, it lacks certain other useful features, such as the ability to repeat
 headers every N rows, the automatic alignment of columns based on cell content (numbers right,
 strings left), and a quick and easy way to automatically resize columns to accommodate cell content
-without overflowing the terminal. Also, as of the time of writing, `table_print`'s last significant
+without overflowing the terminal. Also, as of the time of writing, `table_print`&#8217;s last significant
 commit (ignoring a deprecation warning fix in April 2018) was in March 2016.
 
-Finally, it is worth mentioning the **hirb** library. This is similar to `table_print`, in that it's
+Finally, it is worth mentioning the **hirb** library. This is similar to `table_print`, in that
+it&#8217;s
 well suited to quickly displaying ActiveRecord collections from the Rails console. However, like
-`table_print`, there are certain useful features it's lacking; and using it outside the console
+`table_print`, there are certain useful features it&#8217;s lacking; and using it outside the console
 environment seems cumbersome. Moreover, it seems no longer to be maintained. At the time of writing,
 its last commit was in March 2015.
 
@@ -915,14 +1061,14 @@ The gem is available as open source under the terms of the [MIT
 License](http://opensource.org/licenses/MIT).
 
 [Gem Version]: https://rubygems.org/gems/tabulo
-[Documentation]: http://www.rubydoc.info/gems/tabulo/2.2.0
+[Documentation]: http://www.rubydoc.info/gems/tabulo/2.3.0
 [Build Status]: https://travis-ci.org/matt-harvey/tabulo
 [Coverage Status]: https://coveralls.io/r/matt-harvey/tabulo
 [Code Climate]: https://codeclimate.com/github/matt-harvey/tabulo
 [Awesome Ruby]: https://github.com/markets/awesome-ruby#cli-utilities
 
 [GV img]: https://img.shields.io/gem/v/tabulo.svg
-[DC img]: https://img.shields.io/badge/documentation-v2.2.0-blue.svg
+[DC img]: https://img.shields.io/badge/documentation-v2.3.0-blue.svg
 [BS img]: https://img.shields.io/travis/matt-harvey/tabulo.svg
 [CS img]: https://img.shields.io/coveralls/matt-harvey/tabulo.svg
 [CC img]: https://codeclimate.com/github/matt-harvey/tabulo/badges/gpa.svg

data/VERSION

@@ -1 +1 @@
-2.2.0
+2.3.0

data/lib/tabulo/column.rb

@@ -6,16 +6,23 @@ module Tabulo
     attr_accessor :width
     attr_reader :header
 
-    def initialize(header:, width:, align_header:, align_body:, formatter:, extractor:, styler:,
-      header_styler:, truncation_indicator:, padding_character:)
+    def initialize(
+      align_body:,
+      align_header:,
+      extractor:,
+      formatter:,
+      header:,
+      header_styler:,
+      padding_character:,
+      styler:,
+      truncation_indicator:,
+      width:)
 
-      @header = header
-      @width = width
-      @align_header = align_header
       @align_body = align_body
-      @formatter = formatter
+      @align_header = align_header
       @extractor = extractor
-      @styler = styler || -> (_, s) { s }
+      @formatter = formatter
+      @header = header
 
       @header_styler =
         if header_styler
@@ -24,31 +31,33 @@ module Tabulo
           -> (_, s) { s }
         end
 
-      @truncation_indicator = truncation_indicator
       @padding_character = padding_character
+      @styler = styler || -> (_, s) { s }
+      @truncation_indicator = truncation_indicator
+      @width = width
     end
 
     def header_cell
       Cell.new(
-        value: @header,
-        formatter: -> (s) { s },
         alignment: @align_header,
-        width: @width,
+        formatter: -> (s) { s },
+        padding_character: @padding_character,
         styler: @header_styler,
         truncation_indicator: @truncation_indicator,
-        padding_character: @padding_character,
+        value: @header,
+        width: @width,
       )
     end
 
     def body_cell(source)
       Cell.new(
-        value: body_cell_value(source),
-        formatter: @formatter,
         alignment: @align_body,
-        width: @width,
+        formatter: @formatter,
+        padding_character: @padding_character,
         styler: @styler,
         truncation_indicator: @truncation_indicator,
-        padding_character: @padding_character,
+        value: body_cell_value(source),
+        width: @width,
       )
     end
 

data/lib/tabulo/row.rb

@@ -7,11 +7,11 @@ module Tabulo
     attr_reader :source
 
     # @!visibility private
-    def initialize(table, source, header: :top, divider: false)
+    def initialize(table, source, divider: false, header: :top)
       @table = table
       @source = source
-      @header = header
       @divider = divider
+      @header = header
     end
 
     # Calls the given block once for each {Cell} in the {Row}, passing that {Cell} as parameter.

data/lib/tabulo/table.rb

@@ -74,17 +74,21 @@ module Tabulo
     #   element indicates the amount to apply to the right.
     # @param [Integer, nil] column_width The default column width for columns in this
     #   table, not excluding padding. If <tt>nil</tt>, then {DEFAULT_COLUMN_WIDTH} will be used.
-    # @param [nil, #to_proc] formatter (:to_s.to_proc) The default value for the `formatter` option
-    #   when columns are added to this table via {#add_column}.
+    # @param [nil, #to_proc] formatter (:to_s.to_proc) The default formatter for columns in this
+    #   table. See `formatter` option of {#add_column} for details.
     # @param [:start, nil, Integer] header_frequency (:start) Controls the display of column headers.
     #   If passed <tt>:start</tt>, headers will be shown at the top of the table only. If passed <tt>nil</tt>,
     #   headers will not be shown. If passed an Integer N (> 0), headers will be shown at the top of the table,
     #   then repeated every N rows.
+    # @param [nil, #to_proc] header_styler (nil) The default header styler for columns in this
+    #   table. See `header_styler` option of {#add_column} for details.
     # @param [nil, Integer] row_divider_frequency (nil) Controls the display of horizontal row dividers within
     #   the table body. If passed <tt>nil</tt>, dividers will not be shown. If passed an Integer N (> 0),
     #   dividers will be shown after every N rows. The characters used to form the dividers are
     #   determined by the `border` option, and are the same as those used to form the bottom edge of the
     #   header row.
+    # @param [nil, #to_proc] styler (nil) The default styler for columns in this table. See `styler`
+    #   option of {#add_column} for details.
     # @param [nil, String] truncation_indicator Determines the character used to indicate that a
     #   cell's content has been truncated. If omitted or passed <tt>nil</tt>,
     #   defaults to {DEFAULT_TRUNCATION_INDICATOR}. If passed something other than <tt>nil</tt> or
@@ -114,7 +118,9 @@ module Tabulo
       column_width:          nil,
       formatter:             :to_s.to_proc,
       header_frequency:      :start,
+      header_styler:         nil,
       row_divider_frequency: nil,
+      styler:                nil,
       truncation_indicator:  nil,
       wrap_body_cells_to:    nil,
       wrap_header_cells_to:  nil)
@@ -139,6 +145,7 @@ module Tabulo
       @column_width = (column_width || DEFAULT_COLUMN_WIDTH)
       @formatter = formatter
       @header_frequency = header_frequency
+      @header_styler = header_styler
       @row_divider_frequency = row_divider_frequency
       @truncation_indicator = validate_character(truncation_indicator,
         DEFAULT_TRUNCATION_INDICATOR, InvalidTruncationIndicatorError, "truncation indicator")
@@ -171,6 +178,11 @@ module Tabulo
     #   by the Table-level setting passed to the <tt>align_header</tt> (which itself defaults
     #   to <tt>:center</tt>). Otherwise, this option determines the alignment of the header
     #   content for this column.
+    # @param [Symbol, String, Integer, nil] before (nil) The label of the column before (i.e. to
+    #   the left of) which the new column should inserted. If <tt>nil</tt> is passed, it will be
+    #   inserted after all other columns. If there is no column with the given label, then an
+    #   {InvalidColumnLabelError} will be raised. A non-Integer labelled column can be identified
+    #   in either String or Symbol form for this purpose.
     # @param [#to_proc] formatter (nil) A lambda or other callable object that
     #   will be passed the calculated value of each cell to determine how it should be displayed. This
     #   is distinct from the extractor (see below). For example, if the extractor for this column
@@ -222,6 +234,7 @@ module Tabulo
       label,
       align_body:    nil,
       align_header:  nil,
+      before:        nil,
       formatter:     nil,
       header:        nil,
       header_styler: nil,
@@ -241,19 +254,43 @@ module Tabulo
         raise InvalidColumnLabelError, "Column label already used in this table."
       end
 
-      @column_registry[column_label] =
-        Column.new(
-          align_body: align_body || @align_body,
-          align_header: align_header || @align_header,
-          extractor: extractor || label.to_proc,
-          formatter: formatter || @formatter,
-          header: (header || label).to_s,
-          header_styler: header_styler,
-          padding_character: PADDING_CHARACTER,
-          styler: styler,
-          truncation_indicator: @truncation_indicator,
-          width: width || @column_width,
-        )
+      column = Column.new(
+        align_body: align_body || @align_body,
+        align_header: align_header || @align_header,
+        extractor: extractor || label.to_proc,
+        formatter: formatter || @formatter,
+        header: (header || label).to_s,
+        header_styler: header_styler || @header_styler,
+        padding_character: PADDING_CHARACTER,
+        styler: styler || @styler,
+        truncation_indicator: @truncation_indicator,
+        width: width || @column_width,
+      )
+
+      add_column_before(column, column_label, before)
+    end
+
+    # Removes the column identifed by the passed label.
+    #
+    # @example
+    #   table = Table.new(1..10, :itself, :even?, :odd?)
+    #   table.add_column(:even2, header: "even?") { |n| n.even? }
+    #   table.remove_column(:even2)
+    #   table.remove_column(:odd?)
+    #
+    # @param [Symbol, String, Integer] label The unique identifier for the column to be removed,
+    #   corresponding to the label that was passed as the first parameter to {#add_column} (or was
+    #   used in the table initializer) when the column was originally added. For columns that were
+    #   originally added with a String or Symbol label, either a String or Symbol form of that label
+    #   can be passed to {#remove_column}, indifferently. For example, if the label passed to
+    #   {#add_column} had been `"height"`, then that column could be removed by passing either
+    #   `"height"` or `:height` to {#remove_column}. (However, if an Integer was originally passed
+    #   as the label to {#add_column}, then only that same Integer, as an Integer, can be passed to
+    #   {#remove_column} to remove that column.)
+    # @return [true, false] If the label identifies a column in the table, then the column will be
+    #   removed and true will be returned; otherwise no column will be removed, and false will be returned.
+    def remove_column(label)
+      !!column_registry.delete(Integer === label ? label : label.to_sym)
     end
 
     # @return [String] a graphical "ASCII" representation of the Table, suitable for
@@ -420,15 +457,15 @@ module Tabulo
     # @return [Table] a new {Table}
     # @raise [InvalidBorderError] if invalid argument passed to `border` parameter.
     def transpose(opts = {})
-      default_opts = [:column_width, :column_padding, :formatter, :header_frequency,
-        :row_divider_frequency, :wrap_header_cells_to, :wrap_body_cells_to, :truncation_indicator, :align_header,
-        :align_body, :border, :border_styler].map do |sym|
+      default_opts = [:align_body, :align_header, :border, :border_styler, :column_padding, :column_width,
+        :formatter, :header_frequency, :row_divider_frequency, :truncation_indicator, :wrap_body_cells_to,
+        :wrap_header_cells_to].map do |sym|
         [sym, instance_variable_get("@#{sym}")]
       end.to_h
 
       initializer_opts = default_opts.merge(Util.slice_hash(opts, *default_opts.keys))
-      default_extra_opts = { field_names_width: nil, field_names_header: "",
-        field_names_body_alignment: :right, field_names_header_alignment: :right, headers: :to_s.to_proc }
+      default_extra_opts = { field_names_body_alignment: :right, field_names_header: "",
+        field_names_header_alignment: :right, field_names_width: nil, headers: :to_s.to_proc }
       extra_opts = default_extra_opts.merge(Util.slice_hash(opts, *default_extra_opts.keys))
 
       # The underlying enumerable for the new table, is the columns of the original table.
@@ -440,8 +477,9 @@ module Tabulo
         width_opt = extra_opts[:field_names_width]
         field_names_width = (width_opt.nil? ? fields.map { |f| f.header.length }.max : width_opt)
 
-        t.add_column(:dummy, header: extra_opts[:field_names_header], width: field_names_width, align_header:
-          extra_opts[:field_names_header_alignment], align_body: extra_opts[:field_names_body_alignment], &:header)
+        t.add_column(:dummy, align_body: extra_opts[:field_names_body_alignment],
+          align_header: extra_opts[:field_names_header_alignment], header: extra_opts[:field_names_header],
+          width: field_names_width, &:header)
 
         # Add a column to the new table for each of the original table's sources
         sources.each_with_index do |source, i|
@@ -476,6 +514,28 @@ module Tabulo
 
     private
 
+    # @!visibility private
+    def add_column_before(column, label, before)
+      if before == nil
+        @column_registry[label] = column
+      else
+        old_column_entries = @column_registry.to_a
+        new_column_entries = []
+        found = false
+        old_column_entries.each do |entry|
+          if entry[0] == before
+            found = true
+            new_column_entries << [label, column]
+          end
+          new_column_entries << entry
+        end
+        unless found
+          raise InvalidColumnLabelError, "There is no column with label #{before}"
+        end
+        @column_registry = new_column_entries.to_h
+      end
+    end
+
     # @!visibility private
     def total_column_padding
       @left_column_padding + @right_column_padding

data/lib/tabulo/version.rb

@@ -1,3 +1,3 @@
 module Tabulo
-  VERSION = "2.2.0"
+  VERSION = "2.3.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: tabulo
 version: !ruby/object:Gem::Version
-  version: 2.2.0
+  version: 2.3.0
 platform: ruby
 authors:
 - Matthew Harvey
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2020-01-14 00:00:00.000000000 Z
+date: 2020-02-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: tty-screen