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/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/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/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/renderer/unicode.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, Renderer, Validatable Classes: Border, BorderDSL, BorderOptions, ColumnSet, DimensionMismatchError, Field, Header, Operations, Orientation, Row, TupleMissing

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, #validate_options!

Methods included from Equatable

#attr_reader, included, #inherited

Methods included from Renderer

#pick_renderer, #renderer, #renderer=, #renders_with

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

  • :orientation (Symbol) —

    used to transform table orientation



149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
 
# File 'lib/tty/table.rb', line 149

def initialize(options={}, &block)
  validate_options! options
  @header        = (value = options[:header]) ? Header.new(value) : nil
  @rows          = coerce(options.fetch(:rows) { Row.new([]) })
  @renderer      = pick_renderer options[:renderer]
  @border        = TTY::Table::BorderOptions.from(options.delete(:border))
  @orientation   = Orientation.coerce(options.fetch(:orientation) { :horizontal })
  # TODO: assert that row_size is the same as column widths & aligns
  @column_widths = Array(options.delete(:column_widths)).map(&:to_i)
  @column_aligns = Array(options.delete(:column_aligns)).map(&:to_sym)
  @operations    = TTY::Table::Operations.new(self)
  @operations.add_operation(:alignment, Operation::AlignmentSet.new(@column_aligns))
  @filter        = options.fetch(:filter) { nil }
  @width         = options.fetch(:width) { TTY.terminal.width }

  assert_row_sizes @rows
  @orientation.transform(self)
  yield_or_eval &block if block_given?
end

Instance Attribute Details

#border_class ⇒ Object (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 border class



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

def border_class
  @border_class
end

#column_aligns ⇒ Array (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

Returns:

  • (Array) 


47
48
49
 
# File 'lib/tty/table.rb', line 47

def column_aligns
  @column_aligns
end

#column_widths ⇒ Array

The table enforced column widths

Returns:

  • (Array) 


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

def column_widths
  @column_widths
end

#filter(&block) ⇒ Object

Set table fields filter

Parameters:

  • block (#call) 


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

def filter
  @filter
end

#header ⇒ Enumerable (readonly)

The table header

Returns:

  • (Enumerable) 


25
26
27
 
# File 'lib/tty/table.rb', line 25

def header
  @header
end

#operations ⇒ Object (readonly)

The table operations applied to rows



69
70
71
 
# File 'lib/tty/table.rb', line 69

def operations
  @operations
end

#orientation ⇒ Object

The table orientation out of :horizontal and :vertical



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

def orientation
  @orientation
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']]


81
82
83
 
# File 'lib/tty/table.rb', line 81

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

.extract_tuples(args) ⇒ 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.

Extract header and row tuples from arguments

Parameters:

  • args (Array) 


119
120
121
122
123
124
125
126
127
 
# File 'lib/tty/table.rb', line 119

def self.extract_tuples(args)
  rows   = args.pop
  header = args.size.zero? ? nil : args.first
  if rows.first.is_a?(Hash)
    header = rows.map(&:keys).flatten.uniq
    rows   = rows.inject([]) { |arr, el| arr + el.values }
  end
  { :header => header, :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:

  • *args (Array[Symbol], Hash) 


105
106
107
108
109
110
111
112
 
# File 'lib/tty/table.rb', line 105

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

.renderer ⇒ TTY::Table::Renderer

Determine renderer based on terminal capabilities

Returns:



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) 


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

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

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

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



249
250
251
252
253
254
255
256
 
# File 'lib/tty/table.rb', line 249

def [](i, j=false)
  return row(i) unless j
  if i >= 0 && j >= 0
    rows.fetch(i){return nil}[j]
  else
    raise TTY::Table::TupleMissing.new(i,j)
  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)



264
265
266
 
# File 'lib/tty/table.rb', line 264

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

#border(options = (not_set=true)) { ... } ⇒ Object

Store border characters, style and separator for the table rendering

Parameters:

Yields:

  • block representing border options



235
236
237
238
239
240
241
242
243
244
 
# File 'lib/tty/table.rb', line 235

def border(options=(not_set=true), &block)
  @border = TTY::Table::BorderOptions.new unless @border
  if block_given?
    border_dsl = TTY::Table::BorderDSL.new(&block)
    @border = border_dsl.options
  elsif !not_set
    @border = TTY::Table::BorderOptions.from(options)
  end
  @border
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) 


451
452
453
454
 
# File 'lib/tty/table.rb', line 451

def coerce(rows)
  rows = convert_to_array(rows)
  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:

  • index (Integer, String, Symbol)

Yields:

  • optional block to execute in the iteration operation

Returns:

  • (self) 


315
316
317
318
319
320
321
322
323
324
 
# File 'lib/tty/table.rb', line 315

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

Examples:

table.column_size # => 5

Returns:

  • (Integer) 


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

def column_size
  return rows[0].size if (rows.size > 0)
  return 0
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) 


351
352
353
354
355
 
# File 'lib/tty/table.rb', line 351

def each
  return to_enum unless block_given?
  rows.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



366
367
368
369
370
371
372
373
374
 
# File 'lib/tty/table.rb', line 366

def each_with_index
  return to_enum unless block_given?
  rows.each_with_index do |row, row_index|
    row.each_with_index do |el, col_index|
      yield el, row_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:

  • (Boolean) 


428
429
430
 
# File 'lib/tty/table.rb', line 428

def empty?
  column_size == 0 || row_size == 0
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:

  • (self) 


201
202
203
204
 
# File 'lib/tty/table.rb', line 201

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



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

def rotate_horizontal
  transposed = rows.transpose
  if header && header.empty?
    @header = transposed[0]
    @rows   = transposed[1..-1].map { |row| to_row(row, @header) }
  elsif rotated?
    @rows = transposed.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



209
210
211
212
213
 
# File 'lib/tty/table.rb', line 209

def rotate_vertical
  @rows    = ([header].compact + rows).transpose.map { |row| to_row(row) }
  @header  = [] if header
  @rotated = true
end

#rotated? ⇒ Boolean

Marks this table as rotated

Returns:

  • (Boolean) 


192
193
194
 
# File 'lib/tty/table.rb', line 192

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:

  • index (Integer)

Yields:

  • optional block to execute in the iteration operation

Returns:

  • (self) 


285
286
287
288
289
290
291
292
 
# File 'lib/tty/table.rb', line 285

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:

  • (Integer) 


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

def row_size
  rows.size
end

#size ⇒ Array

Return the number of rows and columns

Examples:

table.size # => [3,5]

Returns:

  • (Array) —

    row x columns



409
410
411
 
# File 'lib/tty/table.rb', line 409

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:



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

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:



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

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

#to_s ⇒ String

Return string representation of table

Returns:

  • (String) 


437
438
439
 
# File 'lib/tty/table.rb', line 437

def to_s
  render(self)
end

#width ⇒ Integer

Check table width

Returns:

  • (Integer) —

    width



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

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