Skip to content

Latest commit

 

History

History
192 lines (143 loc) · 5.38 KB

README.md

File metadata and controls

192 lines (143 loc) · 5.38 KB
Raw

Spinning Cursor

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, Spinning Cursor provides you with a sexy DSL for easy use of the library.

Build Status

Installation

As easy as RubyGems:

$ gem install spinning_cursor

Usage

It's so simple it hurts!

Example

require 'spinning_cursor' # you'll definitely need this bit

SpinningCursor.run do
  banner "An amazing task is happening"
  type :spinner
  action do
    # Zzz
    sleep 10
  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!

Options

  • banner - This displays before the cursor. Defaults to "Loading".
  • type - The type of cursor (currently only :dots and :spinner). Defaults to :spinner.
  • action - The stuff you want to do whilst the cursor is spinning.
  • message - The message you want to show the user once the task is finished. Defaults to "Done".
  • delay - Sets the delay in seconds between the frames of the animation. Defaults depend on type of cursor animation (spinner 0.5s, dots 1s)
  • output - Sets how to display program output during cursor animation (:inline or :at_stop). Defaults to :inline.

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 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. It's pretty simple, just do:

SpinningCursor.run do
  banner "Loading"
  type :dots
  message "Done"
end

# Complex code that takes a long time
sleep 20

SpinningCursor.stop

Notice the absence of the action option. The run method will only keep the cursor running if an action block isn't passed to 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.run 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?)

I need to change the banner message during the task

Yay! All you need is the new version of the gem (v0.1.0) and you can change the banner message in the same way you would the finish message, using set_banner:

SpinningCursor.run 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

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 tracker 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 hasn't already 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.

List of contributors

A massive thanks to those who have taken some time out to help improve Spinning Cursor!

  • Abinoam P. Marques Jr. (@abinoam)