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/orientation.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/orientation/vertical.rb,
lib/tty/table/orientation/horizontal.rb,
lib/tty/table/operation/alignment_set.rb

Defined Under Namespace

Modules: Operation, Renderer, Validatable Classes: Border, ColumnSet, DimensionMismatchError, Orientation, 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



131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
 
# File 'lib/tty/table.rb', line 131

def initialize(options={}, &block)
  validate_options! options

  @header        = options.fetch(:header) { nil }
  @rows          = coerce options.fetch(:rows) { [] }
  @renderer      = pick_renderer options[:renderer]
  @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)
  @alignments    = Operation::AlignmentSet.new Array(options.delete(:column_aligns)).map(&:to_sym)

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

Instance Attribute Details

#alignments ⇒ Operation::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

Returns:



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

def alignments
  @alignments
end

#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



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

def border_class
  @border_class
end

#column_widths ⇒ Array

The table enforced column widths

Returns:

  • (Array) 


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

def column_widths
  @column_widths
end

#header ⇒ Enumerable (readonly)

The table header

Returns:

  • (Enumerable) 


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

def header
  @header
end

#orientation ⇒ Object

The table orientation out of :horizontal and :vertical



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

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']]


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

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) 


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

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) 


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

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) 


276
277
278
279
280
281
 
# File 'lib/tty/table.rb', line 276

def <<(row)
  rows_copy = rows.dup
  assert_row_sizes rows_copy << row
  rows << 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)



198
199
200
201
202
203
204
205
 
# File 'lib/tty/table.rb', line 198

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)



213
214
215
 
# File 'lib/tty/table.rb', line 213

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) 


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

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) 


259
260
261
262
263
264
265
266
267
 
# File 'lib/tty/table.rb', line 259

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_size ⇒ Integer

Return the number of columns

Examples:

table.column_size # => 5

Returns:

  • (Integer) 


310
311
312
313
 
# File 'lib/tty/table.rb', line 310

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) 


294
295
296
297
298
299
300
 
# File 'lib/tty/table.rb', line 294

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) 


354
355
356
 
# File 'lib/tty/table.rb', line 354

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) 


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

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



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

def rotate_horizontal
  transposed = rows.transpose
  if header && header.empty?
    @rows = transposed[1..-1]
    @header = transposed[0]
  elsif rotated?
    @rows = transposed
  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



176
177
178
179
180
 
# File 'lib/tty/table.rb', line 176

def rotate_vertical
  @rows    = ([header].compact + rows).transpose
  @header  = [] if header
  @rotated = true
end

#rotated? ⇒ Boolean

Marks this table as rotated

Returns:

  • (Boolean) 


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

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) 


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

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) 


323
324
325
 
# File 'lib/tty/table.rb', line 323

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



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

def size
  [row_size, column_size]
end

#to_s ⇒ String

Return string representation of table

Returns:

  • (String) 


363
364
365
 
# File 'lib/tty/table.rb', line 363

def to_s
  render(self)
end

#width ⇒ Integer

Check table width

Returns:

  • (Integer) —

    width



344
345
346
 
# File 'lib/tty/table.rb', line 344

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