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_COLUMN_WIDTH = 
12
HORIZONTAL_RULE_CHARACTER = 
"-"
CORNER_CHARACTER = 
"+"

Instance Method Summary collapse

Constructor Details

#initialize(sources, options = { }) {|_self| ... } ⇒ Table

Returns a new Table.

Parameters:

  • sources (Enumerable) —

    the underlying Enumerable from which the table will derive its data

  • options (Hash) (defaults to: { })

Options Hash (options):

  • :columns (Array[Symbol]) — default: [] —

    Specifies the initial columns. 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 (Fixnum, nil) — default: 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, Fixnum) — default: :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 a Fixnum N (> 0), headers will be shown at the top of the table, then repeated every N rows.

  • :wrap_header_cells_to (nil, Fixnum) — default: 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 a Fixnum N (> 0), content will be wrapped up to N rows and then truncated thereafter.

  • :wrap_body_cells_to (nil, Fixnum) — default: 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 a Fixnum N (> 0), content will be wrapped up to N rows and then truncated thereafter.

Yields:

  • (_self)

Yield Parameters:

  • _self (Tabulo::Table) —

    the object that the method was called on



39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
 
# File 'lib/tabulo/table.rb', line 39

def initialize(sources, options = { })
  opts = {
    columns: [],
    column_width: DEFAULT_COLUMN_WIDTH,
    header_frequency: :start,

    # nil to wrap to no max, 1 to wrap to 1 row then truncate, etc..
    wrap_header_cells_to: nil,
    wrap_body_cells_to: nil

  }.merge(options)

  @header_frequency = opts[:header_frequency]
  @wrap_header_cells_to = opts[:wrap_header_cells_to]
  @wrap_body_cells_to = opts[:wrap_body_cells_to]
  @sources = sources
  @joiner = "|"
  @truncation_indicator = "~"
  @padding_character = " "
  @default_column_width = opts[:column_width] || DEFAULT_COLUMN_WIDTH
  @columns = opts[:columns].map { |item| make_column(item) }
  yield self if block_given?
end

Instance Method Details

#add_column(label, options = { }, &extractor) ⇒ Object

Adds a column to the Table.

Parameters:

  • label (Symbol, String) —

    A unique identifier for this column, which by default will also be used as the column header text (see also the header option). 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.

  • options (Hash) (defaults to: { })
  • 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.

Options Hash (options):

  • :header (String) —

    Text to be displayed in the column header. By default the column label will also be used as its header text.

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

    Specifies how the header text should be aligned.

  • :align_body (:left, :center, :right, nil) — default: nil —

    Specifies how the cell body contents should be aligned. Possible If nil is passed, then 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 option.

  • :width (Fixnum) — default: nil —

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

  • :formatter (#to_proc) — default: :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.



95
96
97
 
# File 'lib/tabulo/table.rb', line 95

def add_column(label, options = { }, &extractor)
  @columns << make_column(label, options.merge(extractor: extractor))
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



118
119
120
121
122
123
124
125
126
127
128
129
130
131
 
# File 'lib/tabulo/table.rb', line 118

def each
  @sources.each_with_index do |source, index|
    include_header =
      case @header_frequency
      when :start
        index == 0
      when Fixnum
        index % @header_frequency == 0
      else
        @header_frequency
      end
    yield body_row(source, with_header: include_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.



134
135
136
 
# File 'lib/tabulo/table.rb', line 134

def formatted_header
  format_row(true, &:header_cell)
end

#horizontal_rule ⇒ String

Returns an “ASCII” graphical representation of a horizontal dividing line suitable for printing at any point in the table.

Examples:

Print a horizontal divider after every row:

table.each do |row|
  puts row
  puts table.horizontal_rule
end

Returns:

  • (String) —

    an “ASCII” graphical representation of a horizontal dividing line suitable for printing at any point in the table.



147
148
149
 
# File 'lib/tabulo/table.rb', line 147

def horizontal_rule
  format_row(false, HORIZONTAL_RULE_CHARACTER, CORNER_CHARACTER, &:horizontal_rule)
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.



101
102
103
104
105
106
107
 
# File 'lib/tabulo/table.rb', line 101

def to_s
  if @columns.any?
    join_lines(map(&:to_s))
  else
    ""
  end
end