Skip to content
Browse files

prep for v0.1.0 see changelog

  • Loading branch information...
1 parent b02d740 commit 10e2aadc70b8c85d649c49227dad3fd39c55ba2b @prydonius committed Apr 10, 2012
Showing with 197 additions and 45 deletions.
  1. +18 −0 CHANGELOG
  2. +0 −1 Gemfile.lock
  3. +81 −14 README.md
  4. +2 −16 Rakefile
  5. +59 −9 lib/spinning_cursor.rb
  6. +16 −3 lib/spinning_cursor/cursor.rb
  7. +2 −0 lib/spinning_cursor/parser.rb
  8. +2 −2 test/test_cursors.rb
  9. +17 −0 test/test_spinning_cursor.rb
View
18 CHANGELOG
@@ -0,0 +1,18 @@
+CHANGELOG
+===============================================================================
+
+v0.1.0 (2012-04-10)
+ - First non-pre release
+ - Exceptions in the task cause the cursor to stop and the exception is shown
+ - Added the ability to change the banner message in the task block, allowing
+ you to update the user on the ongoing task.
+ - Returns a hash containing the start, finish and elapsed times
+
+v0.1.0.rc1 (2012-04-09)
+ - Initial release
+ - Features:
+ - A sexy DSL
+ - Set the loading message, type of spinner and finished message
+ - Pass in an action block to do the whole start stop loop, or don't and
+ call stop yourself
+ - Change the finish message within your task block
View
1 Gemfile.lock
@@ -27,7 +27,6 @@ DEPENDENCIES
bundler (~> 1.1.3)
github-markup
jeweler (~> 1.8.3)
- rdoc (~> 3.12)
redcarpet
shoulda
yard
View
95 README.md
@@ -1,11 +1,14 @@
# 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.
+Spinning Cursor is a flexible DSL that allows you to easily produce a
+customizable waiting/loading message for your Ruby command line program.
+
+Beautifully keep your users informed with what your program is doing 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 _sexy_ DSL for easy use of the library.
+[Choice](http://https://github.com/defunkt/choice), Spinning Cursor provides
+you with a _sexy_ DSL for easy use of the library.
## Installation
@@ -17,13 +20,11 @@ $ gem install spinning_cursor --pre
## Usage
-It's so simple it hurts!
+_It's so simple it hurts!_
### Example
```ruby
-# my_awesome_ruby_class.rb
-
require 'spinning_cursor' # you'll definitely need this bit
SpinningCursor.start do
@@ -35,6 +36,14 @@ SpinningCursor.start do
end
message "Huh?! I'm awake!"
end
+
+# [OUPUT]
+# The cursor can't be shown but it would look like this:
+# An amazing task is happening \ <= that's the 'cursor', it animates!
+#
+# Huh?! I'm awake!
+# => {:started=>2012-04-10 17:01:07 +0100,
+# :finished=>2012-04-10 17:01:17 +0100, :elapsed=>10.000513}
```
It's as easy as that!
@@ -48,12 +57,12 @@ It's as easy as that!
* `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!
+### 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
+1. Call a method e.g. `action my_awesome_method`
2. Start and stop the cursor manually
The first option is the simplest, but the second isn't so bad either.
@@ -100,13 +109,71 @@ end
You get the message. (see what I did there?)
+### I need to change the banner message during the task
+
+Yay! All you need is the new version of the gem (v1.0.1) and you can change
+the banner message in the same way you would the finish message, using
+`set_banner`:
+
+```ruby
+SpinningCursor.start do
+ banner "Stealing your food"
+ action do
+ sleep 10
+ SpinningCursor.set_banner "Now eating your food"
+ sleep 10
+ end
+ message "Thanks for the free food!"
+end
+```
+
+### Timing the execution
+
+Spinning Cursor will return a hash with the execution times. If an action
+block is passed, it will be returned in the `SpinningCursor.start` method.
+Otherwise, it will be returned once you call `SpinningCursor.stop`. You can
+also get it with `SpinningCursor.get_exec_time`.
+
+The hash contains the following, self-explanatory keys:
+
+* `:started`
+* `:finished`
+* `:elapsed`
+
## 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.
+
+### What to contribute
+
+#### Suggestions
+
+There isn't much this library should do, but a good suggestion is always
+welcome. Make sure to use the issue track on GitHub to make suggestions -- and
+fork & pull request if you want to implement it yourself, of course.
+
+#### More Cursors!
+
+Spinning Cursor could always use some cooler animated cursors, you can add a
+cursor easily by creating a new method in the Cursor class that runs your
+custom cursor.
+
+#### Code optimisations
+
+I'm pretty new to Ruby and this is my first attempt at a DSL. If you could
+have a look at the source and offer any optimisations I would be greatly
+indebted to you. It's a learning experience for me!
+
+### How to contribute
+
+* 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.
+* 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.
View
18 Rakefile
@@ -17,9 +17,8 @@ Jeweler::Tasks.new do |gem|
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.summary = "A DSL for adding animated loaders to your Ruby command line application."
+ gem.description = "Spinning Cursor is a flexible DSL that allows you to easily produce a customizable waiting/loading message for your Ruby command line program. Beautifully keep your users informed with what your program is doing when a more complex solution, such as a progress bar, doesn't fit your needs."
gem.email = "adnan@prydoni.us"
gem.authors = ["Adnan Abdulhussein"]
# dependencies defined in Gemfile
@@ -34,16 +33,3 @@ Rake::TestTask.new(:test) do |test|
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
View
68 lib/spinning_cursor.rb
@@ -17,9 +17,12 @@ def start(&block)
end
@@parsed = Parser.new(block)
- @@curs = Thread.new {
- Cursor.new((@@parsed.type nil), (@@parsed.banner nil))
- }
+ @@cursor = Cursor.new(@@parsed.banner nil)
+ @@curs = Thread.new { @@cursor.spin(@@parsed.type nil) }
+
+ # Time the execution
+ @@start = Time.now
+
if @@parsed.action.nil?
return
end
@@ -29,31 +32,78 @@ def start(&block)
rescue
set_message "Task failed..."
ensure
- stop
+ return stop
end
end
#
# Kills the cursor thread and prints the finished message
+ # Returns execution time
#
def stop
- @@curs.kill
- reset_line
- puts (@@parsed.message nil)
+ begin
+ @@end = Time.now
+ @@elapsed = @@end - @@start
+
+ @@curs.kill
+ reset_line
+ puts (@@parsed.message nil)
+
+ # Return execution time
+ get_exec_time
+ rescue NameError
+ raise CursorNotRunning.new "Can't stop, no cursor running."
+ end
end
#
# Determines whether the cursor thread is still running
#
def alive?
- @@curs.alive?
+ if not defined? @@curs
+ return false
+ else
+ @@curs.alive?
+ end
end
#
# Sets the finish message (to be used inside the action for
# non-deterministic output)
#
def set_message(msg)
- @@parsed.message msg
+ begin
+ @@parsed.message msg
+ rescue NameError
+ raise CursorNotRunning.new "Cursor isn't running... are you sure " +
+ "you're calling this from an action block?"
+ end
+ end
+
+ #
+ # Sets the banner message during execution
+ #
+ def set_banner(banner)
+ begin
+ @@cursor.banner = banner
+ rescue NameError
+ raise CursorNotRunning.new "Cursor isn't running... are you sure " +
+ "you're calling this from an action block?"
+ end
end
+
+ #
+ # Retrieves execution time information
+ #
+ def get_exec_time
+ begin
+ return { :started => @@start, :finished => @@end,
+ :elapsed => @@elapsed }
+ rescue NameError
+ raise NoTaskError.new "An execution hasn't started or finished."
+ end
+ end
+
+ class NoTaskError < Exception ; end
+ class CursorNotRunning < NoTaskError ; end
end
View
19 lib/spinning_cursor/cursor.rb
@@ -1,10 +1,11 @@
module SpinningCursor
if RUBY_PLATFORM =~ /(win|w)32$/
+ # DOS
# Contains a string to clear the line in the shell
CLR = " \r"
- # Haven't yet found a good solution for Windows...
else
# Unix
+ # Contains a string to clear the line in the shell
CLR = "\e[0K"
end
@@ -19,16 +20,28 @@ def reset_line(text = "")
# This class contains the cursor types (and their helper methods)
#
class Cursor
+ attr_accessor :banner
+
#
- # Start the printing
+ # As of v0.1.0: only initializes the cursor class, use the print
+ # method to start the printing. Takes only the banner argument as
+ # a result of this.
#
- def initialize(type = :spinner, banner = "Loading")
+ def initialize(banner = "Loading")
@banner = banner
+ end
+
+ #
+ # Takes a cursor type symbol and starts the printing
+ #
+ def spin(type = :spinner)
$stdout.sync = true
print @banner
send type
end
+ private
+
#
# Prints three dots and clears the line
#
View
2 lib/spinning_cursor/parser.rb
@@ -41,6 +41,8 @@ def action(&block)
end
end
+ private
+
#
# Pass any other methods to the calling class
#
View
4 test/test_cursors.rb
@@ -5,7 +5,7 @@ class TestSpinningCursorCursor < Test::Unit::TestCase
should "reset line after printing three dots" do
capture_stdout do |out|
dots = Thread.new do
- SpinningCursor::Cursor.new :dots, ""
+ SpinningCursor::Cursor.new("").spin :dots
end
sleep 5
dots.kill
@@ -20,7 +20,7 @@ class TestSpinningCursorCursor < Test::Unit::TestCase
should "cycle through correctly" do
capture_stdout do |out|
spinner = Thread.new do
- SpinningCursor::Cursor.new :spinner, ""
+ SpinningCursor::Cursor.new("").spin :spinner
end
sleep 0.1
assert_equal "|", out.string
View
17 test/test_spinning_cursor.rb
@@ -82,5 +82,22 @@ class TestSpinningCursor < Test::Unit::TestCase
assert_equal true, (out.string.end_with? "Done\n")
end
end
+
+ should "allow you to change the banner" do
+ capture_stdout do |out|
+ SpinningCursor.start do
+ action do
+ # Have to give it time to print the banners
+ sleep 0.1
+ assert_equal true, (out.string.include? "Loading")
+ sleep 0.1
+ SpinningCursor.set_banner "Finishing up"
+ sleep 0.5
+ assert_equal true, (out.string.include? "Finishing up")
+ sleep 0.1
+ end
+ end
+ end
+ end
end
end

0 comments on commit 10e2aad

Please sign in to comment.
Something went wrong with that request. Please try again.