tty-progressbar 0.14.0 → 0.18.0

data/lib/tty-progressbar.rb

@@ -1,2 +1,2 @@
-require_relative 'tty/progressbar'
-require_relative 'tty/progressbar/multi'
+require_relative "tty/progressbar"
+require_relative "tty/progressbar/multi"

data/lib/tty/progressbar.rb

@@ -1,15 +1,18 @@
 # frozen_string_literal: true
 
-require 'io/console'
-require 'forwardable'
-require 'monitor'
-require 'tty-cursor'
-require 'tty-screen'
-
-require_relative 'progressbar/configuration'
-require_relative 'progressbar/formatter'
-require_relative 'progressbar/meter'
-require_relative 'progressbar/version'
+require "io/console"
+require "forwardable"
+require "monitor"
+require "tty-cursor"
+require "tty-screen"
+require "strings-ansi"
+require "unicode/display_width"
+
+require_relative "progressbar/timer"
+require_relative "progressbar/configuration"
+require_relative "progressbar/formatters"
+require_relative "progressbar/meter"
+require_relative "progressbar/version"
 
 module TTY
   # Used for creating terminal progress bar
@@ -19,28 +22,55 @@ module TTY
     extend Forwardable
     include MonitorMixin
 
-    ECMA_CSI = "\e[".freeze
+    ECMA_CSI = "\e["
+
+    NEWLINE = "\n"
 
     CURSOR_LOCK = Monitor.new
 
-    attr_reader :format
+    attr_accessor :format
 
     attr_reader :current
 
-    attr_reader :start_at
-
     attr_reader :row
 
-    def_delegators :@configuration, :total, :width, :no_width,
-                   :complete, :incomplete, :head, :hide_cursor, :clear,
-                   :output, :frequency, :interval, :width=
+    def_delegators :@configuration, :total, :width, :complete, :incomplete,
+                   :head, :clear_head, :hide_cursor, :clear, :output,
+                   :frequency, :interval, :inset, :width=, :unknown, :bar_format
 
     def_delegators :@meter, :rate, :mean_rate
 
-    def_delegator :@formatter, :use
+    def_delegators :@timer, :elapsed_time, :start_time
+
+    # Determine terminal width
+    #
+    # @return [Integer]
+    #
+    # @api public
+    def self.max_columns
+      TTY::Screen.width
+    end
+
+    # Determine the monospace display width of a string
+    #
+    # @param [String] value
+    #   the value to determine width of
+    #
+    # @return [Integer]
+    #
+    # @api public
+    def self.display_columns(value)
+      Unicode::DisplayWidth.of(Strings::ANSI.sanitize(value))
+    end
 
     # Create progress bar
     #
+    # @example
+    #   bar = TTY::Progressbar.new
+    #   bar.configure do |config|
+    #     config.total = 20
+    #   end
+    #
     # @param [String] format
     #   the tokenized string that displays the output
     #
@@ -48,20 +78,29 @@ module TTY
     # @option options [Numeric] :total
     #   the total number of steps to completion
     # @option options [Numeric] :width
-    #   the maximum width for the bars display including
-    #   all formatting options
-    # @option options [Boolean] :no_width
-    #   true when progression is unknown defaulting to false
-    # @option options [Boolean] :clear
-    #   whether or not to clear the progress line
-    # @option options [Boolean] :hide_cursor
-    #   display or hide cursor
+    #   the maximum width for the progress bar except all formatting tokens
+    # @option option [String] :complete
+    #   the complete character in progress animation
+    # @option options [String] :incomplete
+    #   the incomplete character in progress animation
+    # @option options [String] :head
+    #   the head character, defaults to complete
+    # @option options [String] :unknown
+    #   the unknown character for indeterminate progress animation
+    # @option options [Boolean] :bar_format
+    #   the preconfigured bar format name, defaults to :classic
     # @option options [Object] :output
-    #   the object that responds to print call defaulting to stderr
+    #   the object that responds to print call, defaults to stderr
     # @option options [Number] :frequency
-    #   the frequency with which to display bars
+    #   the frequency with which to display a progress bar per second
     # @option options [Number] :interval
-    #   the period for sampling of speed measurement
+    #   the time interval for sampling of speed measurement, defaults to 1 second
+    # @option options [Boolean] :hide_cursor
+    #   whether or not to hide the cursor, defaults to false
+    # @option options [Boolean] :clear
+    #   whether or not to clear the progress line, defaults to false
+    # @option options [Boolean] :clear_head
+    #   whether or not to replace head character with complete, defaults to false
     #
     # @api public
     def initialize(format, options = {})
@@ -74,33 +113,52 @@ module TTY
       @configuration = TTY::ProgressBar::Configuration.new(options)
       yield @configuration if block_given?
 
-      @formatter = TTY::ProgressBar::Formatter.new
-      @meter     = TTY::ProgressBar::Meter.new(interval)
+      @formatters = TTY::ProgressBar::Formatters.new
+      @meter = TTY::ProgressBar::Meter.new(interval)
+      @timer = TTY::ProgressBar::Timer.new
       @callbacks = Hash.new { |h, k| h[k] = [] }
 
