Class: TTY::Table

Inherits:
Object
  • Object
show all
Extended by:
Forwardable
Includes:
Comparable, Enumerable, Conversion, Equatable, Renderer, Validatable
Defined in:
lib/tty/table.rb,
lib/tty/table/error.rb,
lib/tty/table/border.rb,
lib/tty/table/renderer.rb,
lib/tty/table/column_set.rb,
lib/tty/table/border/null.rb,
lib/tty/table/validatable.rb,
lib/tty/table/border/ascii.rb,
lib/tty/table/border/unicode.rb,
lib/tty/table/renderer/ascii.rb,
lib/tty/table/renderer/basic.rb,
lib/tty/table/renderer/color.rb,
lib/tty/table/renderer/unicode.rb,
lib/tty/table/operation/wrapped.rb,
lib/tty/table/operation/alignment.rb,
lib/tty/table/operation/truncation.rb,
lib/tty/table/operation/alignment_set.rb

Defined Under Namespace

Modules: Operation, Renderer, Validatable Classes: Border, ColumnSet, DimensionMismatchError

Constant Summary

Constants included from Validatable

Validatable::MIN_CELL_WIDTH

Constants included from Renderer

Renderer::RENDERER_DELEGATED_METHODS, Renderer::RENDERER_MAPPER

Instance Attribute Summary collapse

Attributes included from Equatable

#comparison_attrs

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Validatable

#assert_matching_widths, #assert_row_sizes, #assert_string_values

Methods included from Equatable

#attr_reader, included, #inherited

Methods included from Renderer

#pick_renderer, #renderer, #renderer=

Methods included from Delegatable

#delegatable_method

Methods included from Conversion

#convert_to_array

Constructor Details

#initialize(options = {}, &block) ⇒ TTY::Table

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Initialize a Table

Parameters:

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

    the options to create the table with

Options Hash (options):

  • :header (String)

    column names to be displayed

  • :rows (String)

    Array of Arrays expressing the rows

  • :renderer (String)

    used to format table output

  • :column_aligns (String)

    used to format table individual column alignment

  • :column_widths (String)

    used to format table individula column width



109
110
111
112
113
114
115
116
117
118
119
120
# File 'lib/tty/table.rb', line 109

def initialize(options={}, &block)
  @header        = options.fetch :header, nil
  @rows          = coerce(options.fetch :rows, [])
  @renderer      = pick_renderer options[:renderer]
  # TODO: assert that row_size is the same as column widths & aligns
  # TODO: this is where column extraction should happen!
  @column_widths = options.fetch :column_widths, []
  @alignments    = Operation::AlignmentSet.new options[:column_aligns] || []

  assert_row_sizes @rows
  yield_or_eval &block if block_given?
end

Instance Attribute Details

#alignmentsOperation::AlignmentSet (readonly)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

The table column alignments



41
42
43
# File 'lib/tty/table.rb', line 41

def alignments
  @alignments
end

#column_widthsArray

The table enforced column widths

Returns:

  • (Array)


34
35
36
# File 'lib/tty/table.rb', line 34

def column_widths
  @column_widths
end

#headerEnumerable (readonly)

The table header

Returns:

  • (Enumerable)


19
20
21
# File 'lib/tty/table.rb', line 19

def header
  @header
end

Class Method Details

.[](*rows) ⇒ Object

Create a new Table where each argument is a row

Examples:

table = TTY::Table.new[['a1', 'a2'], ['b1', 'b2']]


59
60
61
# File 'lib/tty/table.rb', line 59

def self.[](*rows)
  self.new(:rows => rows)
end

.new(*args, &block) ⇒ Object

Instantiate a new Table

Examples:

of no header

rows  = [ ['a1', 'a2'], ['b1', 'b2'] ]
table = Table.new rows

of direct parameters

rows  = [ ['a1', 'a2'], ['b1', 'b2'] ]
table = Table.new ['Header 1', 'Header 2'], rows

of parameters passed as options

rows  = [ ['a1', 'a2'], ['b1', 'b2'] ]
table = Table.new :header => ['Header 1', 'Header 2'], :rows => rows

Parameters:

  • *args (Array[Symbol], Hash)


80
81
82
83
84
85
86
87
88
89
# File 'lib/tty/table.rb', line 80

def self.new(*args, &block)
  options = Utils.extract_options!(args)
  if args.size.nonzero?
    rows = args.pop
    header = args.size.zero? ? nil : args.first
    super({:header => header, :rows => rows}.merge(options), &block)
  else
    super(options, &block)
  end
end

.rendererTTY::Table::Renderer

Determine renderer based on terminal capabilities



11
12
13
14
15
16
17
# File 'lib/tty/table/renderer.rb', line 11

