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

Without a block :

tbl = Tablo::Table.new(...)
tbl.add_column(...)
tbl.add_column(...)

With a block

tbl = Tablo::Table.new(...) do |t|
  t.add_column(...)
  t.add_column(...)
end

Mandatory parameter:

• sources is the only (positional) mandatory parameter. Its type is Enumerable(T), where T is any (union) type. Any Enumerable is accepted (Array, Hash, etc.)(*). For example, [1, 3.14, "ABC"] or {"A" => [1,2], "B" => [3,4]} or [{"A" => [1,2]}, {"B" => [3,4]}] are valid sources.

(*) Presently (Crystal 1.8.2+), a compiler bug prevents the use of the Range type. Use to_a to convert to an array first. See Crystal issue 10518

Optional named parameters:

All parameters below are optional and have commonly used defaults.

• Headings attributes

  • title, subtitle and footer are optional parts of the table layout and their type is Tablo::Heading. Their default value is nil (no display)

• Group attributes : these are default attributes applied to every group header, unless specific values are set at the group level (in the #add_group method)

  • group_alignment : text justification, of type Tablo::Justify (default :center)
  • group_formatter : a Proc to apply some formatting to the value of the cell (see TextCellFormatter
  • group_styler : a Proc to apply some style (color) to the formatted cell contents (see TextCellStyler

• Column header attributes : same logic as for groups

  • header_alignment : default value is nil, meaning alignment is determined by the body cell value running type (numbers are right aligned, booleans are centered, others are left aligned)
  • header_formatter : Tablo::DataCellFormatter
  • header_styler : Tablo::DataCellStyler

• Body:

  • body_alignment: set alignment for all body cells, default to nil (see column header)
  • body_formatter : Tablo::DataCellFormatter
  • body_styler: : Tablo::DataCellStyler

• Border:

  • border_type: define table border. Type is BorderName | String, default to BorderName::Ascii
  • border_styler: Proc to style (colorize) border, type is Tablo::BorderStyler, default : do nothing

• Miscellaneaous:

  • left_padding: an Int32, default to 1
  • right_padding: an Int32, default to 1
  • padding_character: a String, default to " " (a space)
  • width: an Int32, default to 12
  • truncation_indicator: A string appended at end of cell content to indicate truncation, default value : "~"
  • header_frequency: an Int32 or nil
    • nil : no headers at all
    • n == 0 : Headers (including title,...) are automatically displayed before the first row (default)
    • n > 0 : Headers are repeated every n rows
  • row_divider_frequency : nil or a positive Int32 n, for inclusion of a row divider rule between body lines every n rows
  • wrap_mode: mode of cutting content to fit into cell width (type Tablo::WrapMode)
    • Rune : cut line between graphemes
    • Word : cut line between words (default)
  • header_wrap: nil or a positive Int32 to set the maximum number of lines a header cell may contains (defaults to nil : no limit)
  • body_wrap: same as above, for body (raise an Tablo::InvalidValue exception if zero or negative values are given to body_wrap or header_wrap)
  • masked_headers : bool = false. keep all headers from being displayed
  • omit_last_rule : bool = false. If true, the last closing rule of table is not displayed. This is useful for custom rendering (and notably for table linking)

return value: An instance of class Table

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

class property to manage transition between successive rows issued from data source

class property to manage transition between successive rows issued from data source

Class properties to manage row types framing and summary table linking for summary table

Class property to manage transition betwen :main and :summary tables

Class properties to manage row types framing and summary table linking for summary table

Class property to manage transition betwen :main and :summary tables

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

Adds a column to the table

Parameters:

• label is the only (positional) mandatory parameter, of type LabelType

• A block (&extractor) must be provided to the method call to extract the cell raw data from the source. Extractor type is Proc(T, Int32, CellType).

All other are optional named parameters, and have default values taken from Table parameters, except header which defaults to label

Returns an instance of class Column(T)

Adds a group to the table

A group is the set of the last defined columns not attached to a group yet.

Parameters:

• label is the only (positional) mandatory parameter, of type LabelType

All other are optional named parameters, and have default values taken from Table parameters, except header which defaults to label

Returns an instance of class TextCell

Produce a horizontal dividing line suitable for printing at the top, bottom or middle of the table, or before or after the table title, if any.

This method is also suitable to customize output of a table, for example, to list a table with an horizontal rule between rows, as in :

table.each_with_index do |row, i|
  puts table.horizontal_rule(Tablo::Position::Middle) unless i == 0
  puts row
end
puts table.horizontal_rule(Tablo::Position::Bottom)

The method calculates an array of column widths (including padding), passing it to the Border.horizontal_rule method.

• position indicates the type of horizontal rule expected

• Returns a String representing the formatted horizontal rule

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

• width: 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, only starting_widths == AutoSized has an effect.

• starting_widths : column widths taken as starting point for resizing, possible values are :

  • Current : resizing starts from columns current width
  • Initial : current values are reset to their initial values, at column definition time
  • AutoSized : current values are set to their 'best fit' values, ie they are automatically adapted to their largest content

• except: column or array of columns excluded from being resized, identified by their label

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.

returns the Table itself

Changes the sources data used by the table

• reset the summary table to nil
• returns the new sources

Table parameters

The summary method, with two parameters, is used to define a new SummaryTable by applying user-defined functions to the numerical values of columns, such as Sum or Average functions.

parameters:

• summary_def, of type Hash(LabelType, NamedTuple) allows you to define column content and formatting.

Permitted NamedTuple keys and value types are :

• body_alignment: Justify
• header_alignment: Justify
• header: String
• body_formatter: DataCellFormatter
• header_formatter: DataCellFormatter
• body_styler: DataCellStyler
• header_styler: DataCellStyler
  and
• any (unique) key: SummaryNumCol or SummaryNumCols

for example:

{
  "A" => {
    header:           "Sum",
    header_formatter: ->(c : Tablo::CellType) { c.to_s.downcase },
    body_styler:      ->(c : Tablo::CellType, s : String) { s.colorize(:yellow).to_s },
    proc:             ->(ary : Tablo::NumCol) { ary.sum.to_i },
  },
  "B" => {
    header: "Sum/Avg",
    proc1:  ->(ary : Tablo::NumCol) { ary.sum.to_i },
    proc2:  ->(ary : Tablo::NumCols) { ary["B"].size > 0 ? (ary["B"].sum/ary["B"].size).to_s : "NA" },
  },
}

• summary_options , of type Hash(LabelType, NamedTuple) allows you to redefine table initialization parameters. By default, the current parameters of the main table are used.

Parameters             | Default values
-----------------------+------------------------------
title                  | default Table value
subtitle               |       idem
footer                 |       idem
footer                 |       idem

Returns the summary table

Returns a previously defined summary table

returns the total actual width of the table as a whole

TODO : to be renamed to 'width' ??? but wait for global refactoring and renaming