tty-spinner 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 8e04e5566451769e21e19b19e1e737a2a4680529
-  data.tar.gz: f62fbd9e4da87305573bdf3214f32029d51efd41
+  metadata.gz: 9b97fa767937b67b27ecbba2fb06a5b9f69c4d6b
+  data.tar.gz: 20dee6fe62ec0e5f431424f54a26848291773245
 SHA512:
-  metadata.gz: 36bc537184f487b0d0b1ee2b97075c0179eb07e5bd1e7cdc42036d1a7fc67972b22161fd178577e96dbdd959a498073aa6f4cd7b36aef5c35f8ad7c6a326a81c
-  data.tar.gz: 02d7cf58e0fd5650249ee89e249211217f10793feee1d9aaa77600a220de2c789ec029150ebc5848e6446a105cdf9db673bfadd29306c31df1bf78de9e79b157
+  metadata.gz: bae4dcda349f6d01fe50d39dafbc1519a386e160e0d3568702c588648fcbdd2d673c2e06a8c6508c3b8623cf558ddbe76101c67384892e37d41e7e195f321458
+  data.tar.gz: e319158428db89baa850bbcd14dba26caa9ad9230377bb2f65cde8fdfd42c40b53eec9f205962421e8745a44f31d0406b8cd85f67a49f191aa55956d4b82fbfa

data/README.md

