fatty 0.99.0 → 0.99.4

data/lib/fatty/progress.rb

@@ -0,0 +1,421 @@
+# frozen_string_literal: true
+
+module Fatty
+  class Progress
+    PARTIAL_BLOCKS = ["", "▏", "▎", "▍", "▌", "▋", "▊", "▉"].freeze
+    FULL_BLOCK = "█"
+    EMPTY_BAR = "."
+
+    SHADE_EMPTY = "░"
+    SHADE_HALF  = "▒"
+    SHADE_FULL  = "▓"
+
+    BRAILLE_STEPS = ["⠀", "⣀", "⣄", "⣆", "⣇", "⣧", "⣷", "⣿"].freeze
+
+    STYLES = %i[
+      count
+      percent
+      count_percent
+      trail
+      bar
+      unicode_bar
+      braille_bar
+      spinner
+      ].freeze
+
+    DEFAULT_LABEL = "Progress"
+    DEFAULT_ROLE = :info
+    DEFAULT_STYLE = :percent
+    DEFAULT_WIDTH = 40
+
+    attr_reader :terminal, :label, :total, :current, :style, :role, :width
+
+    # The width parameter's purpose varies by style:
+    #
+    # | Style          | Width Purpose                                     |
+    # |----------------+---------------------------------------------------|
+    # | :trail         | width = max visible width of the trail portion    |
+    # | :bar           | width = max bar width                             |
+    # | :unicode_bar   | width = max bar width                             |
+    # | :braille_bar   | width = max bar width                             |
+    # | :spinner       | width ignored, unless later used for suffix/trail |
+    # | :count         | width ignored                                     |
+    # | :percent       | width ignored                                     |
+    # | :count_percent | width ignored                                     |
+    def initialize(
+      terminal:,
+      label: DEFAULT_LABEL,
+      total: nil,
+      style: DEFAULT_STYLE,
+      role: DEFAULT_ROLE,
+      width: DEFAULT_WIDTH
+    )
+      @terminal = terminal
+      @label = normalize_label(label)
+      @total = normalize_total(total)
+      @style = normalize_style(style)
+      @role = normalize_role(role)
+      @width = normalize_width(width)
+      @trail = []
+      @current = 0
+      @spinner_index = 0
+      validate_total_requirement!
+      refresh
+    end
+
+    def update(current: nil, indicator: nil, render: false)
+      @current = normalize_current(current) unless current.nil?
+      if style == :spinner
+        advance_spinner
+      else
+        append_indicator(indicator)
+      end
+      refresh(render:)
+      self
+    end
+
+    def finish(message = nil, clear: false, role: @role, render: false)
+      if clear
+        clear_status
+      else
+        text =
+          if message && !message.empty?
+            render_text(suffix: message)
+          else
+            render_text
+          end
+        show_status(text, role: role)
+      end
+      terminal.render_frame if render
+      self
+    end
+
+    def clear
+      clear_status
+      self
+    end
+
+    private
+
+    # simplecov:disable
+
+    def normalize_label(value)
+      text = value.to_s.strip
+      text.empty? ? DEFAULT_LABEL : text
+    end
+
+    # Return the total but not less than 1 to avoid division-by-zero errors
+    # when calculating percentages.
+    def normalize_total(value)
+      return if value.nil?
+
+      val = Integer(value, exception: false)
+      val = 1 unless val
+      [1, val].max
+    end
+
+    def normalize_style(value)
+      candidate = value&.to_sym || DEFAULT_STYLE
+      return candidate if STYLES.include?(candidate)
+
+      raise ArgumentError, "unknown progress style: #{value.inspect}"
+    end
+
+    def normalize_role(value)
+      text = value.to_s.strip
+      return DEFAULT_ROLE if text.empty?
+
+      candidate = text.downcase.to_sym
+      return candidate if %i[good info warn error].include?(candidate)
+
+      raise ArgumentError, "progress role must be :good, :info, :warn, or :error"
+    end
+
+    def normalize_width(value)
+      candidate = Integer(value, exception: false)
+      candidate&.positive? ? candidate : DEFAULT_WIDTH
+    end
+
+    def normalize_current(value)
+      candidate = Integer(value, exception: false)
+      return candidate if candidate
+
+      raise ArgumentError, "progress current must be an integer: #{value.inspect}"
+    end
+
+    def show_status(text, role:)
+      terminal.apply_command(Command.session(:status, :show, text: text, role: role))
+      nil
+    end
+
+    def clear_status
+      terminal.apply_command(Command.session(:status, :clear))
+      nil
+    end
+
+    def append_indicator(indicator)
+      return if indicator.nil?
+
+      item = normalize_indicator(indicator)
+      return if renderable_indicator_text(item).empty?
+
+      @trail << item
+    end
+
+    def refresh(render: false)
+      terminal.without_cursor_restore do
+        terminal.apply_command(
+          Command.session(
+            :status,
+            :show,
+            text: render_text,
+            role: role,
+          )
+        )
+        terminal.render_frame if render
+      end
+      nil
+    end
+
+    def render_text(suffix: nil)
+      case style
+      when :count
+        base = total ? "#{label} [#{current}/#{total}]" : "#{label} [#{current}]"
+        suffix_text(base, suffix)
+      when :percent
+        base = total && total > 0 ? "#{label} #{percent}%" : label.to_s
+        suffix_text(base, suffix)
+      when :count_percent
+        base =
+          if total && total > 0
+            "#{label} [#{current}/#{total}] #{percent}%"
+          else
+            "#{label} [#{current}]"
+          end
+        suffix_text(base, suffix)
+      when :trail
+        render_trail_text(suffix:)
+      when :bar
+        render_bar_text(suffix:, mode: :solid)
+      when :unicode_bar
+        render_bar_text(suffix:, mode: :unicode)
+      when :braille_bar
+        render_bar_text(suffix:, mode: :braille)
+      when :spinner
+        render_spinner_text(suffix:)
+      else
+        raise ArgumentError, "unknown progress style: #{style.inspect}"
+      end
+    end
+
+    def percent
+      ((current.to_f / total.to_f) * 100).round
+    end
+
+    def suffix_text(base, suffix)
+      extra = suffix.to_s
+      return base if extra.empty?
+
+      "#{base}  #{extra}"
+    end
+
+    def render_trail_text(suffix: nil)
+      base =
+        if total && total > 0
+          "#{label} [#{current}/#{total}] #{percent}%"
+        else
+          "#{label} [#{current}]"
+        end
+
+      trailer = suffix.to_s.empty? ? "" : "  #{suffix}"
+      return "#{base}#{trailer}" if @trail.empty?
+
+      [base, "  ", *@trail, trailer]
+    end
+
+    def visible_length(value)
+      if value.is_a?(Hash) && value.key?(:text)
+        Fatty::Ansi.visible_length(value[:text].to_s)
+      else
+        Fatty::Ansi.visible_length(value.to_s)
+      end
+    end
+
+    def normalize_indicator(indicator)
+      if indicator.is_a?(Hash) && indicator.key?(:text)
+        indicator.merge(text: renderable_indicator_text(indicator))
+      else
+        renderable_indicator_text(indicator)
+      end
+    end
+
+    def renderable_indicator_text(item)
+      text =
+        if item.is_a?(Hash) && item.key?(:text)
+          item[:text].to_s
+        else
+          item.to_s
+        end
+      text.gsub(/\s+/, " ").strip
+    end
+
+    def render_bar_text(suffix: nil, mode: :solid)
+      base = label.to_s
+      info = progress_info_text
+      extra = suffix.to_s
+      trailer = extra.empty? ? "" : "  #{extra}"
+
+      bar_width = bar_width_for(base, info, trailer)
+      bar =
+        case mode
+        when :unicode
+          unicode_bar(bar_width)
+        when :braille
+          braille_bar(bar_width)
+        else
+          solid_bar(bar_width)
+        end
+
+      pieces = [base]
+      pieces << "[#{bar}]" unless bar.empty?
+      pieces << info unless info.empty?
+
+      text = pieces.join(" ")
+      text = "#{text}#{trailer}" unless trailer.empty?
+      text
+    end
+
+    def render_spinner_text(suffix: nil)
+      frame = spinner_frames[@spinner_index % spinner_frames.length]
+      base =
+        if total && total > 0
+          "#{label} #{frame} #{percent}%"
+        else
+          "#{label} #{frame}"
+        end
+
+      suffix_text(base, suffix)
+    end
+
+    def progress_info_text
+      if total && total > 0
+        "#{percent}% [#{current}/#{total}]"
+      else
+        "[#{current}]"
+      end
+    end
+
+    def bar_width_for(base, info, trailer)
+      cols =
+        if terminal.screen
+          terminal.screen.cols.to_i
+        else
+          80
+        end
+
+      reserved = visible_length(base)
+      reserved += 1 + visible_length(info) unless info.empty?
+      reserved += visible_length(trailer) unless trailer.empty?
+
+      # Space for:
+      #   " ["
+      #   "]"
+      # around the bar
+      available = cols - reserved - 4
+      available = 0 if available < 0
+      [available, @width].min
+    end
+
+    def solid_bar(width)
+      return "" if width <= 0
+
+      ratio = progress_ratio
+      filled = (ratio * width).round
+      filled = 0 if filled < 0
+      filled = width if filled > width
+
+      empty = width - filled
+      (FULL_BLOCK * filled) + (EMPTY_BAR * empty)
+    end
+
+    def unicode_bar(width)
+      return "" if width <= 0
+
+      raw = progress_ratio * width
+      full = raw.floor
+
+      # Show a transition block whenever the bar is in progress but not complete,
+      # provided there is space for it.
+      half =
+        if progress_ratio.positive? && progress_ratio < 1.0 && full < width
+          1
+        else
+          0
+        end
+
+      bar = +""
+      bar << (SHADE_FULL * full)
+      bar << SHADE_HALF if half == 1
+
+      remaining = width - Fatty::Ansi.visible_length(bar)
+      remaining = 0 if remaining < 0
+      bar << (SHADE_EMPTY * remaining)
+      bar
+    end
+
+    def braille_bar(width)
+      return "" if width <= 0
+
+      raw = progress_ratio * width
+      full = raw.floor
+      remainder = raw - full
+
+      partial_idx = (remainder * (BRAILLE_STEPS.length - 1)).round
+      partial_idx = 0 if partial_idx < 0
+      partial_idx = BRAILLE_STEPS.length - 1 if partial_idx >= BRAILLE_STEPS.length
+
+      bar = +""
+      bar << (BRAILLE_STEPS[-1] * full)
+
+      if progress_ratio.positive? && progress_ratio < 1.0 && full < width
+        partial =
+          if partial_idx.zero?
+            BRAILLE_STEPS[1]
+          else
+            BRAILLE_STEPS[partial_idx]
+          end
+        bar << partial
+      end
+
+      remaining = width - Fatty::Ansi.visible_length(bar)
+      remaining = 0 if remaining < 0
+      bar << (BRAILLE_STEPS[0] * remaining)
+      bar
+    end
+
+    def progress_ratio
+      return 0.0 unless total && total > 0
+
+      ratio = current.to_f / total.to_f
+      ratio = 0.0 if ratio < 0.0
+      ratio = 1.0 if ratio > 1.0
+      ratio
+    end
+
+    def validate_total_requirement!
+      return if style == :spinner && total.nil?
+      return if total&.positive?
+
+      raise ArgumentError,
+            "progress style #{style.inspect} requires a positive integer total:"
+    end
+
+    def advance_spinner
+      @spinner_index = (@spinner_index + 1) % spinner_frames.length
+    end
+
+    def spinner_frames
+      BRAILLE_STEPS[1..]
+    end
+  end
+end