spinning_cursor 0.1.0.rc1

data/.document

@@ -0,0 +1,5 @@
+lib/**/*.rb
+bin/*
+- 
+features/**/*.feature
+LICENSE.txt

data/Gemfile

@@ -0,0 +1,13 @@
+source "http://rubygems.org"
+# Add dependencies required to use your gem here.
+# Example:
+#   gem "activesupport", ">= 2.3.5"
+
+# Add dependencies to develop your gem here.
+# Include everything needed to run rake, tests, features, etc.
+group :development do
+  gem "shoulda", ">= 0"
+  gem "rdoc", "~> 3.12"
+  gem "bundler", "~> 1.1.3"
+  gem "jeweler", "~> 1.8.3"
+end

data/Gemfile.lock

@@ -0,0 +1,27 @@
+GEM
+  remote: http://rubygems.org/
+  specs:
+    git (1.2.5)
+    jeweler (1.8.3)
+      bundler (~> 1.0)
+      git (>= 1.2.5)
+      rake
+      rdoc
+    json (1.6.6)
+    rake (0.9.2.2)
+    rdoc (3.12)
+      json (~> 1.4)
+    shoulda (3.0.1)
+      shoulda-context (~> 1.0.0)
+      shoulda-matchers (~> 1.0.0)
+    shoulda-context (1.0.0)
+    shoulda-matchers (1.0.0)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  bundler (~> 1.1.3)
+  jeweler (~> 1.8.3)
+  rdoc (~> 3.12)
+  shoulda

data/LICENSE.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2012 Adnan Abdulhussein
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.rdoc

@@ -0,0 +1,111 @@
+== Spinning Cursor
+
+Spinning Cursor is a tiny library that allows you to easily produce a
+waiting/loading message for your Ruby command line program, when a more
+complex solution, such as a progress bar, doesn't fit your needs.
+
+Inspired by Chris Wanstrath's Choice[http://https://github.com/defunkt/choice],
+Spinning Cursor provides you with a DSL for easy use of the library.
+
+== Installation
+
+As easy as RubyGems:
+
+  $ gem install spinning_cursor --pre
+
+== Usage
+
+It's so simple it hurts!
+
+=== Example
+
+  # my_awesome_ruby_class.rb
+
+  require 'spinning_cursor' # you'll definitely need this bit
+
+  class MyAwesomeRubyClass
+    def amazing_task
+      SpinningCursor.start do
+        banner "An amazing task is happening"
+        type :spinner
+        action do
+          # Zzz
+          sleep 10
+        end
+        message "Huh?! I'm awake!"
+      end
+    end
+  end
+
+  great_instance = MyAwesomeRubyClass.new
+  great_instance.amazing_task
+
+It's as easy as that!
+
+=== Options
+
+* +banner+ - This displays before the cursor. Defaults to "Loading".
+* +type+ - The type of spinner (currently only +:dots+ and +:spinner+).
+  Defaults to +:spinner+.
+* +action+ - The stuff you want to do whilst the spinner is spinning.
+* +message+ - The message you want to show the user once the task is finished.
+  Defaults to "Done".
+
+=== But the +action+ block would get too messy!
+
+Fear not, lost soul. There are two ways to prevent messy code as a result of
+the block.
+
+1. Call a method
+2. Start and stop the cursor manually
+
+The first option is the simplest, but the second isn't so bad either.
+It's pretty simple, just do:
+
+  SpinningCursor.start do
+    banner "Loading"
+    type :dots
+    message "Done"
+  end
+
+  # Complex code that takes a long time
+  sleep 20
+
+  SpinningCursor.stop
+
+*Notice* the absense of the +action+ option. The start method will only keep
+the cursor running if an +action+ block isn't passed into it.
+
+=== I want to be able to change the finish message conditionally!
+
+Do you? Well that's easy too (I'm starting to see a pattern here...)!
+
+Use the +set_message+ method to change the message during the execution:
+
+  SpinningCursor.start do
+    banner "Calculating your favour colour, please wait"
+    type :dots
+    action do
+      sleep 20
+      if you_are_romantic
+        SpinningCursor.set_message "Your favourite colour is pink."
+      elsif you_are_peaceful
+        SpinningCursor.set_message "Your favourite colour is blue."
+      else
+        SpinningCursor.set_message "Can't figure it out =[!"
+      end
+    end
+  end
+
+You get the +message+. (see what I did there?)
+
+== Contributing to Spinning Cursor
+ 
+* Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet.
+* Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it.
+* Fork the project.
+* Start a feature/bugfix branch.
+* Commit and push until you are happy with your contribution.
+* Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.
+* Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.
+