@@ -1,19 +1,22 @@
-# TTY::Spinner
+# TTY::Spinner [![Gitter](https://badges.gitter.im/Join%20Chat.svg)][gitter]
 [![Gem Version](https://badge.fury.io/rb/tty-spinner.svg)][gem]
-[![Build Status](https://secure.travis-ci.org/peter-murach/tty-spinner.svg?branch=master)][travis]
-[![Code Climate](https://codeclimate.com/github/peter-murach/tty-spinner/badges/gpa.png)][codeclimate]
-[![Coverage Status](https://coveralls.io/repos/peter-murach/tty-spinner/badge.svg)][coverage]
-[![Inline docs](http://inch-ci.org/github/peter-murach/tty-spinner.svg?branch=master)][inchpages]
+[![Build Status](https://secure.travis-ci.org/piotrmurach/tty-spinner.svg?branch=master)][travis]
+[![Code Climate](https://codeclimate.com/github/piotrmurach/tty-spinner/badges/gpa.png)][codeclimate]
+[![Coverage Status](https://coveralls.io/repos/piotrmurach/tty-spinner/badge.svg)][coverage]
+[![Inline docs](http://inch-ci.org/github/piotrmurach/tty-spinner.svg?branch=master)][inchpages]
 
+[gitter]: https://gitter.im/piotrmurach/tty
 [gem]: http://badge.fury.io/rb/tty-spinner
-[travis]: http://travis-ci.org/peter-murach/tty-spinner
-[codeclimate]: https://codeclimate.com/github/peter-murach/tty-spinner
-[coverage]: https://coveralls.io/r/peter-murach/tty-spinner
-[inchpages]: http://inch-ci.org/github/peter-murach/tty-spinner
+[travis]: http://travis-ci.org/piotrmurach/tty-spinner
+[codeclimate]: https://codeclimate.com/github/piotrmurach/tty-spinner
+[coverage]: https://coveralls.io/r/piotrmurach/tty-spinner
+[inchpages]: http://inch-ci.org/github/piotrmurach/tty-spinner
 
 > A terminal spinner for tasks that have non-deterministic time frame.
 
-**TTY::Spinner** provides independent spinner component for [TTY](https://github.com/peter-murach/tty) toolkit.
+**TTY::Spinner** provides independent spinner component for [TTY](https://github.com/piotrmurach/tty) toolkit.
+
+![](demo.gif)
 
 ## Installation
 
@@ -38,8 +41,10 @@ Or install it yourself as:
   * [2.1 spin](#21-spin)
   * [2.2 start](#22-start)
   * [2.3 stop](#23-stop)
-  * [2.4 success](#24-success)
-  * [2.5 error](#25-error)
+    * [2.3.1 success](#231-success)
+    * [2.3.2 error](#232-error)
+  * [2.4 run](#24-run)
+  * [2.5 update](#25-update)
   * [2.6 reset](#26-reset)
   * [2.7 join](#27-join)
 * [3. Configuration](#3-configuration)
@@ -87,13 +92,21 @@ and when finished output:
 _ Loading ... Done!
 ```
 
-For more usage examples please see [examples directory](https://github.com/peter-murach/tty-spinner/tree/master/examples)
+For more usage examples please see [examples directory](https://github.com/piotrmurach/tty-spinner/tree/master/examples)
 
 ## 2. API
 
 ### 2.1 spin
 
-The main workhorse of the spinner is the `spin` method. Looping over `spin` method will animate a given spinner.
+The main workhorse of the spinner is the `spin` method.
+
+Looping over `spin` method will animate a given spinner.
+
+```ruby
+loop do
+  spinner.spin
+end
+```
 
 ### 2.2 start
 
@@ -103,7 +116,7 @@ To perform automatic spinning call `start` method like so:
 spinner.start
 ```
 
-The speed with which the spinning happens is determined by the `:interval` parameter. All the spinner formats have their default intervals specified [see](https://github.com/peter-murach/tty-spinner/blob/master/lib/tty/spinner/formats.rb)
+The speed with which the spinning happens is determined by the `:interval` parameter. All the spinner formats have their default intervals specified ([see](https://github.com/piotrmurach/tty-spinner/blob/master/lib/tty/spinner/formats.rb)).
 
 ### 2.3 stop
 
@@ -119,7 +132,7 @@ You can further pass a message to print when animation is finished.
 spinner.stop('Done!')
 ```
 
-### 2.4 success
+#### 2.3.1 success
 
 Use `success` call to stop the spinning animation and replace the spinning symbol with checkmark character to indicate successful completion.
 
@@ -134,7 +147,7 @@ This will produce:
 [✔] Task name (successful)
 ```
 
-### 2.5 error
+#### 2.3.2 error
 
 Use `error` call to stop the spining animation and replace the spinning symbol with cross character to indicate error completion.
 
@@ -149,6 +162,44 @@ This will produce:
 [✖] Task name (error)
 ```
 
+### 2.4 run
+
+Use `run` with a code block that will automatically display spinning animation while the block executes and finish animation when the block terminates. Optionally you can provide a stop message to display when animation is finished.
+
+```ruby
+spinner.run('Done!') { ... }
+```
+
+### 2.5 update
+
+Use `update` call to dynamically change label name(s).
+
+Provide an arbitrary token name(s) in the message string, such as `:title`
+
+```ruby
+spinner = TTY::Spinner.new("[:spinner] :title")
+```
+
+and then pass token name and value:
+
+```ruby
+spinner.update(title: 'Downloading file1')
+```
+
+next start animation:
+
+```ruby
+spinner.run { ... }
+# => | Downloading file1
+```
+
+Once animation finishes you can kick start another one with a different name:
+
+```ruby
+spinner.update(title: 'Downloading file2')
+spinner.run { ... }
+```
+
 ### 2.6 reset
 
 In order to reset the spinner to its initial frame do:
@@ -183,7 +234,7 @@ Use one of the predefined spinner styles by passing the formatting token `:forma
 spinner = TTY::Spinner.new(format: :pulse_2)
 ```
 
-All spinner formats that **TTY::Spinner** accepts are defined in [/lib/tty/spinner/formats.rb](https://github.com/peter-murach/tty-spinner/blob/master/lib/tty/spinner/formats.rb)
+All spinner formats that **TTY::Spinner** accepts are defined in [/lib/tty/spinner/formats.rb](https://github.com/piotrmurach/tty-spinner/blob/master/lib/tty/spinner/formats.rb)
 
 If you wish to see all available formats in action run the `formats.rb` file in examples folder like so:
 
@@ -279,7 +330,7 @@ spinner.on(:error) { ... }
 
 ## Contributing
 
-1. Fork it ( https://github.com/peter-murach/tty-spinner/fork )
+1. Fork it ( https://github.com/piotrmurach/tty-spinner/fork )
 2. Create your feature branch (`git checkout -b my-new-feature`)
 3. Commit your changes (`git commit -am 'Add some feature'`)
 4. Push to the branch (`git push origin my-new-feature`)

data/lib/tty/spinner.rb

@@ -10,6 +10,9 @@ module TTY
   class Spinner
     include Formats
 
+    # @raised when attempting to join dead thread
+    NotSpinningError = Class.new(StandardError)
+
     ECMA_ESC = "\x1b".freeze
     ECMA_CSI = "\x1b[".freeze
     ECMA_CHA = 'G'.freeze
@@ -19,7 +22,7 @@ module TTY
     DEC_SET = 'h'.freeze
     DEC_TCEM = '?25'.freeze
 
-    MATCHER = /:spinner/.freeze
+    MATCHER = /:spinner/
     TICK = '✔'.freeze
     CROSS = '✖'.freeze
 
@@ -50,6 +53,14 @@ module TTY
     # @api public
     attr_reader :message
 
+    # Tokens for the message
+    #
+    # @return [Hash[Symbol, Object]]
+    #   the current tokens
+    #
+    # @api public
+    attr_reader :tokens
+
     # Initialize a spinner
     #
     # @example
@@ -74,23 +85,27 @@ module TTY
     def initialize(*args)
       options  = args.last.is_a?(::Hash) ? args.pop : {}
       @message = args.empty? ? ':spinner' : args.pop
+      @tokens  = {}
 
       @format      = options.fetch(:format) { :classic }
       @output      = options.fetch(:output) { $stderr }
       @hide_cursor = options.fetch(:hide_cursor) { false }
-      @frames      = options.fetch(:frames) {
-                       fetch_format(@format.to_sym, :frames) }
+      @frames      = options.fetch(:frames) do
+                       fetch_format(@format.to_sym, :frames)
+                     end
       @clear       = options.fetch(:clear) { false }
       @success_mark= options.fetch(:success_mark) { TICK }
       @error_mark  = options.fetch(:error_mark) { CROSS }
-      @interval    = options.fetch(:interval) {
-                       fetch_format(@format.to_sym, :interval) }
+      @interval    = options.fetch(:interval) do
+                       fetch_format(@format.to_sym, :interval)
+                     end
 
       @callbacks   = Hash.new { |h, k| h[k] = [] }
       @length      = @frames.length
       @current     = 0
       @done        = false
       @state       = :stopped
+      @thread      = nil
     end
 
     def spinning?
@@ -113,22 +128,41 @@ module TTY
       self
     end
 
-    # Start automatic spinning
-    #
+    # Start automatic spinning animation
     #
     # @api public
     def start
       @started_at = Time.now
+      @done = false
       sleep_time = 1.0 / @interval
 
       @thread = Thread.new do
-        while @started_at do
+        while @started_at
           spin
           sleep(sleep_time)
         end
       end
     end
 
+    # Run spinner while executing job
+    #
+    # @param [String] stop_message
+    #   the message displayed when block is finished
+    #
+    # @yield automatically animate and finish spinner
+    #
+    # @example
+    #   spinner.run('Migrated DB') { ... }
+    #
+    # @api public
+    def run(stop_message = nil, &block)
+      start
+      @work = Thread.new(&block)
+      @work.join
+    ensure
+      stop(stop_message)
+    end
+
     # Duration of the spinning animation
     #
     # @return [Numeric]
@@ -145,9 +179,9 @@ module TTY
     #
     # @api public
     def join(timeout = nil)
-      fail NotSpinningError.new(
-        "Cannot join spinner that is not running"
-      ) unless @thread
+      unless @thread
+        raise(NotSpinningError, 'Cannot join spinner that is not running')
+      end
 
       timeout ? @thread.join(timeout) : @thread.join
     end
@@ -173,6 +207,7 @@ module TTY
       end
 
       data = message.gsub(MATCHER, @frames[@current])
+      data = replace_tokens(data)
       write(data, true)
       @current = (@current + 1) % @length
       @state = :spinning
@@ -186,30 +221,42 @@ module TTY
     #
     # @api public
     def stop(stop_message = '')
-      if @hide_cursor && spinning?
+      return if @done
+
+      if @hide_cursor
         write(ECMA_CSI + DEC_TCEM + DEC_SET, false)
       end
-      @done = true
-      @started_at = nil
-      emit(:done)
       return clear_line if @clear
 
-      char = if success?
-               @success_mark
-             elsif error?
-               @error_mark
-             else
-               @frames[@current - 1]
-             end
-      data = message.gsub(MATCHER, char)
-
+      data = message.gsub(MATCHER, next_char)
+      data = replace_tokens(data)
       if !stop_message.empty?
         data << ' ' + stop_message
       end
 
       write(data, true)
       write("\n", false) unless @clear
-      reset
+    ensure
+      @state      = :stopped
+      @done       = true
+      @started_at = nil
+      emit(:done)
+      kill
+    end
+
+    # Retrieve next character
+    #
+    # @return [String]
+    #
+    # @api private
+    def next_char
+      if success?
+        @success_mark
+      elsif error?
+        @error_mark
+      else
+        @frames[@current - 1]
+      end
     end
 
     # Finish spinning and set state to :success
@@ -237,12 +284,21 @@ module TTY
       output.print(ECMA_CSI + '0m' + ECMA_CSI + '1000D' + ECMA_CSI + ECMA_CLR)
     end
 
+    # Update string formatting tokens
+    #
+    # @param [Hash[Symbol]] tokens
+    #   the tokens used in formatting string
+    #
+    # @api public
+    def update(tokens)
+      @tokens.merge!(tokens)
+    end
+
     # Reset the spinner to initial frame
     #
     # @api public
     def reset
       @current = 0
-      @state   = :stopped
     end
 
     private
@@ -282,5 +338,21 @@ module TTY
         raise ArgumentError, "Unknown format token `:#{token}`"
       end
     end
+
+    # Replace any token inside string
+    #
+    # @param [String] string
+    #   the string containing tokens
+    #
+    # @return [String]
+    #
+    # @api private
+    def replace_tokens(string)
+      data = string.dup
+      @tokens.each do |name, val|
+        data.gsub!(/\:#{name}/, val)
+      end
+      data
+    end
   end # Spinner
 end # TTY

data/lib/tty/spinner/version.rb

@@ -2,6 +2,6 @@
 
 module TTY
   class Spinner
-    VERSION = "0.2.0"
+    VERSION = "0.3.0"
   end # Spinner
 end # TTY

metadata

@@ -1,47 +1,47 @@
 --- !ruby/object:Gem::Specification
 name: tty-spinner
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Piotr Murach
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-03-13 00:00:00.000000000 Z
+date: 2016-07-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: 1.5.0
-    - - <
+    - - "<"
       - !ruby/object:Gem::Version
         version: '2.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: 1.5.0
-    - - <
+    - - "<"
       - !ruby/object:Gem::Version
         version: '2.0'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
 description: A terminal spinner for tasks that have non-deterministic time frame.
@@ -51,13 +51,13 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- lib/tty/spinner/formats.rb
-- lib/tty/spinner/version.rb
-- lib/tty/spinner.rb
-- lib/tty-spinner.rb
 - LICENSE.txt
 - README.md
-homepage: https://github.com/peter-murach/tty-spinner
+- lib/tty-spinner.rb
+- lib/tty/spinner.rb
+- lib/tty/spinner/formats.rb
+- lib/tty/spinner/version.rb
+homepage: https://github.com/piotrmurach/tty-spinner
 licenses:
 - MIT
 metadata: {}
@@ -67,17 +67,17 @@ require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
-  - - '>='
+  - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - '>='
+  - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.0.3
+rubygems_version: 2.5.1
 signing_key: 
 specification_version: 4
 summary: A terminal spinner for tasks that have non-deterministic time frame.