is-term 0.8.0

data/lib/is-term/statustable.rb

@@ -0,0 +1,410 @@
+# frozen_string_literal: true
+
+require 'set'
+require 'singleton'
+require 'tty-screen'
+
+require_relative 'info'
+require_relative 'boolean'
+require_relative 'string_helpers'
+
+class IS::Term::Error < StandardError; end
+class IS::Term::StateError < IS::Term::Error; end
+
+class IS::Term::StatusTable
+
+  # module Formats; end
+  # module Functions; end
+
+  include Singleton
+  
+  using IS::Term::StringHelpers
+
+  INVERT = "\e[7m"
+
+  DEFAULT_IO = $stdout
+  DEFAULT_SUMMARY_PREFIX = INVERT
+
+  # @private
+  def initialize
+    @mutex = Thread::Mutex::new
+    @in_configure = true
+    reset!
+    @in_configure = nil
+  end
+
+  # @group Configuration Info
+
+  # @return [IO]
+  attr_reader :term
+
+  # @return [Array<Hash|String>]
+  attr_reader :defs
+
+  # @endgroup
+
+  # @group Data Manipulation
+
+  # @return [Array<Hash>]
+  def rows
+    @rows ||= []
+    @rows.dup.freeze
+  end
+
+  # @return [Hash, nil]
+  def row row_id
+    return nil if @id_field.nil?
+    @rows.find { |r| r[@id_field] == row_id }.dup.freeze
+  end
+
+  # @endgroup
+
+  # @group State
+
+  def configured?
+    !!@id_field && !@defs.empty?
+  end
+
+  def available?
+    !!@term && @term.is_a?(IO) && File.chardev?(@term)
+  end
+
+  # @return [self]
+  def reset!
+    if @in_configure
+      @defs = []
+      @id_field = nil
+      @inactivate_if = nil
+      @term = DEFAULT_IO
+      @show_summary = nil
+      @summary_prefix = DEFAULT_SUMMARY_PREFIX
+      @summary_values = {}
+      @started = Time::now
+      @rows = []
+    else
+      @mutex.synchronize do
+        @started = Time::now
+        @rows = []
+      end
+    end
+    self
+  end
+
+  # @endgroup
+
+  # @group Data Manipulation
+
+  # @yield
+  # @yieldparam [Hash] row
+  # @return [Hash]
+  def append **data
+    raise IS::Term::StateError, "StatusTable is not ready for work", caller_locations unless available? && configured?
+    data.transform_keys!(&:to_sym)
+    id = data[@id_field]
+    raise ArgumentError, "Row Id must be specified", caller_locations if id.nil?
+    raise ArgumentError, "Row with Id = #{ id.inspect } already exists", caller_locations if @rows.any? { |r| r[@id_field] == id }
+    row = {}
+    row[:_active] = true
+    row[:_started] = Time::now
+    row[:_mutex] = Thread::Mutex::new
+    row.merge! data
+    yield row if block_given?
+    @mutex.synchronize do
+      @rows << row
+      @term.puts ''
+      render_table
+    end
+    row
+  end
+
+  # @yield
+  # @yieldparam [Hash] row
+  # @return [Hash]
+  def update **data
+    raise IS::Term::StateError, "StatusTable is not ready for work", caller_locations unless available? && configured?
+    data.transform_keys!(&:to_sym)
+    id = data[@id_field]
+    raise ArgumentError, "Row Id must be specified", caller_locations if id.nil?
+    row = find_row id
+    raise ArgumentError, "Row with Id = #{id.inspect} must be exists", caller_locations if row.nil?
+    row[:_mutex].synchronize do
+      row.merge! data
+      yield row if block_given?
+      if row[:_active] && @inactivate_if && @inactivate_if.call(row)
+        row[:_active] = false
+        row[:_finished] = Time::now
+        render_table
+      else
+        render_line row
+      end
+    end
+    row
+  end
+
+  # @endgroup
+
+  # @group Configuration
+
+  # @yield
+  # @return [self]
+  def configure &block
+    if block_given?
+      @mutex.synchronize do
+        @in_configure = true
+        instance_eval(&block)
+        @in_configure = nil
+      end
+    end
+    @term.puts ''
+    self
+  end
+
+  # @endgroup
+
+  private
+
+  # @private
+  def find_row id
+    @rows.find { |r| r[@id_field] == id }
+  end
+
+  # @private
+  def apply_format value, format
+    case format
+    when String
+      format % value
+    when Proc
+      format[value]
+    else
+      raise ArgumentError, "Unknown format value: #{ format.inspect }", caller_locations
+    end
+  end
+
+  # @private
+  def prerender_line row
+    result = []
+    @defs.each do |definition|
+      case definition
+      when String
+        result << definition
+      when Hash
+        value = if definition[:func]
+          definition[:func].call row
+        else
+          row[definition[:name]]
+        end
+        skip_width = value.is_a?(Array)
+        value = value.first if skip_width
+        if definition[:format]
+          value = apply_format value, definition[:format]
+        else
+          value = value.to_s
+        end
+        if definition[:width] && !skip_width
+          value = value.ellipsis definition[:width]
+        end
+        return false if !skip_width && value.width > definition[:_width] && !@in_table_render
+        result << value
+        break if skip_width
+      else
+        raise IS::Term::StateError, "Invalid column definition: #{ definition.inspect }", caller_locations
+      end
+    end
+    result
+  end
+
+  # @private
+  def prerender_table
+    result = @rows.map { |r| prerender_line r }
+    result << prerender_summary if @show_summary
+    result
+  end
+
+  # @private
+  def prerender_summary
+    result = []
+    @defs.each do |definition|
+      case definition
+      when String
+        result << definition
+      when Hash
+        name = definition[:name]
+        value = case definition[:summary]
+        when nil
+          ''
+        when :value
+          @summary_values[name]
+        when Proc
+          definition[:summary].call
+        end
+        skip_width = value.is_a?(Array)
+        value = value.first if skip_width
+        if definition[:format] && !value.nil? && value != ''
+          value = apply_format value, definition[:format]
+        else
+          value = value.to_s
+        end
+        if definition[:width] && !skip_width
+          value = value.ellipsis definition[:width]
+        end
+        return false if !skip_width && value.width > definition[:_width] && !@in_table_render
+        result << value
+        break if skip_width
+      else
+        raise IS::Term::StateError, "Invalid column definition: #{definition.inspect}", caller_locations
+      end
+    end
+    result
+  end
+
+  # @private
+  def render_line row
+    prerendered = prerender_line row 
+    summary = @show_summary ? prerender_summary : :skip
+    if prerendered && summary
+      line = ''
+      (0 .. prerendered.size - 1).each do |idx|
+        value = prerendered[idx]
+        definition = @defs[idx]
+        value = value.align definition[:_width], (definition[:align] || IS::Term::StringHelpers::ALIGN_LEFT) if !definition.is_a?(String)
+        line += value
+      end
+      shift = row[:_shift]
+      @term.print "\e[0m\e[#{ shift }A\e[0m#{ line.ellipsis TTY::Screen::width }\e[0m\e[K\r\e[#{ shift }B"
+      if @show_summary
+        line = ''
+        (0 .. summary.size - 1).each do |idx|
+          value = summary[idx]
+          definition = @defs[idx]
+          value = value.align definition[:_width], (definition[:align] || IS::Term::StringHelpers::ALIGN_LEFT) if !definition.is_a?(String)
+          line += value
+        end
+        @term.print "\e[0m\e[1A#{ @summary_prefix }#{ line.ellipsis TTY::Screen::width }\e[0m\e[K\r\e[1B"
+      end
+    else
+      @mutex.synchronize { render_table } unless @in_table_render
+    end
+  end
+
+  # @private
+  def render_table
+    @in_table_render = true
+    @rows.sort_by! { |r| [ r[:_active], r[:_started] ] }
+    size = @rows.size
+    size += 1 if @show_summary
+    @rows.each_with_index { |row, idx| row[:_shift] = size - idx }
+    prerendered = prerender_table
+    @defs.each_with_index do |definition, idx|
+      case definition
+      when Hash
+        definition[:_width] = prerendered.map { |row| row[idx]&.width }.compact.max
+      end
+    end
+    text = ''
+    last = prerendered.size - 1
+    prerendered.each_with_index do |ln, i|
+      if @show_summary && i == last
+        line = @summary_prefix
+      else
+        line = ''
+      end
+      ln.each_with_index do |value, idx|
+        definition = @defs[idx]
+        value = value.align definition[:_width], (definition[:align] || IS::Term::StringHelpers::ALIGN_LEFT) if !definition.is_a?(String)
+        line += value
+      end
+      text += "\e[0m\e[K#{ line.ellipsis TTY::Screen::width }\e[0m\e[K\n"
+    end
+    @term.print "\e[0m\e[#{ prerendered.size }A#{ text }\e[0m\e[1B"
+    @in_table_render = nil
+  end
+
+  # @group Configuration DSL
+
+  # @private
+  SUMMARY_NONE = [ :none, false ].freeze
+  # @private
+  SUMMARY_VALS = [ :value ].freeze  
+
+  # @return [void]
+  def column name, id: false, func: nil, format: nil, width: nil, align: nil, summary: nil
+    raise ArgumentError, "Invalid name value: #{ name.inspect }", caller_locations unless name.is_a?(String) || name.is_a?(Symbol)
+    raise ArgumentError, "Name can not be empty", caller_locations if name == '' || name == :''
+    name = name.to_sym
+    raise ArgumentError, "Column name already exists: #{ name }", caller_locations if @defs.any? { |d| d.is_a?(Hash) && d[:name] == name }
+    raise ArgumentError, "Invalid id value: #{ id.inspect }", caller_locations unless id.nil? || id == true || id == false
+    id = nil if id == false
+    raise ArgumentError, "Id field already exists (#{ @id_field })" if @id_field && id
+    func_keys = Set[]
+    if self.class.const_defined?(:Functions)
+      func_keys |= Set[*Functions::ROW_METHODS]
+    end
+    raise ArgumentError, "Invalid func value: #{ func.inspect }", caller_locations unless func.nil? || func.respond_to?(:call) || func_keys.include?(func)
+    if self.class.const_defined?(:Functions) && func.is_a?(Symbol)
+      func = Functions::RF func
+    end
+    format_keys = Set[]
+    if self.class.const_defined?(:Formats)
+      format_keys |= Set[*Formats::SPECIAL_FORMATS]
+    end
+    raise ArgumentError, "Invalid format value: #{ format.inspect }", caller_locations unless format.nil? || format.is_a?(String) || format.is_a?(Array) || format.respond_to?(:call) || format_keys.include?(format)
+    if self.class.const_defined?(:Formats) && format && !format.respond_to?(:call)
+      format = Formats::fmt format if format.is_a?(Symbol)
+      format = Formats::bar(*format) if format.is_a?(Array) 
+    end
+    raise ArgumentError, "Invalid width value: #{ width.inspect }", caller_locations unless width.nil? || width.is_a?(Integer)
+    raise ArgumentError, "Invalid align value: #{ align.inspect }", caller_locations unless align.nil? || IS::Term::StringHelpers::ALIGN_MODES.include?(align)
+    summary_keys = Set[*(SUMMARY_NONE + SUMMARY_VALS)]
+    if self.class.const_defined?(:Functions)
+      summary_keys |= Set[*(Functions::TABLE_METHODS + Functions::AGGREGATE_METHODS)]
+    end
+    raise ArgumentError, "Invalid summary value: #{ summary.inspect }", caller_locations unless summary_keys.include?(summary) || summary.is_a?(Proc) || summary.nil?
+    summary = nil if SUMMARY_NONE.include?(summary) || summary.nil?
+    if self.class.const_defined?(:Functions)
+      summary = Functions::TF summary if Functions::TABLE_METHODS.include?(summary)
+      summary = Functions::AF summary, name if Functions::AGGREGATE_METHODS.include?(summary)
+    end
+    definition = { name: name, id: id, func: func, format: format, width: width, _width: (width || 0), align: align, summary: summary }.compact
+    @defs << definition
+    @id_field = name if id
+    self
+  end
+
+  # @return [void]
+  def separator str = ' '
+    raise ArgumentError, "Invalid separator: #{ str.inspect }", caller_locations unless str.is_a?(String)
+    @defs << str
+    self
+  end
+
+  # @yield
+  # @yieldparam [Hash] row
+  # @return [void]
+  def inactivate_if &block
+    raise ArgumentError, "Block condition must be specified", caller_locations unless block_given?
+    @inactivate_if = block
+    self
+  end
+
+  # @return [void]
+  def terminal io
+    raise ArgumentError, "Invalid terminal value: #{ io.inspect }", caller_locations unless io.is_a?(IO) && File.chardev?(io)
+    @term = io
+    self
+  end
+
+  public
+
+  # @return [void]
+  def summary show = nil, prefix: nil, **values
+    @show_summary = show unless show.nil?
+    @show_summary = true if @show_summary.nil?
+    @summary_prefix = prefix unless prefix.nil?
+    @summary_values.merge! values.transform_keys(&:to_sym)
+    self
+  end
+
+  # @endgroup
+
+end
+