-      @formatter.load
+      @formatters.load(self)
       reset
+
+      @first_render = true
+      @multibar = nil
+      @row = nil
     end
 
     # Reset progress to default configuration
     #
     # @api public
     def reset
-      @width             = 0 if no_width
+      @width             = 0 if indeterminate?
       @render_period     = frequency == 0 ? 0 : 1.0 / frequency
       @current           = 0
+      @unknown           = 0
       @last_render_time  = Time.now
       @last_render_width = 0
       @done              = false
       @stopped           = false
-      @start_at          = Time.now
-      @started           = false
+      @paused            = false
       @tokens            = {}
-      @multibar          = nil
-      @row               = nil
-      @first_render      = true
 
       @meter.clear
+      @timer.reset
+    end
+
+    # Access instance configuration
+    #
+    # @api public
+    def configure
+      yield @configuration
+    end
+
+    # Check if progress can be determined or not
+    #
+    # @return [Boolean]
+    #
+    # @api public
+    def indeterminate?
+      total.nil?
     end
 
     # Attach this bar to multi bar
@@ -113,13 +171,26 @@ module TTY
       @multibar = multibar
     end
 
+    # Use custom token formatter
+    #
+    # @param [Object] formatter_class
+    #   the formatter class to add to formatting pipeline
+    #
+    # @api public
+    def use(formatter_class)
+      unless formatter_class.is_a?(Class)
+        raise ArgumentError, "Formatter needs to be a class"
+      end
+
+      @formatters.use(formatter_class.new(self))
+    end
+
     # Start progression by drawing bar and setting time
     #
     # @api public
     def start
       synchronize do
-        @started  = true
-        @start_at = Time.now
+        @timer.start
         @meter.start
       end
 
@@ -135,21 +206,25 @@ module TTY
       return if done?
 
       synchronize do
-        emit(:progress)
+        emit(:progress, progress)
         if progress.respond_to?(:to_hash)
           tokens, progress = progress, 1
         end
-        @start_at  = Time.now if @current.zero? && !@started
-        @current  += progress
-        @tokens    = tokens
+        @timer.start
+        @current += progress
+        # When progress is unknown increase by 2% up to max 200%, after
+        # that reset back to 0%
+        @unknown += 2 if indeterminate?
+        @unknown = 0 if @unknown > 199
+        @tokens = tokens
         @meter.sample(Time.now, progress)
 
-        if !no_width && @current >= total
+        if !indeterminate? && @current >= total
           finish && return
         end
 
-        now = Time.now
-        return if (now - @last_render_time) < @render_period
+        return if (Time.now - @last_render_time) < @render_period
+
         render
       end
     end
@@ -166,7 +241,7 @@ module TTY
     #   be convenient in "unsure number of iterations" situations
     #   (like downloading in chunks, when server may eventually send
     #   more chunks than predicted), but be careful to not pass infinite
-    #   enumerators without previosly doing `.take(some_finite_number)`
+    #   enumerators without previously doing `.take(some_finite_number)`
     #   on them.
     #
     # @example
@@ -201,7 +276,9 @@ module TTY
     def update(options = {})
       synchronize do
         options.each do |name, val|
-          @configuration.public_send("#{name}=", val)
+          if @configuration.respond_to?("#{name}=")
+            @configuration.public_send("#{name}=", val)
+          end
         end
       end
     end
@@ -231,12 +308,20 @@ module TTY
 
     # Ratio of completed over total steps
     #
+    # When the total is unknown the progress ratio oscillates
+    # by going up from 0 to 1 and then down from 1 to 0 and
+    # up again to infinity.
+    #
     # @return [Float]
     #
     # @api public
     def ratio
       synchronize do
-        proportion = total > 0 ? (@current.to_f / total) : 0
+        proportion = if total
+                       total > 0 ? (@current.to_f / total) : 0
+                     else
+                       (@unknown > 100 ? 200 - @unknown : @unknown).to_f / 100
+                     end
         [[proportion, 0].max, 1].min
       end
     end
@@ -246,18 +331,28 @@ module TTY
     # @api private
     def render
       return if done?
-      if hide_cursor && @last_render_width == 0 && !(@current >= total)
+
+      if hide_cursor && @last_render_width == 0 &&
+         (indeterminate? || @current < total)
         write(TTY::Cursor.hide)
       end
 
-      formatted = @formatter.decorate(self, @format)
+      if @multibar
+        characters_in = @multibar.line_inset(self)
+        update(inset: self.class.display_columns(characters_in))
+      end
+
+      formatted = @formatters.decorate(@format)
       @tokens.each do |token, val|
         formatted = formatted.gsub(":#{token}", val)
       end
-      write(formatted, true)
+
+      padded = padout(formatted)
+
+      write(padded, true)
 
       @last_render_time  = Time.now
-      @last_render_width = formatted.length
+      @last_render_width = self.class.display_columns(formatted)
     end
 
     # Move cursor to a row of the current bar if the bar is rendered
