Module: IS::Term::StatusTable::Functions

Extended by:
Functions
Included in:
IS::Term::StatusTable, Functions
Defined in:
lib/is-term/functions.rb

Overview

Provides calculation functions for status table rows and aggregates.

This module contains methods for retrieving and calculating timing metrics (start/finish times, elapsed time, estimated completion), progress percentages, and aggregate statistics (sum, average, min, max, count) for rows in a IS::Term::StatusTable.

Methods support polymorphic signatures accepting either a Hash row, an identifier, or no argument (for table-wide aggregation).

Examples:

Calculating progress for a specific row

percent(some_row)  # => 45
elapsed(some_row)  # => 123.45

Table-wide aggregation

percent    # => 32 (percent for entire table)
active     # => 3 (count of active rows)
sum(:size) # => 1024 (sum of :size field across all rows)

Aggregate or Table Function collapse

ROW_METHODS =

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

[ :started, :finished, :percent, :estimated, :elapsed, :speed, :current, :total, :active?, :done? ].freeze
TABLE_METHODS =

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

[ :started, :finished, :percent, :estimated, :elapsed, :speed, :current, :total, :active, :active?, :done, :done?, :count, :empty? ].freeze
AGGREGATE_METHODS =

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

[ :sum, :avg, :min, :max, :cnt, :count ].freeze

Internal Setup collapse

Row or Table Functions collapse

Table-only Functions collapse

Aggregate Functions collapse

Aggregate or Table Function collapse

Function Access collapse

Instance Attribute Details

#_table ⇒ IS::Term::StatusTable (protected)

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 status table context for function execution.

Returns the singleton instance by default, but can be overridden to use a different table context (e.g., for testing or custom implementations). The setter validates that the value responds to both row and rows methods (duck typing for table interface).

Returns:

Raises:

  • (ArgumentError) —

    if assigned value does not respond to row and rows



43
44
45
 
# File 'lib/is-term/functions.rb', line 43

def _table
  @status_table ||= IS::Term::StatusTable::instance
end

Class Method Details

.aggregate_func(method_name, field_name) ⇒ Proc Also known as: AF

Returns:

  • (Proc)

Raises:

  • (NameError) 


450
451
452
453
454
 
# File 'lib/is-term/functions.rb', line 450

def aggregate_func method_name, field_name
  raise NameError, "Invalid function name: #{ method_name.inspect }", caller_locations unless AGGREGATE_METHODS.include?(method_name)
  meth = self.method method_name
  lambda { meth.call(field_name) }
end

.row_func(method_name) ⇒ Proc Also known as: RF

Returns:

  • (Proc)

Raises:

  • (NameError) 


433
434
435
436
 
# File 'lib/is-term/functions.rb', line 433

def row_func method_name
  raise NameError, "Invalid function name: #{ method_name.inspect }", caller_locations unless ROW_METHODS.include?(method_name)
  self.method(method_name).to_proc
end

.table_func(method_name) ⇒ Proc Also known as: TF

Returns:

  • (Proc)

Raises:

  • (NameError) 


439
440
441
442
443
444
445
446
447
 
# File 'lib/is-term/functions.rb', line 439

def table_func method_name
  raise NameError, "Invalid function name: #{ method_name.inspect }", caller_locations unless TABLE_METHODS.include?(method_name)
  meth = self.method method_name
  if ROW_METHODS.include?(method_name) || AGGREGATE_METHODS.include?(method_name) 
    lambda { meth.call(nil) }
  else
    meth.to_proc
  end
end

Instance Method Details

#active ⇒ Integer

Count of active rows

Returns:

  • (Integer) 


333
334
335
336
 
# File 'lib/is-term/functions.rb', line 333

def active
  tbl = _table
  tbl.rows.select { |r| r[:_active] }.count
end

#active?(row) ⇒ Boolean? #active?(id) ⇒ Boolean? #active? ⇒ Boolean?

Is a row or table active?

Overloads:

  • #active?(row) ⇒ Boolean?

    Is this row active?

    Parameters:

    • row (Hash)
  • #active?(id) ⇒ Boolean?

    Is row with specified id active?

    Parameters:

    • id (Object)
  • #active? ⇒ Boolean?

    Is any row of table active?

Returns:

  • (Boolean, nil) 


294
295
296
297
298
299
300
301
302
303
304
305
306
 
# File 'lib/is-term/functions.rb', line 294

def active? row = nil
  if row.is_a?(Hash)
    row[:_active]
  else
    tbl = _table
    if row.nil?
      tbl.rows.any? { |r| r[:_active] }
    else
      r = tbl.row row
      r.nil? ? nil : active?(r)
    end
  end
end

#avg(name) ⇒ Numeric?

Average value of field

Returns:

  • (Numeric, nil) 


364
365
366
367
368
369
370
371
372
373
374
 
# File 'lib/is-term/functions.rb', line 364