data/lib/is-term/string_helpers.rb

@@ -0,0 +1,198 @@
+# frozen_string_literal: true
+
+require_relative 'info'
+
+  # Terminal string rendering utilities with proper width calculation for Unicode
+  # characters, emoji, East Asian characters, and ANSI escape sequences.
+  #
+  # This module provides essential string manipulation methods for terminal UIs,
+  # handling complex Unicode display widths correctly while ignoring ANSI color/style
+  # codes. It extends +String+ via Refinements to provide
+  # a clean, chainable API.
+  #
+  # == Features
+  #
+  # * Correct width calculation (emoji=2, CJK=2, ASCII=1, ANSI=0)
+  # * Safe truncation preserving ANSI codes
+  # * Flexible alignment (left, right, center)
+  # * Ellipsis with configurable marker
+  #
+  # == Usage
+  #
+  #   require 'is-term/string_helpers'
+  #
+  # Standalone (no refinements, no includes):
+  #   IS::Term::StringHelpers.str_width("中👨‍⚕️")
+  #   # => 4
+  #
+  # Include private methods:
+  #   include IS::Term::StringHelpers
+  #   str_width("中👨‍⚕️")
+  #   # => 4
+  #
+  # With refinements (recommended):
+  #   using IS::Term::StringHelpers
+  #   "中👨‍⚕️".width       # => 4
+  #   "中👨‍⚕️".ellipsis(3) # => "中…"
+  #
+module IS::Term::StringHelpers
+
+  # @private
+  ESC_CODES = /\e\[[0-9;]*[a-zA-Z]/.freeze
+  # @private
+  EMOJI     = /\p{Emoji_Presentation}/.freeze
+  # @private
+  EAST_ASIA = /\p{Han}|\p{Hiragana}|\p{Katakana}|\p{Hangul}/.freeze
+  # @private
+  TOKEN     = /#{ ESC_CODES }|\X/.freeze
+
+  private_constant :ESC_CODES, :EMOJI, :EAST_ASIA, :TOKEN
+
+  ALIGN_LEFT   = :left
+  ALIGN_RIGHT  = :right
+  ALIGN_CENTER = :center
+  ALIGN_MODES  = [ ALIGN_LEFT, ALIGN_RIGHT, ALIGN_CENTER ].freeze
+
+  DEFAULT_ELLIPSIS_MARKER = '…'
+  DEFAULT_ALIGN_MODE = ALIGN_LEFT
+
+  # Calculates the display width of a string in terminal context.
+  #
+  # Handles Unicode display rules:
+  # * ANSI escape sequences: width 0
+  # * Emoji: width 2
+  # * East Asian characters (Han, Hiragana, Katakana, Hangul): width 2
+  # * Other characters: width 1
+  #
+  # @param str [String] Input string
+  # @return [Integer] Display width in columns
+  # @example
+  #   IS::Term::StringHelpers.str_width("中👨‍⚕️A")         # => 5
+  #   IS::Term::StringHelpers.str_width("\e[31mHi\e[0m") # => 2
+  def str_width str
+    current = 0
+    str.scan(TOKEN) do |match|
+      w = case match
+      when ESC_CODES
+        0
+      when EMOJI, EAST_ASIA
+        2
+      else
+        1
+      end
+      current += w
+    end
+    current
+  end
+
+  # Truncates string to specified display width, preserving ANSI escape sequences.
+  #
+  # ANSI codes are fully skipped (width 0), truncation occurs only on visible
+  # characters. Returns original string if already within width or empty string
+  # for non-positive widths.
+  #
+  # @param str [String] Input string
+  # @param width [Integer] Maximum display width
+  # @return [String] Truncated string (may be empty)
+  # @raise +ArgumentError+ if width is invalid
+  # @example
+  #   IS::Term::StringHelpers.str_truncate("中ABC", 2)            # => "中"
+  #   IS::Term::StringHelpers.str_truncate("\e[31mHello\e[0m", 3) # => "\e[31mHel"
+  def str_truncate str, width
+    return str if str.length <= width
+    return '' if width <= 0
+    current = 0
+    position = 0
+    str.scan(TOKEN) do |match|
+      w = case match
+      when ESC_CODES
+        0
+      when EMOJI, EAST_ASIA
+        2
+      else
+        1
+      end
+      current += w
+      return str[0, position] if current > width
+      position += match.length
+    end
+    str
+  end
+
+  # Truncates string to fit within width, appending ellipsis marker if truncated.
+  #
+  # Raises +ArgumentError+ if marker display width exceeds target width.
+  # Preserves ANSI codes and handles Unicode widths correctly.
+  #
+  # @param str [String] Input string
+  # @param width [Integer] Target display width
+  # @param marker [String] Ellipsis marker (default: +…+)
+  # @return [String] Truncated string with marker or original string
+  # @raise +ArgumentError+ if {str_width} of +marker+ > +width+
+  # @example
+  #   IS::Term::StringHelpers.str_ellipsis("中ABC", 3)  # => "中…"
+  #   IS::Term::StringHelpers.str_ellipsis("short", 10) # => "short"
+  def str_ellipsis str, width, marker = DEFAULT_ELLIPSIS_MARKER
+    marker_width = str_width marker
+    raise ArgumentError, "Marker too long: #{ marker.inspect }", caller_locations if marker_width > width
+    if str_width(str) > width
+      str_truncate(str, width - marker_width) + marker
+    else
+      str
+    end
+  end
+
+  # Aligns string within specified display width using spaces.
+  #
+  # Returns original string if source width is greater than or equal to target.
+  # Supports left, right, and center alignment.
+  #
+  # @param str [String] Input string
+  # @param width [Integer] Target display width
+  # @param mode [:left, :right, :center] Alignment mode
+  # @return [String] Aligned string padded with spaces
+  # @raise +ArgumentError+ if invalid alignment +mode+
+  # @example
+  #   IS::Term::StringHelpers.str_align("hi", 6)          # => "hi    "
+  #   IS::Term::StringHelpers.str_align("hi", 6, :right)  # => "    hi"
+  #   IS::Term::StringHelpers.str_align("hi", 6, :center) # => "  hi  "
+  def str_align str, width, mode = DEFAULT_ALIGN_MODE
+    src_width = str_width str
+    return str if src_width >= width
+    case mode
+    when ALIGN_LEFT
+      str + ' ' * (width - src_width)
+    when ALIGN_RIGHT
+      ' ' * (width - src_width) + str
+    when ALIGN_CENTER
+      left = (width - src_width) / 2
+      right = width - src_width - left
+      ' ' * left + str + ' ' * right
+    else
+      raise ArgumentError, "Invalid align value: #{ mode.inspect }", caller_locations
+    end
+  end
+
+  module_function :str_width, :str_truncate, :str_ellipsis, :str_align
+
+  refine String do
+
+    def width
+      IS::Term::StringHelpers::str_width self
+    end
+
+    def truncate width
+      IS::Term::StringHelpers::str_truncate self, width
+    end
+
+    def ellipsis width, marker = DEFAULT_ELLIPSIS_MARKER
+      IS::Term::StringHelpers::str_ellipsis self, width, marker
+    end
+
+    def align width, mode = DEFAULT_ALIGN_MODE
+      IS::Term::StringHelpers::str_align self, width, mode
+    end
+
+  end
+
+end