clif 0.1.0

data/.document

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

data/.gitignore

@@ -0,0 +1,5 @@
+*.sw?
+.DS_Store
+coverage
+rdoc
+pkg

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 jameswilding
+
+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.markdown

@@ -0,0 +1,106 @@
+# 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 <code>ask</code>, <code>say</code>, and <code>perform_action</code> 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 <code>yes?</code> and <code>no?</code> 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 <code>perform_action</code> and <code>explain</code> methods are intended to talk the user through a serious of related steps: an installation, a plugin generation process, etc. 
+
+The <code>perform_action</code>	method explains an action to the user, and then performs the action. This next example outputs "install: some/file.rb" and runs <code>FileUtils.install</code>:
+
+	@clif.perform_action(:install, 'some/file.rb') do
+		FileUtils.install('some/file.rb', '/usr/local/lib')
+	end
+
+When you use <code>:pretend => true</code>, 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 <code>explain</code> to comment on steps that don't require any actions:
+
+	@clif.explain(:exists, 'app/views') # => "exists: app/views"
+	
+### Mixin!
+	
+Mix in the <code>Clif::Helper</code> module to use clif's methods in your own classes:
+
+	class Butler
+	  include Clif::Helper
+	end
+	
+	Butler.new.ask('May I take your coat?')
+
+<code>Clif::Helper</code> assumes that you have an instance variable called <code>@options</code> 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.
+
+== Copyright
+
+Copyright (c) 2009 James Wilding. See LICENSE for details.

data/Rakefile

@@ -0,0 +1,62 @@
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'jeweler'
+  
+  # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
+  Jeweler::Tasks.new do |gem|
+    gem.name        = "clif"
+    gem.summary     = %Q{Ready-made command line interface for ruby libraries}
+    gem.description = %Q{clif (Command Line InterFace) acts as a bridge between your code and the command line}
+    gem.email       = "james@jameswilding.net"
+    gem.homepage    = "http://github.com/jameswilding/clif"
+    gem.authors     = ["jameswilding"]
+    gem.add_development_dependency "thoughtbot-shoulda"
+    gem.add_development_dependency "redgreen"    
+  end
+  
+  # Releases go to gemcutter.org
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: sudo gem install jeweler"
+end
+
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test'
+  test.pattern = 'test/**/*_test.rb'
+  test.verbose = true
+end
+
+begin
+  require 'rcov/rcovtask'
+  Rcov::RcovTask.new do |test|
+    test.libs << 'test'
+    test.pattern = 'test/**/*_test.rb'
+    test.rcov_opts = ['--exclude /Library'] # otherwise depandencies are analysed, too
+    test.verbose = true
+  end
+rescue LoadError
+  task :rcov do
+    abort "RCov is not available. In order to run rcov, you must: sudo gem install spicycode-rcov"
+  end
+end
+
+#task :test => :check_dependencies # => "don't know how to build task'check_dependencies'"
+
+task :default => :test
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  if File.exist?('VERSION')
+    version = File.read('VERSION')
+  else
+    version = ""
+  end
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "clif #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/VERSION

@@ -0,0 +1 @@
+0.1.0

data/lib/clif.rb

@@ -0,0 +1,9 @@
+require 'clif/helper'
+
+class Clif
+  include Clif::Helper
+
+  def initialize(options = {})
+    @options = options
+  end
+end

data/lib/clif/helper.rb

@@ -0,0 +1,50 @@
+require 'clif/questioner'
+
+class Clif
+  module Helper
+    
+    def say(message)
+      $stdout.puts(message) unless quiet?
+    end
+
+    def no?(question)
+      !yes?(question)
+    end  
+  
+    def yes?(question)
+      !!ask(question)
+    end
+  
+    def ask(question, options = {})
+      ::Clif::Questioner.new(options).ask(question)
+    end
+    alias :prompt :ask
+    
+    def perform_action(action, message, &block)
+      explain(action, message)
+      yield unless pretend?
+    end
+  
+    def explain(action, message)
+      say "#{title_for_action(action)}: #{message}"
+    end
+  
+    def quiet?
+      @options[:quiet] || false
+    end
+  
+    def pretend?
+      @options[:pretend] || false
+    end
+  
+    private
+    def title_for_action(action)
+      action.to_s.rjust(indent)
+    end
+  
+    def indent
+      @options[:indent] || 8
+    end
+        
+  end
+end