data/Rakefile

@@ -0,0 +1,49 @@
+# encoding: utf-8
+
+require 'rubygems'
+require 'bundler'
+begin
+  Bundler.setup(:default, :development)
+rescue Bundler::BundlerError => e
+  $stderr.puts e.message
+  $stderr.puts "Run `bundle install` to install missing gems"
+  exit e.status_code
+end
+require 'rake'
+
+require 'jeweler'
+Jeweler::Tasks.new do |gem|
+  # gem is a Gem::Specification... see http://docs.rubygems.org/read/chapter/20 for more options
+  gem.name = "spinning_cursor"
+  gem.homepage = "http://github.com/Prydonius/spinning_cursor"
+  gem.license = "MIT"
+  gem.summary = "A loader for command line tools in Ruby."
+  gem.description = "Spinning Cursor is a tiny library that allows you to easily produce a
+waiting/loading message for your Ruby command line program."
+  gem.email = "adnan@prydoni.us"
+  gem.authors = ["Adnan Abdulhussein"]
+  # dependencies defined in Gemfile
+end
+Jeweler::RubygemsDotOrgTasks.new
+
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test'
+  test.pattern = 'test/**/test_*.rb'
+  test.verbose = true
+end
+
+task :default => :test
+
+require 'rdoc/task'
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "spinning_cursor #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('LICENSE*')
+  rdoc.rdoc_files.include('VERSION')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+  rdoc.main = "README.rdoc"
+end

data/VERSION

@@ -0,0 +1 @@
+0.1.0.rc1

data/lib/spinning_cursor.rb

@@ -0,0 +1,53 @@
+require "spinning_cursor/cursor"
+require "spinning_cursor/parser"
+
+module SpinningCursor
+  extend self
+
+  #
+  # Sends passed block to Parser, and starts cursor thread
+  # It will execute the action block and kill the cursor
+  # thread if an action block is passed.
+  #
+  def start(&block)
+    if defined? @@curs
+      if @@curs.alive?
+        stop
+      end
+    end
+
+    @@parsed = Parser.new(block)
+    @@curs = Thread.new {
+      Cursor.new((@@parsed.type nil), (@@parsed.banner nil))
+    }
+    if @@parsed.action.nil?
+      return
+    end
+    @@parsed.originator.instance_eval &@@parsed.action
+    stop
+  end
+
+  #
+  # Kills the cursor thread and prints the finished message
+  #
+  def stop
+    @@curs.kill
+    reset_line
+    puts (@@parsed.message nil)
+  end
+
+  #
+  # Determines whether the cursor thread is still running
+  #
+  def alive?
+    @@curs.alive?
+  end
+
+  #
+  # Sets the finish message (to be used inside the action for
+  # non-deterministic output)
+  #
+  def set_message(msg)
+    @@parsed.message msg
+  end
+end

data/lib/spinning_cursor/cursor.rb

@@ -0,0 +1,64 @@
+module SpinningCursor
+  if RUBY_PLATFORM =~ /(win|w)32$/
+    # Contains a string to clear the line in the shell
+    CLR = "                                                               \r"
+    # Haven't yet found a good solution for Windows...
+  else
+    # Unix
+    CLR = "\e[0K"
+  end
+
+  #
+  # Manages line reset in the console
+  #
+  def reset_line(text = "")
+    print "\r#{CLR}#{text}"
+  end
+
+  #
+  # This class contains the cursor types (and their helper methods)
+  #
+  class Cursor
+    #
+    # Start the printing
+    #
+    def initialize(type = :spinner, banner = "Loading")
+      @banner = banner
+      $stdout.sync = true
+      print @banner
+      send type
+    end
+
+    #
+    # Prints three dots and clears the line
+    #
+    def dots
+      i = 1
+      loop do
+        sleep 1
+        if i % 4 == 0
+          SpinningCursor.reset_line @banner
+          i += 1
+          next
+        end
+        i += 1
+        print "."
+      end
+    end
+
+    #
+    # Cycles through '|', '/', '-', '\', resembling a spinning cursor
+    #
+    def spinner
+      spinners = ['|', '/', '-', '\\']
+      i = 0
+      loop do
+        print " " unless @banner.empty?
+        print spinners[i % 4]
+        sleep 0.5
+        SpinningCursor.reset_line @banner
+        i += 1
+      end
+    end
+  end
+end

