tty-progressbar 0.5.1 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 2f2cf9c0a69a06ce555230e540d06eb2ead51d7b
-  data.tar.gz: 658a14537dd201fbab6378aa4acc27c6e8cc216e
+  metadata.gz: 054aa5020aa87b8cd5b5899fb2f6eb512f0d3f4f
+  data.tar.gz: dbb0d52019b12e27b032bb61d3a839034e319e98
 SHA512:
-  metadata.gz: 89b95358acafece957b2f627dfde1e70ba4455acde5c1f186555db8f669437521d53d9e266980c0cf4d2d1d5c838cc71decd1ef90e08c3ea53abafac6c031e62
-  data.tar.gz: 974c483f4a929549136c981213eefe26dd378eeadfcfc7cae6f97e7033f4593f8c321afbfbfdca50f25bc58f366197274168176892e0550a567f789ed5bf73ba
+  metadata.gz: f4b8f93d30a0ad12bd80ecf94541b4fbd574d5aa1c6ab063dfacf439116f2258586560bcc236f6d91b25e6c77f19d89ee148edfa8fa7b96acb0c2bbb90505e3e
+  data.tar.gz: cd3020b089d687a5ccca2d1b4d5d7193bdad58bed77eec7864550121964e5b3e62776e2e758becf6736e3c5677cda2e297082475dca5d379745409e5da128232

data/CHANGELOG.md

@@ -1,3 +1,9 @@
+0.6.0 (June 27, 2015)
+
+* Add ability to add custom tokens
+* Internal cleanup of parameters for formatters and pipeline
+* Fix ratio to avoid division by zero by @sleewoo issue #9
+
 0.5.1 (May 31, 2015)
 
 * Update tty-screen dependency with bug fixes

data/Gemfile

@@ -4,7 +4,7 @@ gemspec
 
 group :development do
   gem 'rake',    '~> 10.3.2'
-  gem 'rspec',   '~> 3.1.0'
+  gem 'rspec',   '~> 3.3.0'
   gem 'yard',    '~> 0.8.7'
   gem 'timecop', '~> 0.7.1'
   gem 'pastel',  '~> 0.4.0'

data/README.md