data/lib/clif/questioner.rb

@@ -0,0 +1,45 @@
+class Clif
+  class Questioner
+    
+    def initialize(options = {})
+      @options  = options
+    end
+    
+    def ask(question)
+      @question = question
+      ask_question
+      get_response
+    end
+    
+    private
+    def ask_question
+      $stdout.print(formatted_question + " ")      
+    end
+    
+    def get_response
+      response = ($stdin.gets || '').chomp
+      
+      if boolean_question?
+        boolean_response(response)
+      else
+        response
+      end
+    end
+
+    def boolean_response(response)
+      %w(y yes).include?(response.downcase) ? true : false
+    end
+            
+    def formatted_question
+      if boolean_question?
+        "#{@question} [y/n]:"
+      else
+        @question =~ /\?$/ ? "#{@question}" : "#{@question}:"
+      end
+    end
+    
+    def boolean_question?
+      @options[:boolean] || false
+    end    
+  end
+end

data/test/clif_test.rb

@@ -0,0 +1,185 @@
+require 'test_helper'
+require 'clif'
+
+class ClifTest < Test::Unit::TestCase
+  
+  def setup
+    @real_stdout, $stdout = $stdout, StringIO.new
+    @real_stdin, $stdin   = $stdin, StringIO.new
+    
+    def $stdin.gets
+      $stdin.string
+    end
+  end
+  
+  def teardown
+    $stdout = @real_stdout
+    $stdin  = @real_stdin
+  end
+
+  context 'a Clif::CLI instance' do
+    
+    setup { @cli = new_clif }
+    
+    should 'be able to say things' do
+      expected = "Hello world"
+
+      assert_stdout(expected) { @cli.say 'Hello world' }
+    end
+    
+    context 'when initialized with :quiet => true' do
+      
+      setup { @cli = new_clif(:quiet => true) }
+      
+      should 'communicate whether it should be quiet' do
+        assert @cli.quiet?
+      end
+      
+      should 'not say things when asked to' do
+        expected = ''
+        
+        assert_stdout(expected) { @cli.say 'Nothing' }
+      end
+    end
+    
+    context 'when initialized without :quiet' do
+      
+      setup { @cli = new_clif }
+      
+      should 'return false when asked if it should be quiet' do
+        assert_equal false, @cli.quiet?
+      end
+    end   
+    
+    context 'when initialized with :pretend => true' do
+      
+      setup { @cli = new_clif(:pretend => true, :quiet => true) }
+      
+      should 'not actually do things when asked to' do
+        expected = nil
+        actual   = @cli.perform_action(:add, '1 plus 1') { destroy_the_city }
+        
+        assert_equal expected, actual
+      end
+    end 
+    
+    should 'be able to do things' do
+      expected = 2
+      actual   = new_clif(:quiet => true).perform_action(:add, '1 plus 1') { 1 + 1 }
+    end
+        
+    should 'explain its action before performing them' do
+      expected = '     add: 1 plus 1'
+      
+      assert_stdout(expected) do 
+        new_clif.perform_action(:add, '1 plus 1') { 1 + 1 }
+      end
+    end
+    
+    should 'just explain things with no action' do
+      expected = '    skip: something'
+      
+      assert_stdout(expected) do
+        new_clif.explain(:skip, 'something')
+      end
+    end
+    
+    should 'not explain things when :quiet => true' do
+      expected = ''
+      
+      assert_stdout(expected) do
+        new_clif(:quiet => true).explain(:do, 'something')
+      end
+    end
+    
+    should 'allow for setting of indent level in explanations' do
+      expected = 'do: something'
+      
+      assert_stdout(expected) do
+        new_clif(:indent => 0).explain(:do, 'something')
+      end
+    end
+    
+    should 'be able to ask nicely formatted questions, without indenting' do
+      expected = formatted_question_for("What's your name?")
+      
+      assert_stdout expected do
+        new_clif.ask("What's your name?")
+      end
+    end
+    
+    should 'alias :ask as :prompt' do
+      expected = formatted_question_for('Your name')
+      
+      assert_stdout expected do
+        new_clif.prompt('Your name')
+      end
+    end
+    
+    should 'ask nicely formatted yes/no questions, if :boolean => true' do
+      expected = formatted_question_for('Launch rockets?', :boolean => true)
+      
+      assert_stdout expected do
+        new_clif.ask('Launch rockets?', :boolean => true)
+      end
+    end
+    
+    should 'have a shortcut for getting a yes? answer' do
+      expected = formatted_question_for('Do something?')
+      
+      assert_stdout expected do
+        assert_respond_to @cli, :yes?
+        @cli.yes?('Do something?')
+      end
+    end
+    
+    should 'have a shortcut for getting a no? answer' do
+      expected = formatted_question_for('Do something?')
+      
+      assert_stdout expected do
+        assert_respond_to @cli, :no?        
+        @cli.no?('Do something?')
+      end      
+    end
+
+    context 'asking boolean questions' do
+      should 'turn Y into true' do
+        expected = true
+        
+        with_input('Y') do 
+          actual = @cli.ask('Are you there?', :boolean => true)
+          assert_equal expected, actual, "Expected 'Y' to produce #{expected} (got #{actual})"
+        end
+      end
+      
+      should 'turn y into true' do
+        expected = true
+        
+        with_input('y') do 
+          actual = @cli.ask('Are you there?', :boolean => true)
+          assert_equal expected, actual, "Expected 'y' to produce #{expected} (got #{actual})"
+        end
+      end
+      
+      should 'turn N into false' do
+        expected = false
+
+        with_input('N') do 
+          actual = @cli.ask('Are you there?', :boolean => true)
+          assert_equal expected, actual, "Expected 'N' to produce #{expected} (got #{actual})"
+        end
+      end
+      
+      should 'turn n into false' do
+        expected = false
+
+        with_input('n') do 
+          actual = @cli.ask('Are you there?', :boolean => true)
+          assert_equal expected, actual, "Expected 'n' to produce #{expected} (got #{actual})"
+        end
+      end
+    end
+        
+  end
+              
+end

