Class: TTY::Table

Inherits:
Object
  • Object
show all
Extended by:
Forwardable
Includes:
Comparable, Enumerable, Equatable, Validatable
Defined in:
lib/tty/table.rb,
lib/tty/table/row.rb,
lib/tty/table/error.rb,
lib/tty/table/field.rb,
lib/tty/table/border.rb,
lib/tty/table/header.rb,
lib/tty/table/padder.rb,
lib/tty/table/columns.rb,
lib/tty/table/renderer.rb,
lib/tty/table/border_dsl.rb,
lib/tty/table/column_set.rb,
lib/tty/table/operations.rb,
lib/tty/table/border/null.rb,
lib/tty/table/indentation.rb,
lib/tty/table/orientation.rb,
lib/tty/table/validatable.rb,
lib/tty/table/border/ascii.rb,
lib/tty/table/border/unicode.rb,
lib/tty/table/border_options.rb,
lib/tty/table/renderer/ascii.rb,
lib/tty/table/renderer/basic.rb,
lib/tty/table/renderer/color.rb,
lib/tty/table/transformation.rb,
lib/tty/table/border/row_line.rb,
lib/tty/table/operation/escape.rb,
lib/tty/table/operation/filter.rb,
lib/tty/table/renderer/unicode.rb,
lib/tty/table/operation/padding.rb,
lib/tty/table/operation/wrapped.rb,
lib/tty/table/operation/alignment.rb,
lib/tty/table/operation/truncation.rb,
lib/tty/table/orientation/vertical.rb,
lib/tty/table/orientation/horizontal.rb,
lib/tty/table/operation/alignment_set.rb

Overview

A core class intended for storing data in a structured, tabular form. Once the data is stored in a TTY::Table various operations can be performed before the information is dumped into a stdout.

Defined Under Namespace

Modules: Operation, Validatable Classes: Border, BorderDSL, BorderOptions, ColumnSet, Columns, DimensionMismatchError, Field, Header, Indentation, Operations, Orientation, Padder, Renderer, Row, Transformation, TupleMissing

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Validatable

#assert_row_sizes, #assert_table_type, #validate_options!

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:

  • (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

  • :orientation (Symbol) —

    used to transform table orientation

API:

  • private



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

def initialize(options = {}, &block)
  validate_options! options
  @converter     = Necromancer.new
  @header        = (value = options[:header]) ? Header.new(value) : nil
  @rows          = coerce(options.fetch(:rows) { Row.new([]) })
  @rotated       = false
  self.orientation = options.fetch(:orientation) { :horizontal }

  assert_row_sizes @rows
  orientation.transform(self)

  yield_or_eval(&block) if block_given?
end

Instance Attribute Details

#header ⇒ Enumerable (readonly)

The table header

Returns:

API:

  • public



23
24
25
 
# File 'lib/tty/table.rb', line 23

def header
  @header
end

#orientation ⇒ Object

The table orientation out of :horizontal and :vertical

API:

  • public



38
39
40
 
# File 'lib/tty/table.rb', line 38

def orientation
  @orientation
end

#original_columns ⇒ Object (readonly)

The table original column count

API:

  • public



52
53
54
 
# File 'lib/tty/table.rb', line 52

def original_columns
  @original_columns
end

#original_rows ⇒ Object (readonly)

The table original row count

API:

  • public



45
46
47
 
# File 'lib/tty/table.rb', line 45

def original_rows
  @original_rows
end

#rows ⇒ Enumerable (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 rows

Returns:

API:

  • private



30
31
32
 
# File 'lib/tty/table.rb', line 30

def rows
  @rows
end

Class Method Details

.[](*rows) ⇒ Object

Create a new Table where each argument is a row

Examples:

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

API:

  • public



64
65
66
 
# File 'lib/tty/table.rb', line 64

def self.[](*rows)
  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

of parameters passed as hash

Table.new [ {'Header1' => ['a1','a2'], 'Header2' => ['b1', 'b2'] }] }

Parameters:

API:

  • public



88
89
90
91
92
93
94
95
 
# File 'lib/tty/table.rb', line 88

def self.new(*args, &block)
  options = Utils.extract_options!(args)
  if args.size.nonzero?
    super(Transformation.extract_tuples(args).merge(options), &block)
  else
    super(options, &block)
  end
end

Instance Method Details

#<<(row) ⇒ self

Add row to table

Parameters:

Returns:

API:

  • public



274
275
276
277
278
279
 
# File 'lib/tty/table.rb', line 274

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

#[](row_index, column_index = false) ⇒ Object Also known as: at, element, component

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

API:

  • public



190
191
192
193
194
195
196
197
 
# File 'lib/tty/table.rb', line 190

def [](row_index, column_index = false)
  return row(row_index) unless column_index
  if row_index >= 0 && column_index >= 0
    rows.fetch(row_index) { return nil }[column_index]
  else
    fail TTY::Table::TupleMissing.new(row_index, column_index)
  end
end

#[]=(row_index, column_index, 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)

API:

  • private



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

def []=(row_index, column_index, val)
  @rows[row_index][column_index] = 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:

  • the object to coerce

Returns:

API:

  • public



459
460
461
462
 
# File 'lib/tty/table.rb', line 459

def coerce(rows)
  rows = @converter.convert(rows).to(:array)
  rows.map { |row| to_row(row, header) }
end

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

Return a column number at the index of the table as an Array. If the table has a header then column can be searched by header name. When a block is given, the elements of that Array are iterated over.

Examples:

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

Parameters:

Yields:

  • optional block to execute in the iteration operation

Returns:

API:

  • public



256
257
258
259
260
261
262
263
264
265
 
# File 'lib/tty/table.rb', line 256

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