def self.renderer
  @renderer ||= if TTY.terminal.color?
    TTY::Table::Renderer::Color
  else
    TTY::Table::Renderer::Basic
  end
end

.renderer=(klass) ⇒ Object



20
21
22
# File 'lib/tty/table/renderer.rb', line 20

def self.renderer=(klass)
  @renderer = klass
end

Instance Method Details

#<<(row) ⇒ self

Add row to table

Parameters:

  • row (Array)

Returns:

  • (self)


202
203
204
205
206
207
# File 'lib/tty/table.rb', line 202

def <<(row)
  rows_copy = rows.dup
  assert_row_sizes rows_copy << row
  rows << row
  self
end

#[](i, j) ⇒ Object Also known as: at, element, component

Lookup element of the table given a row(i) and column(j)



125
126
127
128
129
130
131
# File 'lib/tty/table.rb', line 125

def [](i, j)
  if i >= 0 && j >= 0
    rows.fetch(i){return nil}[j]
  else
    raise IndexError.new("element at(#{i},#{j}) not found")
  end
end

#[]=(i, j, val) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Set table value at row(i) and column(j)



139
140
141
# File 'lib/tty/table.rb', line 139

def []=(i, j, val)
  @rows[i][j] = val
end

#coerce(rows) ⇒ Array

Coerce an Enumerable into a Table This coercion mechanism is used by Table to handle Enumerable types and force them into array type.

Parameters:

  • object (Enumerable)

    the object to coerce

Returns:

  • (Array)


303
304
305
# File 'lib/tty/table.rb', line 303

def coerce(rows)
  convert_to_array(rows)
end

#column(index) { ... } ⇒ self

Return a column number at the index of the table as an Array. When a block is given, the elements of that Array are iterated over.

Examples:

rows  = [ ['a1', 'a2'], ['b1', 'b2'] ]
table = TTY::Table.new :rows => rows
table.column(1) { |element| ... }

Parameters:

  • index (Integer)

Yields:

  • optional block to execute in the iteration operation

Returns:

  • (self)


185
186
187
188
189
190
191
192
193
# File 'lib/tty/table.rb', line 185

def column(index)
  if block_given?
    return self if index >= column_size || index < 0
    rows.map { |row| yield row[index].compact }
  else
    return nil if index >= column_size || index < 0
    rows.map { |row| row[index] }.compact
  end
end

#column_sizeInteger

Return the number of columns

Examples:

table.column_size # => 5

Returns:

  • (Integer)


236
237
238
239
# File 'lib/tty/table.rb', line 236

def column_size
  return rows[0].size if (rows.size > 0)
  return 0
end

#directionObject

The table orientation



49
50
51
# File 'lib/tty/table.rb', line 49

def direction
  # TODO implement table orientation
end

#each {|Array[Array]| ... } ⇒ self

Iterate over each tuple in the set

Examples:

table = TTY::Table.new(header, tuples)
table.each { |row| ... }

Yields:

  • (Array[Array])

Returns:

  • (self)


220
221
222
223
224
225
226
# File 'lib/tty/table.rb', line 220

def each
  return to_enum unless block_given?
  rows.each do |row|
    yield row
  end
  self
end

#empty?Boolean

Return true if this is an empty table, i.e. if the number of rows or the number of columns is 0

Returns:

  • (Boolean)


280
281
282
# File 'lib/tty/table.rb', line 280

def empty?
  column_size == 0 || row_size == 0
end

#row(index) { ... } ⇒ self

Return a row number at the index of the table as an Array. When a block is given, the elements of that Array are iterated over.

Examples:

rows  = [ ['a1', 'a2'], ['b1', 'b2'] ]
table = TTY::Table.new :rows => rows
table.row(1) { |element| ... }

Parameters:

  • index (Integer)

Yields:

  • optional block to execute in the iteration operation

Returns:

  • (self)


160
161
162
163
164
165
166
167
# File 'lib/tty/table.rb', line 160

def row(index, &block)
  if block_given?
    rows.fetch(index){return self}.each(&block)
    self
  else
    rows.fetch(index){return nil}
  end
end

#row_sizeInteger

Return the number of rows

Examples:

table.row_size # => 5

Returns:

  • (Integer)


249
250
251
# File 'lib/tty/table.rb', line 249

def row_size
  rows.size
end

#sizeArray

Return the number of rows and columns

Examples:

table.size # => [3,5]

Returns:

  • (Array)

    row x columns



261
262
263
# File 'lib/tty/table.rb', line 261

def size
  [row_size, column_size]
end

#to_sString

Return string representation of table

Returns:

  • (String)


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

def to_s
  render(self)
end

#widthInteger

Check table width

Returns:

  • (Integer)

    width



270
271
272
# File 'lib/tty/table.rb', line 270

def width
  ColumnSet.new(self).extract_widths!.total_width
end