@@ -270,7 +365,7 @@ module TTY
           if @first_render
             @row = @multibar.next_row
             yield if block_given?
-            output.print "\n"
+            output.print NEWLINE
             @first_render = false
           else
             lines_up = (@multibar.rows + 1) - @row
@@ -309,6 +404,7 @@ module TTY
     # @api public
     def resize(new_width = nil)
       return if done?
+
       synchronize do
         clear_line
         if new_width
@@ -321,45 +417,75 @@ module TTY
     #
     # @api public
     def finish
-      # reenable cursor if it is turned off
-      if hide_cursor && @last_render_width != 0
-        write(TTY::Cursor.show, false)
-      end
       return if done?
-      @current = total unless no_width
+
+      @current = total unless indeterminate?
       render
-      clear ? clear_line : write("\n", false)
+      clear ? clear_line : write(NEWLINE, false)
     ensure
       @meter.clear
       @done = true
+      @timer.stop
+
+      # reenable cursor if it is turned off
+      if hide_cursor && @last_render_width != 0
+        write(TTY::Cursor.show, false)
+      end
+
       emit(:done)
     end
 
+    # Resume rendering when bar is done, stopped or paused
+    #
+    # @api public
+    def resume
+      synchronize do
+        @done = false
+        @stopped = false
+        @paused = false
+      end
+    end
+
     # Stop and cancel the progress at the current position
     #
     # @api public
     def stop
-      # reenable cursor if it is turned off
-      if hide_cursor && @last_render_width != 0
-        write(TTY::Cursor.show, false)
-      end
       return if done?
+
       render
-      clear ? clear_line : write("\n", false)
+      clear ? clear_line : write(NEWLINE, false)
     ensure
       @meter.clear
       @stopped = true
+      @timer.stop
+
+      # reenable cursor if it is turned off
+      if hide_cursor && @last_render_width != 0
+        write(TTY::Cursor.show, false)
+      end
+
       emit(:stopped)
     end
 
+    # Pause the progress at the current position
+    #
+    # @api public
+    def pause
+      synchronize do
+        @paused = true
+        @timer.stop
+        emit(:paused)
+      end
+    end
+
     # Clear current line
     #
     # @api public
     def clear_line
-      output.print(ECMA_CSI + '0m' + TTY::Cursor.clear_line)
+      output.print("#{ECMA_CSI}0m#{TTY::Cursor.clear_line}")
     end
 
-    # Check if progress is finised
+    # Check if progress is finished
     #
     # @return [Boolean]
     #   true when progress finished, false otherwise
@@ -378,13 +504,22 @@ module TTY
       @stopped
     end
 
-    # Check if progress is finished or stopped
+    # Check if progress is paused
+    #
+    # @return [Boolean]
+    #
+    # @api public
+    def paused?
+      @paused
+    end
+
+    # Check if progress is finished, stopped or paused
     #
     # @return [Boolean]
     #
     # @api public
     def done?
-      @done || @stopped
+      @done || @stopped || @paused
     end
 
     # Register callback with this bar
@@ -409,26 +544,17 @@ module TTY
     #
     # @api public
     def log(message)
-      sanitized_message = message.gsub(/\r|\n/, ' ')
+      sanitized_message = message.gsub(/\r|\n/, " ")
       if done?
-        write(sanitized_message + "\n", false)
+        write("#{sanitized_message}#{NEWLINE}", false)
         return
       end
       sanitized_message = padout(sanitized_message)
 
-      write(sanitized_message + "\n", true)
+      write("#{sanitized_message}#{NEWLINE}", true)
       render
     end
 
-    # Determine terminal width
-    #
-    # @return [Integer]
-    #
-    # @api public
-    def max_columns
-      TTY::Screen.width
-    end
-
     # Show bar format
     #
     # @return [String]
@@ -445,13 +571,14 @@ module TTY
     # @api public
     def inspect
       "#<#{self.class.name} " \
-      "@format=\"#{format}\", " \
+      "@format=\"#{@format}\", " \
       "@current=\"#{@current}\", " \
       "@total=\"#{total}\", " \
       "@width=\"#{width}\", " \
       "@complete=\"#{complete}\", " \
       "@head=\"#{head}\", " \
       "@incomplete=\"#{incomplete}\", " \
+      "@unknown=\"#{unknown}\", " \
       "@interval=\"#{interval}\">"
     end
 
@@ -461,9 +588,11 @@ module TTY
     #
     # @api private
     def padout(message)
-      if @last_render_width > message.length
-        remaining_width = @last_render_width - message.length
-        message += ' ' * remaining_width
+      message_length = self.class.display_columns(message)
+
+      if @last_render_width > message_length
+        remaining_width = @last_render_width - message_length
+        message += " " * remaining_width
       end
       message
     end
@@ -476,7 +605,7 @@ module TTY
     # @api private
     def emit(name, *args)
       @callbacks[name].each do |callback|
-        callback.call(*args)
+        callback.(*args)
       end
     end