clif

clif is a ready-made interface between your library and the command-line. Write less code, get more done.

Why clif?

clif will ask questions, get answers, convert yes/no responses into true/false values, and more. Use clif to run an installation procedure, explain build steps, get user input for a command line script: anywhere your library needs to interact with the use on the command line, clif can help.

Some examples

In the following examples, the output of methods like ask, say, and perform_action is displayed on the command-line (and input from the command line is passed back to your code, where appropriate).

Setup

Clif respects the :quiet and :pretend options:

Clif.new                        # speaks messages, performs action
Clif.new(:quiet => true)    # performs actions silently (will still ask questions)
Clif.new(:pretend => true)  # speaks but doesn't act (useful for dry runs)

# Let's go
@clif = Clif.new

Speaking

# Clif can speak
@clif.say "Hello world!" # => 'Hello world!'

# Set :quiet to true to supress messages (questions will still be spoken)
Clif.new(:quiet => true).say('Hello world!') # => nil

Asking Questions

Ask a question on the command line and get a response from the user:

user_status = @clif.ask('How are you?')

Yes/no ('boolean') questions return true or false:

hungry = @clif.ask('Are you hungry?', :boolean => true) # "Are you hungry? [y/n]:"

And as a convenience, clif provide yes? and no? methods:

hungry  = @clif.yes?('Are you hungry?')
thirsty = @clif.no?('Have you drunk?')

Prompt for responses

name = @clif.prompt('Your name, please') # "Your name, please: "
puts "Your name is #{name}"

Perform Actions

The perform_action and explain methods are intended to talk the user through a serious of related steps: an installation, a plugin generation process, etc.

The perform_action method explains an action to the user, and then performs the action. This next example outputs "install: some/file.rb" and runs FileUtils.install:

@clif.perform_action(:install, 'some/file.rb') do
    FileUtils.install('some/file.rb', '/usr/local/lib')
end

When you use :pretend => true, clif will explain actions but won't actually perform them. This is useful for dry runs:

file = 'some/file.rb'

Clif.new(:pretend => true).perform_action(:create, file) do
    FileUtils.touch(file) # won't run
end

File.file?(file) # => false

Use explain to comment on steps that don't require any actions:

@clif.explain(:exists, 'app/views') # => "exists: app/views"

Mixin!

Mix in the Clif::Helper module to use clif's methods in your own classes:

class Butler
  include Clif::Helper
end

Butler.new.ask('May I take your coat?')

Clif::Helper assumes that you have an instance variable called @options available in your objects.

TODO

Cleaner testing of output to $stdout and input from $stdin
Persistently ask yes/no questions until the response is some variant of 'y', 'yes, 'n', or 'no'

Note on Patches/Pull Requests

Fork the project.
Make your feature addition or bug fix.
Add tests for it. This is important so I don't break it in a future version unintentionally.
Commit: do not mess with rakefile, version, or history. (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
Send me a pull request. Bonus points for topic branches.