tabulo 2.3.3 → 2.6.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6104501fe177f52639fb3e05c12c5cd53d62d1388ad85e2abecaa58f15b3d39d
-  data.tar.gz: 35648de653973f20a5871a71bb2cd9340eb1b80196dc25f510477e7e8143a9db
+  metadata.gz: 5bf2b89914117264e5f213553c792d1456d4f5d99ae8afac565ff1dbc069400b
+  data.tar.gz: 6220df7007ae352c400291101f6308f99ad063fe98c5820820da599f674d4a43
 SHA512:
-  metadata.gz: e5c158f65f97272c637bf37fab53f542001264f3e094ea07a67b4a5e6d583cfb315a40d0a51abad2135fa84169b1edce77420dc9fded8f619f842aa5087c7262
-  data.tar.gz: 0d0f2abb4a82098b4c4886926254f65c17c80b751509818927f8a237c2f4dce35f61d8fcdf028ba9d47640611d14349437eb767ffd2deaf92ebc5c8ee16eda8c
+  metadata.gz: 13228bb55890713cb9483f18d55339dcf7393aff65a7f91383eb9a5d7dce03acd968e09e883ae3f72088e4d543d1bdc962cb38a0c9444cdd1a93482c55f9c354
+  data.tar.gz: e865337603240b4b8456f5b2b7bbb64f660b18acfc4caf0318ef9869f58070801da24bbdd7de740133a6ef386d5c6c02ee198098605fb7a13acd60547bbdb04e

data/.travis.yml

@@ -4,7 +4,7 @@ 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.8
+  - 2.6.6
+  - 2.7.1

data/CHANGELOG.md

@@ -1,5 +1,37 @@
 # Changelog
 
+### 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
+* Fix minor error in README
+* Minor documentation tweaks
+
+### v2.4.0
+
+* Add additional, optional `CellData` parameter to `styler` and `formatter` callbacks
+* Add optional `column_index` parameter to `header_styler` callback
+* Add optional `row_index` parameter to `extractor` callback
+* Add `rake yard` Rake task for generating YARD documentation
+* Minor documentation fixes
+* Upgrade dependency version: `unicode-display_width` gem to 1.7.0
+
 ### v2.3.3
 
 * Fix styler option on Table initializer, which had no effect

data/README.md

@@ -7,7 +7,11 @@
 [![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:_
 
@@ -41,40 +45,39 @@ end
 └────┴────────────┴───────────┘
 ```
 
+<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:
@@ -216,8 +220,31 @@ end
 +--------------+--------------+--------------+
 ```
 
+The `add_column` method can be passed a single parameter callable, as shown in the above example,
+with the parameter representing the member of the underyling enumerable; or it can be passed
+2-parameter callable, with the second parameter representing the (0-based) index of each row. This can be
+useful if you want to display a row number in one of the columns:
+
+```ruby
+table = Tabulo::Table.new(["a", "b", "c"]) do |t|
+  t.add_column("Row") { |letter, row_index| row_index }
+  t.add_column("Value", &:itself)
+end
+```
+
+```
+> puts table
++--------------+--------------+
+|      Row     |     Value    |
++--------------+--------------+
+|            0 | a            |
+|            1 | b            |
+|            2 | c            |
++--------------+--------------+
+```
+
 <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.
@@ -231,14 +258,14 @@ 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
 `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 = Tabulo::Table.new([1, 2, 3], :itself, :odd?)
 table.add_column(:even?, before: :odd?)
 ```
 
@@ -254,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:
@@ -263,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`
@@ -284,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`:
@@ -329,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
@@ -350,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
@@ -398,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`
@@ -412,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
@@ -430,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:
@@ -492,8 +596,34 @@ 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     |
++--------------+--------------+--------------+
+```
+
 <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
@@ -550,11 +680,17 @@ end
 Formatters set for individual columns on calling `#add_column` always override the default formatter for
 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.6.1/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
@@ -587,19 +723,23 @@ table.add_column(
 )
 ```
 
-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).
+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.1/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
+(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.
+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
+#### 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.:
@@ -608,24 +748,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" })
 ```
 
-<a name="default-styles"></a>
-#### Setting default styles
+The `header_styler` option accepts a 1-, 2- or 3-parameter callable. See the
+[documentation](https://www.rubydoc.info/gems/tabulo/2.6.1/Tabulo/Table#add_column-instance_method)
+for details.
 
-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:
+<a name="styling-title"></a>
+#### Styling the table title [&#x2191;](#contents)
+
+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.1/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.:
@@ -634,8 +776,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,
@@ -669,8 +827,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,
@@ -699,7 +859,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
@@ -735,7 +895,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:
 
@@ -770,7 +930,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
@@ -798,10 +958,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.3.3/Tabulo/Table#transpose-instance_method).
+[documentation](https://www.rubydoc.info/gems/tabulo/2.6.1/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.
@@ -817,6 +977,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:
@@ -830,6 +1001,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: :modern, title: "Numbers")
+┌────────────────────────────────────────────┐
+│                   Numbers                  │
+├──────────────┬──────────────┬──────────────┤
+│    itself    │     even?    │     odd?     │
+├──────────────┼──────────────┼──────────────┤
+│            1 │     false    │     true     │
+│            2 │     true     │     false    │
+│            3 │     false    │     true     │
+└──────────────┴──────────────┴──────────────┘
 ```
 
 `:markdown`&mdash;renders a GitHub flavoured Markdown table:
@@ -841,8 +1023,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:
 
 ```
@@ -851,6 +1045,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:
@@ -864,6 +1066,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:
@@ -877,6 +1090,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_ascii, title: "Numbers")
+────────────────────────────────────────────
+                   Numbers                  
+────────────── ────────────── ──────────────
+    itself          even?          odd?     
+────────────── ────────────── ──────────────
+            1       false          true     
+            2       true           false    
+            3       false          true     
+────────────── ────────────── ──────────────
 ```
 
 `:classic`&mdash;reproduces the default behaviour in Tabulo v1; this is like the `:ascii` option,
@@ -890,13 +1114,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
@@ -935,7 +1169,7 @@ 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
+### 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
@@ -1005,7 +1239,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:
 
@@ -1090,7 +1324,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.
 
@@ -1101,20 +1335,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.3.3
+[Documentation]: http://www.rubydoc.info/gems/tabulo/2.6.1
 [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.3.3-blue.svg
+[DC img]: https://img.shields.io/badge/documentation-v2.6.1-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