whirly 0.1.1 → 0.2.0

data/data/whirly-static-spinners.json

@@ -0,0 +1,86 @@
+{
+  "roman_numerals": {
+    "interval": 90,
+    "mode": "swing",
+    "frames": [
+      "Ⅰ",
+      "Ⅱ",
+      "Ⅲ",
+      "Ⅳ",
+      "Ⅴ",
+      "Ⅵ",
+      "Ⅶ",
+      "Ⅷ",
+      "Ⅸ",
+      "Ⅹ"
+    ]
+  },
+  "double_mark": {
+    "interval": 120,
+    "mode": "random",
+    "frames": [
+      "⁇",
+      "⁈",
+      "⁉",
+      "‼"
+    ]
+  },
+  "heart_exclamation": {
+    "interval": 45,
+    "frames": [
+      "❢",
+      "❣"
+    ]
+  },
+  "pencil": {
+    "interval": 200,
+    "frames": [
+      "✏",
+      "✎"
+    ]
+  },
+  "bars": {
+    "interval": 80,
+    "mode": "swing",
+    "frames": [
+      "𝍠",
+      "𝍡",
+      "𝍢",
+      "𝍣",
+      "𝍤"
+    ]
+  },
+  "dice": {
+    "interval": 100,
+    "mode": "random",
+    "frames": [
+      "⚀",
+      "⚁",
+      "⚂",
+      "⚃",
+      "⚄",
+      "⚅"
+    ]
+  },
+  "hanoi": {
+    "interval": 150,
+    "mode": "swing",
+    "frames": [
+      "𝍥",
+      "𝍦",
+      "𝍧",
+      "𝍨"
+    ]
+  },
+  "vertical_bars": {
+    "interval": 80,
+    "mode": "swing",
+    "frames": [
+      "𝍩",
+      "𝍪",
+      "𝍫",
+      "𝍬",
+      "𝍭"
+    ]
+  }
+}

data/examples/all_spinners.rb

@@ -0,0 +1,21 @@
+require_relative "../lib/whirly"
+require "paint"
+
+# Demonstrates all available spinners
+
+if spinner_pack = $*[0]
+  constants = [spinner_pack.upcase]
+else
+  constants = Whirly::Spinners.constants
+end
+
+constants.each{ |spinner_pack|
+  puts
+  puts Paint[spinner_pack, :underline]
+  puts
+  Whirly::Spinners.const_get(spinner_pack).keys.sort.each{ |spinner_name|
+    Whirly.start(spinner: spinner_name, status: spinner_name){
+      sleep 1.5
+    }
+  }
+}

data/examples/asciinema_bundled_spinners.rb

@@ -0,0 +1,12 @@
+require_relative "../lib/whirly"
+require "paint"
+
+system "clear"
+
+Whirly::Spinners::WHIRLY.keys.sort.each{ |spinner_name|
+  Whirly.start(spinner: spinner_name, status: spinner_name, append_newline: false, ansi_escape_mode: "line", remove_after_stop: true){
+    sleep 1.5
+  }
+}
+
+system "exit"

data/{euruko.rb → examples/euruko.rb}

@@ -1,6 +1,8 @@
-require_relative 'lib/whirly'
+require_relative '../lib/whirly'
 require 'paint'
 
+# Lightning talk at EuRuKo 2016
+
 # # # Whirly
 
 print "\033c"
@@ -22,16 +24,6 @@ puts
 puts "Done"
 sleep 5
 
-
-
-
-
-
-
-
-
-
-
 # # # Earth
 
 print "\033c"
@@ -48,14 +40,6 @@ puts
 puts "Done"
 sleep 5
 
-
-
-
-
-
-
-
-
 # # # Pong Game
 
 print "\033c"
@@ -65,22 +49,12 @@ Whirly.start spinner: "pong", use_color: false, status: "Two computers in a game
   sleep 9
 end
 
-
 puts
 puts
 puts
 puts "Done"
 sleep 5
 
-
-
-
-
-
-
-
-
-
 # # # Ticking Clock
 
 print "\033c"
