methadone 1.0.0.rc2 → 1.0.0.rc3

data/bin/methadone

@@ -48,7 +48,7 @@ main do |app_name|
     "  #{gem_variable}.add_development_dependency('rdoc')",
     "  #{gem_variable}.add_development_dependency('aruba')",
     "  #{gem_variable}.add_development_dependency('rake','~> 0.9.2')",
-    "  #{gem_variable}.add_dependency('methadone')",
+    "  #{gem_variable}.add_dependency('methadone', '~>1.0.0.rc3')",
   ], :before => /^end\s*$/
 end
 
@@ -64,7 +64,7 @@ on("-l LICENSE","--license",licenses,"Specify the license for your project (#{li
 
 use_log_level_option
 
-arg :app_name, :required
+arg :app_name, :required, "Name of your app, which is used for the gem name and executable name"
 
 version Methadone::VERSION
 

data/lib/methadone/cucumber.rb

@@ -34,7 +34,9 @@ module Methadone
   # 
   # * Checks that the app's usage banner documents that its arguments are <tt>args</tt>
   # 
-  #     Then the banner should document that this app's arguments are "args"
+  #     Then the banner should document that this app's arguments are
+  #       |foo|which is optional|
+  #       |bar|which is required|
   # 
   # * Do the opposite; check that your app doesn't take any arguments
   # 
@@ -42,7 +44,7 @@ module Methadone
   # 
   # * Check for a usage description which occurs after the banner and a blank line
   # 
-  #     Then there should be a one-line summary of what the app does
+  #     Then there should be a one line summary of what the app does
   # 
   module Cucumber
   end
@@ -59,7 +61,7 @@ Then /^the following options should be documented:$/ do |options|
 end
 
 Then /^the option "([^"]*)" should be documented$/ do |option|