data/test/test_helper.rb

@@ -0,0 +1,41 @@
+require 'rubygems'
+require 'test/unit'
+require 'shoulda'
+require 'redgreen'
+
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+$LOAD_PATH.unshift(File.dirname(__FILE__))
+require 'clif'
+
+class Test::Unit::TestCase
+
+  def new_clif(options = {})
+    Clif.new(options)
+  end
+    
+  def formatted_question_for(message, options = {})
+    if options[:boolean]
+      "#{message} [y/n]: "
+    else
+      message =~ /\?$/ ? "#{message} " : "#{message}: "
+    end
+  end  
+    
+  def assert_stdout(expected, &block)
+    result = silently(&block)
+    assert_equal expected, result
+  end
+  
+  def with_input(text, &block)
+    silently do
+      $stdin.write(text); yield
+    end
+  ensure
+    $stdin.string.replace('')
+  end  
+  
+  def silently(&block)
+    yield; $stdout.string.chomp
+  end
+    
+end

metadata

@@ -0,0 +1,86 @@
+--- !ruby/object:Gem::Specification 
+name: clif
+version: !ruby/object:Gem::Version 
+  version: 0.1.0
+platform: ruby
+authors: 
+- jameswilding
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-10-21 00:00:00 +01:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: thoughtbot-shoulda
+  type: :development
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+    version: 
+- !ruby/object:Gem::Dependency 
+  name: redgreen
+  type: :development
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+    version: 
+description: clif (Command Line InterFace) acts as a bridge between your code and the command line
+email: james@jameswilding.net
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- LICENSE
+- README.markdown
+files: 
+- .document
+- .gitignore
+- LICENSE
+- README.markdown
+- Rakefile
+- VERSION
+- lib/clif.rb
+- lib/clif/helper.rb
+- lib/clif/questioner.rb
+- test/clif_test.rb
+- test/test_helper.rb
+has_rdoc: true
+homepage: http://github.com/jameswilding/clif
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.5
+signing_key: 
+specification_version: 3
+summary: Ready-made command line interface for ruby libraries
+test_files: 
+- test/clif_test.rb
+- test/test_helper.rb