def avg name
  tbl = _table
  vls = tbl.rows.map { |r| r[name] }.compact
  sum = vls.sum
  cnt = vls.count
  if cnt == 0
    nil
  else
    sum / cnt
  end
end

#cnt(name) ⇒ Integer #count ⇒ Integer Also known as: cnt

Count of rows, See Details.

Overloads:

  • #cnt(name) ⇒ Integer

    Count of unique not null values of field

    Parameters:

    • name (Symbol)
  • #count ⇒ Integer

    Count of rows

Returns:

  • (Integer) 


404
405
406
407
408
409
410
411
 
# File 'lib/is-term/functions.rb', line 404

def count name = nil
  rows = _table.rows
  if name.nil?
    rows.count
  else
    rows.map { |r| r[name] }.compact.uniq.count
  end
end

#current(row) ⇒ Integer? #current(id) ⇒ Integer? #current ⇒ Integer?

Return current steps value for row or whole table.

Overloads:

  • #current(row) ⇒ Integer?

    Current step in specified row

    Parameters:

    • row (Hash)
  • #current(id) ⇒ Integer?

    Current step in row with specified id

    Parameters:

    • id (Object)
  • #current ⇒ Integer?

    Sum of current of whole table

Returns:

  • (Integer, nil) 


238
239
240
241
242
243
244
245
246
247
248
249
250
 
# File 'lib/is-term/functions.rb', line 238

def current row = nil
  if row.is_a?(Hash)
    row[:current]
  else
    tbl = _table
    if row.nil?
      tbl.rows.map { |r| r[:total] ? r[:current] : nil }.compact.sum
    else
      r = tbl.row row
      r.nil? ? nil : current(r)
    end
  end
end

#done ⇒ Integer

Count of done rows

Returns:

  • (Integer) 


340
341
342
343
 
# File 'lib/is-term/functions.rb', line 340

def done
  tbl = _table
  tbl.rows.select { |r| !r[:_active] }.count
end

#done?(row) ⇒ Boolean? #done?(id) ⇒ Boolean? #done? ⇒ Boolean?

Is a row or table done?

Overloads:

  • #done?(row) ⇒ Boolean?

    Is this row done?

    Parameters:

    • row (Hash)
  • #done?(id) ⇒ Boolean?

    Is row with specified id done?

    Parameters:

    • id (Object)
  • #done? ⇒ Boolean?

    Is all rows if table done?

Returns:

  • (Boolean, nil) 


322
323
324
325
 
# File 'lib/is-term/functions.rb', line 322

def done? row = nil
  active = self.active? row
  active.nil? ? nil : !active
end

#elapsed(row) ⇒ Float? #elapsed(id) ⇒ Float? #elapsed ⇒ Float?

Return elapsed time in seconds.

Overloads:

  • #elapsed(row) ⇒ Float?

    Elapsed time of row execution

    Parameters:

    • row (Hash)
  • #elapsed(id) ⇒ Float?

    Elapsed time of row with specified id

    Parameters:

    • id (Object)
  • #elapsed ⇒ Float?

    Elapsed time of whole table

Returns:

  • (Float, nil) —

    Value in seconds



182
183
184
185
186
187
188
189
190
191
192
 
# File 'lib/is-term/functions.rb', line 182

def elapsed row = nil
  started = self.started row
  finished = self.finished row
  if started.nil?
    nil
  elsif finished.nil?
    Time::now - started
  else
    finished - started
  end
end

#empty? ⇒ Boolean

Is table empty?

Returns:

  • (Boolean) 


347
348
349
 
# File 'lib/is-term/functions.rb', line 347

def empty?
  self.count == 0
end

#estimated(row) ⇒ Float? #estimated(id) ⇒ Float? #estimated ⇒ Float?

Return estimated remaining execution time is seconds.

Overloads:

  • #estimated(row) ⇒ Float?

    Estimated remaining time of row execution

    Parameters:

    • row (Hash)
  • #estimated(id) ⇒ Float?

    Estimated remaining time of row with specified id

    Parameters:

    • id (Object)
  • #estimated ⇒ Float?

    Estimated remaining time of whole table

Returns:

  • (Float, nil) —

    Value in seconds



157
158
159
160
161
162
163
164
165
166
 
# File 'lib/is-term/functions.rb', line 157

def estimated row = nil
  elapsed = self.elapsed row
  current = self.current row
  total = self.total row
  if elapsed.nil? || current.nil? || total.nil? || current == 0
    nil
  else
    (elapsed.to_f / current) * (total - current)
  end
end

#finished(row) ⇒ Time? #finished(id) ⇒ Time? #finished ⇒ Time?

Return finishing time of row or whole table.

Overloads:

  • #finished(row) ⇒ Time?

    When this row was finished.

    Parameters:

    • row (Hash) —

      the row hash containing :_finished key

  • #finished(id) ⇒ Time?

    Find row by id and return when it finished. Returns nil if row not found or not finished

    Parameters:

    • id (Object) —

      the row identifier

  • #finished ⇒ Time?

    When the whole table was finished (maximum finish time across all rows). Returns nil if any row is still active (not finished) or table is empty.

