Class: Tabulo::Table

Inherits:
Object
  • Object
show all
Includes:
Enumerable
Defined in:
lib/tabulo/table.rb

Overview

Represents a table primarily intended for "pretty-printing" in a fixed-width font.

A Table is also an Enumerable, of which each element is a Row.

Constant Summary collapse

DEFAULT_BORDER = 
:ascii
DEFAULT_COLUMN_WIDTH = 
12
DEFAULT_COLUMN_PADDING = 
1
DEFAULT_TRUNCATION_INDICATOR = 
"~"

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(sources, *columns, column_width: nil, column_padding: nil, header_frequency: :start, wrap_header_cells_to: nil, wrap_body_cells_to: nil, truncation_indicator: nil, align_header: :center, align_body: :auto, border: nil, border_styler: nil) {|_self| ... } ⇒ Table

Returns a new Tabulo::Table.

Parameters:

  • sources (Enumerable) —

    the underlying Enumerable from which the table will derive its data

  • columns (Array[Symbol]) —

    Specifies the initial columns. The Symbols provided must be unique. Each element of the Array will be used to create a column whose content is created by calling the corresponding method on each element of sources. Note the #add_column method is a much more flexible way to set up columns on the table.

  • column_width (Integer, nil) (defaults to: nil) —

    The default column width for columns in this table, not excluding padding. If nil, then DEFAULT_COLUMN_WIDTH will be used.

  • header_frequency (:start, nil, Integer) (defaults to: :start) —

    Controls the display of column headers. If passed :start, headers will be shown at the top of the table only. If passed nil, headers will not be shown. If passed an Integer N (> 0), headers will be shown at the top of the table, then repeated every N rows.

  • wrap_header_cells_to (nil, Integer) (defaults to: nil) —

    Controls wrapping behaviour for header cells if the content thereof is longer than the column's fixed width. If passed nil (default), content will be wrapped for as many rows as required to accommodate it. If passed an Integer N (> 0), content will be wrapped up to N rows and then truncated thereafter.

  • wrap_body_cells_to (nil, Integer) (defaults to: nil) —

    Controls wrapping behaviour for table cells (excluding headers), if their content is longer than the column's fixed width. If passed nil, content will be wrapped for as many rows as required to accommodate it. If passed an Integer N (> 0), content will be wrapped up to N rows and then truncated thereafter. headers), if their content is longer than the column's fixed width. If passed nil, content will be wrapped for as many rows as required to accommodate it. If passed an Integer N (> 0), content will be wrapped up to N rows and then truncated thereafter.

  • truncation_indicator (nil, String) (defaults to: nil) —

    Determines the character used to indicate that a cell's content has been truncated. If omitted or passed nil, defaults to DEFAULT_TRUNCATION_INDICATOR. If passed something other than nil or a single-character String, raises InvalidTruncationIndicatorError.

  • column_padding (nil, Integer, Array) (defaults to: nil) —

    (1) Determines the amount of blank space with which to pad either side of each column. If passed an Integer, then the given amount of padding is applied to each side of each column. If passed a two-element Array, then the first element of the Array indicates the amount of padding to apply to the left of each column, and the second element indicates the amount to apply to the right.

  • align_header (:left, :right, :center) (defaults to: :center) —

    (:center) Determines the alignment of header text for columns in this Table. Can be overridden for individual columns using the align_header option passed to #add_column

  • align_body (:left, :right, :center, :auto) (defaults to: :auto) —

    (:auto) Determines the alignment of body cell (i.e. non-header) content within columns in this Table. Can be overridden for individual columns using the align_body option passed to #add_column. If passed :auto, alignment is determined by cell content, with numbers aligned right, booleans center-aligned, and other values left-aligned.

  • border (:ascii, :markdown, :modern, :blank, nil) (defaults to: nil) —

    (nil) Determines the characters used for the Table border, including both the characters around the outside of table, and the lines drawn within the table to separate columns from each other and the header row from the Table body. If nil, then the value of DEFAULT_BORDER will be used. Possible values are:

    • :ascii Uses ASCII characters only
    • :markdown Produces a GitHub-flavoured Markdown table
    • :modern Uses non-ASCII Unicode characters to render a border with smooth continuous lines
    • :blank No border characters are rendered
    • :classic Like :ascii, but does not have a horizontal line at the bottom of the table. This reproduces the default behaviour in tabulo v1.
  • border_styler (nil, #to_proc) (defaults to: nil) —

    (nil) A lambda or other callable object taking a single parameter, representing a section of the table's borders (which for this purpose include any horizontal and vertical lines inside the table), and returning a string. If passed nil, then no additional styling will be applied to borders. If passed a callable, then that callable will be called for each border section, with the resulting string rendered in place of that border. The extra width of the string returned by the border_styler is not taken into consideration by the internal table rendering calculations Thus it can be used to apply ANSI escape codes to border characters, to colour the borders for example, without breaking the table formatting.

Yields:

  • (_self)

Yield Parameters:

  • _self (Tabulo::Table) —

    the object that the method was called on

Raises:


95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
 
# File 'lib/tabulo/table.rb', line 95

def initialize(sources, *columns, column_width: nil, column_padding: nil, header_frequency: :start,
  wrap_header_cells_to: nil, wrap_body_cells_to: nil, truncation_indicator: nil, align_header: :center,
  align_body: :auto, border: nil, border_styler: nil)

  @sources = sources
  @header_frequency = header_frequency
  @wrap_header_cells_to = wrap_header_cells_to
  @wrap_body_cells_to = wrap_body_cells_to
  @default_column_width = (column_width || DEFAULT_COLUMN_WIDTH)
  @align_header = align_header
  @align_body = align_body

  @column_padding = (column_padding || DEFAULT_COLUMN_PADDING)
  @left_column_padding, @right_column_padding =
    case @column_padding
    when Array
      @column_padding
    else
      [@column_padding, @column_padding]
    end

  @border = (border || DEFAULT_BORDER)
  @border_styler = border_styler
  @border_instance = Border.from(@border, @border_styler)

  @truncation_indicator = validate_character(truncation_indicator,
    DEFAULT_TRUNCATION_INDICATOR, InvalidTruncationIndicatorError, "truncation indicator")

  @column_registry = { }
  columns.each { |item| add_column(item) }

  yield self if block_given?
end

Instance Attribute Details

#sources ⇒ Enumerable

Returns the underlying enumerable from which the table derives its data.

Returns:

  • (Enumerable) —

    the underlying enumerable from which the table derives its data


31
32
33
 
# File 'lib/tabulo/table.rb', line 31

def sources
  @sources
end

Instance Method Details

#add_column(label, header: nil, align_header: nil, align_body: nil, width: nil, formatter: :to_s.to_proc, styler: nil, header_styler: nil, &extractor) ⇒ Object

Adds a column to the Table.

Parameters:

  • label (Symbol, String, Integer) —

    A unique identifier for this column, which by default will also be used as the column header text (see also the header param). If the extractor argument is not also provided, then the label argument should correspond to a method to be called on each item in the table sources to provide the content for this column. If a String is passed as the label, then it will be converted to a Symbol for the purpose of serving as this label.

  • header (nil, #to_s) (defaults to: nil) —

    (nil) Text to be displayed in the column header. If passed nil, the column's label will also be used as its header text.

  • align_header (:left, :center, :right, nil) (defaults to: nil) —

    (nil) Specifies how the header text should be aligned. If nil is passed, then the alignment is determined by the Table-level setting passed to the align_header (which itself defaults to :center). Otherwise, this option determines the alignment of the header content for this column.

  • align_body (:left, :center, :right, :auto, nil) (defaults to: nil) —

    (nil) Specifies how the cell body contents should be aligned. If nil is passed, then the alignment is determined by the Table-level setting passed to the align_body option on Table initialization (which itself defaults to :auto). Otherwise this option determines the alignment of this column. If :auto is passed, the alignment is determined by the type of the cell value, with numbers aligned right, booleans center-aligned, and other values left-aligned. Note header text alignment is configured separately using the :align_header param.

  • width (Integer) (defaults to: nil) —

    (nil) Specifies the width of the column, excluding padding. If nil, then the column will take the width provided by the column_width param with which the Table was initialized.

  • formatter (#to_proc) (defaults to: :to_s.to_proc) —

    (:to_s.to_proc) A lambda or other callable object that will be passed the calculated value of each cell to determine how it should be displayed. This is distinct from the extractor (see below). For example, if the extractor for this column generates a Date, then the formatter might format that Date in a particular way. If no formatter is provided, then .to_s will be called on the extracted value of each cell to determine its displayed content.

  • styler (nil, #to_proc) (defaults to: nil) —

    (nil) A lambda or other callable object that will be passed two arguments: the calculated value of the cell (prior to the formatter being applied); and a string representing a single formatted line within the cell. For example, if the cell content is wrapped over three lines, then for that cell, the styler will be called three times, once for each line of content within the cell. If passed nil, then no additional styling will be applied to the cell content (other than what was already applied by the formatter). If passed a callable, then that callable will be called for each line of content within the cell, and the resulting string rendered in place of that line. The styler option differs from the formatter option in that the extra width of the string returned by styler is not taken into consideration by the internal table and cell width calculations involved in rendering the table. Thus it can be used to apply ANSI escape codes to cell content, to colour the cell content for example, without breaking the table formatting. Note that if the content of a cell is truncated, then the whatever styling is applied by the styler to the cell content will also be applied to the truncation indicator character.

  • header_styler (nil, #to_proc) (defaults to: nil) —

    (nil) A lambda or other callable object taking a single parameter, representing a single line of within the header content for this column. For example, if the header cell content is wrapped over three lines, then the header_styler will be called once for each line. If passed nil, then no additional styling will be applied to the header cell content. If passed a callable, then that callable will be called for each line of content within the header cell, and the resulting string rendered in place of that line. The extra width of the string returned by the header_styler is not taken into consideration by the internal table and cell width calculations involved in rendering the table. Thus it can be used to apply ANSI escape codes to header cell content, to colour the cell content for example, without breaking the table formatting. Note that if the header content is truncated, then any header_styler will be applied to the truncation indicator character as well as to the truncated content.

  • extractor (#to_proc) —

    A block or other callable that will be passed each of the Table sources to determine the value in each cell of this column. If this is not provided, then the column label will be treated as a method to be called on each source item to determine each cell's value.

Raises:

  • (InvalidColumnLabelError) —

    if label has already been used for another column in this Table. (This is case-sensitive, but is insensitive to whether a String or Symbol is passed to the label parameter.)


195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
 
# File 'lib/tabulo/table.rb', line 195

def add_column(label, header: nil, align_header: nil, align_body: nil,
  width: nil, formatter: :to_s.to_proc, styler: nil, header_styler: nil, &extractor)

  column_label =
    case label
    when Integer, Symbol
      label
    when String
      label.to_sym
    end

  if column_registry.include?(column_label)
    raise InvalidColumnLabelError, "Column label already used in this table."
  end

  @column_registry[column_label] =
    Column.new(
      header: (header || label).to_s,
      align_header: align_header || @align_header,
      align_body: align_body || @align_body,
      width: (width || @default_column_width),
      formatter: formatter,
      extractor: (extractor || label.to_proc),
      styler: styler,
      header_styler: header_styler,
      truncation_indicator: @truncation_indicator,
      padding_character: PADDING_CHARACTER,
    )
end

#each ⇒ Object

Calls the given block once for each Row in the Table, passing that Row as parameter.

Note that when printed, the first row will visually include the headers (assuming these were not disabled when the Table was initialized).

Examples:

table.each do |row|
  puts row
end

246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
 
# File 'lib/tabulo/table.rb', line 246

def each
  @sources.each_with_index do |source, index|
    header =
      case @header_frequency
      when :start
        :top if index == 0
      when Integer
        if index == 0
          :top
        elsif index % @header_frequency == 0
          :middle
        end
      else
        @header_frequency
      end
    yield body_row(source, header: header)
  end
end

#formatted_header ⇒ String

Returns an "ASCII" graphical representation of the Table column headers.

Returns:

  • (String) —

    an "ASCII" graphical representation of the Table column headers.


266
267
268
269
 
# File 'lib/tabulo/table.rb', line 266

def formatted_header
  cells = column_registry.map { |_, column| column.header_cell }
  format_row(cells, @wrap_header_cells_to)
end

#horizontal_rule(position = :bottom) ⇒ String

It may be that :top, :middle and :bottom all look the same. Whether this is the case depends on the characters used for the table border.

Examples:

Print a horizontal divider between each pair of rows, and again

at the bottom:

table.each_with_index do |row, i|
  puts table.horizontal_rule(:middle) unless i == 0
  puts row
end
puts table.horizontal_rule(:bottom)

Parameters:

  • align_body (:top, :middle, :bottom) —

    (:bottom) Specifies the position for which the resulting horizontal dividing line is intended to be printed. This determines the border characters that are used to construct the line.

Returns:

  • (String) —

    an "ASCII" graphical representation of a horizontal dividing line suitable for printing at the top, bottom or middle of the table.


288
289
290
291
 
# File 'lib/tabulo/table.rb', line 288

def horizontal_rule(position = :bottom)
  column_widths = column_registry.map { |_, column| column.width + total_column_padding }
  @border_instance.horizontal_rule(column_widths, position)
end

#pack(max_table_width: :auto) ⇒ Table

Reset all the column widths so that each column is just wide enough to accommodate its header text as well as the formatted content of each its cells for the entire collection, together with a single character of padding on either side of the column, without any wrapping.

Note that calling this method will cause the entire source Enumerable to be traversed and all the column extractors and formatters to be applied in order to calculate the required widths.

Note also that this method causes column widths to be fixed as appropriate to the formatted cell contents given the state of the source Enumerable at the point it is called. If the source Enumerable changes between that point, and the point when the Table is printed, then columns will not be resized yet again on printing.

Parameters:

  • max_table_width (nil, Numeric) (defaults to: :auto) —

    (:auto) With no args, or if passed :auto, stops the total table width (including padding and borders) from expanding beyond the bounds of the terminal screen. If passed nil, the table width will not be capped. Width is deducted from columns if required to achieve this, with one character progressively deducted from the width of the widest column until the target is reached. When the table is printed, wrapping or truncation will then occur in these columns as required (depending on how they were configured). Note that regardless of the value passed to max_table_width, the table will always be left wide enough to accommodate at least 1 character's width of content, 1 character of left padding and 1 character of right padding in each column, together with border characters (1 on each side of the table and 1 between adjacent columns). I.e. there is a certain width below width the Table will refuse to shrink itself.

Returns:

  • (Table) —

    the Table itself


321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
 
# File 'lib/tabulo/table.rb', line 321

def pack(max_table_width: :auto)
  return self if column_registry.none?
  columns = column_registry.values

  columns.each { |column| column.width = wrapped_width(column.header) }

  @sources.each do |source|
    columns.each do |column|
      width = wrapped_width(column.body_cell(source).formatted_content)
      column.width = width if width > column.width
    end
  end

  if max_table_width
    max_table_width = TTY::Screen.width if max_table_width == :auto
    shrink_to(max_table_width)
  end

  self
end

#to_s ⇒ String

Returns a graphical "ASCII" representation of the Table, suitable for display in a fixed-width font.

Returns:

  • (String) —

    a graphical "ASCII" representation of the Table, suitable for display in a fixed-width font.


227
228
229
230
231
232
233
234
235
 
# File 'lib/tabulo/table.rb', line 227

def to_s
  if column_registry.any?
    bottom_edge = horizontal_rule(:bottom)
    rows = map(&:to_s)
    bottom_edge.empty? ? join_lines(rows) : join_lines(rows + [bottom_edge])
  else
    ""
  end
end

#transpose(opts = {}) ⇒ Table

Creates a new Tabulo::Table from the current Table, transposed, that is rotated 90 degrees, relative to the current Table, so that the header names of the current Table form the content of left-most column of the new Table, and each column thereafter corresponds to one of the elements of the current Table's sources, with the header of that column being the String value of that element.

Examples:

puts Tabulo::Table.new(-1..1, :even?, :odd?, :abs).transpose
  # => +-------+--------------+--------------+--------------+
  #    |       |      -1      |       0      |       1      |
  #    +-------+--------------+--------------+--------------+
  #    | even? |     false    |     true     |     false    |
  #    |  odd? |     true     |     false    |     true     |
  #    |   abs |            1 |            0 |            1 |

Parameters:

  • opts (Hash) (defaults to: {}) —

    Options for configuring the new, transposed Tabulo::Table. The following options are the same as the keyword params for the #initialize method for Tabulo::Table: column_width, column_padding, header_frequency, wrap_header_cells_to, wrap_body_cells_to, border, border_styler, truncation_indicator, align_header, align_body. These are applied in the same way as documented for #initialize, when creating the new, transposed Table. Any options not specified explicitly in the call to #transpose will inherit their values from the original Tabulo::Table (with the exception of settings for the left-most column, containing the field names, which are determined as described below). In addition, the following options also apply to #transpose:

Options Hash (opts):

  • :field_names_width (nil, Integer) —

    Determines the width of the left-most column of the new Table, which contains the names of "fields" (corresponding to the original Table's column headings). If this is not provided, then by default this column will be made just wide enough to accommodate its contents.

  • :field_names_header (String) — default: "" —

    By default the left-most column will have a blank header; but this can be overridden by passing a String to this option.

  • :field_names_header_alignment (:left, :center, :right) — default: :right —

    Specifies how the header text of the left-most column (if it has header text) should be aligned.

  • :field_names_body_alignment (:left, :center, :right) — default: :right —

    Specifies how the body text of the left-most column should be aligned.

  • :headers (#to_proc) — default: :to_s.to_proc —

    A lambda or other callable object that will be passed in turn each of the elements of the current Table's sources Enumerable, to determine the text to be displayed in the header of each column of the new Table (other than the left-most column's header, which is determined as described above).

Returns:

Raises:


384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
 
# File 'lib/tabulo/table.rb', line 384

def transpose(opts = {})
  default_opts = [:column_width, :column_padding, :header_frequency, :wrap_header_cells_to,
    :wrap_body_cells_to, :truncation_indicator, :align_header, :align_body, :border,
    :border_styler].map do |sym|
    [sym, instance_variable_get("@#{sym}")]
  end.to_h

  initializer_opts = default_opts.merge(Util.slice_hash(opts, *default_opts.keys))
  default_extra_opts = { field_names_width: nil, field_names_header: "",
    field_names_body_alignment: :right, field_names_header_alignment: :right, headers: :to_s.to_proc }
  extra_opts = default_extra_opts.merge(Util.slice_hash(opts, *default_extra_opts.keys))

  # The underlying enumerable for the new table, is the columns of the original table.
  fields = column_registry.values

  Table.new(fields, **initializer_opts) do |t|

    # Left hand column of new table, containing field names
    width_opt = extra_opts[:field_names_width]
    field_names_width = (width_opt.nil? ? fields.map { |f| f.header.length }.max : width_opt)

    t.add_column(:dummy, header: extra_opts[:field_names_header], width: field_names_width, align_header:
      extra_opts[:field_names_header_alignment], align_body: extra_opts[:field_names_body_alignment], &:header)

    # Add a column to the new table for each of the original table's sources
    sources.each_with_index do |source, i|
      t.add_column(i, header: extra_opts[:headers].call(source)) do |original_column|
        original_column.body_cell_value(source)
      end
    end
  end
end