tabulo 2.4.1 → 2.6.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d49cd1a3bfb031b2ced0f4539bd8ea16b2943df0c999f7b70e8ddf83cfcd5fa1
-  data.tar.gz: 745a3834a8c62ba85a7fbd8bdd826dc0bf9e18a1cb6fd54ac81e311870c02f61
+  metadata.gz: cdf2e4da09cd06510108899c38ddd3c144b04daa4b8f54f3a45593a78aee4f92
+  data.tar.gz: fb604197bd38a80a74b1282ca693903fd6a064502410e13ad4b1022b64f3adcc
 SHA512:
-  metadata.gz: 939d50fdbe7bdfd94740ddddc86d3774c688e505633e693e27f41806224af8c601de6a4aa124ff868aefdc151ca72d4da89dfa2c045bce2b9e45c61064a7723a
-  data.tar.gz: 6cad47f7c06a52de935ebeec3710722344ac7d28159bca3d7efb2b9b627751a1c4d879d8b0d22beb0eb4af8705f03ee310d925b96b86d175d4c39e3f7b76acbf
+  metadata.gz: ee8a6b465a79fef67af10a08c7affc5c83a804b959aaa326202f24efe96aa189dfdd27c31650104f7e80c7eaccbf06ec04374f06f4e76fbdf381151356f438d5
+  data.tar.gz: 18b13fd6d50be85f7e18c98ef23f4d0e3ce035a89ddc494589d5419fec94a85a99d323da969c111455de4890fd4ad8f34ee091da0ceeda320e69621dfc6cef92

data/.travis.yml

@@ -4,7 +4,8 @@ rvm:
   - 2.1.10
   - 2.2.10
   - 2.3.8
-  - 2.4.9
-  - 2.5.7
-  - 2.6.5
-  - 2.7.0
+  - 2.4.10
+  - 2.5.9
+  - 2.6.7
+  - 2.7.3
+  - 3.0.1

data/CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+### v2.6.3
+
+* Update dependency versions
+
+### v2.6.2
+
+* Ensure line break character sequences are property formatted in output, regardless
+  of whether they are "\r\n", "\r" or "\n".
+
+### v2.6.1
+
+* Update dependency versions
+* Minor documentation improvements
+
+### v2.6.0
+
+* Add an additional, optional parameter to `styler`, `header_styler` and `title_styler`
+  callbacks, which will receive the index (0, 1 or etc.) of the line within the cell
+  being styled.
+* Allow padding to be configured on a column-by-column basis.
+* Minor documentation improvements.
+
+### v2.5.0
+
+* Add option of table title, together with options for styling and aligning the title
+
 ### v2.4.1
 
 * Fix warnings under Ruby 2.7

data/README.md

@@ -7,24 +7,28 @@
 [![Code Climate][CC img]][Code Climate]
 [![Awesome][AR img]][Awesome Ruby]
 
-Tabulo is a terminal table generator for Ruby. It is both highly configurable and very easy to use.
+Tabulo is a Ruby library for generating plain text tables (also known as “terminal tables”
+or “ASCII tables”). It is both highly configurable and very easy to use.
+
+<a name="overview"></a>
+## Overview
 
 _Quick API:_
 
 ```
-> puts Tabulo::Table.new(User.all, :id, :first_name, :last_name, border: :modern).pack
-┌────┬────────────┬───────────┐
-│ id │ first_name │ last_name │
-├────┼────────────┼───────────┤
-│  1 │ John       │ Citizen   │
-│  2 │ Jane       │ Doe       │
-└────┴────────────┴───────────┘
+> puts Tabulo::Table.new(User.all, :id, :first_name, :last_name).pack
++----+------------+-----------+
+| id | first_name | last_name |
++----+------------+-----------+
+|  1 | John       | Citizen   |
+|  2 | Jane       | Doe       |
++----+------------+-----------+
 ```
 
 _Full API:_
 
 ```
-table = Tabulo::Table.new(User.all, border: :modern) do |t|
+table = Tabulo::Table.new(User.all) do |t|
   t.add_column("ID", &:id)
   t.add_column("First name", &:first_name)
   t.add_column("Last name") { |user| user.last_name.upcase }
@@ -33,48 +37,47 @@ end
 
 ```
 > puts table.pack
