tty-progressbar 0.17.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,17 +1,18 @@
 # frozen_string_literal: true
 
-require 'io/console'
-require 'forwardable'
-require 'monitor'
-require 'tty-cursor'
-require 'tty-screen'
-require 'strings-ansi'
-require 'unicode/display_width'
-
-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
@@ -21,7 +22,9 @@ module TTY
     extend Forwardable
     include MonitorMixin
 
-    ECMA_CSI = "\e[".freeze
+    ECMA_CSI = "\e["
+
+    NEWLINE = "\n"
 
     CURSOR_LOCK = Monitor.new
 
@@ -29,17 +32,15 @@ module TTY
 
     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, :inset, :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
     #
@@ -64,6 +65,12 @@ module TTY
 
     # 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
     #
@@ -71,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 = {})
@@ -97,34 +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
+      @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            = {}
 
       @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
@@ -137,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
 
@@ -163,17 +210,21 @@ module TTY
         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
@@ -190,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
@@ -257,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
@@ -272,7 +331,9 @@ 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
 
@@ -281,7 +342,7 @@ module TTY
         update(inset: self.class.display_columns(characters_in))
       end
 
-      formatted = @formatter.decorate(self, @format)
+      formatted = @formatters.decorate(@format)
       @tokens.each do |token, val|
         formatted = formatted.gsub(":#{token}", val)
       end
@@ -304,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
@@ -343,6 +404,7 @@ module TTY
     # @api public
     def resize(new_width = nil)
       return if done?
+
       synchronize do
         clear_line
         if new_width
@@ -356,12 +418,14 @@ module TTY
     # @api public
     def finish
       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
@@ -371,31 +435,57 @@ module TTY
       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
@@ -414,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
@@ -445,14 +544,14 @@ 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
 
@@ -472,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
 
@@ -492,7 +592,7 @@ module TTY
 
       if @last_render_width > message_length
         remaining_width = @last_render_width - message_length
-        message += ' ' * remaining_width
+        message += " " * remaining_width
       end
       message
     end
@@ -505,7 +605,7 @@ module TTY
     # @api private
     def emit(name, *args)
       @callbacks[name].each do |callback|
-        callback.call(*args)
+        callback.(*args)
       end
     end