-  step %(the output should match /^\\s*#{option}\\s+\\w\\w\\w+/)
+  step %(the output should match /\\s*#{option}[\\s\\W]+\\w\\w\\w+/)
 end
 
 Then /^the banner should be present$/ do
@@ -75,6 +77,7 @@ Then /^the banner should document that this app's arguments are:$/ do |table|
   expected_arguments = table.raw.map { |row|
     option = row[0]
     option = "[#{option}]" if row[1] == 'optional' || row[1] == 'which is optional'
+    option
   }.join(' ')
   step %(the output should contain "#{expected_arguments}")
 end

data/lib/methadone/error.rb

@@ -16,8 +16,9 @@ module Methadone
     # The command that caused the failure
     attr_reader :command
 
-    def initialize(exit_code,command)
-      super(exit_code,"Command '#{command}' exited #{exit_code}")
+    def initialize(exit_code,command,custom_error_message = nil)
+      error_message = String(custom_error_message).empty? ?  "Command '#{command}' exited #{exit_code}" : custom_error_message
+      super(exit_code,error_message)
       @command = command
     end
   end

data/lib/methadone/exit_now.rb

@@ -0,0 +1,25 @@
+module Methadone
+  module ExitNow
+    def self.included(k)
+      k.extend(self)
+    end
+    # Call this to exit the program immediately
+    # with the given error code and message.
+    #
+    # +exit_code+:: exit status you'd like to exit with
+    # +message+:: message to display to the user explaining the problem
+    #
+    # Also can be used without an exit code like so:
+    #
+    #     exit_now!("Oh noes!")
+    #
+    # In this case, it's equivalent to <code>exit_now!(1,"Oh noes!")</code>.
+    def exit_now!(exit_code,message=nil)
+      if exit_code.kind_of?(String) && message.nil?
+        raise Methadone::Error.new(1,exit_code)
+      else
+        raise Methadone::Error.new(exit_code,message)
+      end
+    end
+  end
+end

data/lib/methadone/main.rb

@@ -61,6 +61,7 @@ module Methadone
   # *not* do this.
   #
   module Main
+    include Methadone::ExitNow
     def self.included(k)
       k.extend(self)
     end
@@ -118,7 +119,6 @@ module Methadone
       @env_var = env_var
       opts.separator ''
       opts.separator "Default values can be placed in the #{env_var} environment variable"
-      opts.separator ''
     end
 
     # Start your command-line app, exiting appropriately when
@@ -136,6 +136,7 @@ module Methadone
     #
     def go!
       normalize_defaults
+      opts.post_setup
       if @env_var
         String(ENV[@env_var]).split(/\s+/).each do |arg|
           ::ARGV.unshift(arg)
@@ -156,15 +157,6 @@ module Methadone
       exit 64 # Linux standard for bad command line
     end
 
-    # Call this to exit the program immediately
-    # with the given error code and message.
-    #
-    # +exit_code+:: exit status you'd like to exit with
-    # +message+:: message to display to the user explaining the problem
-    def exit_now!(exit_code,message=nil)
-      raise Methadone::Error.new(exit_code,message)
-    end
-
     # Returns an OptionParser that you can use
     # to declare your command-line interface.  Generally, you
     # won't use this and will use #on directly, but this allows
@@ -212,6 +204,7 @@ module Methadone
     #             <tt>:one</tt>:: only one of this arg should be supplied (default)
     #             <tt>:many</tt>::  many of this arg may be supplied, but at least one is required
     #             <tt>:any</tt>:: any number, include zero, may be supplied
+    #             A string:: if present, this will be documentation for the argument and appear in the help
     def arg(arg_name,*options)
       opts.arg(arg_name,*options)
     end
@@ -311,6 +304,7 @@ module Methadone
       @accept_options = false
       @args = []
       @arg_options = {}
+      @arg_documentation = {}
       @description = nil
       @version = nil
       set_banner
@@ -363,6 +357,9 @@ module Methadone
       options << :one unless options.include?(:any) || options.include?(:many)
       @args << arg_name
       @arg_options[arg_name] = options
+      options.select { |_| _.kind_of? ::String }.each do |doc|
+        @arg_documentation[arg_name] = doc + (options.include?(:optional) ? " (optional)" : "")
+      end
       set_banner
     end
 
@@ -388,6 +385,20 @@ module Methadone
       set_banner
     end
 
+    # We need some documentation to appear at the end, after all OptionParser setup
+    # has occured, but before we actually start.  This method serves that purpose
+    def post_setup
+      unless @arg_documentation.empty?
+        @option_parser.separator ''
+        @option_parser.separator "Arguments:"
+        @option_parser.separator ''
+        @args.each do |arg|
+          @option_parser.separator "    #{arg}"
+          @option_parser.separator "        #{@arg_documentation[arg]}"
+        end
+      end
+    end
+
     private
 
     def add_default_value_to_docstring(*args)

data/lib/methadone/sh.rb

@@ -57,6 +57,9 @@ module Methadone
   # This is to make it easy for you to shell-out to external commands and have your app be robust and
   # easy to maintain.
   module SH
+    def self.included(k)
+      k.extend(self)
+    end
     # Run a shell command, capturing and logging its output.
     # If the command completed successfully, it's output is logged at DEBUG.
     # If not, its output as logged at INFO.  In either case, its
@@ -87,10 +90,10 @@ module Methadone
       sh_logger.warn("Error output of '#{command}': #{stderr}") unless stderr.strip.length == 0
 
       if status.exitstatus != 0
-        sh_logger.info("Output of '#{command}': #{stdout}")
+        sh_logger.info("Output of '#{command}': #{stdout}") unless stdout.strip.length == 0
         sh_logger.warn("Error running '#{command}'")
       else
-        sh_logger.debug("Output of '#{command}': #{stdout}") 
+        sh_logger.debug("Output of '#{command}': #{stdout}") unless stdout.strip.length == 0
         call_block(block,stdout,stderr) unless block.nil?
       end
 
@@ -103,10 +106,22 @@ module Methadone
     # Run a command, throwing an exception if the command exited nonzero.
     # Otherwise, behaves exactly like #sh.
     #
+    # options - options hash, responding to:
+    #           <tt>:on_fail</tt>:: a custom error message.  This allows you to have your
+    #                               app exit on shell command failures, but customize the error
+    #                               message that they see.
+    #
     # Raises Methadone::FailedCommandError if the command exited nonzero.
-    def sh!(command,&block)
+    #
+    # Examples:
+    #
+    #     sh!("rsync foo bar")
+    #     # => if command fails, app exits and user sees: "error: Command 'rsync foo bar' exited 12"
+    #     sh!("rsync foo bar", :on_fail => "Couldn't rsync, check log for details")
+    #     # => if command fails, app exits and user sees: "error: Couldn't rsync, check log for details
+    def sh!(command,options={},&block)
       sh(command,&block).tap do |exitstatus|
-        raise Methadone::FailedCommandError.new(exitstatus,command) if exitstatus != 0
+        raise Methadone::FailedCommandError.new(exitstatus,command,options[:on_fail]) if exitstatus != 0
       end
     end
 

data/lib/methadone/version.rb

@@ -1,3 +1,3 @@
 module Methadone
-  VERSION = "1.0.0.rc2"
+  VERSION = "1.0.0.rc3"
 end

data/lib/methadone.rb

@@ -1,6 +1,7 @@
 require 'methadone/version'
 require 'methadone/cli_logger'
 require 'methadone/cli_logging'
+require 'methadone/exit_now'
 require 'methadone/main'
 require 'methadone/error'
 require 'methadone/execution_strategy/base'

data/templates/full/Rakefile.erb

@@ -17,7 +17,7 @@ end
 CUKE_RESULTS = 'results.html'
 CLEAN << CUKE_RESULTS
 Cucumber::Rake::Task.new(:features) do |t|
-  t.cucumber_opts = "features --format html -o #{CUKE_RESULTS} --format progress -x"
+  t.cucumber_opts = "features --format html -o #{CUKE_RESULTS} --format pretty --no-source -x"
   t.fork = false
 end
 

data/templates/full/features/step_definitions/executable_steps.rb.erb

@@ -1 +1 @@
-# Put your step defintions here
+# Put your step definitions here

data/test/test_exit_now.rb

@@ -0,0 +1,37 @@
+require 'base_test'
+require 'methadone'
+require 'stringio'
+
+class TestExitNow < BaseTest
+  include Methadone
+  include Methadone::ExitNow
+
+  test_that "exit_now raises the proper error" do
+    Given {
+      @exit_code = any_int :min => 1
+      @message = any_string
+    }
+    When {
+      @code = lambda { exit_now!(@exit_code,@message) }
+    }
+    Then {
+      exception = assert_raises(Methadone::Error,&@code)
+      exception.exit_code.should == @exit_code
+      exception.message.should == @message
+    }
+  end
+
+  test_that "exit_now without an exit code uses 1 as the exti code" do
+    Given {
+      @message = any_string
+    }
+    When {
+      @code = lambda { exit_now!(@message) }
+    }
+    Then {
+      exception = assert_raises(Methadone::Error,&@code)
+      exception.exit_code.should == 1
+      exception.message.should == @message
+    }
+  end
+end 

data/test/test_main.rb

@@ -334,17 +334,23 @@ class TestMain < BaseTest
 
   end
 
-  test_that "I can specify which arguments my app takes and if they are required" do
+  test_that "I can specify which arguments my app takes and if they are required as well as document them" do
     Given {
       main {}
+      @db_name_desc = any_string 
+      @user_desc = any_string
+      @password_desc = any_string
 
-      arg :db_name
-      arg :user, :required
-      arg :password, :optional
+      arg :db_name, @db_name_desc
+      arg :user, :required, @user_desc
+      arg :password, :optional, @password_desc
     }
-
+    When run_go_safely
     Then {
       opts.banner.should match /db_name user \[password\]$/
+      opts.to_s.should match /#{@db_name_desc}/
+      opts.to_s.should match /#{@user_desc}/
+      opts.to_s.should match /#{@password_desc}/
     }
   end
 

data/test/test_sh.rb

@@ -170,6 +170,23 @@ class TestSH < Clean::Test::TestCase
     }
   end
 
+  test_that "sh! runs a command that will fail and includes an error message that appears in the exception" do 
+    Given {
+      use_capturing_logger
+      @command = test_command("foo")
+      @custom_error_message = any_sentence
+    }
+    When {
+      @code = lambda { sh! @command, :on_fail => @custom_error_message }
+    }
+    Then {
+      exception = assert_raises(Methadone::FailedCommandError,&@code)
+      exception.command.should == @command
+      exception.message.should == @custom_error_message
+      assert_logger_output_for_failure(@logger,@command,test_command_stdout,test_command_stderr)
+    }
+  end
+
   class MyTestApp
     include Methadone::SH
     def initialize(logger)

data/tutorial/.vimrc

@@ -0,0 +1,6 @@
+set spell spelllang=en_us
+syn spell toplevel
+set spf=~/Projects/methadone/tutorial/en.utf-8.add
+ab taht that
+ab builting built-in
+ab builtin built-in

data/tutorial/1_intro.md

@@ -0,0 +1,52 @@
+# Awesome Ruby Command Line Apps with Methadone
+
+Kick the bash habit, and make all your command-line apps with Ruby.  
+
+In [Build Awesome Command-Line Applications in Ruby][clibook], I lay out how to make an awesome command-line application using
+Ruby.  The book focuses on tools like `OptionParser` to create the app.  As I wrote and researched, it became clear that there
+was a gap between `OptionParser`, which is very powerful, yet verbose, and other command line tools like [trollop][trollop], 
+[main][main], and [thor][thor], which have simple APIs, but aren't very powerful.  
+
+[clibook]: http://www.awesomecommandlineapps.com
+[main]: http://github.com/ahoward/main
+[trollop]: http://trollop.rubyforge.org
+[thor]: http://www.github.com/wycats/thor
+
+I created Methadone to bridge that gap.  Methadone provides all the power of `OptionParser`, but has a simple, clean API.
+Methadone also includes additional tools and classes to make your command-line apps even better.
+
+This tutorial will show you how to make a simple command-line app using Methadone that will be easy-to-use, easy-to-maintain, and
+fully tested.
+
+## What you'll need
+
+You'll need an installation of Ruby and the ability to install Ruby gems.  I would recommend that you use rvm and a gemset to
+work through these, but they aren't required.  There's a decent [walkthrough][setup] on my book's website of setting this up the
+way I work.  Although Methadone works on most versions of Ruby, I would recommend you use Ruby
+1.9.3, if you can.  If not, try to use an MRI Ruby as those versions (1.8.7, REE, 1.9.2, or 1.9.3) have the highest compatibility
+with other gems.
+
+[setup]: http://www.awesomecommandlineapps.com/setup.html
+
+## How this is organized
+
+This is a tutorial for making a simple command-line app.  Unlike some tutorials and books, we will be working through this using
+a "test-first" approach.  One thing that Methadone tries to enable is using [TDD][tdd] for creating and writing your command-line
+app.  As such, we'll write tests as much as possible to drive our work.
+
+[tdd]: http://en.wikipedia.org/wiki/Test-driven_development
+
+## The tutorial app
+
+The app we'll build is going to manage "dot files".  These are the files that live in your home directory and configure your
+shell, editor, and various other programs.  For example, `~/.bashrc` is the file to configure `bash`.  Many developers keep these
+files on [Github][github] so that they can maintain the same files across multiple computers.
+
+[github]: http://www.github.com
+
+To set this up on a new computer, you have to checkout the repo, and symlink all the files to your home directory.  To update the
+files you have to update the repo and then check if any new files were added.  This is the sort of tedious manual process that is
+ripe for automation via a command-line app.
+
+We'll develop a simplified version to demonstrate how to use Methadone.
+

data/tutorial/2_bootstrap.md

@@ -0,0 +1,176 @@
+# Bootstrapping our app
+
+One thing that's great about writing a webapp with Ruby on Rails is that, with one command, you have a skeleton app, including
+a fully functional test framework set up.  You can start writing tests immediately.  There's no common equivalent for a
+command-line app, which is what Methadone aims to provide.
+
+Methadone will also bootstrap other aspects of your app, such a `Rakefile`, a gemspec, a shell of an executable, a license, and a
+README.  First, let's install Methadone via RubyGems (note that if your aren't using rvm, you may need to use `sudo` to install
+gems):
+
+```sh
+$ gem install methadone
+Fetching: methadone-1.0.0.gem (100%)
+Successfully installed methadone-1.0.0
+1 gem installed
+Installing ri documentation for methadone-1.0.0...
+Installing RDoc documentation for methadone-1.0.0...
+```
+
+Methadone comes bundled with a command-linen app that will do the bootstrapping:
+
+```sh
+$ methadone --help
+Usage: methadone [options] app_name
+
+Kick the bash habit by bootstrapping your Ruby command-line apps
+
+v1.0.0
+
+Options:
+        --force                      Overwrite files if they exist
+        --[no-]readme                [Do not ]produce a README file
+    -l, --license LICENSE            Specify the license for your project (mit|apache|custom|NONE)
+        --log-level LEVEL            Set the logging level (debug|info|warn|error|fatal)
+                                     (Default: info)
+        --version                    Show help/version info
+
+Default values can be placed in the METHODONE_OPTS environment variable
+```
+
+The app that we'll be building in this tutorial is be called `fullstop`, which is derived from the [British name][fullstop] for a period, which is the character used as a prefix to our dotfiles, and, is the reason they are called "dot" files in the first place.  Based on the command-line syntax for `methadone`, we can create our app right now with one simple command.  We'll use the Apache license as well as a README.
+
+[fullstop]: http://en.wikipedia.org/wiki/Full_stop
+
+```sh
+$ methadone --readme --license apache fullstop
+$ ls fullstop
+Gemfile           README.rdoc       bin/              
+fullstop.gemspec  test/             LICENSE.txt       
+Rakefile          features/         lib/
+```
+
+As you can see, we've got a generic gemified project.  Before we can start developing, we'll need to install a few gems using Bundler first:
+
+```sh
+$ cd fullstop
+$ bundle install
+Fetching source index for http://rubygems.org/
+Installing rake (0.9.2.2) 
+Installing ffi (1.0.11) with native extensions 
+Installing childprocess (0.3.1) 
+Installing builder (3.0.0) 
+Installing diff-lcs (1.1.3) 
+Installing json (1.6.5) with native extensions 
+Installing gherkin (2.7.6) with native extensions 
+Installing term-ansicolor (1.0.7) 
+Installing cucumber (1.1.4) 
+Installing rspec-core (2.8.0) 
+Installing rspec-expectations (2.8.0) 
+Installing rspec-mocks (2.8.0) 
+Installing rspec (2.8.0) 
+Installing aruba (0.4.11) 
+Using bundler (1.0.21) 
+Installing methadone (0.5.1) 
+Using fullstop (0.0.1) from source at /Users/davec/Projects/methadone/tutorial/code/fullstop 
+Installing rdoc (3.12) 
+Your bundle is complete! Use `bundle show [gemname]` to see where a bundled gem is installed.
+```
+
+Your versions might not match up, but this should be more or less what you see.  The first thing you'll notice is that this seems
+like a *lot* of gems!  Most of them are brought in by our acceptance testing framework, [aruba][aruba], which is a library on top
+of [cucumber][cucumber] tailor-made for testing command-line apps.  Methadone also assumes  you'll be unit
+testing with `Test::Unit`, which is a fine default.   In fact, both unit and acceptance tests are set up for you and available
+via `rake` tasks.  Let's see them in action.
+
+[aruba]: http://www.github.com/cucumber/aruba
+[cucumber]: http://cukes.info
+
+```sh
+$ rake
+Run options: 
+
+# Running tests:
+
+.
+
+Finished tests in 0.000623s, 1605.1364 tests/s, 1605.1364 assertions/s.
+
+1 tests, 1 assertions, 0 failures, 0 errors, 0 skips
+......
+
+1 scenario (1 passed)
+6 steps (6 passed)
+0m0.136s
+```
+
+As you can see, we ran one unit test and one cucumber scenario.  These were provided by Methadone as placeholders for your tests.
+Just like what Ruby on Rails does when you create an app, Methadone has reduced the friction between your need to write software
+and your ability to do so.
+
+Methadone also generated a very basic scaffold of the command-line app itself.  It's in `bin` and is called `fullstop` (the
+argument we gave to `methadone`).  Let's run it now:
+
+```sh
+$ bin/fullstop
+/Users/davec/.rvm/rubies/ruby-1.9.3-p0/lib/ruby/site_ruby/1.9.1/rubygems/custom_require.rb:36:in `require': cannot load such file -- fullstop (LoadError)
+from /Users/davec/.rvm/rubies/ruby-1.9.3-p0/lib/ruby/site_ruby/1.9.1/rubygems/custom_require.rb:36:in `require'
+from bin/fullstop:5:in `<main>'
+```
+
+Oops!  What happened?  
+
+Methadone is encouraging you to develop your app with best practices, and one such practice is to not have
+your executables mess with the load path.  In many Ruby command-line applications, you'll see code like this at the top of the
+file:
+
+```ruby
+$: << File.join(File.dirname(__FILE__),'..','lib')
+```
+
+This puts the `lib` directory, that is relative to the `bin` directory (where our executable lives), into Ruby's load path.  This will allow *us* to run the app easily, but for your users, it's not necessary if you distribute your app with RubyGems (which you should do) and it's generally not a good idea to modify the load path.  In order to run the app directly during development, we'll need to use `bundle exec`, like so (note that we won't be running our app a lot in development, but scripting it using Aruba so we can test its behavior in an automated way):
+
+```sh
+$ bundle exec bin/fullstop --help
+Usage: fullstop [options]
+
+v0.0.1
+
+Options:
+        --version                    Show help/version info
+        --log-level LEVEL            Set the logging level (debug|info|warn|error|fatal)
+                                         (Default: info)
+```
+
+
+Not too bad!  We've got the makings of a reasonable help system, versioning support, a usage statement and a working executable.
+Just remember to run the app with `bundle exec` while you're developing.  Remember, your users won't have to worry about as long
+as they installed it with RubyGems.
+
+Before we move on, let's look at the cucumber scenario that Methadone generated for us.  We're going to work "outside in" on our
+app, so this will be a sneak peek at what we'll be doing next.
+
+```sh
+$ cat features/fullstop.feature 
+```
+```cucumber
+Feature: My bootstrapped app kinda works
+  In order to get going on coding my awesome app
+  I want to have aruba and cucumber setup
+  So I don't have to do it myself
+
+  Scenario: App just runs
+    When I get help for "fullstop"
+    Then the exit status should be 0
+    And the banner should be present
+    And the banner should document that this app takes options
+    And the following options should be documented:
+      |--version|
+    And the banner should document that this app takes no arguments
+```
+
+We probably won't keep this exactly scenario around, but it's a good demonstration of Aruba and Cucumber, and will help to get us
+going.  Since this scenario passes, that means that we already have the cucumber steps defined somewhere.  As we'll see, the
+combination of Aruba and Methadone results in a lot of pre-defined steps that make acceptance testing a snap.
+
+In the next section, we'll expand this scenario to create the user interface we'll need to get our app going.