First constructor : Table constructor has two versions to initialize a new Table instance, depending on whether a block is given or not.

Mandatory parameters:

• sources: is any⁽¹⁾ Enumerable of any type T^{(2)
  (1)} Currently, a Range Enumerable is not supported in this context: Convert to array beforehand.
  ⁽²⁾ Provided that the type includes the Tablo::CellType module

Optional named parameters, with default values

• title: Default set by Config::Defaults.title

• subtitle: Default set by Config::Defaults.subtitle
  (depends on title existence for display)

• footer: Default set by Config::Defaults.footer

• border: A dedicated struct for managing the rows and columns separating data cells.
  See Border.new for initialization default parameters.

• group_alignment: Default value set by Config::Defaults.group_alignment

• group_formatter: Default value set by Config::Defaults.group_formatter

• group_styler: Default value set by Config::Defaults.group_styler

• header_alignment: Default value set by Config::Defaults.header_alignment

• header_formatter: Default value set by Config::Defaults.header_formatter,

• header_styler: Defaut value set by Config::Defaults.header_styler

• body_alignment: Default value set by Config::Defaults.body_alignment

• body_formatter: Default value set by Config::Defaults.body_formatter

• body_styler: Default value set by Config::Defaults.body_styler

• left_padding: Default value set by Config::Defaults.left_padding

• right_padding: Default value set by Config::Defaults.right_padding
  

  For both left and right padding, permitted range of values is governed by Config::Controls.padding_width_range
  (raises Error::InvalidValue runtime exception if value not in range)

• padding_character: Default value set by Config::Defaults.padding_character
  (raises an Error::InvalidValue runtime exception if string size is not exactly 1)

• truncation_indicator: Defaut value set by Config::Defaults.truncation_indicator
  (raises an Error::InvalidValue runtime exception if string size is not exactly 1)

• width: Default value set by Config::Defaults.column_width
  Permitted range of values is governed by Config::Controls.column_width_range
  (raises Error::InvalidValue runtime exception if value not in range)

• header_frequency: Default value set by Config::Defaults.header_frequency
  Permitted range of values is governed by Config::Controls.header_frequency_range
  (raises Error::InvalidValue runtime exception unless value in range or nil)

  • If set to 0, rows of data other than body are displayed only once, at the beginning for titles and headers, at the end for the footer.
  • If set to n (positive), group or column headers are repeated every n rows, as are footers, but titles and subtitles are not repeated (unless title repeated attribute is set to true)
  • If set to nil, only body rows are displayed.

• row_divider_frequency: Default value set by Config::Defaults.row_divider_frequency
  Permitted range of values is governed by Config::Controls.row_divider_frequency_range
  (raises Error::InvalidValue runtime exception unless value in range or nil)

• wrap_mode: Default value set by Config::Defaults.wrap_mode
  The WrapMode enum defines 2 modes :

  • Rune : long lines are cut between characters (graphemes)
  • Word : long lines are cut between words only

• header_wrap: Default value set by Config::Defaults.header_wrap
  Permitted range of values is governed by Config::Controls.header_wrap_range
  (raises Error::InvalidValue runtime exception unless value in range or nil)

• body_wrap: Default value set by Config::Defaults.body_wrap
  Permitted range of values is governed by Config::Controls.body_wrap_range
  (raises Error::InvalidValue runtime exception unless value in range or nil)

• masked_headers: Default value set by Config::Defaults.masked_headers?
  If true, groups and column headers are not displayed
  (this does not prevent display of title, subtitle and footer)

• omit_group_header_rule: Default value set by Config::Defaults.omit_group_header_rule?
  If true, the rule between Group and Header rows is not displayed.
  (This is useful for headers custom rendering)

• omit_last_rule: Default value set by Config::Defaults.omit_last_rule?
  If true, the closing rule of table is not displayed. This is useful for custom rendering (and notably for "graphically" joining Detail and Summary tables)

Returns an instance of Table(T)

Second constructor, with same parameters as the first one, but with a block given