@@ -95,23 +69,11 @@ puts
 puts
 puts "Time is over"
 
-
-
-
-
-
-
-
-
-
-
 # # # URL
 
-
 print "\033c"
 puts Paint["Get WHIRLY", :bold]
 
-Whirly.start status: 'https://github.com/janlelis/whirly' do
+Whirly.start spinner: "whirly", status: "https://github.com/janlelis/whirly" do
   sleep 60
 end
-

data/examples/multi_lines.rb

@@ -0,0 +1,20 @@
+require_relative "../lib/whirly"
+require "paint"
+
+# Demonstrate the look of using multiple spinners
+
+Whirly.configure(spinner: "dots", stop: "✔")
+
+Whirly.start status: "Processing" do
+  sleep 2
+end
+
+Whirly.start status: "More processing" do
+  sleep 2
+end
+
+Whirly.start status: "Even more processing" do
+  sleep 2
+end
+
+puts "Done"

data/examples/single.rb

@@ -0,0 +1,6 @@
+require_relative "../lib/whirly"
+require "paint"
+
+# Call a single spinner from the command-line
+
+Whirly.start(spinner: $*[0], status: $*[2] || $*[0], use_color: false){ sleep(($*[1] || 10).to_i) }

data/examples/status.rb

@@ -0,0 +1,7 @@
+require_relative "../lib/whirly"
+
+Whirly.start status: "Initial status, passed when starting Whirly"
+sleep 3
+Whirly.status = "Status update"
+sleep 3
+Whirly.stop

data/lib/whirly.rb

@@ -1,78 +1,163 @@
 require_relative "whirly/version"
 require_relative "whirly/spinners"
 
-require "paint"
+require "unicode/display_width"
 
-# TODO configure extra-line below
-# TODO clear previous frame
+begin
+  require "paint"
+rescue LoadError
+end
 
 module Whirly
+  @configured = false
+
   CLI_COMMANDS = {
     hide_cursor: "\x1b[?25l",
     show_cursor: "\x1b[?25h",
-  }
+  }.freeze
+
+  DEFAULT_OPTIONS = {
+    ambiguous_character_width: 1,
+    ansi_escape_mode: "restore",
+    append_newline: true,
+    color: !!defined?(Paint),
+    color_change_rate: 30,
+    hide_cursor: true,
+    non_tty: false,
+    position: "normal",
+    remove_after_stop: false,
+    spinner: "whirly",
+    spinner_packs: [:whirly, :cli],
+    status: nil,
+    stream: $stdout,
+  }.freeze
+
+  SOFT_DEFAULT_OPTIONS = {
+    interval: 100,
+    mode: "linear",
+    stop: nil,
+  }.freeze
 
   class << self
     attr_accessor :status
-  end
+    attr_reader :options
 
-  def self.enabled?
-    @enabled
-  end
-  
-  def self.paused?
-    @paused
+    def enabled?
+      !!(defined?(@enabled) && @enabled)
+    end
+
+    def configured?
+      !!(@configured)
+    end
   end
 
-  def self.start(stream: $stdout,
-                 interval: nil,
-                 spinner: "whirly",
-                 use_color: defined?(Paint),
-                 color_change_rate: 30,
-                 status: nil,
-                 hide_cursor: true,
-                 non_tty: false)
-    # only actviate if we are on a real terminal (or forced)
-    return false unless stream.tty? || non_tty
-
-    # ensure cursor is visible after exit
-    at_exit{ @stream.print CLI_COMMANDS[:show_cursor] } if !defined?(@enabled) && hide_cursor
-
-    # only activate once
-    return false if @enabled
-
-    # save options and preprocess
-    @enabled  = true
-    @paused   = false
-    @stream   = stream
-    @status   = status
-    if spinner.is_a? Hash
-      @spinner = spinner
+  # set spinner directly or lookup
+  def self.configure_spinner(spinner_option)
+    case spinner_option
+    when Hash
+      spinner = spinner_option.dup
+    when Enumerable
+      spinner = { "frames" => spinner_option.dup }
+    when Proc
+      spinner = { "proc" => spinner_option.dup }
     else