-┌────┬────────────┬───────────┐
-│ ID │ First name │ Last name │
-├────┼────────────┼───────────┤
-│  1 │ John       │ CITIZEN   │
-│  2 │ Jane       │ DOE       │
-└────┴────────────┴───────────┘
++----+------------+-----------+
+| ID | First name | Last name |
++----+------------+-----------+
+|  1 | John       | CITIZEN   |
+|  2 | Jane       | DOE       |
++----+------------+-----------+
 ```
 
+<a name="features"></a>
 ## Features
 
-* Presents a [DRY initialization interface](#adding-columns): by being &ldquo;column based&rdquo; rather than
-  &ldquo;row based&rdquo;, it spares the developer the burden of syncing the ordering within the header row
-  with that of the body rows.
+* Presents a [DRY API](#adding-columns) that is column-based, not row-based, meaning header and body rows are
+  automatically in sync
 * Lets you set [fixed column widths](#fixed-column-widths), then either [wrap](#overflow-handling)
-  or [truncate](#overflow-handling) the overflow.
-* Alternatively, you can [&ldquo;pack&rdquo;](#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.
-* Since a `Tabulo::Table` is itself also an `Enumerable`, you can [step through it](#enumerator) a
-  row at a time, printing as you go, without waiting for the entire underlying collection to load.
-  In other words, you get a [streaming interface](#enumerator) for free.
-* Each `Tabulo::Row` is also an `Enumerable`, [providing access](#accessing-cell-values) to the
-  underlying cell values.
-* The header row can be [repeated](#repeating-headers) at arbitrary intervals.
-* Newlines within cell content are correctly handled.
-* 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.
+  or [truncate](#overflow-handling) the overflow
+* Alternatively, [&ldquo;pack&rdquo;](#pack) the table so that columns are auto-sized to their
+  contents, but [without overflowing the terminal](#max-table-width)
+* Cell alignment 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
+* [Step through](#enumerator) your table a row at a time, printing as you go, without waiting for the
+  underlying collection to load. In other words, have a [streaming interface](#enumerator) for free.
+* Add an optional [title](#title) to your table
+* The header row can be [repeated](#repeating-headers) at arbitrary intervals
+* Newlines within cell content are correctly handled
+* 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, &ldquo;ASCII&rdquo;, and smoothly
-  joined Unicode border characters.
+  joined Unicode border characters
 
 Tabulo has also been ported to Crystal (with some modifications): see [Tablo](https://github.com/hutou/tablo).
 
+<a name="contents"></a>
 ## Contents
 
+  * [Overview](#overview)
   * [Features](#features)
   * [Table of contents](#table-of-contents)
   * [Installation](#installation)
   * [Detailed usage](#detailed-usage)
-     * [Requiring the gem](#requiring-the-gem)
      * [Creating a table](#table-initialization)
      * [Adding columns](#adding-columns)
         * [Quick API](#quick-api)
@@ -82,18 +85,21 @@ Tabulo has also been ported to Crystal (with some modifications): see [Tablo](ht
         * [Column labels _vs_ headers](#labels-headers)
         * [Positioning columns](#column-positioning)
      * [Removing columns](#removing-columns)
+     * [Adding a title](#title)
      * [Cell alignment](#cell-alignment)
      * [Column width, wrapping and truncation](#column-width-wrapping-and-truncation)
         * [Configuring fixed widths](#configuring-fixed-widths)
         * [Automating column widths](#automating-column-widths)
         * [Configuring padding](#configuring-padding)
         * [Overflow handling](#overflow-handling)
+        * [Manual cell wrapping](#manual-wrapping)
      * [Formatting cell values](#formatting-cell-values)
      * [Colours and other styling](#colours-and-styling)
         * [Styling cell content](#styling-cell-content)
         * [Styling column headers](#styling-column-headers)
+        * [Styling the table title](#styling-title)
         * [Setting default styles](#default-styles)
-        * [Styling borders](#border-styling)
+        * [Styling borders](#styling-borders)
      * [Repeating headers](#repeating-headers)
      * [Using a Table Enumerator](#using-a-table-enumerator)
      * [Accessing cell values](#accessing-cell-values)
@@ -106,7 +112,7 @@ Tabulo has also been ported to Crystal (with some modifications): see [Tablo](ht
   * [Contributing](#contributing)
   * [License](#license)
 
-## Installation
+## Installation [&#x2191;](#contents)
 
 Add this line to your application&#8217;s Gemfile:
 
@@ -122,16 +128,14 @@ Or install it yourself:
 
     $ gem install tabulo
 
-## Detailed usage
-
-### Requiring the gem
+To use the gem, you need to require it in your source code as follows:
 
 ```ruby
 require 'tabulo'
 ```
 
 <a name="table-initialization"></a>
-### Creating a table
+### Creating a table [&#x2191;](#contents)
 
 You instantiate a `Tabulo::Table` by passing it an underlying `Enumerable`, being the collection of
 things that you want to tabulate. Each member of this collection will end up
@@ -146,10 +150,10 @@ other_table = Tabulo::Table.new(User.all)
 For the table to be useful, however, it must also contain columns&hellip;
 
 <a name="adding-columns"></a>
-### Adding columns
+### Adding columns [&#x2191;](#contents)
 
 <a name="quick-api"></a>
-#### Quick API
+#### Quick API [&#x2191;](#contents)
 
 When the columns correspond to methods on members of the underlying enumerable, you can use
 the &ldquo;quick API&rdquo;, by passing a symbol directly to `Tabulo::Table.new` for each column.
@@ -171,7 +175,7 @@ table = Tabulo::Table.new([1, 2, 5], :itself, :even?, :odd?)
 ```
 
 <a name="full-api"></a>