@@ -54,7 +54,8 @@ Or install it yourself as:
   * [2.2 Interval](#22-interval)
 * [3. Formatting](#3-formatting)
   * [3.1 Tokens](#31-tokens)
-  * [3.2 Custom Formatters](#31-custom-formatters)
+  * [3.2 Custom Formatters](#32-custom-formatters)
+  * [3.3 Custom Tokens](#33-custom-tokens)
 * [4. Logging](#4-logging)
 * [5. Examples](#5-examples)
   * [5.1 Color](#51-color)
@@ -224,29 +225,23 @@ These are the tokens that are currently supported:
 
 ### 3.2 Custom Formatters
 
-If the provided tokens do not meet your needs, you can write your own formatter and instrument formatting pipeline to use a formatter you prefer.
+If the provided tokens do not meet your needs, you can write your own formatter and instrument formatting pipeline to use a formatter you prefer. This option is preferred if you are going to rely on progress bar internal data such as `rate`, `current` etc. which will all be available on the passed in progress bar instance.
 
 For example, begin by creating custom formatter called `TimeFormatter` that will dynamicly update `:time` token in format string. The methods that you need to specify are `initialize`, `matches?` and `format` like follows:
 
 ```ruby
 class TimeFormatter
   def initialize(progress)
-    @progress = progress
+    @progress = progress # current progress bar instance
   end
 
-  def matches?(value)  # specify condition to match for
+  def matches?(value)  # specify condition to match for in display string
     value.to_s =~ /:time/
   end
 
-  def format(value)  # specify how value is formatted
-    transformed = transform(value)
-    value.gsub(/:time/, transformed.to_s)   # => :time token
-  end
-
-  private
-
-  def transfrom
-    value * (Time.now - @progress.start_at).to_i
+  def format(value)  # specify how display string is formatted
+    transformed = (Time.now - @progress.start_at).to_s
+    value.gsub(/:time/, transformed)   # => :time token replacement
   end
 end
 ```
@@ -265,6 +260,29 @@ Then add `TimeFormatter` to the pipeline like so:
 bar.use TimeFormatter
 ```
 
+and then invoke progression:
+
+```ruby
+bar.advance
+```
+
+### 3.3 Custom Tokens
+
+You can define custom tokens by passing pairs `name: value` to `advance` method in order to dynamically update formatted bar. This option is useful for lightweight content replacement such as titles that doesn't depend on the internal data of progressbar. For example:
+
+```ruby
+bar = TTY::ProgressBar.new("(:current) :title", total: 4)
+bar.advance(title: 'Hello Piotr!')
+bar.advance(3, title: 'Bye Piotr!')
+```
+
+which outputs:
+
+```ruby
+(1) Hello Piotr!
+(4) Bye Piotr!
+```
+
 ## 4. Logging
 
 If you want to print messages out to terminal along with the progress bar use the `log` method. The messages will appear above the progress bar and will continue scrolling up as more are logged out.

data/examples/color.rb

@@ -1,3 +1,5 @@
+# coding: utf-8
+
 require 'tty-progressbar'
 require 'pastel'
 

data/examples/simple.rb

@@ -1,3 +1,5 @@
+# coding: utf-8
+
 require 'tty-progressbar'
 
 bar = TTY::ProgressBar.new("downloading [:bar] :elapsed :percent", total: 30)

data/examples/tokens.rb

@@ -0,0 +1,14 @@
+# coding: utf-8
+
+require 'tty-progressbar'
+
+files = [
+  'file1.txt', 'file2.txt', 'file3.txt', 'file4.txt', 'file5.txt',
+  'file6.txt', 'file7.txt', 'file8.txt', 'file9.txt', 'file10.txt'
+]
+
+bar = TTY::ProgressBar.new("downloading :file :percent", total: files.size)
+10.times do |num|
+  sleep(0.1)
+  bar.advance(file: files[num])
+end

data/lib/tty/progressbar.rb

@@ -51,6 +51,8 @@ module TTY
     #   the object that responds to print call defaulting to stderr
     # @option options [Number] :frequency
     #   the frequency with which to display bars
+    # @option options [Number] :interval
+    #   the period for sampling of speed measurement
     #
     # @api public
     def initialize(format, options = {})
@@ -67,6 +69,7 @@ module TTY
       @done              = false
       @start_at          = Time.now
       @started           = false
+      @tokens            = {}
       @formatter         = TTY::ProgressBar::Formatter.new
       @meter             = Meter.new(options.fetch(:interval, 1))
 
@@ -78,8 +81,8 @@ module TTY
     #
     # @api public
     def start
-      @started    = true
-      @started_at = Time.now
+      @started  = true
+      @start_at = Time.now
       @meter.start
 
       advance(0)
@@ -90,12 +93,16 @@ module TTY
     # @param [Object|Number] progress
     #
     # @api public
-    def advance(progress = 1)
+    def advance(progress = 1, tokens = {})
       return if @done
 
+      if progress.respond_to?(:to_hash)
+        tokens, progress = progress, 1
+      end
       @start_at  = Time.now if @current.zero? && !@started
       @readings += 1
       @current  += progress
+      @tokens    = tokens
       @meter.sample(Time.now, progress)
 
       if !no_width && @current >= total
@@ -136,7 +143,7 @@ module TTY
     #
     # @api public
     def ratio
-      proportion = (@current.to_f / total)
+      proportion = total > 0 ? (@current.to_f / total) : 0
       [[proportion, 0].max, 1].min
     end
 
@@ -150,6 +157,9 @@ module TTY
       end
 
       formatted = @formatter.decorate(self, @format)
+      @tokens.each do |token, val|
+        formatted = formatted.gsub(":#{token}", val)
+      end
       write(formatted, true)
 
       @last_render_time  = Time.now

data/lib/tty/progressbar/formatter.rb

@@ -9,7 +9,7 @@ module TTY
 
       # @api private
       def initialize(pipeline = nil)
-        @pipeline = TTY::ProgressBar::Pipeline.new
+        @pipeline = pipeline || TTY::ProgressBar::Pipeline.new
       end
 
       # Prepare default pipeline formatters

data/lib/tty/progressbar/formatter/bar.rb

@@ -8,7 +8,7 @@ module TTY
     class BarFormatter
       MATCHER = /:bar/.freeze
 
-      def initialize(progress, *args, &block)
+      def initialize(progress)
         @progress = progress
       end
 

data/lib/tty/progressbar/formatter/byte_rate.rb

@@ -2,7 +2,7 @@
 
 module TTY
   class ProgressBar
-    # Used by {Pipeline} to format :current token
+    # Used by {Pipeline} to format :byte_rate token
     #
     # @api private
     class ByteRateFormatter

data/lib/tty/progressbar/formatter/current_byte.rb

@@ -2,11 +2,12 @@
 
 module TTY
   class ProgressBar
+    # Used by {Pipeline} to format :byte and :current_byte tokens
+    #
+    # @api private
     class ByteFormatter
       MATCHER = /(:current_byte|:byte)\b/i.freeze
-      # Used by {Pipeline} to format :byte token
-      #
-      # @api private
+
       def initialize(progress)
         @progress = progress
         @converter = Converter.new

data/lib/tty/progressbar/formatter/elapsed.rb

@@ -8,7 +8,7 @@ module TTY
     class ElapsedFormatter
       MATCHER = /:elapsed/.freeze
 
-      def initialize(progress, *args, &block)
+      def initialize(progress)
         @progress  = progress
         @converter = Converter.new
       end

data/lib/tty/progressbar/formatter/mean_byte.rb

@@ -2,7 +2,7 @@
 
 module TTY
   class ProgressBar
-    # Used by {Pipeline} to format :current token
+    # Used by {Pipeline} to format :mean_byte token
     #
     # @api private
     class MeanByteFormatter

data/lib/tty/progressbar/formatter/mean_rate.rb

@@ -2,7 +2,7 @@
 
 module TTY
   class ProgressBar
-    # Used by {Pipeline} to format :current token
+    # Used by {Pipeline} to format :mean_rate token
     #
     # @api private
     class MeanRateFormatter

data/lib/tty/progressbar/formatter/rate.rb

@@ -2,7 +2,7 @@
 
 module TTY
   class ProgressBar
-    # Used by {Pipeline} to format :current token
+    # Used by {Pipeline} to format :rate token
     #
     # @api private
     class RateFormatter

data/lib/tty/progressbar/formatter/total.rb

@@ -2,6 +2,9 @@
 
 module TTY
   class ProgressBar
+    # Used by {Pipeline} to format :total token
+    #
+    # @api private
     class TotalFormatter
       MATCHER = /:total\b/i.freeze
 

data/lib/tty/progressbar/meter.rb

@@ -22,6 +22,9 @@ module TTY
         @last_sample_at = @start_time
       end
 
+      # Start sampling timer
+      #
+      # @api public
       def start
         @start_time     = Time.now.to_f
         @last_sample_at = @start_time
@@ -31,7 +34,7 @@ module TTY
       #
       # @api public
       def sample(at, value)
-        if @interval < at.to_f - @last_sample_at
+        if @interval < (at.to_f - @last_sample_at)
           @marker += 1
         end
         @samples[@marker] << value
@@ -39,7 +42,10 @@ module TTY
         @last_sample_at = at.to_f
       end
 
-      # The rate of sampling
+      # The current rate of sampling for a given interval
+      #
+      # @return [Number]
+      #   the current rate in decimal or 0 if cannot be determined
       #
       # @api public
       def rate
@@ -57,7 +63,10 @@ module TTY
         end
       end
 
-      # The mean rate
+      # The mean rate of all the sampled rates
+      #
+      # @return [Number]
+      #   the mean rate
       #
       # @api public
       def mean_rate

data/lib/tty/progressbar/pipeline.rb

@@ -8,17 +8,29 @@ module TTY
     class Pipeline
       include Enumerable
 
+      # Create formatting pipeline
+      #
+      # @api private
       def initialize(formatters = [])
         @formatters = formatters
+        freeze
       end
 
-      # Add new formatter
+      # Add a new formatter
+      #
+      # @example
+      #   use(TTY::ProgressBar::TotalFormatter)
       #
-      # @ api public
-      def use(formatter, *args, &block)
-        formatters << proc { |progress| formatter.new(progress, *args, &block) }
+      # @api public
+      def use(formatter)
+        formatters << proc { |progress| formatter.new(progress) }
       end
 
+      # Decorate the tokenized string with actual values
+      #
+      # @return [nil]
+      #
+      # @api private
       def decorate(progress, tokenized)
         base = tokenized.dup
         formatters.inject(base) do |formatted, formatter|

data/lib/tty/progressbar/version.rb

@@ -2,6 +2,6 @@
 
 module TTY
   class ProgressBar
-    VERSION = '0.5.1'
+    VERSION = '0.6.0'
   end # ProgressBar
 end # TTY

data/spec/unit/advance_spec.rb

@@ -1,10 +1,14 @@
 # coding: utf-8
 
-require 'spec_helper'
-
 RSpec.describe TTY::ProgressBar, '.advance' do
   let(:output) { StringIO.new('', 'w+') }
 
+  it "advances by custom value" do
+    progress = TTY::ProgressBar.new("[:bar]", output: output, total: 10)
+    progress.advance(8)
+    expect(progress.current).to eq(8)
+  end
+
   it "allows to go back" do
     progress = TTY::ProgressBar.new("[:bar]", output: output, total: 10)
     5.times { progress.advance(1) }

data/spec/unit/custom_formatter_spec.rb

@@ -1,14 +1,12 @@
 # coding: utf-8
 
-require 'spec_helper'
-
-RSpec.describe TTY::ProgressBar, 'custom' do
+RSpec.describe TTY::ProgressBar, 'custom formatter' do
   let(:output) { StringIO.new('', 'w+') }
 
   it "allows for custom tag" do
     progress = TTY::ProgressBar.new(":hi", output: output, total: 10)
 
-    HiFormatter = Class.new do
+    stub_const("HiFormatter", Class.new do
       def initialize(progress)
         @progress = progress
       end
@@ -20,7 +18,7 @@ RSpec.describe TTY::ProgressBar, 'custom' do
       def format(value)
         value.gsub(/:hi/, "Hello")
       end
-    end
+    end)
 
     progress.use(HiFormatter)
     progress.advance

data/spec/unit/custom_token_spec.rb

@@ -0,0 +1,16 @@
+# coding: utf-8
+
+RSpec.describe TTY::ProgressBar, 'custom token' do
+  let(:output) { StringIO.new('', 'w+') }
+
+  it "allows to specify custom tokens" do
+    progress = TTY::ProgressBar.new("(:current) :title", output: output, total: 4)
+    progress.advance(title: 'Hello Piotr!')
+    progress.advance(3, title: 'Bye Piotr!')
+    output.rewind
+    expect(output.read).to eq([
+      "\e[1G(1) Hello Piotr!",
+      "\e[1G(4) Bye Piotr!\n"
+    ].join)
+  end
+end

data/spec/unit/meter_spec.rb

@@ -1,8 +1,6 @@
 # coding: utf-8
 
-require 'spec_helper'
-
-RSpec.describe TTY::ProgressBar::Meter, '' do
+RSpec.describe TTY::ProgressBar::Meter, '.rate' do
 
   before { Timecop.safe_mode = false }
 
@@ -69,4 +67,3 @@ RSpec.describe TTY::ProgressBar::Meter, '' do
     expect(meter.rate).to eq(0)
   end
 end
-

data/spec/unit/ratio_spec.rb

@@ -1,8 +1,6 @@
 # coding: utf-8
 
-require 'spec_helper'
-
-RSpec.describe TTY::ProgressBar, 'ratio=' do
+RSpec.describe TTY::ProgressBar, '.ratio=' do
   let(:output) { StringIO.new('', 'w+') }
 
   it "allows to set ratio" do
@@ -20,4 +18,16 @@ RSpec.describe TTY::ProgressBar, 'ratio=' do
     progress.ratio = 0.5
     expect(progress.current).to eq(1)
   end
+
+  it "doesn't allow to set wrong ratio" do
+    progress = TTY::ProgressBar.new("[:bar]", output: output, total: 3)
+    progress.ratio = 3.2
+    expect(progress.current).to eq(3)
+    expect(progress.complete?).to eq(true)
+  end
+
+  it "avoids division by zero" do
+    progress = TTY::ProgressBar.new("[:bar]", output: output, total: 0)
+    expect(progress.ratio).to eq(0)
+  end
 end

data/tasks/console.rake

@@ -8,3 +8,4 @@ task :console do
   ARGV.clear
   IRB.start
 end
+task :c => :console

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: tty-progressbar
 version: !ruby/object:Gem::Version
-  version: 0.5.1
+  version: 0.6.0
 platform: ruby
 authors:
 - Piotr Murach
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-05-31 00:00:00.000000000 Z
+date: 2015-06-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: tty-screen
@@ -57,6 +57,7 @@ files:
 - examples/color.rb
 - examples/simple.rb
 - examples/speed.rb
+- examples/tokens.rb
 - lib/tty-progressbar.rb
 - lib/tty/progressbar.rb
 - lib/tty/progressbar/configuration.rb
@@ -85,6 +86,7 @@ files:
 - spec/unit/converter/to_seconds_spec.rb
 - spec/unit/converter/to_time_spec.rb
 - spec/unit/custom_formatter_spec.rb
+- spec/unit/custom_token_spec.rb
 - spec/unit/finish_spec.rb
 - spec/unit/formatter/bar_spec.rb
 - spec/unit/formatter/byte_rate_spec.rb
@@ -147,6 +149,7 @@ test_files:
 - spec/unit/converter/to_seconds_spec.rb
 - spec/unit/converter/to_time_spec.rb
 - spec/unit/custom_formatter_spec.rb
+- spec/unit/custom_token_spec.rb
 - spec/unit/finish_spec.rb
 - spec/unit/formatter/bar_spec.rb
 - spec/unit/formatter/byte_rate_spec.rb