data/lib/spinning_cursor/parser.rb

@@ -0,0 +1,51 @@
+module SpinningCursor
+  class Parser
+    attr_reader :originator
+
+    #
+    # Parses proc
+    #
+    def initialize(proc)
+      @banner = "Loading"
+      @type = :spinner
+      @message = "Done"
+
+      if not proc.nil?
+        # Store the originating class for use in method_missing
+        @originator = eval "self", proc.binding
+        instance_eval &proc
+      end
+
+      self
+    end
+
+    #
+    # Getter and setter for the action block
+    #
+    def action(&block)
+      @action = block unless block.nil?
+
+      @action
+    end
+
+    #
+    # Getters and setters for +banner+, +type+ and +message+
+    # attributes.
+    # Note:: for getting, pass nil e.g. <tt>banner nil</tt>
+    #
+    %w[banner type message].each do |method|
+      define_method(method) do |string|
+        var = "@#{method}"
+        return instance_variable_get(var) if string.nil?
+        instance_variable_set(var, string)
+      end
+    end
+
+    #
+    # Pass any other methods to the calling class
+    #
+    def method_missing(method, *args, &block)
+      @originator.send method, *args, &block
+    end
+  end
+end

data/test/helper.rb

@@ -0,0 +1,33 @@
+require 'rubygems'
+require 'bundler'
+begin
+  Bundler.setup(:default, :development)
+rescue Bundler::BundlerError => e
+  $stderr.puts e.message
+  $stderr.puts "Run `bundle install` to install missing gems"
+  exit e.status_code
+end
+require 'test/unit'
+require 'shoulda'
+
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+$LOAD_PATH.unshift(File.dirname(__FILE__))
+require 'spinning_cursor'
+
+# Allows capturing of stdout
+# (http://thinkingdigitally.com/archive/capturing-output-from-puts-in-ruby/)
+
+require 'stringio'
+ 
+module Kernel
+  def capture_stdout
+    out = StringIO.new
+    $stdout = out
+    yield out
+  ensure
+    $stdout = STDOUT
+  end
+end
+
+class Test::Unit::TestCase
+end

data/test/test_cursors.rb

@@ -0,0 +1,43 @@
+require 'helper'
+
+class TestSpinningCursorCursor < Test::Unit::TestCase
+  context "dots" do
+    should "reset line after printing three dots" do
+      capture_stdout do |out|
+        dots = Thread.new do
+          SpinningCursor::Cursor.new :dots, ""
+        end
+        sleep 5
+        dots.kill
+        # \r\e[0K is move cursor to the start of the line and clear line
+        # in bash
+        assert_equal "...\r\e[0K", out.string
+      end
+    end
+  end
+
+  context "spinner" do
+    should "cycle through correctly" do
+      capture_stdout do |out|
+        spinner = Thread.new do
+          SpinningCursor::Cursor.new :spinner, ""
+        end
+        sleep 0.1
+        assert_equal "|", out.string
+        buffer = "|\r\e[0K"
+        sleep 0.5
+        assert_equal "#{buffer}/", out.string
+        buffer += "/\r\e[0K"
+        sleep 0.5
+        assert_equal "#{buffer}-", out.string
+        buffer += "-\r\e[0K"
+        sleep 0.5
+        assert_equal "#{buffer}\\", out.string
+        buffer += "\\\r\e[0K"
+        sleep 0.5
+        assert_equal "#{buffer}|", out.string
+        spinner.kill
+      end
+    end
+  end
+end