-#### Full API
+#### Full API [&#x2191;](#contents)
 
 Columns can also be added to the table one-by-one using `add_column`. This &ldquo;full API&rdquo; is
 more verbose, but provides greater configurability:
@@ -240,7 +244,7 @@ end
 ```
 
 <a name="labels-headers"></a>
-#### Column labels _vs_ headers
+#### Column labels _vs_ headers [&#x2191;](#contents)
 
 The first argument to `add_column` is the called the _label_ for that column. It serves as the
 column&#8217;s unique identifier: only one column may have a given label per table.
@@ -254,7 +258,7 @@ table.add_column(:itself2, header: "N", &:itself)  # header need not be unique
 ```
 
 <a name="column-positioning"></a>
-#### Positioning columns
+#### Positioning columns [&#x2191;](#contents)
 
 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
@@ -277,7 +281,7 @@ table.add_column(:even?, before: :odd?)
 ```
 
 <a name="removing-columns"></a>
-### Removing columns
+### Removing columns [&#x2191;](#contents)
 
 There is also a `#remove_column` method, for deleting an existing column from a table. Pass it
 the label of the column you want to remove:
@@ -286,8 +290,34 @@ the label of the column you want to remove:
 table.remove_column(:even?)
 ```
 
+<a name="title"></a>
+### Adding a title [&#x2191;](#contents)
+
+You can give your table a title, using the `title` option:
+
+```ruby
+table = Tabulo::Table.new([1, 2, 3], :itself, :even?, :odd?, title: "Numbers")
+```
+
+```
+> puts table
++--------------------------------------------+
+|                   Numbers                  |
++--------------+--------------+--------------+
+|    itself    |     even?    |     odd?     |
++--------------+--------------+--------------+
+|            1 |     false    |     true     |
+|            2 |     true     |     false    |
+|            3 |     false    |     true     |
++--------------+--------------+--------------+
+```
+
+There is a caveat: Using the `title` option with the `:markdown` [border type](#borders) will cause
+the rendered table to cease being valid Markdown, as unfortunately almost no markdown engines support
+adding a captions (i.e. titles) to tables.
+
 <a name="cell-alignment"></a>
-### Cell alignment
+### Cell alignment [&#x2191;](#contents)
 
 By default, column header text is center-aligned, while the content of each body cell is aligned
 according to its data type. Numbers are right-aligned, text is left-aligned, and booleans (`false`
@@ -307,10 +337,17 @@ passing similarly-named options to `add_column`, e.g.:
 table.add_column("Doubled", align_header: :right, align_body: :left) { |n| n * 2 }
 ```
 