Returns:

  • (Time, nil) 


100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
 
# File 'lib/is-term/functions.rb', line 100

def finished row = nil
  if row.is_a?(Hash)
    row[:_finished]
  else
    tbl = _table
    if row.nil?
      values = tbl.rows.map { |r| r[:_finished] }
      if values.any? { |v| v.nil? }
        nil
      else
        values.max
      end
    else
      r = tbl.row row
      r.nil? ? nil : finished(r)
    end
  end
end

#max(name) ⇒ Comparable?

Maximum of field values

Returns:

  • (Comparable, nil) 


385
386
387
388
 
# File 'lib/is-term/functions.rb', line 385

def max name
  tbl = _table
  tbl.rows.map { |r| r[name] }.compact.max
end

#min(name) ⇒ Comparable?

Minimum of field values

Returns:

  • (Comparable, nil) 


378
379
380
381
 
# File 'lib/is-term/functions.rb', line 378

def min name
  tbl = _table
  tbl.rows.map { |r| r[name] }.compact.min
end

#percent(row) ⇒ Integer? #percent(id) ⇒ Integer? #percent ⇒ Integer?

Return a percent of execution — (0 .. 100).

Overloads:

  • #percent(row) ⇒ Integer?

    Execution percent of row

    Parameters:

    • row (Hash)
  • #percent(id) ⇒ Integer?

    Execution percent of row with specified id

    Parameters:

    • id (Object)
  • #percent ⇒ Integer?

    Execution percent of whole table

Returns:

  • (Integer, nil) 


133
134
135
136
137
138
139
140
141
 
# File 'lib/is-term/functions.rb', line 133

def percent row = nil
  current = self.current row
  total = self.total row
  if current.nil? || total.nil? || total == 0
    nil
  else
    (current * 100) / total
  end
end

#speed(row) ⇒ Float? #speed(id) ⇒ Float? #speed ⇒ Float?

Return average execution speed (steps in second).

Overloads:

  • #speed(row) ⇒ Float?

    Speed of row execution

    Parameters:

    • row (Hash)
  • #speed(id) ⇒ Float?

    Speed of row with specified id

    Parameters:

    • id (Object)
  • #speed ⇒ Float?

    Execution speed of whole table

Returns:

  • (Float, nil) 


208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
 
# File 'lib/is-term/functions.rb', line 208

def speed row = nil
  elapsed = self.elapsed row
  current = self.current row
  finished = self.finished row
  total = self.total row
  if elapsed.nil? || current.nil?
    nil
  else
    if finished && total
      total.to_f / elapsed
    else
      current.to_f / elapsed
    end
  end
end

#started(row) ⇒ Time? #started(id) ⇒ Time? #started ⇒ Time?

Return starting time of row or whole table.

Overloads:

  • #started(row) ⇒ Time?

    When this row was started.

    Parameters:

    • row (Hash) —

      the row hash containing :_started key

  • #started(id) ⇒ Time?

    Find row by id and return when it started. Returns nil if row not found.

    Parameters:

    • id (Object) —

      the row identifier

  • #started ⇒ Time?

    When the whole table was started (minimum start time across all rows). Returns nil if table is empty or no rows have started.

Returns:

  • (Time, nil) 


72
73
74
75
76
77
78
79
80
81
82
83
84
 
# File 'lib/is-term/functions.rb', line 72

def started row = nil
  if row.is_a?(Hash)
    row[:_started]
  else
    tbl = _table
    if row.nil?
      tbl.rows.map { |r| r[:_started] }.min
    else
      r = tbl.row row
      r.nil? ? nil : started(r)
    end
  end
end

#sum(name) ⇒ Numeric

Sum of field values

Returns:

  • (Numeric) 


357
358
359
360
 
# File 'lib/is-term/functions.rb', line 357

def sum name
  tbl = _table
  tbl.rows.map { |r| r[name] }.compact.sum
end

#total(row) ⇒ Integer? #total(id) ⇒ Integer? #total ⇒ Integer?

Return total steps value of row or table.

Overloads:

  • #total(row) ⇒ Integer?

    Total step count of row

    Parameters:

    • row (Hash)
  • #total(id) ⇒ Integer?

    Total step count of row with specified id

    Parameters:

    • id (Object)
  • #total ⇒ Integer?

    Total step count of whole table

Returns:

  • (Integer, nil) 


266
267
268
269
270
271
272
273
274
275
276
277
278
 
# File 'lib/is-term/functions.rb', line 266

def total row = nil
  if row.is_a?(Hash)
    row[:total]
  else
    tbl = _table
    if row.nil?
      tbl.rows.map { |r| r[:total] }.compact.sum
    else
      r = tbl.row row
      r.nil? ? nil : total(r)
    end
  end
end