-      @spinner  = SPINNERS[spinner.to_s]
+      spinner = nil
+      catch(:found){
+        @options[:spinner_packs].each{ |spinner_pack|
+          spinners = Whirly::Spinners.const_get(spinner_pack.to_s.upcase)
+          if spinners[spinner_option]
+            spinner = spinners[spinner_option].dup
+            throw(:found)
+          end
+        }
+      }
     end
-    raise(ArgumentError, "Whirly: Invalid spinner given") if !@spinner || (!@spinner["frames"] && !@spinner["proc"])
-    @hide_cursor = hide_cursor
-    @interval = (interval || @spinner["interval"] || 100) * 0.001
-    @frames   = @spinner["frames"] && @spinner["frames"].cycle
-    @proc     = @spinner["proc"]
 
-    # init color
-    if use_color
-      if defined?(Paint)
-        @color = "%.6x" % rand(16777216)
-        @color_directions = (0..2).map{ |e| rand(3) - 1 }
-        @color_change_rate = color_change_rate
+    # validate spinner
+    if !spinner || (!spinner["frames"] && !spinner["proc"])
+      raise(ArgumentError, "Whirly: Invalid spinner given")
+    end
+
+    spinner
+  end
+
+  # frames can be generated from enumerables or procs
+  def self.configure_frames(spinner)
+    if spinner["frames"]
+      case spinner["mode"]
+      when "swing"
+        frames = (spinner["frames"].to_a + spinner["frames"].to_a[1..-2].reverse).cycle
+      when "random"
+        frame_pool = spinner["frames"].to_a
+        frames = ->(){ frame_pool.sample }
+      when "reverse"
+        frames = spinner["frames"].to_a.reverse.cycle
       else
-        warn "Whirly warning: Using colors requires the paint gem"
+        frames = spinner["frames"].cycle
+      end
+    elsif spinner["proc"]
+      frames = spinner["proc"].dup
+    else
+      raise(ArgumentError, "Whirly: Invalid spinner given")
+    end
+
+    if frames.is_a? Proc
+      class << frames
+        alias next call
       end
     end
 
+    frames
+  end
+
+  # save options and preprocess, set defaults if value is still unknown
+  def self.configure(**options)
+    if !defined?(@configured) || !@configured || !defined?(@options) || !@options
+      @options = DEFAULT_OPTIONS.dup
+      @configured = true
+    end
+
+    @options.merge!(options)
+
+    spinner = configure_spinner(@options[:spinner])
+    spinner_overwrites = {}
+    spinner_overwrites["mode"] = @options[:mode] if @options.key?(:mode)
+    @frames   = configure_frames(spinner.merge(spinner_overwrites))
+
+    @interval = (@options[:interval] || spinner["interval"] || SOFT_DEFAULT_OPTIONS[:interval]) * 0.001
+    @stop     = @options[:stop] || spinner["stop"]
+    @status   = @options[:status]
+  end
+
+  def self.start(**options)
+    # optionally overwrite configuration on start
+    configure(**options)
+
+    # ensure cursor is visible after exit the program (only register for the very first time)
+    if (!defined?(@at_exit_handler_registered) || !@at_exit_handler_registered) && @options[:hide_cursor]
+      @at_exit_handler_registered = true
+      stream = @options[:stream]
+      at_exit{ stream.print CLI_COMMANDS[:show_cursor] }
+    end
+
+    # only enable once
+    return false if defined?(@enabled) && @enabled
+
+    # set status to enabled
+    @enabled = true
+
+    # only do something if we are on a real terminal (or forced)
+    return false unless @options[:stream].tty? || @options[:non_tty]
+
+    # init color
+    initialize_color if @options[:color]
+
     # hide cursor
-    @stream.print CLI_COMMANDS[:hide_cursor] if @hide_cursor
+    @options[:stream].print CLI_COMMANDS[:hide_cursor] if @options[:hide_cursor]
 
     # start spinner loop
     @thread = Thread.new do