-### Column width, wrapping and truncation
+If a table title is present, it is center-aligned by default. This can be changed using the
+`align_title` option when initializing the table:
+
+```ruby
+table = Tabulo::Table.new([1, 2], :itself, :even?, title: "Numbers", align_title: :left)
+```
+
+### Column width, wrapping and truncation [&#x2191;](#contents)
 
 <a name="fixed-column-widths"></a>
-#### Configuring fixed widths
+#### Configuring fixed widths [&#x2191;](#contents)
 
 By default, column width is fixed at 12 characters, plus 1 character of padding on either side.
 This can be adjusted on a column-by-column basis using the `width` option of `add_column`:
@@ -352,7 +389,7 @@ table = Tabulo::Table.new([1, 2], :itself, :even?, column_width: 6)
 Widths set for individual columns always override the default column width for the table.
 
 <a name="pack"></a>
-#### Automating column widths
+#### Automating column widths [&#x2191;](#contents)
 
 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
@@ -373,6 +410,26 @@ table.pack
 +-------------------------+------+
 ```
 
+If the table [title](#title) happens to be too long to for the existing width of the table, `pack`
+will also arrange for the table to be widened sufficiently to accommodate it without wrapping:
+
+```ruby
+table = Tabulo::Table.new(["a", "b"], :itself, :size, title: "Here are some letters of the alphabet")
+table.pack
+```
+
+```
+> puts table
++---------------------------------------+
+| Here are some letters of the alphabet |
++-------------------+-------------------+
+|       itself      |        size       |
++-------------------+-------------------+
+| a                 |                 1 |
+| b                 |                 1 |
++-------------------+-------------------+
+```
+
 The `pack` method returns the table itself, so you can &ldquo;pack-and-print&rdquo; in one go:
 
 ```ruby