The initialize macro generates two `initialize' methods, one with block_given = true and one with block_given = false

Returns an instance of Column(T)

Mandatory positional parameter:

• label: The column identifier (of type LabelType)

Optional named parameters, with default values

• header: The column header, default value is label.to_s
  Can be an empty string

• header_alignment: Default value inherited from Table initializer

• header_formatter: Default value inherited from table initializer

• header_styler: Default value inherited from table initializer

• body_alignment: Default value inherited from table initializer

• body_formatter: Default value inherited from table initializer

• body_styler: Default value inherited from table initializer

• left_padding: Default value inherited from table initializer

• right_padding: Default value inherited from table initializer

• padding_character: Default value inherited from table initializer

• width: Default value inherited from table initializer

• truncation_indicator: Default value inherited from table initializer

• wrap_mode: Default value inherited from table initializer

Captured block

• &extractor: type is (T | Int32) -> CellType
  Captured block for extracting data from source

Returns an instance of Cell::Text

Creates a group including all previous columns not already grouped. After adding the last column, a group is automatically created (with an empty header) if not explicitly specified.

Mandatory positional parameter

• label: The group identifier (of type LabelType)

Optional named parameters, with default values

• header: The group header, default value is label.to_s
  Can be an empty string

• alignment: Default value inherited from table initializer

• formatter: Default value inherited from table initializer

• styler: Default value inherited from table initializer

• padding_character: Default value inherited from table initializer

• truncation_indicator: Default value inherited from table initializer

• wrap_mode: Default value inherited from table initializer

The #add_summary method creates a summary table, attached to the main table.

Mandatory positional parameters:

• summary_definition: an array of structs, where structs may be one or more instances of Summary::UserProc, Summary::HeaderColumn, Summary::BodyColumn or Summary::BodyRow

• summary_options: type is NamedTuple(<Table parameters>)
  where <Table parameters> is a list of any number of Table initializers (may be empty).

See Tablo::Summary for detailed examples and explanations on use.

Returns self, an instance of Table(T), with an embedded Summary Table

Second form : summary_options given as a list of Table initializers

Returns an array of data extracted from Table sources for a specific column

Mandatory positional parameter:

• column_label: The column identifier

example:

require "tablo"
table = Tablo::Table.new([1, 2, 3]) do |t|
  t.add_column("itself", &.itself)
  t.add_column("double", &.itself.*(2))
end
puts table.column_data("double") # => [2, 4, 6]

Returns successive formatted rows, with all their corresponding headers and footers, according to the Table header_frequency value.

In fact,

table.each do |row|
  puts row
end

is the same as

puts table

Produce a horizontal dividing line suitable for printing between rendered rows, so as to customize table output.

For example, to insert a horizontal line at specific row positions, here between some Body rows, we can do :

table.each_with_index do |row, i|
  puts table.horizontal_rule(Tablo::RuleType::BodyBody) unless i == 0 || i == 2
  puts row
end

• Returns a String representing the formatted horizontal rule

#pack method (1. all displayable columns)
Returns self (the current Table instance) after modifying its column widths

The #pack method comes in 3 overloaded versions :

• Version 1: all columns are selected for packing
• Version 2: some columns are excluded (except parameter)
• Version 3: only certain columns are selected (only parameter)

The #pack method allows for adapting the total width of the table. It accepts 3 parameters, all optional:

• width: type is Int32?
  Default value is nil
  total width required for the formatted table. If no width is given and if the value of parameter Config.terminal_capped_width? is true, the value of width is read from the size of the terminal, otherwise its value is nil and in that case, #pack has no effect unless autosize == true or widths are harmonized between the main and summary tables.

• autosize: type is Bool
  Default value is true
  if true, current width values are set to their 'best fit' values, ie they are automatically adapted to their largest content, before packing

• except: type is LabelType or Array(LabelType)
  Default value: None, but mandatory in overloaded version 2
  Column or array of columns excluded from being resized

• only: type is LabelType or Array(LabelType)
  Default value: None, but mandatory in overloaded version 3
  Column or array of columns selected exclusively for resizing

The following examples will illustrate the behaviour of the different parameters values, starting from the 'standard' one, with all column widths to their default value : 12 characters.

require "tablo"
data = [[1, "A long sequence of characters", 123.456789]]
table = Tablo::Table.new(data) do |t|
  t.add_column(:col1, &.[0])
  t.add_column(:col2, &.[1])
  t.add_column(:col3, &.[2])
end

Here are the different results depending on the parameters passed.

First, table is printed without any packing

puts table
+--------------+--------------+--------------+
|         col1 | col2         |         col3 |
+--------------+--------------+--------------+
|            1 | A long       |   123.456789 |
|              | sequence of  |              |
|              | characters   |              |
+--------------+--------------+--------------+
Total table width = 46

A packing instruction with no automatic adaptation request (autosize=false), but with a total width to be reached, will modify the width of each column, starting from its current value, until the target total width is reached (see explanation of the packing algorithm below).

puts table.pack(40, autosize: false)
+------------+------------+------------+
|       col1 | col2       |       col3 |
+------------+------------+------------+
|          1 | A long     | 123.456789 |
|            | sequence   |            |
|            | of         |            |
|            | characters |            |
+------------+------------+------------+
Total table width = 40

With autosize = true, column widths are first recalculated to fit the contents of each cell, then packing is performed to conform to the total width requested. We can see the "packing quality" is much better.

puts table.pack(40, autosize: true)
+------+------------------+------------+
| col1 | col2             |       col3 |
+------+------------------+------------+
|    1 | A long sequence  | 123.456789 |
|      | of characters    |            |
+------+------------------+------------+
Total table width = 40

Without specifying a total width to be achieved, each column width is adapted to its largest content.

puts table.pack(autosize: true)
+------+-------------------------------+------------+
| col1 | col2                          |       col3 |
+------+-------------------------------+------------+
|    1 | A long sequence of characters | 123.456789 |
+------+-------------------------------+------------+
Total table width = 53

A packing instruction without automatic adaptation (autosize=false) or total width requested, will produce two different results depending on the value of the Config.terminal_capped_width? parameter:

• if true: the total width requested will be equal to the number of terminal columns
• if false: column widths will revert to their initial values (as in the output below)

puts table.pack(autosize: false)
+--------------+--------------+--------------+
|         col1 | col2         |         col3 |
+--------------+--------------+--------------+
|            1 | A long       |   123.456789 |
|              | sequence of  |              |
|              | characters   |              |
+--------------+--------------+--------------+
Total table width = 46

We can also obtain various results using the except: or only: parameters, For examples :

puts table.pack(only: :col1
+------+--------------+--------------+
| col1 | col2         |         col3 |
+------+--------------+--------------+
|    1 | A long       |   123.456789 |
|      | sequence of  |              |
|      | characters   |              |
+------+--------------+--------------+
Total table width = 38

or:

puts table.pack(except: :col3)
+------+-------------------------------+--------------+
| col1 | col2                          |         col3 |
+------+-------------------------------+--------------+
|    1 | A long sequence of characters |   123.456789 |
+------+-------------------------------+--------------+
Total table width = 55

Description of the packing algorithm

The resizing algorithm is actually quite simple:
If the final value of the width parameter is not nil, it first compares the table's current width with the requested width, to determine whether this is a reduction or an increase in size. Then, depending on the case, either the widest column is reduced, or the narrowest increased, in steps of 1, until the requested table width is reached.
The final result then depends on the value of the column widths before the packing operation, hence the importance of the autosize parameter in this calculation.

#pack method (2. displayable columns with exceptions)
Returns self (the current Table instance) after modifying its column widths

#pack method (3. displayable and selected columns only)
Returns self (the current Table instance) after modifying its column widths

returns the sources Enumerable(T)

Replaces existing data source with a new one.

Mandatory positional parameter

• sources: New data source, whose type is Enumerable(T), where T is the same type as at table initialization

table = Tablo::Table.new([1, 2, 3]) do |t|
  t.add_column(:number) { |n| n }
  t.add_column(:doubled, header: "Number X 2") { |n| n * 2 }
end
puts table
puts
table.sources = [50, 60]
puts table

+--------------+--------------+
|       number |   Number X 2 |
+--------------+--------------+
|            1 |            2 |
|            2 |            4 |
|            3 |            6 |
+--------------+--------------+

+--------------+--------------+
|       number |   Number X 2 |
+--------------+--------------+
|           50 |          100 |
|           60 |          120 |
+--------------+--------------+

Existing sources may also be altered, as in the following example.

arr = [1, 2, 3]
table = Tablo::Table.new(arr) do |t|
  t.add_column(:number) { |n| n }
  t.add_column(:doubled, header: "Number X 2") { |n| n * 2 }
end
puts table
puts
arr << 42
arr.shift
puts table

+--------------+--------------+
|       number |   Number X 2 |
+--------------+--------------+
|            1 |            2 |
|            2 |            4 |
|            3 |            6 |
+--------------+--------------+

+--------------+--------------+
|       number |   Number X 2 |
+--------------+--------------+
|            2 |            4 |
|            3 |            6 |
|           42 |           84 |
+--------------+--------------+

Returns a previously defined summary table or nil

Returns the table as a formatted string

returns the total actual width of the table as a whole

transpose(opts = {}) returns a Tablo::Table instance

The #transpose method creates a new Tablo::Table from the current table, transposed, i.e. rotated 90 degrees with respect to the current table, so that the header names of the current table form the contents of the leftmost column of the new table, and each subsequent column corresponds to one of the source elements of the current table, the header of that column being the string value of that element.

Example:

require "tablo"
table = Tablo::Table.new([-1, 0, 1]) do |t|
  t.add_column("Even?", &.even?)
  t.add_column("Odd?", &.odd?)
  t.add_column("Abs", &.abs)
end.transpose
puts table

+-------+--------------+--------------+--------------+
|       |      -1      |       0      |       1      |
+-------+--------------+--------------+--------------+
| Even? |     false    |     true     |     false    |
| Odd?  |     true     |     false    |     true     |
| Abs   |            1 |            0 |            1 |
+-------+--------------+--------------+--------------+

By default, the transposed table inherits all the parameters of the current table, with their values, except those appearing in the opts parameter of the #transpose method with a different value.

These parameters apply to all columns, with one notable exception: the first column, the leftmost, is special, as it is created from the column headers (field names) of the current table and therefore has its own width and alignment parameters, namely:

• field_names_header_alignment: default value = nil, i.e. alignment depends on the body data type, in this case, a left-aligned string.
• field_names_body_alignment: default value = nil, i.e. dependent on data type, i.e. a character string, left-aligned
• field_names_width: default value = nil, triggering optimal width calculation based on content

Two other parameters complete the transposed table:

• field_names_header: default value = nil, replaced by an empty character string
• body_headers : default value = nil, which returns the current value of source in each column

All these values can be modified in the opts parameter, according to their data type.

However, body_headers is a special case: if it contains a character string, it will be rendered as such, unless it contains the integer display format %d, which will then be replaced by the original row number.

Modified previous example:

require "tablo"
table = Tablo::Table.new([-1, 0, 1],
 header_alignment: Tablo::Justify::Center,
 body_alignment: Tablo::Justify::Center) do |t|
 t.add_column("Even?", &.even?)
 t.add_column("Odd?", &.odd?)
 t.add_column("Abs", &.abs)
end.transpose(
 field_names_header_alignment: Tablo::Justify::Right,
 field_names_body_alignment: Tablo::Justify::Right,
 field_names_header: "Field names",
 body_headers: "Row #%d content"
)
puts table

+-------+--------------+--------------+--------------+
| Field |    Row #0    |    Row #1    |    Row #2    |
| names |    content   |    content   |    content   |
+-------+--------------+--------------+--------------+
| Even? |     false    |     true     |     false    |
|  Odd? |     true     |     false    |     true     |
|   Abs |       1      |       0      |       1      |
+-------+--------------+--------------+--------------+

Once a table has been defined, the Table#using_column_indexes method is used to select the columns to be displayed by their index in the column registry, and to reorder them if necessary.

Mandatory parameter:

• *indexes : type is Int32 || Tuple{Int32, Int32}
  At least one column (or Tuple) identifier must be given. Column tuples define an interval, selecting all the columns it contains.

Optional named parameter

• reordered : type is Bool, with a default value of false
  If true, allows to reorder the selected columns according to the order in which they appear in the *indexes parameter.

Using the #using_column_indexes method with reordering (reordered=true) temporarily disables the display of group headers.

Examples:

require "tablo"

data = [[-1.14, "Abc", "Hello", 4, 5],
        [42.3, "Xyz", "Halo", 33, 42]]

table = Tablo::Table.new(data) do |t|
  t.add_column(:col1, &.[0])
  t.add_column(:col2, &.[1])
  t.add_group(:group1)
  t.add_column(:col3, &.[2])
  t.add_group(:group2)
  t.add_column(:col4, &.[3])
  t.add_column(:col5, &.[4])
  t.add_group(:group3)
end

Display of the defined table :

puts table
+-----------------------------+--------------+-----------------------------+
|            group1           |    group2    |            group3           |
+--------------+--------------+--------------+--------------+--------------+
|         col1 | col2         | col3         |         col4 |         col5 |
+--------------+--------------+--------------+--------------+--------------+
|        -1.14 | Abc          | Hello        |            4 |            5 |
|         42.3 | Xyz          | Halo         |           33 |           42 |
+--------------+--------------+--------------+--------------+--------------+

Display 3 columns out of 5, without reordering them.
Group headers are kept

puts table.using_column_indexes({1, 2}, 0)
+-----------------------------+--------------+
|            group1           |    group2    |
+--------------+--------------+--------------+
|         col1 | col2         | col3         |
+--------------+--------------+--------------+
|        -1.14 | Abc          | Hello        |
|         42.3 | Xyz          | Halo         |
+--------------+--------------+--------------+

Display 3 columns out of 5, in the order specified in columns parameter.
Group headers are omitted

puts table.using_column_indexes({1, 2}, 0, reordered: true)
+--------------+--------------+--------------+
| col2         | col3         |         col1 |
+--------------+--------------+--------------+
| Abc          | Hello        |        -1.14 |
| Xyz          | Halo         |         42.3 |
+--------------+--------------+--------------+

Once a table has been defined, the Table#using_columns method is used to select the columns to be displayed, and to reorder them if necessary.

Mandatory parameter:

• *columns : type is LabelType || Tuple{LabelType, LabelType}
  At least one column (or Tuple) identifier must be given. Column tuples define an interval, selecting all the columns it contains.

Optional named parameter

• reordered : type is Bool, with a default value of false
  If true, allows to reorder the selected columns according to the order in which they appear in the *columns parameter.

Using the #using_columns method with reordering (reordered=true) temporarily disables the display of group headers.

Examples:

require "tablo"

data = [[-1.14, "Abc", "Hello", 4, 5],
        [42.3, "Xyz", "Halo", 33, 42]]

table = Tablo::Table.new(data) do |t|
  t.add_column(:col1, &.[0])
  t.add_column(:col2, &.[1])
  t.add_group(:group1)
  t.add_column(:col3, &.[2])
  t.add_group(:group2)
  t.add_column(:col4, &.[3])
  t.add_column(:col5, &.[4])
  t.add_group(:group3)
end

Display of the defined table :

puts table
+-----------------------------+--------------+-----------------------------+
|            group1           |    group2    |            group3           |
+--------------+--------------+--------------+--------------+--------------+
|         col1 | col2         | col3         |         col4 |         col5 |
+--------------+--------------+--------------+--------------+--------------+
|        -1.14 | Abc          | Hello        |            4 |            5 |
|         42.3 | Xyz          | Halo         |           33 |           42 |
+--------------+--------------+--------------+--------------+--------------+

Display all columns in reverse order, group headers are omitted.

puts table.using_columns({:col5,:col1}, reordered: true)
+--------------+--------------+--------------+--------------+--------------+
|         col5 |         col4 | col3         | col2         |         col1 |
+--------------+--------------+--------------+--------------+--------------+
|            5 |            4 | Hello        | Abc          |        -1.14 |
|           42 |           33 | Halo         | Xyz          |         42.3 |
+--------------+--------------+--------------+--------------+--------------+