data/test/test_parser.rb

@@ -0,0 +1,34 @@
+require 'helper'
+
+class TestSpinningCursorParser < Test::Unit::TestCase
+  context "parser" do
+    should "check calling class for any missing methods" do
+      def banner_text
+        "Banner"
+      end
+      parser = SpinningCursor::Parser.new Proc.new { banner banner_text }
+      assert_equal banner_text, (parser.banner nil)
+    end
+  end
+
+  context "banner, type, message and action methods" do
+    setup do
+      @parser = SpinningCursor::Parser.new Proc.new { }
+    end
+
+    should "act as getters and setters" do
+      @parser.banner "a new banner"
+      assert_equal "a new banner", (@parser.banner nil)
+
+      @parser.type :dots
+      assert_equal :dots, (@parser.type nil)
+
+      @parser.message "a message"
+      assert_equal "a message", (@parser.message nil)
+
+      proc = Proc.new { }
+      @parser.action &proc
+      assert_equal proc, @parser.action
+    end
+  end
+end

data/test/test_spinning_cursor.rb

@@ -0,0 +1,58 @@
+require 'helper'
+
+class TestSpinningCursor < Test::Unit::TestCase
+  context "when an action block is passed it" do
+    should "start the cursor, run block content and kill the cursor" do
+      # Hide any output
+      capture_stdout do |out|
+        SpinningCursor.start do
+          action { sleep 1 }
+        end
+        # Give it some time to abort
+        sleep 0.1
+        assert_equal false, SpinningCursor.alive?
+      end
+    end
+
+    should "evalute the block from the calling class" do
+      @num = 1
+      capture_stdout do |out|
+        SpinningCursor.start do
+          action { @num += 1 }
+        end
+
+        assert_equal 2, @num
+      end
+    end
+  end
+
+  context "when an action block isn't passed it" do
+    should "start the cursor, and keep it going until stop is called" do
+      capture_stdout do |out|
+        SpinningCursor.start do
+          banner "no action block"
+        end
+        sleep 2
+        assert_equal true, SpinningCursor.alive?
+        SpinningCursor.stop
+        sleep 0.1
+        assert_equal false, SpinningCursor.alive?
+      end
+    end
+  end
+
+  context "whilst running it" do
+    should "allow you to change the end message" do
+      capture_stdout do |out|
+        SpinningCursor.start do
+          action do
+            SpinningCursor.set_message "Failed!"
+          end
+          message "Finished!"
+        end
+
+        assert_equal true, (out.string.end_with? "Failed!\n")
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,131 @@
+--- !ruby/object:Gem::Specification
+name: spinning_cursor
+version: !ruby/object:Gem::Version
+  version: 0.1.0.rc1
+  prerelease: 6
+platform: ruby
+authors:
+- Adnan Abdulhussein
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-04-10 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: shoulda
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rdoc
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '3.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '3.12'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 1.1.3
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 1.1.3
+- !ruby/object:Gem::Dependency
+  name: jeweler
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 1.8.3
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 1.8.3
+description: ! 'Spinning Cursor is a tiny library that allows you to easily produce
+  a
+
+  waiting/loading message for your Ruby command line program.'
+email: adnan@prydoni.us
+executables: []
+extensions: []
+extra_rdoc_files:
+- LICENSE.txt
+- README.rdoc
+files:
+- .document
+- Gemfile
+- Gemfile.lock
+- LICENSE.txt
+- README.rdoc
+- Rakefile
+- VERSION
+- lib/spinning_cursor.rb
+- lib/spinning_cursor/cursor.rb
+- lib/spinning_cursor/parser.rb
+- test/helper.rb
+- test/test_cursors.rb
+- test/test_parser.rb
+- test/test_spinning_cursor.rb
+homepage: http://github.com/Prydonius/spinning_cursor
+licenses:
+- MIT
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+      segments:
+      - 0
+      hash: 837562280990932011
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>'
+    - !ruby/object:Gem::Version
+      version: 1.3.1
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.21
+signing_key: 
+specification_version: 3
+summary: A loader for command line tools in Ruby.
+test_files: []