tabulo 2.3.3 → 2.6.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +4 -4
- data/.travis.yml +4 -4
- data/CHANGELOG.md +32 -0
- data/README.md +330 -96
- data/Rakefile +6 -1
- data/VERSION +1 -1
- data/assets/social_media_preview/table.png +0 -0
- data/lib/tabulo.rb +1 -0
- data/lib/tabulo/border.rb +66 -102
- data/lib/tabulo/cell.rb +56 -19
- data/lib/tabulo/cell_data.rb +14 -0
- data/lib/tabulo/column.rb +52 -6
- data/lib/tabulo/row.rb +8 -5
- data/lib/tabulo/table.rb +268 -110
- data/lib/tabulo/util.rb +20 -0
- data/lib/tabulo/version.rb +1 -1
- data/tabulo.gemspec +3 -3
- metadata +11 -10
checksums.yaml
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
---
|
2
2
|
SHA256:
|
3
|
-
metadata.gz:
|
4
|
-
data.tar.gz:
|
3
|
+
metadata.gz: 5bf2b89914117264e5f213553c792d1456d4f5d99ae8afac565ff1dbc069400b
|
4
|
+
data.tar.gz: 6220df7007ae352c400291101f6308f99ad063fe98c5820820da599f674d4a43
|
5
5
|
SHA512:
|
6
|
-
metadata.gz:
|
7
|
-
data.tar.gz:
|
6
|
+
metadata.gz: 13228bb55890713cb9483f18d55339dcf7393aff65a7f91383eb9a5d7dce03acd968e09e883ae3f72088e4d543d1bdc962cb38a0c9444cdd1a93482c55f9c354
|
7
|
+
data.tar.gz: e865337603240b4b8456f5b2b7bbb64f660b18acfc4caf0318ef9869f58070801da24bbdd7de740133a6ef386d5c6c02ee198098605fb7a13acd60547bbdb04e
|
data/.travis.yml
CHANGED
data/CHANGELOG.md
CHANGED
@@ -1,5 +1,37 @@
|
|
1
1
|
# Changelog
|
2
2
|
|
3
|
+
### v2.6.1
|
4
|
+
|
5
|
+
* Update dependency versions
|
6
|
+
* Minor documentation improvements
|
7
|
+
|
8
|
+
### v2.6.0
|
9
|
+
|
10
|
+
* Add an additional, optional parameter to `styler`, `header_styler` and `title_styler`
|
11
|
+
callbacks, which will receive the index (0, 1 or etc.) of the line within the cell
|
12
|
+
being styled.
|
13
|
+
* Allow padding to be configured on a column-by-column basis.
|
14
|
+
* Minor documentation improvements.
|
15
|
+
|
16
|
+
### v2.5.0
|
17
|
+
|
18
|
+
* Add option of table title, together with options for styling and aligning the title
|
19
|
+
|
20
|
+
### v2.4.1
|
21
|
+
|
22
|
+
* Fix warnings under Ruby 2.7
|
23
|
+
* Fix minor error in README
|
24
|
+
* Minor documentation tweaks
|
25
|
+
|
26
|
+
### v2.4.0
|
27
|
+
|
28
|
+
* Add additional, optional `CellData` parameter to `styler` and `formatter` callbacks
|
29
|
+
* Add optional `column_index` parameter to `header_styler` callback
|
30
|
+
* Add optional `row_index` parameter to `extractor` callback
|
31
|
+
* Add `rake yard` Rake task for generating YARD documentation
|
32
|
+
* Minor documentation fixes
|
33
|
+
* Upgrade dependency version: `unicode-display_width` gem to 1.7.0
|
34
|
+
|
3
35
|
### v2.3.3
|
4
36
|
|
5
37
|
* Fix styler option on Table initializer, which had no effect
|
data/README.md
CHANGED
@@ -7,7 +7,11 @@
|
|
7
7
|
[![Code Climate][CC img]][Code Climate]
|
8
8
|
[![Awesome][AR img]][Awesome Ruby]
|
9
9
|
|
10
|
-
Tabulo is a
|
10
|
+
Tabulo is a Ruby library for generating plain text tables (also known as “terminal tables”
|
11
|
+
or “ASCII tables”). It is both highly configurable and very easy to use.
|
12
|
+
|
13
|
+
<a name="overview"></a>
|
14
|
+
## Overview
|
11
15
|
|
12
16
|
_Quick API:_
|
13
17
|
|
@@ -41,40 +45,39 @@ end
|
|
41
45
|
└────┴────────────┴───────────┘
|
42
46
|
```
|
43
47
|
|
48
|
+
<a name="features"></a>
|
44
49
|
## Features
|
45
50
|
|
46
|
-
* Presents a [DRY
|
47
|
-
|
48
|
-
with that of the body rows.
|
51
|
+
* Presents a [DRY API](#adding-columns) that is column-based, not row-based, meaning header and body rows are
|
52
|
+
automatically in sync
|
49
53
|
* Lets you set [fixed column widths](#fixed-column-widths), then either [wrap](#overflow-handling)
|
50
|
-
or [truncate](#overflow-handling) the overflow
|
51
|
-
* Alternatively,
|
52
|
-
|
53
|
-
*
|
54
|
-
|
55
|
-
* Tabulate any `Enumerable`: the underlying collection need not be an array
|
56
|
-
*
|
57
|
-
|
58
|
-
|
59
|
-
*
|
60
|
-
|
61
|
-
*
|
62
|
-
*
|
63
|
-
*
|
64
|
-
* Apply [colours](#colours-and-styling) and other styling to table content and borders, without breaking the table.
|
65
|
-
* Easily [transpose](#transposition) the table, so that rows are swapped with columns.
|
54
|
+
or [truncate](#overflow-handling) the overflow
|
55
|
+
* Alternatively, [“pack”](#pack) the table so that columns are auto-sized to their
|
56
|
+
contents, but [without overflowing the terminal](#max-table-width)
|
57
|
+
* Cell alignment is [configurable](#cell-alignment), but has helpful content-based defaults (numbers right, strings
|
58
|
+
left)
|
59
|
+
* Tabulate any `Enumerable`: the underlying collection need not be an array
|
60
|
+
* [Step through](#enumerator) your table a row at a time, printing as you go, without waiting for the
|
61
|
+
underlying collection to load. In other words, have a [streaming interface](#enumerator) for free.
|
62
|
+
* Add an optional [title](#title) to your table
|
63
|
+
* The header row can be [repeated](#repeating-headers) at arbitrary intervals
|
64
|
+
* Newlines within cell content are correctly handled
|
65
|
+
* Multibyte Unicode characters are correctly handled
|
66
|
+
* Apply [colours](#colours-and-styling) and other styling to table content and borders, without breaking the table
|
67
|
+
* Easily [transpose](#transposition) the table, so that rows are swapped with columns
|
66
68
|
* Choose from multiple [border configurations](#borders), including Markdown, “ASCII”, and smoothly
|
67
|
-
joined Unicode border characters
|
69
|
+
joined Unicode border characters
|
68
70
|
|
69
71
|
Tabulo has also been ported to Crystal (with some modifications): see [Tablo](https://github.com/hutou/tablo).
|
70
72
|
|
73
|
+
<a name="contents"></a>
|
71
74
|
## Contents
|
72
75
|
|
76
|
+
* [Overview](#overview)
|
73
77
|
* [Features](#features)
|
74
78
|
* [Table of contents](#table-of-contents)
|
75
79
|
* [Installation](#installation)
|
76
80
|
* [Detailed usage](#detailed-usage)
|
77
|
-
* [Requiring the gem](#requiring-the-gem)
|
78
81
|
* [Creating a table](#table-initialization)
|
79
82
|
* [Adding columns](#adding-columns)
|
80
83
|
* [Quick API](#quick-api)
|
@@ -82,18 +85,21 @@ Tabulo has also been ported to Crystal (with some modifications): see [Tablo](ht
|
|
82
85
|
* [Column labels _vs_ headers](#labels-headers)
|
83
86
|
* [Positioning columns](#column-positioning)
|
84
87
|
* [Removing columns](#removing-columns)
|
88
|
+
* [Adding a title](#title)
|
85
89
|
* [Cell alignment](#cell-alignment)
|
86
90
|
* [Column width, wrapping and truncation](#column-width-wrapping-and-truncation)
|
87
91
|
* [Configuring fixed widths](#configuring-fixed-widths)
|
88
92
|
* [Automating column widths](#automating-column-widths)
|
89
93
|
* [Configuring padding](#configuring-padding)
|
90
94
|
* [Overflow handling](#overflow-handling)
|
95
|
+
* [Manual cell wrapping](#manual-wrapping)
|
91
96
|
* [Formatting cell values](#formatting-cell-values)
|
92
97
|
* [Colours and other styling](#colours-and-styling)
|
93
98
|
* [Styling cell content](#styling-cell-content)
|
94
99
|
* [Styling column headers](#styling-column-headers)
|
100
|
+
* [Styling the table title](#styling-title)
|
95
101
|
* [Setting default styles](#default-styles)
|
96
|
-
* [Styling borders](#
|
102
|
+
* [Styling borders](#styling-borders)
|
97
103
|
* [Repeating headers](#repeating-headers)
|
98
104
|
* [Using a Table Enumerator](#using-a-table-enumerator)
|
99
105
|
* [Accessing cell values](#accessing-cell-values)
|
@@ -106,7 +112,7 @@ Tabulo has also been ported to Crystal (with some modifications): see [Tablo](ht
|
|
106
112
|
* [Contributing](#contributing)
|
107
113
|
* [License](#license)
|
108
114
|
|
109
|
-
## Installation
|
115
|
+
## Installation [↑](#contents)
|
110
116
|
|
111
117
|
Add this line to your application’s Gemfile:
|
112
118
|
|
@@ -122,16 +128,14 @@ Or install it yourself:
|
|
122
128
|
|
123
129
|
$ gem install tabulo
|
124
130
|
|
125
|
-
|
126
|
-
|
127
|
-
### Requiring the gem
|
131
|
+
To use the gem, you need to require it in your source code as follows:
|
128
132
|
|
129
133
|
```ruby
|
130
134
|
require 'tabulo'
|
131
135
|
```
|
132
136
|
|
133
137
|
<a name="table-initialization"></a>
|
134
|
-
### Creating a table
|
138
|
+
### Creating a table [↑](#contents)
|
135
139
|
|
136
140
|
You instantiate a `Tabulo::Table` by passing it an underlying `Enumerable`, being the collection of
|
137
141
|
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)
|
|
146
150
|
For the table to be useful, however, it must also contain columns…
|
147
151
|
|
148
152
|
<a name="adding-columns"></a>
|
149
|
-
### Adding columns
|
153
|
+
### Adding columns [↑](#contents)
|
150
154
|
|
151
155
|
<a name="quick-api"></a>
|
152
|
-
#### Quick API
|
156
|
+
#### Quick API [↑](#contents)
|
153
157
|
|
154
158
|
When the columns correspond to methods on members of the underlying enumerable, you can use
|
155
159
|
the “quick API”, 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?)
|
|
171
175
|
```
|
172
176
|
|
173
177
|
<a name="full-api"></a>
|
174
|
-
#### Full API
|
178
|
+
#### Full API [↑](#contents)
|
175
179
|
|
176
180
|
Columns can also be added to the table one-by-one using `add_column`. This “full API” is
|
177
181
|
more verbose, but provides greater configurability:
|
@@ -216,8 +220,31 @@ end
|
|
216
220
|
+--------------+--------------+--------------+
|
217
221
|
```
|
218
222
|
|
223
|
+
The `add_column` method can be passed a single parameter callable, as shown in the above example,
|
224
|
+
with the parameter representing the member of the underyling enumerable; or it can be passed
|
225
|
+
2-parameter callable, with the second parameter representing the (0-based) index of each row. This can be
|
226
|
+
useful if you want to display a row number in one of the columns:
|
227
|
+
|
228
|
+
```ruby
|
229
|
+
table = Tabulo::Table.new(["a", "b", "c"]) do |t|
|
230
|
+
t.add_column("Row") { |letter, row_index| row_index }
|
231
|
+
t.add_column("Value", &:itself)
|
232
|
+
end
|
233
|
+
```
|
234
|
+
|
235
|
+
```
|
236
|
+
> puts table
|
237
|
+
+--------------+--------------+
|
238
|
+
| Row | Value |
|
239
|
+
+--------------+--------------+
|
240
|
+
| 0 | a |
|
241
|
+
| 1 | b |
|
242
|
+
| 2 | c |
|
243
|
+
+--------------+--------------+
|
244
|
+
```
|
245
|
+
|
219
246
|
<a name="labels-headers"></a>
|
220
|
-
#### Column labels _vs_ headers
|
247
|
+
#### Column labels _vs_ headers [↑](#contents)
|
221
248
|
|
222
249
|
The first argument to `add_column` is the called the _label_ for that column. It serves as the
|
223
250
|
column’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
|
|
231
258
|
```
|
232
259
|
|
233
260
|
<a name="column-positioning"></a>
|
234
|
-
#### Positioning columns
|
261
|
+
#### Positioning columns [↑](#contents)
|
235
262
|
|
236
263
|
By default, each new column is added to the right of all the other columns so far added to the
|
237
264
|
table. However, if you want to insert a new column into some other position, you can use the
|
238
265
|
`before` option, passing the label of the column to the left of which you want the new column to be added:
|
239
266
|
|
240
267
|
```ruby
|
241
|
-
table =
|
268
|
+
table = Tabulo::Table.new([1, 2, 3], :itself, :odd?)
|
242
269
|
table.add_column(:even?, before: :odd?)
|
243
270
|
```
|
244
271
|
|
@@ -254,7 +281,7 @@ table.add_column(:even?, before: :odd?)
|
|
254
281
|
```
|
255
282
|
|
256
283
|
<a name="removing-columns"></a>
|
257
|
-
### Removing columns
|
284
|
+
### Removing columns [↑](#contents)
|
258
285
|
|
259
286
|
There is also a `#remove_column` method, for deleting an existing column from a table. Pass it
|
260
287
|
the label of the column you want to remove:
|
@@ -263,8 +290,34 @@ the label of the column you want to remove:
|
|
263
290
|
table.remove_column(:even?)
|
264
291
|
```
|
265
292
|
|
293
|
+
<a name="title"></a>
|
294
|
+
### Adding a title [↑](#contents)
|
295
|
+
|
296
|
+
You can give your table a title, using the `title` option:
|
297
|
+
|
298
|
+
```ruby
|
299
|
+
table = Tabulo::Table.new([1, 2, 3], :itself, :even?, :odd?, title: "Numbers")
|
300
|
+
```
|
301
|
+
|
302
|
+
```
|
303
|
+
> puts table
|
304
|
+
+--------------------------------------------+
|
305
|
+
| Numbers |
|
306
|
+
+--------------+--------------+--------------+
|
307
|
+
| itself | even? | odd? |
|
308
|
+
+--------------+--------------+--------------+
|
309
|
+
| 1 | false | true |
|
310
|
+
| 2 | true | false |
|
311
|
+
| 3 | false | true |
|
312
|
+
+--------------+--------------+--------------+
|
313
|
+
```
|
314
|
+
|
315
|
+
There is a caveat: Using the `title` option with the `:markdown` [border type](#borders) will cause
|
316
|
+
the rendered table to cease being valid Markdown, as unfortunately almost no markdown engines support
|
317
|
+
adding a captions (i.e. titles) to tables.
|
318
|
+
|
266
319
|
<a name="cell-alignment"></a>
|
267
|
-
### Cell alignment
|
320
|
+
### Cell alignment [↑](#contents)
|
268
321
|
|
269
322
|
By default, column header text is center-aligned, while the content of each body cell is aligned
|
270
323
|
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.:
|
|
284
337
|
table.add_column("Doubled", align_header: :right, align_body: :left) { |n| n * 2 }
|
285
338
|
```
|
286
339
|
|
287
|
-
|
340
|
+
If a table title is present, it is center-aligned by default. This can be changed using the
|
341
|
+
`align_title` option when initializing the table:
|
342
|
+
|
343
|
+
```ruby
|
344
|
+
table = Tabulo::Table.new([1, 2], :itself, :even?, title: "Numbers", align_title: :left)
|
345
|
+
```
|
346
|
+
|
347
|
+
### Column width, wrapping and truncation [↑](#contents)
|
288
348
|
|
289
349
|
<a name="fixed-column-widths"></a>
|
290
|
-
#### Configuring fixed widths
|
350
|
+
#### Configuring fixed widths [↑](#contents)
|
291
351
|
|
292
352
|
By default, column width is fixed at 12 characters, plus 1 character of padding on either side.
|
293
353
|
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)
|
|
329
389
|
Widths set for individual columns always override the default column width for the table.
|
330
390
|
|
331
391
|
<a name="pack"></a>
|
332
|
-
#### Automating column widths
|
392
|
+
#### Automating column widths [↑](#contents)
|
333
393
|
|
334
394
|
Instead of setting column widths “manually”, you can tell the table to sort out the widths
|
335
395
|
itself, so that each column is just wide enough for its header and contents (plus a character
|
@@ -350,6 +410,26 @@ table.pack
|
|
350
410
|
+-------------------------+------+
|
351
411
|
```
|
352
412
|
|
413
|
+
If the table [title](#title) happens to be too long to for the existing width of the table, `pack`
|
414
|
+
will also arrange for the table to be widened sufficiently to accommodate it without wrapping:
|
415
|
+
|
416
|
+
```ruby
|
417
|
+
table = Tabulo::Table.new(["a", "b"], :itself, :size, title: "Here are some letters of the alphabet")
|
418
|
+
table.pack
|
419
|
+
```
|
420
|
+
|
421
|
+
```
|
422
|
+
> puts table
|
423
|
+
+---------------------------------------+
|
424
|
+
| Here are some letters of the alphabet |
|
425
|
+
+-------------------+-------------------+
|
426
|
+
| itself | size |
|
427
|
+
+-------------------+-------------------+
|
428
|
+
| a | 1 |
|
429
|
+
| b | 1 |
|
430
|
+
+-------------------+-------------------+
|
431
|
+
```
|
432
|
+
|
353
433
|
The `pack` method returns the table itself, so you can “pack-and-print” in one go:
|
354
434
|
|
355
435
|
```ruby
|
@@ -398,7 +478,7 @@ table itself. There are [ways around this](#freezing-a-table), however, if this
|
|
398
478
|
behaviour—see [below](#freezing-a-table).
|
399
479
|
|
400
480
|
<a name="configuring-padding"></a>
|
401
|
-
#### Configuring padding
|
481
|
+
#### Configuring padding [↑](#contents)
|
402
482
|
|
403
483
|
The single character of padding either side of each column is not counted in the column width.
|
404
484
|
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)
|
|
412
492
|
```
|
413
493
|
|
414
494
|
```
|
415
|
-
> puts table
|
416
|
-
|
417
|
-
|
|
418
|
-
|
419
|
-
|
|
420
|
-
|
|
421
|
-
|
|
422
|
-
|
495
|
+
> puts table.pack
|
496
|
+
+------+-----+-----+
|
497
|
+
|itself|even?| odd?|
|
498
|
+
+------+-----+-----+
|
499
|
+
| 1|false| true|
|
500
|
+
| 2| true|false|
|
501
|
+
| 5|false| true|
|
502
|
+
+------+-----+-----+
|
423
503
|
```
|
424
504
|
|
425
505
|
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,
|
|
430
510
|
```
|
431
511
|
|
432
512
|
```
|
433
|
-
> puts table
|
434
|
-
|
435
|
-
|
|
436
|
-
|
437
|
-
|
|
438
|
-
|
|
439
|
-
|
|
440
|
-
|
513
|
+
> puts table.pack
|
514
|
+
+--------+-------+-------+
|
515
|
+
|itself |even? | odd? |
|
516
|
+
+--------+-------+-------+
|
517
|
+
| 1 |false | true |
|
518
|
+
| 2 | true |false |
|
519
|
+
| 5 |false | true |
|
520
|
+
+--------+-------+-------+
|
521
|
+
```
|
522
|
+
|
523
|
+
Note how the padding amount is completely unaffected by the call `pack`.
|
524
|
+
|
525
|
+
Padding can also be configured on a column-by-column basis, using the `padding` option when calling
|
526
|
+
`add_column`:
|
527
|
+
|
528
|
+
```ruby
|
529
|
+
table = Tabulo::Table.new([1, 2, 5], :itself, :even?)
|
530
|
+
table.add_column(:odd?, padding: 3)
|
531
|
+
```
|
532
|
+
|
441
533
|
```
|
534
|
+
> puts table.pack
|
535
|
+
+--------+-------+-----------+
|
536
|
+
| itself | even? | odd? |
|
537
|
+
+--------+-------+-----------+
|
538
|
+
| 1 | false | true |
|
539
|
+
| 2 | true | false |
|
540
|
+
| 5 | false | true |
|
541
|
+
+--------+-------+-----------+
|
542
|
+
```
|
543
|
+
|
544
|
+
This column-level `padding` setting always overrides any table-level `column_padding` setting, for
|
545
|
+
the column in question.
|
442
546
|
|
443
547
|
<a name="overflow-handling"></a>
|
444
|
-
#### Overflow handling
|
548
|
+
#### Overflow handling [↑](#contents)
|
445
549
|
|
446
550
|
By default, if cell contents exceed their column width, they are wrapped for as many rows as
|
447
551
|
required:
|
@@ -492,8 +596,34 @@ table = Tabulo::Table.new(
|
|
492
596
|
The character used to indicate truncation, which defaults to `~`, can be configured using the
|
493
597
|
`truncation_indicator` option passed to `Table.new`.
|
494
598
|
|
599
|
+
<a name="manual-wrapping"></a>
|
600
|
+
#### Manual cell wrapping [↑](#contents)
|
601
|
+
|
602
|
+
You can “manually” wrap the content of a title, header or body cell at a particular
|
603
|
+
point, simply by placing a newline character at that point:
|
604
|
+
|
605
|
+
```ruby
|
606
|
+
table = Tabulo::Table.new(1..3) do |t|
|
607
|
+
t.add_column("The number\nitself", &:itself)
|
608
|
+
t.add_column("Even?", &:even?)
|
609
|
+
t.add_column("Odd?", &:odd?)
|
610
|
+
end
|
611
|
+
```
|
612
|
+
|
613
|
+
```
|
614
|
+
> puts table
|
615
|
+
+--------------+--------------+--------------+
|
616
|
+
| The number | Even? | Odd? |
|
617
|
+
| itself | | |
|
618
|
+
+--------------+--------------+--------------+
|
619
|
+
| 1 | false | true |
|
620
|
+
| 2 | true | false |
|
621
|
+
| 3 | false | true |
|
622
|
+
+--------------+--------------+--------------+
|
623
|
+
```
|
624
|
+
|
495
625
|
<a name="formatting-cell-values"></a>
|
496
|
-
### Formatting cell values
|
626
|
+
### Formatting cell values [↑](#contents)
|
497
627
|
|
498
628
|
While the callable passed to `add_column` determines the underyling, calculated value in each
|
499
629
|
cell of the column, there is a separate concept, of a “formatter”, that determines how
|
@@ -550,11 +680,17 @@ end
|
|
550
680
|
Formatters set for individual columns on calling `#add_column` always override the default formatter for
|
551
681
|
the table.
|
552
682
|
|
683
|
+
The `formatter` callback also has an alternative, 2-parameter version. If `formatter` is passed
|
684
|
+
a 2-parameter callable, the second parameter will be given a `CellData` instance,
|
685
|
+
containing additional information about the cell that may be useful in determining how to format
|
686
|
+
it—see the [documentation](https://www.rubydoc.info/gems/tabulo/2.6.1/Tabulo/CellData.html)
|
687
|
+
for details.
|
688
|
+
|
553
689
|
<a name="colours-and-styling"></a>
|
554
|
-
### Colours and other styling
|
690
|
+
### Colours and other styling [↑](#contents)
|
555
691
|
|
556
692
|
<a name="styling-cell-content"></a>
|
557
|
-
#### Styling cell content
|
693
|
+
#### Styling cell content [↑](#contents)
|
558
694
|
|
559
695
|
In most terminals, if you want to print text that is coloured, or has certain other styles such as
|
560
696
|
underlining, you need to use ANSI escape sequences, either directly, or by means of a library such
|
@@ -587,19 +723,23 @@ table.add_column(
|
|
587
723
|
)
|
588
724
|
```
|
589
725
|
|
590
|
-
The `styler` option should be passed a callable that takes
|
591
|
-
the underlying value of the cell (in this case a boolean indicating whether the
|
592
|
-
|
593
|
-
any processing by the [formatter](#formatting-cell-values).
|
594
|
-
|
595
|
-
|
596
|
-
|
726
|
+
The `styler` option should be passed a callable that takes either 2, 3 or 4 parameters.
|
727
|
+
The first parameter represents the underlying value of the cell (in this case a boolean indicating whether the
|
728
|
+
number is even). The second parameter represents the formatted string value of that cell, i.e. the cell
|
729
|
+
content after any processing by the [formatter](#formatting-cell-values). The third and fourth
|
730
|
+
parameters are optional, and contain further information about the cell and its contents that may be useful in
|
731
|
+
determining how to style it. See the
|
732
|
+
[documentation](https://www.rubydoc.info/gems/tabulo/2.6.1/Tabulo/Table#add_column-instance_method) for details.
|
733
|
+
|
734
|
+
If the content of a cell is wrapped over multiple lines, then the `styler` will be called once
|
735
|
+
per line, so that each line of the cell will have the escape sequence applied to it separately
|
736
|
+
(ensuring the styling doesn’t bleed into neighbouring cells).
|
597
737
|
|
598
|
-
If the content of a cell has been [truncated](#overflow-handling), then whatever colours or other
|
599
|
-
apply to the cell content will also be applied the truncation indicator character.
|
738
|
+
If the content of a cell has been [truncated](#overflow-handling), then whatever colours or other
|
739
|
+
styling apply to the cell content will also be applied the truncation indicator character.
|
600
740
|
|
601
741
|
<a name="styling-column-headers"></a>
|
602
|
-
#### Styling column headers
|
742
|
+
#### Styling column headers [↑](#contents)
|
603
743
|
|
604
744
|
If you want to apply colours or other styling to the content of a column header, as opposed
|
605
745
|
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.:
|
|
608
748
|
table.add_column(:even?, header_styler: -> (s) { "\033[32m#{s}\033[0m" })
|
609
749
|
```
|
610
750
|
|
611
|
-
|
612
|
-
|
751
|
+
The `header_styler` option accepts a 1-, 2- or 3-parameter callable. See the
|
752
|
+
[documentation](https://www.rubydoc.info/gems/tabulo/2.6.1/Tabulo/Table#add_column-instance_method)
|
753
|
+
for details.
|
613
754
|
|
614
|
-
|
615
|
-
|
616
|
-
|
617
|
-
|
618
|
-
|
755
|
+
<a name="styling-title"></a>
|
756
|
+
#### Styling the table title [↑](#contents)
|
757
|
+
|
758
|
+
To apply colours or other styling to the table title, if present, use the `title_styler` option
|
759
|
+
when initializing the table. This accepts a single-parameter callable:
|
619
760
|
|
620
761
|
```ruby
|
621
|
-
table = Tabulo::Table.new(1..5, :itself, :even?, :odd?,
|
762
|
+
table = Tabulo::Table.new(1..5, :itself, :even?, :odd?, title: "Numbers", title_styler: -> (s) { "\033[32m#{s}\033[0m" })
|
622
763
|
```
|
623
764
|
|
624
|
-
|
625
|
-
|
765
|
+
The `title_styler` option accepts a 1- or 2-parameter callable. See the
|
766
|
+
[documentation](https://www.rubydoc.info/gems/tabulo/2.6.1/Tabulo/Table#initialize-instance_method)
|
767
|
+
for details.
|
626
768
|
|
627
|
-
<a name="
|
628
|
-
#### Styling borders
|
769
|
+
<a name="styling-borders"></a>
|
770
|
+
#### Styling borders [↑](#contents)
|
629
771
|
|
630
772
|
Styling can also be applied to borders and dividing lines, using the `border_styler` option when
|
631
773
|
initializing the table, e.g.:
|
@@ -634,8 +776,24 @@ initializing the table, e.g.:
|
|
634
776
|
table = Tabulo::Table.new(1..5, :itself, :even?, :odd?, border_styler: -> (s) { "\033[32m#{s}\033[0m" })
|
635
777
|
```
|
636
778
|
|
779
|
+
<a name="default-styles"></a>
|
780
|
+
#### Setting default styles [↑](#contents)
|
781
|
+
|
782
|
+
By default, no styling is applied to the headers or body content of a column unless configured to do
|
783
|
+
so via the `header_styler` or `styler` option when calling `add_column` for that particular column.
|
784
|
+
It is possible to apply styling by default to _all_ columns in a table, however, as the table initializer
|
785
|
+
also accepts both a `header_styler` and a `styler` option. For example, if you want all the header text
|
786
|
+
in the table to be green, you could do:
|
787
|
+
|
788
|
+
```ruby
|
789
|
+
table = Tabulo::Table.new(1..5, :itself, :even?, :odd?, header_styler: -> (s) { "\033[32m#{s}\033[0m" })
|
790
|
+
```
|
791
|
+
|
792
|
+
Now, all columns in the table will automatically have green header text, unless overridden by another
|
793
|
+
header styler being passed to `#add_column`.
|
794
|
+
|
637
795
|
<a name="repeating-headers"></a>
|
638
|
-
### Repeating headers
|
796
|
+
### Repeating headers [↑](#contents)
|
639
797
|
|
640
798
|
By default, headers are only shown once, at the top of the table (`header_frequency: :start`). If
|
641
799
|
`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)
|
|
669
827
|
+--------------+--------------+
|
670
828
|
```
|
671
829
|
|
830
|
+
Note that if the table has a [title](#title), it will not be repeated; only column headers are repeated.
|
831
|
+
|
672
832
|
<a name="enumerator"></a>
|
673
|
-
### Using a Table Enumerator
|
833
|
+
### Using a Table Enumerator [↑](#contents)
|
674
834
|
|
675
835
|
Because it’s an `Enumerable`, a `Tabulo::Table` can also give you an `Enumerator`,
|
676
836
|
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
|
|
699
859
|
calculated.)
|
700
860
|
|
701
861
|
<a name="accessing-cell-values"></a>
|
702
|
-
### Accessing cell values
|
862
|
+
### Accessing cell values [↑](#contents)
|
703
863
|
|
704
864
|
Each `Tabulo::Table` is an `Enumerable` of which each element is a `Tabulo::Row`. Each `Tabulo::Row`
|
705
865
|
is itself an `Enumerable`, of `Tabulo::Cell`. The `Tabulo::Cell#value` method will return the
|
@@ -735,7 +895,7 @@ end
|
|
735
895
|
```
|
736
896
|
|
737
897
|
<a name="accessing-sources"></a>
|
738
|
-
### Accessing the underlying enumerable
|
898
|
+
### Accessing the underlying enumerable [↑](#contents)
|
739
899
|
|
740
900
|
The underlying enumerable for a table can be retrieved by calling the `sources` getter:
|
741
901
|
|
@@ -770,7 +930,7 @@ end
|
|
770
930
|
```
|
771
931
|
|
772
932
|
<a name="transposition"></a>
|
773
|
-
### Transposing rows and columns
|
933
|
+
### Transposing rows and columns [↑](#contents)
|
774
934
|
|
775
935
|
By default, Tabulo generates a table in which each row corresponds to a _record_, i.e. an element of
|
776
936
|
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:
|
|
798
958
|
By default, a header row is added to the new table, showing the string value of the element
|
799
959
|
represented in that column. This can be configured, however, along with other aspects of
|
800
960
|
`transpose`’s behaviour. For details, see the
|
801
|
-
[documentation](https://www.rubydoc.info/gems/tabulo/2.
|
961
|
+
[documentation](https://www.rubydoc.info/gems/tabulo/2.6.1/Tabulo/Table#transpose-instance_method).
|
802
962
|
|
803
963
|
<a name="borders"></a>
|
804
|
-
### Configuring borders
|
964
|
+
### Configuring borders [↑](#contents)
|
805
965
|
|
806
966
|
You can configure the kind of border and divider characters that are used when the table is printed.
|
807
967
|
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
|
|
817
977
|
| 2 | true | false |
|
818
978
|
| 3 | false | true |
|
819
979
|
+--------------+--------------+--------------+
|
980
|
+
|
981
|
+
> puts Tabulo::Table.new(1..3, :itself, :even?, :odd?, border: :ascii, title: "Numbers")
|
982
|
+
+--------------------------------------------+
|
983
|
+
| Numbers |
|
984
|
+
+--------------+--------------+--------------+
|
985
|
+
| itself | even? | odd? |
|
986
|
+
+--------------+--------------+--------------+
|
987
|
+
| 1 | false | true |
|
988
|
+
| 2 | true | false |
|
989
|
+
| 3 | false | true |
|
990
|
+
+--------------+--------------+--------------+
|
820
991
|
```
|
821
992
|
|
822
993
|
`:modern`—uses smoothly joined Unicode characters:
|
@@ -830,6 +1001,17 @@ This is done using the `border` option passed to `Table.new`. The options are as
|
|
830
1001
|
│ 2 │ true │ false │
|
831
1002
|
│ 3 │ false │ true │
|
832
1003
|
└──────────────┴──────────────┴──────────────┘
|
1004
|
+
|
1005
|
+
> puts Tabulo::Table.new(1..3, :itself, :even?, :odd?, border: :modern, title: "Numbers")
|
1006
|
+
┌────────────────────────────────────────────┐
|
1007
|
+
│ Numbers │
|
1008
|
+
├──────────────┬──────────────┬──────────────┤
|
1009
|
+
│ itself │ even? │ odd? │
|
1010
|
+
├──────────────┼──────────────┼──────────────┤
|
1011
|
+
│ 1 │ false │ true │
|
1012
|
+
│ 2 │ true │ false │
|
1013
|
+
│ 3 │ false │ true │
|
1014
|
+
└──────────────┴──────────────┴──────────────┘
|
833
1015
|
```
|
834
1016
|
|
835
1017
|
`:markdown`—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
|
|
841
1023
|
| 1 | false | true |
|
842
1024
|
| 2 | true | false |
|
843
1025
|
| 3 | false | true |
|
1026
|
+
|
1027
|
+
> puts Tabulo::Table.new(1..3, :itself, :even?, :odd?, border: :markdown, title: "Numbers")
|
1028
|
+
| Numbers |
|
1029
|
+
| itself | even? | odd? |
|
1030
|
+
|--------------|--------------|--------------|
|
1031
|
+
| 1 | false | true |
|
1032
|
+
| 2 | true | false |
|
1033
|
+
| 3 | false | true |
|
844
1034
|
```
|
845
1035
|
|
1036
|
+
_However_, note that when a table is rendered using the `:markdown` border type in combination with a
|
1037
|
+
(non-`nil`) `title`, the result will be _invalid Markdown_. This is because Markdown engines do not
|
1038
|
+
generally support adding a caption (i.e. title) element to tables.
|
1039
|
+
|
846
1040
|
`:blank`—no border or divider characters are printed:
|
847
1041
|
|
848
1042
|
```
|
@@ -851,6 +1045,14 @@ This is done using the `border` option passed to `Table.new`. The options are as
|
|
851
1045
|
1 false true
|
852
1046
|
2 true false
|
853
1047
|
3 false true
|
1048
|
+
|
1049
|
+
|
1050
|
+
> puts Tabulo::Table.new(1..3, :itself, :even?, :odd?, border: :blank, title: "Numbers")
|
1051
|
+
Numbers
|
1052
|
+
itself even? odd?
|
1053
|
+
1 false true
|
1054
|
+
2 true false
|
1055
|
+
3 false true
|
854
1056
|
```
|
855
1057
|
|
856
1058
|
`:reduced_ascii`—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
|
|
864
1066
|
2 true false
|
865
1067
|
3 false true
|
866
1068
|
-------------- -------------- --------------
|
1069
|
+
|
1070
|
+
> puts Tabulo::Table.new(1..3, :itself, :even?, :odd?, border: :reduced_modern, title: "Numbers")
|
1071
|
+
--------------------------------------------
|
1072
|
+
Numbers
|
1073
|
+
-------------- -------------- --------------
|
1074
|
+
itself even? odd?
|
1075
|
+
-------------- -------------- --------------
|
1076
|
+
1 false true
|
1077
|
+
2 true false
|
1078
|
+
3 false true
|
1079
|
+
-------------- -------------- --------------
|
867
1080
|
```
|
868
1081
|
|
869
1082
|
`:reduced_modern`—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
|
|
877
1090
|
2 true false
|
878
1091
|
3 false true
|
879
1092
|
────────────── ────────────── ──────────────
|
1093
|
+
|
1094
|
+
> puts Tabulo::Table.new(1..3, :itself, :even?, :odd?, border: :reduced_ascii, title: "Numbers")
|
1095
|
+
────────────────────────────────────────────
|
1096
|
+
Numbers
|
1097
|
+
────────────── ────────────── ──────────────
|
1098
|
+
itself even? odd?
|
1099
|
+
────────────── ────────────── ──────────────
|
1100
|
+
1 false true
|
1101
|
+
2 true false
|
1102
|
+
3 false true
|
1103
|
+
────────────── ────────────── ──────────────
|
880
1104
|
```
|
881
1105
|
|
882
1106
|
`:classic`—reproduces the default behaviour in Tabulo v1; this is like the `:ascii` option,
|
@@ -890,13 +1114,23 @@ but without a bottom border:
|
|
890
1114
|
| 1 | false | true |
|
891
1115
|
| 2 | true | false |
|
892
1116
|
| 3 | false | true |
|
1117
|
+
|
1118
|
+
> puts Tabulo::Table.new(1..3, :itself, :even?, :odd?, border: :classic, title: "Numbers")
|
1119
|
+
+--------------------------------------------+
|
1120
|
+
| Numbers |
|
1121
|
+
+--------------+--------------+--------------+
|
1122
|
+
| itself | even? | odd? |
|
1123
|
+
+--------------+--------------+--------------+
|
1124
|
+
| 1 | false | true |
|
1125
|
+
| 2 | true | false |
|
1126
|
+
| 3 | false | true |
|
893
1127
|
```
|
894
1128
|
|
895
1129
|
Note that, by default, none of the border options includes lines drawn _between_ rows in the body of the table.
|
896
1130
|
These are configured via a separate option: see [below](#dividers).
|
897
1131
|
|
898
1132
|
<a name="dividers"></a>
|
899
|
-
### Row dividers
|
1133
|
+
### Row dividers [↑](#contents)
|
900
1134
|
|
901
1135
|
To add lines between rows in the table body, use the `row_divider_frequency` option when initializing
|
902
1136
|
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
|
|
935
1169
|
```
|
936
1170
|
|
937
1171
|
<a name="freezing-a-table"></a>
|
938
|
-
### Using a table as a snapshot rather than as a dynamic view
|
1172
|
+
### Using a table as a snapshot rather than as a dynamic view [↑](#contents)
|
939
1173
|
|
940
1174
|
The nature of a `Tabulo::Table` is that of a dynamic view onto the underlying `sources` enumerable
|
941
1175
|
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
|
|
1005
1239
|
```
|
1006
1240
|
|
1007
1241
|
<a name="motivation"></a>
|
1008
|
-
## Comparison with other libraries
|
1242
|
+
## Comparison with other libraries [↑](#contents)
|
1009
1243
|
|
1010
1244
|
There are other libraries for generating plain text tables in Ruby. Popular among these are:
|
1011
1245
|
|
@@ -1090,7 +1324,7 @@ environment seems cumbersome. Moreover, it seems no longer to be maintained. At
|
|
1090
1324
|
its last commit was in March 2015.
|
1091
1325
|
|
1092
1326
|
<a name="contributing"></a>
|
1093
|
-
## Contributing
|
1327
|
+
## Contributing [↑](#contents)
|
1094
1328
|
|
1095
1329
|
Issues and pull requests are welcome on GitHub at https://github.com/matt-harvey/tabulo.
|
1096
1330
|
|
@@ -1101,20 +1335,20 @@ install dependencies.
|
|
1101
1335
|
`bundle exec rake spec` will run the test suite. For a list of other Rake tasks that are available in
|
1102
1336
|
the development environment, run `bundle exec rake -T`.
|
1103
1337
|
|
1104
|
-
## License
|
1338
|
+
## License [↑](#contents)
|
1105
1339
|
|
1106
1340
|
The gem is available as open source under the terms of the [MIT
|
1107
1341
|
License](http://opensource.org/licenses/MIT).
|
1108
1342
|
|
1109
1343
|
[Gem Version]: https://rubygems.org/gems/tabulo
|
1110
|
-
[Documentation]: http://www.rubydoc.info/gems/tabulo/2.
|
1344
|
+
[Documentation]: http://www.rubydoc.info/gems/tabulo/2.6.1
|
1111
1345
|
[Build Status]: https://travis-ci.org/matt-harvey/tabulo
|
1112
1346
|
[Coverage Status]: https://coveralls.io/r/matt-harvey/tabulo
|
1113
1347
|
[Code Climate]: https://codeclimate.com/github/matt-harvey/tabulo
|
1114
1348
|
[Awesome Ruby]: https://github.com/markets/awesome-ruby#cli-utilities
|
1115
1349
|
|
1116
1350
|
[GV img]: https://img.shields.io/gem/v/tabulo.svg
|
1117
|
-
[DC img]: https://img.shields.io/badge/documentation-v2.
|
1351
|
+
[DC img]: https://img.shields.io/badge/documentation-v2.6.1-blue.svg
|
1118
1352
|
[BS img]: https://img.shields.io/travis/matt-harvey/tabulo.svg
|
1119
1353
|
[CS img]: https://img.shields.io/coveralls/matt-harvey/tabulo.svg
|
1120
1354
|
[CC img]: https://codeclimate.com/github/matt-harvey/tabulo/badges/gpa.svg
|