#column_size ⇒ Integer

Return the number of columns

TODO: renmae to columns_size

Examples:

table.column_size # => 5

Returns:

API:

  • public



334
335
336
 
# File 'lib/tty/table.rb', line 334

def column_size
  rows.size > 0 ? rows[0].size : 0
end

#data ⇒ Array

Provides access to all table data

Returns:

API:

  • public



130
131
132
 
# File 'lib/tty/table.rb', line 130

def data
  (header && !header.empty?) ? [header] + rows : rows
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:

API:

  • public



292
293
294
295
296
 
# File 'lib/tty/table.rb', line 292

def each
  return to_enum unless block_given?
  data.each { |row| yield row }
  self
end

#each_with_index ⇒ Object

Iterate over each element yielding in addition row and column index

Examples:

table = TTY::Table.new(header, tuples)
table.each_with_index { |el, row, col| puts "#{el} at #{row},#{col}" }

Returns:

  • self

API:

  • public



307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
 
# File 'lib/tty/table.rb', line 307

def each_with_index
  return to_enum unless block_given?
  start_index = 0
  if header && !header.empty?
    header.attributes.each_with_index do |el, col_index|
      yield el, 0, col_index
    end
    start_index = 1
  end

  rows.each_with_index do |row, row_index|
    row.fields.each_with_index do |el, col_index|
      yield el, row_index + start_index, col_index
    end
  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:

API:

  • public



377
378
379
 
# File 'lib/tty/table.rb', line 377

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

#render(*args) {|renderer| ... } ⇒ String

Render a given table. This method takes options which will be passed to the renderer prior to rendering, which allows the caller to set any table rendering variables.

Parameters:

  • the renderer to be used

Yields:

Yield Parameters:

Returns:

API:

  • public



419
420
421
 
# File 'lib/tty/table.rb', line 419

def render(*args, &block)
  render_with(nil, *args, &block)
end

#render_with(border_class, renderer_type = (not_set=true), options = {}) {|renderer| ... } ⇒ String

Render a given table using custom border class.

Parameters:

  • (defaults to: (not_set=true))

Yields:

Yield Parameters:

Returns:

API:

  • public



437
438
439
440
441
442
443
444
445
446
447
 
# File 'lib/tty/table.rb', line 437

def render_with(border_class, renderer_type=(not_set=true), options={}, &block)
  unless not_set
    if renderer_type.respond_to?(:to_hash)
      options = renderer_type
    else
      options[:renderer] = renderer_type
    end
  end

  Renderer.render_with(border_class, self, options, &block)
end

#renderer(type = :basic, options = {}) ⇒ Object

Return renderer for this table

Parameters:

  • (defaults to: :basic)

    the renderer type

  • (defaults to: {})

    the renderer options



398
399
400
 
# File 'lib/tty/table.rb', line 398

def renderer(type = :basic, options = {})
  @renderer ||= Renderer.select(type).new(self, options)
end

#rotate ⇒ self

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.

Rotate the table between vertical and horizontal orientation

Returns:

API:

  • private



157
158
159
160
 
# File 'lib/tty/table.rb', line 157

def rotate
  orientation.transform(self)
  self
end

#rotate_horizontal ⇒ 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.

Rotate the table horizontally

API:

  • private



176
177
178
179
180
181
182
183
184
185
 
# File 'lib/tty/table.rb', line 176

def rotate_horizontal
  return unless rotated?
  head, body = orientation.slice(self)
  if header && header.empty?
    @header = head[0]
    @rows   = body.map { |row| to_row(row, @header) }
  else
    @rows = body.map { |row| to_row(row) }
  end
end

#rotate_vertical ⇒ 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.

Rotate the table vertically

API:

  • private



165
166
167
168
169
170
171
 
# File 'lib/tty/table.rb', line 165

def rotate_vertical
  @original_columns = column_size
  @original_rows    = row_size
  @rows             = orientation.slice(self)
  @header           = [] if header
  @rotated          = true
end

#rotated? ⇒ Boolean

Marks this table as rotated

Returns:

API:

  • public



148
149
150
 
# File 'lib/tty/table.rb', line 148

def rotated?
  @rotated
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:

Yields:

  • optional block to execute in the iteration operation

Returns:

API:

  • public



226
227
228
229
230
231
232
233
 
# File 'lib/tty/table.rb', line 226

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

#row_size ⇒ Integer

Return the number of rows

Examples:

table.row_size # => 5

Returns:

API:

  • public



346
347
348
 
# File 'lib/tty/table.rb', line 346

def row_size
  rows.size
end

#size ⇒ Array

Return the number of rows and columns

Examples:

table.size # => [3,5]

Returns:

  • row x columns

API:

  • public



358
359
360
 
# File 'lib/tty/table.rb', line 358

def size
  [row_size, column_size]
end

#to_header(row) ⇒ TTY::Table::Header

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.

Convert an Array row into Header

Returns:

API:

  • private



13
14
15
 
# File 'lib/tty/table/header.rb', line 13

def to_header(row)
  Header.new(row)
end

#to_row(row, header = nil) ⇒ TTY::Table::Row

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.

Convert an Array row into Row

Returns:

API:

  • private



12
13
14
 
# File 'lib/tty/table/row.rb', line 12

def to_row(row, header = nil)
  Row.new(row, header)
end

#to_s ⇒ String

Return string representation of table using basic renderer.

Returns:

API:

  • public



386
387
388
 
# File 'lib/tty/table.rb', line 386

def to_s
  render(:basic)
end

#width ⇒ Integer

Check table width

Returns:

  • width

API:

  • public



367
368
369
 
# File 'lib/tty/table.rb', line 367

def width
  ColumnSet.new(self).total_width
end