+      @current_frame = nil
       while true # it's just a spinner, no exact timing here
         next_color if @color
         render
@@ -80,7 +165,7 @@ module Whirly
       end
     end
 
-    # idiomatic block syntax
+    # idiomatic block syntax support
     if block_given?
       yield
       Whirly.stop
@@ -89,50 +174,76 @@ module Whirly
     true
   end
 
-  def self.stop(delete = false)
+  def self.stop(stop_frame = nil)
     return false unless @enabled
-    @thread.terminate
+    @thread.terminate if @thread
+    render(stop_frame || @stop) if stop_frame || @stop
+    unrender if @options[:remove_after_stop]
+    @options[:stream].puts if @options[:append_newline]
+    @options[:stream].print CLI_COMMANDS[:show_cursor] if @options[:hide_cursor]
     @enabled = false
-    @stream.print CLI_COMMANDS[:show_cursor] if @hide_cursor
-    print "TODO" if delete
-    
+
     true
   end
 
-  def self.pause
-    # unrender
-    @paused = true
-    @stream.print CLI_COMMANDS[:show_cursor] if @hide_cursor
-    if block_given?
-      yield
-      continue
-    end
+  def self.reset
+    at_exit_handler_registered = defined?(@at_exit_handler_registered) && @at_exit_handler_registered
+    instance_variables.each{ |iv| remove_instance_variable(iv) }
+    @at_exit_handler_registered = at_exit_handler_registered
+    @configured = false
   end
 
-  def self.continue
-    @stream.print CLI_COMMANDS[:hide_cursor] if @hide_cursor
-    @paused = false
-  end
+  # - - -
 
   def self.unrender
     return unless @current_frame
-    current_frame_size = @current_frame.size
-    @stream.print "\n\e[s#{' ' * current_frame_size}\e[u\e[1A"
+    case @options[:ansi_escape_mode]
+    when "restore"
+      @options[:stream].print(render_prefix + (
+          ' ' * (Unicode::DisplayWidth.of(@current_frame, @options[:ambiguous_character_width]) + 1)
+      ) + render_suffix)
+    when "line"
+      @options[:stream].print "\e[1K"
+    end
   end
 
-  def self.render
-    return if @paused
+  def self.render(next_frame = nil)
     unrender
-    @current_frame = @proc ? @proc.call : @frames.next
-    @current_frame = Paint[@current_frame, @color] if @color
+
+    @current_frame = next_frame || @frames.next
+    @current_frame = Paint[@current_frame, @color] if @options[:color]
     @current_frame += "  #{@status}" if @status
-    # @stream.print "\e[s#{@current_frame}\e[u"
-    @stream.print "\n\e[s#{@current_frame}\e[u\e[1A"
+
+    @options[:stream].print(render_prefix + @current_frame.to_s + render_suffix)
+  end
+
+  def self.render_prefix
+    res = ""
+    res << "\n" if @options[:position] == "below"
+    res << "\e[s" if @options[:ansi_escape_mode] == "restore"
+    res << "\e[G" if @options[:ansi_escape_mode] == "line"
+    res
+  end
+
+  def self.render_suffix
+    res = ""
+    res << "\e[u" if @options[:ansi_escape_mode] == "restore"
+    res << "\e[1A" if @options[:position] == "below"
+    res
+  end
+
+  def self.initialize_color
+    if !defined?(Paint)
+      warn "Whirly warning: Using colors requires the paint gem"
+    else
+      @color = "%.6x" % rand(16777216)
+      @color_directions = (0..2).map{ |e| rand(3) - 1 }
+    end
   end
 
   def self.next_color
     @color = @color.scan(/../).map.with_index{ |c, i|
-      color_change = rand(@color_change_rate) * @color_directions[i]
+      color_change = rand(@options[:color_change_rate]) * @color_directions[i]
       nc = c.to_i(16) + color_change
       if nc <= 0
         nc = 0