@@ -421,7 +478,7 @@ table itself. There are [ways around this](#freezing-a-table), however, if this
 behaviour&mdash;see [below](#freezing-a-table).
 
 <a name="configuring-padding"></a>
-#### Configuring padding
+#### Configuring padding [&#x2191;](#contents)
 
 The single character of padding either side of each column is not counted in the column width.
 The amount of this extra padding can be configured for the table as a whole, using the `column_padding`
@@ -435,14 +492,14 @@ table = Tabulo::Table.new([1, 2, 5], :itself, :even?, :odd?, column_padding: 0)
 ```
 
 ```
-> puts table
-+------------+------------+------------+
-|   itself   |    even?   |    odd?    |
-+------------+------------+------------+
-|           1|    false   |    true    |
-|           2|    true    |    false   |
-|           5|    false   |    true    |
-+------------+------------+------------+
+> puts table.pack
++------+-----+-----+
+|itself|even?| odd?|
++------+-----+-----+
+|     1|false| true|
+|     2| true|false|
+|     5|false| true|
++------+-----+-----+
 ```
 
 Passing an array of _two_ integers to this option configures the left and right padding for each
@@ -453,18 +510,42 @@ table = Tabulo::Table.new([1, 2, 5], :itself, :even?, :odd?, column_padding: [0,
 ```
 
 ```
-> puts table
-+--------------+--------------+--------------+
-|   itself     |    even?     |    odd?      |
-+--------------+--------------+--------------+
-|           1  |    false     |    true      |
-|           2  |    true      |    false     |
-|           5  |    false     |    true      |
-+--------------+--------------+--------------+
+> puts table.pack
++--------+-------+-------+
+|itself  |even?  | odd?  |
++--------+-------+-------+
+|     1  |false  | true  |
+|     2  | true  |false  |
+|     5  |false  | true  |
++--------+-------+-------+
+```
+
+Note how the padding amount is completely unaffected by the call `pack`.
+
+Padding can also be configured on a column-by-column basis, using the `padding` option when calling
+`add_column`:
+
+```ruby
+table = Tabulo::Table.new([1, 2, 5], :itself, :even?)
+table.add_column(:odd?, padding: 3)
+```
+
+```
+> puts table.pack
++--------+-------+-----------+
+| itself | even? |    odd?   |
++--------+-------+-----------+
+|      1 | false |    true   |
+|      2 |  true |   false   |
+|      5 | false |    true   |
++--------+-------+-----------+
 ```
 
+This column-level `padding` setting always overrides any table-level `column_padding` setting, for
+the column in question.
+
 <a name="overflow-handling"></a>
-#### Overflow handling
+#### Overflow handling [&#x2191;](#contents)
 
 By default, if cell contents exceed their column width, they are wrapped for as many rows as
 required:
@@ -515,8 +596,39 @@ table = Tabulo::Table.new(
 The character used to indicate truncation, which defaults to `~`, can be configured using the
 `truncation_indicator` option passed to `Table.new`.
 
+<a name="manual-wrapping"></a>
+#### Manual cell wrapping [&#x2191;](#contents)
+
+You can &ldquo;manually&rdquo; wrap the content of a title, header or body cell at a particular
+point, simply by placing a newline character, at that point:
+
+```ruby
+table = Tabulo::Table.new(1..3) do |t|
+  t.add_column("The number\nitself", &:itself)
+  t.add_column("Even?", &:even?)
+  t.add_column("Odd?", &:odd?)
+end
+```
+
+```
+> puts table
++--------------+--------------+--------------+
+|  The number  |     Even?    |     Odd?     |
+|    itself    |              |              |
++--------------+--------------+--------------+
+|            1 |     false    |     true     |
+|            2 |     true     |     false    |
+|            3 |     false    |     true     |
++--------------+--------------+--------------+
+```
+
+Tabulo will treat any of the character combinations `"\n"`, `"\r\n"` or `"\r"` equally, as a line break,
+regardless of the platform it&#8217;s currently being run on. This ensures things are formatted as
+expected if, for example, you are examining content that was produced on another platform from
+the one you&#8217;re running Tabulo on.
+
 <a name="formatting-cell-values"></a>
-### Formatting cell values
+### Formatting cell values [&#x2191;](#contents)
 
 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 &ldquo;formatter&rdquo;, that determines how
@@ -576,14 +688,14 @@ the table.
 The `formatter` callback also has an alternative, 2-parameter version. If `formatter` is passed
 a 2-parameter callable, the second parameter will be given a `CellData` instance,
 containing additional information about the cell that may be useful in determining how to format
-it&mdash;see the [documentation](https://www.rubydoc.info/gems/tabulo/2.4.1/Tabulo/CellData.html)
+it&mdash;see the [documentation](https://www.rubydoc.info/gems/tabulo/2.6.3/Tabulo/CellData.html)
 for details.
 
 <a name="colours-and-styling"></a>
-### Colours and other styling
+### Colours and other styling [&#x2191;](#contents)
 
 <a name="styling-cell-content"></a>
-#### Styling cell content
+#### Styling cell content [&#x2191;](#contents)
 
 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
@@ -616,13 +728,13 @@ table.add_column(
 )
 ```
 
-The `styler` option should be passed a callable that takes either two or three parameters: the
-first parameter represents the underlying value of the cell (in this case a boolean indicating whether
-the number is even); the second represents the formatted string value of that cell, i.e. the cell
-content after any processing by the [formatter](#formatting-cell-values); and the third parameter,
-if present, will be passed a `CellData` object, containing other information about the cell
-that may be useful in determining how to style it&mdash;see the
-[documentation](https://www.rubydoc.info/gems/tabulo/2.4.1/Tabulo/CellData.html) for details.
+The `styler` option should be passed a callable that takes either 2, 3 or 4 parameters.
+The first parameter represents the underlying value of the cell (in this case a boolean indicating whether the
+number is even). The second parameter represents the formatted string value of that cell, i.e. the cell
+content after any processing by the [formatter](#formatting-cell-values). The third and fourth
+parameters are optional, and contain further information about the cell and its contents that may be useful in
+determining how to style it. See the
+[documentation](https://www.rubydoc.info/gems/tabulo/2.6.3/Tabulo/Table#add_column-instance_method) for details.
 
 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
@@ -632,7 +744,7 @@ If the content of a cell has been [truncated](#overflow-handling), then whatever
 styling apply to the cell content will also be applied the truncation indicator character.
 
 <a name="styling-column-headers"></a>
-#### Styling column headers
+#### Styling column headers [&#x2191;](#contents)
 
 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.:
@@ -641,28 +753,26 @@ 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" })
 ```
 
-The `header_styler` option accepts either a 1- or 2-parameter callable. See the
-[documentation](https://www.rubydoc.info/gems/tabulo/2.4.1/Tabulo/Table#add_column-instance_method)
+The `header_styler` option accepts a 1-, 2- or 3-parameter callable. See the
+[documentation](https://www.rubydoc.info/gems/tabulo/2.6.3/Tabulo/Table#add_column-instance_method)
 for details.
 
-<a name="default-styles"></a>
-#### Setting default styles
+<a name="styling-title"></a>
+#### Styling the table title [&#x2191;](#contents)
 
-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:
+To apply colours or other styling to the table title, if present, use the `title_styler` option
+when initializing the table. This accepts a single-parameter callable:
 
 ```ruby
-table = Tabulo::Table.new(1..5, :itself, :even?, :odd?, header_styler: -> (s) { "\033[32m#{s}\033[0m" })
+table = Tabulo::Table.new(1..5, :itself, :even?, :odd?, title: "Numbers", title_styler: -> (s) { "\033[32m#{s}\033[0m" })
 ```
 
-Now, all columns in the table will have automatically have green header text, unless overridden
-by another header styler being passed to `#add_column`.
+The `title_styler` option accepts a 1- or 2-parameter callable. See the
+[documentation](https://www.rubydoc.info/gems/tabulo/2.6.3/Tabulo/Table#initialize-instance_method)
+for details.
 
-<a name="border-styling"></a>
-#### Styling borders
+<a name="styling-borders"></a>
+#### Styling borders [&#x2191;](#contents)
 
 Styling can also be applied to borders and dividing lines, using the `border_styler` option when
 initializing the table, e.g.:
@@ -671,8 +781,24 @@ initializing the table, e.g.:
 table = Tabulo::Table.new(1..5, :itself, :even?, :odd?, border_styler: -> (s) { "\033[32m#{s}\033[0m" })
 ```
 
+<a name="default-styles"></a>
+#### Setting default styles [&#x2191;](#contents)
+
+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?, header_styler: -> (s) { "\033[32m#{s}\033[0m" })
+```
+
+Now, all columns in the table will automatically have green header text, unless overridden by another
+header styler being passed to `#add_column`.
+
 <a name="repeating-headers"></a>
-### Repeating headers
+### Repeating headers [&#x2191;](#contents)
 
 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,
@@ -706,8 +832,10 @@ table = Tabulo::Table.new(1..10, :itself, :even?, header_frequency: 5)
 +--------------+--------------+
 ```
 
+Note that if the table has a [title](#title), it will not be repeated; only column headers are repeated.
+
 <a name="enumerator"></a>
-### Using a Table Enumerator
+### Using a Table Enumerator [&#x2191;](#contents)
 
 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,
@@ -736,7 +864,7 @@ in that case the entire collection must be traversed up front in order for colum
 calculated.)
 
 <a name="accessing-cell-values"></a>
-### Accessing cell values
+### Accessing cell values [&#x2191;](#contents)
 
 Each `Tabulo::Table` is an `Enumerable` of which each element is a `Tabulo::Row`. Each `Tabulo::Row`
 is itself an `Enumerable`, of `Tabulo::Cell`. The `Tabulo::Cell#value` method will return the
@@ -772,7 +900,7 @@ end
 ```
 
 <a name="accessing-sources"></a>
-### Accessing the underlying enumerable
+### Accessing the underlying enumerable [&#x2191;](#contents)
 
 The underlying enumerable for a table can be retrieved by calling the `sources` getter:
 
@@ -807,7 +935,7 @@ end
 ```
 
 <a name="transposition"></a>
-### Transposing rows and columns
+### Transposing rows and columns [&#x2191;](#contents)
 
 By default, Tabulo generates a table in which each row corresponds to a _record_, i.e. an element of
 the underlying enumerable, and each column to a _field_. However, there are times when one instead
@@ -835,10 +963,10 @@ 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`&#8217;s behaviour. For details, see the
-[documentation](https://www.rubydoc.info/gems/tabulo/2.4.1/Tabulo/Table#transpose-instance_method).
+[documentation](https://www.rubydoc.info/gems/tabulo/2.6.3/Tabulo/Table#transpose-instance_method).
 
 <a name="borders"></a>
-### Configuring borders
+### Configuring borders [&#x2191;](#contents)
 
 You can configure the kind of border and divider characters that are used when the table is printed.
 This is done using the `border` option passed to `Table.new`. The options are as follows.
@@ -854,6 +982,17 @@ This is done using the `border` option passed to `Table.new`. The options are as
 |            2 |     true     |     false    |
 |            3 |     false    |     true     |
 +--------------+--------------+--------------+
+
+> puts Tabulo::Table.new(1..3, :itself, :even?, :odd?, border: :ascii, title: "Numbers")
++--------------------------------------------+
+|                   Numbers                  |
++--------------+--------------+--------------+
+|    itself    |     even?    |     odd?     |
++--------------+--------------+--------------+
+|            1 |     false    |     true     |
+|            2 |     true     |     false    |
+|            3 |     false    |     true     |
++--------------+--------------+--------------+
 ```
 
 `:modern`&mdash;uses smoothly joined Unicode characters:
@@ -867,8 +1006,23 @@ This is done using the `border` option passed to `Table.new`. The options are as
 │            2 │     true     │     false    │
 │            3 │     false    │     true     │
 └──────────────┴──────────────┴──────────────┘
+
+> puts Tabulo::Table.new(1..3, :itself, :even?, :odd?, border: :modern, title: "Numbers")
+┌────────────────────────────────────────────┐
+│                   Numbers                  │
+├──────────────┬──────────────┬──────────────┤
+│    itself    │     even?    │     odd?     │
+├──────────────┼──────────────┼──────────────┤
+│            1 │     false    │     true     │
+│            2 │     true     │     false    │
+│            3 │     false    │     true     │
+└──────────────┴──────────────┴──────────────┘
 ```
 
+_Note: The unicode characters used for the `:modern` border may not render properly
+when viewing this documentation on some browsers or devices. This doesn&#8217;t reflect any brokenness
+in `tabulo` itself._
+
 `:markdown`&mdash;renders a GitHub flavoured Markdown table:
 
 ```
@@ -878,8 +1032,20 @@ This is done using the `border` option passed to `Table.new`. The options are as
 |            1 |     false    |     true     |
 |            2 |     true     |     false    |
 |            3 |     false    |     true     |
+
+> puts Tabulo::Table.new(1..3, :itself, :even?, :odd?, border: :markdown, title: "Numbers")
+|                   Numbers                  |
+|    itself    |     even?    |     odd?     |
+|--------------|--------------|--------------|
+|            1 |     false    |     true     |
+|            2 |     true     |     false    |
+|            3 |     false    |     true     |
 ```
 
+_However_, note that when a table is rendered using the `:markdown` border type in combination with a
+(non-`nil`) `title`, the result will be _invalid Markdown_. This is because Markdown engines do not
+generally support adding a caption (i.e. title) element to tables.
+
 `:blank`&mdash;no border or divider characters are printed:
 
 ```
@@ -888,6 +1054,14 @@ This is done using the `border` option passed to `Table.new`. The options are as
             1      false         true     
             2      true          false    
             3      false         true     
+
+
+> puts Tabulo::Table.new(1..3, :itself, :even?, :odd?, border: :blank, title: "Numbers")
+                  Numbers                 
+    itself         even?         odd?     
+            1      false         true     
+            2      true          false    
+            3      false         true     
 ```
 
 `:reduced_ascii`&mdash;similar to `:ascii`, but without vertical lines:
@@ -901,6 +1075,17 @@ This is done using the `border` option passed to `Table.new`. The options are as
             2       true           false    
             3       false          true     
 -------------- -------------- --------------
+
+> puts Tabulo::Table.new(1..3, :itself, :even?, :odd?, border: :reduced_modern, title: "Numbers")
+--------------------------------------------
+                   Numbers                  
+-------------- -------------- --------------
+    itself          even?          odd?     
+-------------- -------------- --------------
+            1       false          true     
+            2       true           false    
+            3       false          true     
+-------------- -------------- --------------
 ```
 
 `:reduced_modern`&mdash;similar to `:modern`, but without vertical lines:
@@ -914,8 +1099,23 @@ This is done using the `border` option passed to `Table.new`. The options are as
             2       true           false    
             3       false          true     
 ────────────── ────────────── ──────────────
+
+> puts Tabulo::Table.new(1..3, :itself, :even?, :odd?, border: :reduced_ascii, title: "Numbers")
+────────────────────────────────────────────
+                   Numbers                  
+────────────── ────────────── ──────────────
+    itself          even?          odd?     
+────────────── ────────────── ──────────────
+            1       false          true     
+            2       true           false    
+            3       false          true     
+────────────── ────────────── ──────────────
 ```
 
+_Note: The unicode characters used for the `:reduced_modern` border may not render properly
+when viewing this documentation on some browsers or devices. This doesn&#8217;t reflect any brokenness
+in `tabulo` itself._
+
 `:classic`&mdash;reproduces the default behaviour in Tabulo v1; this is like the `:ascii` option,
 but without a bottom border:
 
@@ -927,13 +1127,23 @@ but without a bottom border:
 |            1 |     false    |     true     |
 |            2 |     true     |     false    |
 |            3 |     false    |     true     |
+
+> puts Tabulo::Table.new(1..3, :itself, :even?, :odd?, border: :classic, title: "Numbers")
++--------------------------------------------+
+|                   Numbers                  |
++--------------+--------------+--------------+
+|    itself    |     even?    |     odd?     |
++--------------+--------------+--------------+
+|            1 |     false    |     true     |
+|            2 |     true     |     false    |
+|            3 |     false    |     true     |
 ```
 
 Note that, by default, none of the border options includes lines drawn _between_ rows in the body of the table.
 These are configured via a separate option: see [below](#dividers).
 
 <a name="dividers"></a>
-### Row dividers
+### Row dividers [&#x2191;](#contents)
 
 To add lines between rows in the table body, use the `row_divider_frequency` option when initializing
 the table. The default value for this option is `nil`, meaning there are no dividing lines between
@@ -959,20 +1169,20 @@ every Nth row. For example:
 If you want a line before every row, pass `1` to `row_divider_frequency`. For example:
 
 ```
-> puts Tabulo::Table.new(1..3, :itself, :even?, :odd?, border: :modern, row_divider_frequency: 1)
-┌──────────────┬──────────────┬──────────────┐
-│    itself    │     even?    │     odd?     │
-├──────────────┼──────────────┼──────────────┤
-│            1 │     false    │     true     │
-├──────────────┼──────────────┼──────────────┤
-│            2 │     true     │     false    │
-├──────────────┼──────────────┼──────────────┤
-│            3 │     false    │     true     │
-└──────────────┴──────────────┴──────────────┘
+> puts Tabulo::Table.new(1..3, :itself, :even?, :odd?, row_divider_frequency: 1)
++--------------+--------------+--------------+
+|    itself    |     even?    |     odd?     |
++--------------+--------------+--------------+
+|            1 |     false    |     true     |
++--------------+--------------+--------------+
+|            2 |     true     |     false    |
++--------------+--------------+--------------+
+|            3 |     false    |     true     |
++--------------+--------------+--------------+
 ```
 
 <a name="freezing-a-table"></a>
-### Using a table as a snapshot rather than as a dynamic view
+### Using a table as a snapshot rather than as a dynamic view [&#x2191;](#contents)
 
 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
@@ -1042,7 +1252,7 @@ rendered_table = Tabulo::Table.new(1..10, :itself, :even?, :odd?).pack.to_s
 ```
 
 <a name="motivation"></a>
-## Comparison with other libraries
+## Comparison with other libraries [&#x2191;](#contents)
 
 There are other libraries for generating plain text tables in Ruby. Popular among these are:
 
@@ -1127,7 +1337,7 @@ environment seems cumbersome. Moreover, it seems no longer to be maintained. At
 its last commit was in March 2015.
 
 <a name="contributing"></a>
-## Contributing
+## Contributing [&#x2191;](#contents)
 
 Issues and pull requests are welcome on GitHub at https://github.com/matt-harvey/tabulo.
 
@@ -1138,20 +1348,20 @@ install dependencies.
 `bundle exec rake spec` will run the test suite. For a list of other Rake tasks that are available in
 the development environment, run `bundle exec rake -T`.
 
-## License
+## License [&#x2191;](#contents)
 
 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.4.1
+[Documentation]: http://www.rubydoc.info/gems/tabulo/2.6.3
 [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.4.1-blue.svg
+[DC img]: https://img.shields.io/badge/documentation-v2.6.3-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