cape 1.1.0 → 1.2.0

data/.gitignore

@@ -1,4 +1,5 @@
 .bundle
+.rbx
 .rvmrc
 .yardoc
 Gemfile.lock

data/.travis.yml

@@ -1,4 +1,4 @@
-bundler_args: --without debug doc
+bundler_args: --without debug doc tooling
 rvm:
   - 1.8.7
   - 1.9.3

data/Gemfile

@@ -3,16 +3,18 @@ source 'http://rubygems.org'
 gemspec
 
 group :debug do
-  gem 'ruby-debug',           :platforms => :mri_18
-
-  # This is a dependency of ruby-debug. We're specifying it here because its
-  # v0.45 is incompatible with Ruby v1.8.7.
-  gem 'linecache', '<= 0.43', :platforms => :mri_18
-
-  gem 'ruby-debug19',         :platforms => :mri_19
+  gem   'ruby-debug',   '~> 0', :platforms => :mri_18
+  gem   'ruby-debug19', '~> 0', :platforms => :mri_19, :require => 'ruby-debug'
 end
 
 group :doc do
-  gem 'yard',                 :platforms => [:ruby, :mswin, :mingw]
-  gem 'rdiscount',            :platforms => [:ruby, :mswin, :mingw]
+  gem   'yard',         '~> 0', :platforms => [:ruby, :mswin, :mingw]
+  gem   'rdiscount',    '~> 1', :platforms => [:ruby, :mswin, :mingw]
+end
+
+group :tooling do
+  gem   'guard-rspec',  '~> 0'
+  if RUBY_PLATFORM =~ /darwin/i
+    gem 'rb-fsevent',   '~> 0',                        :require => false
+  end
 end

data/Guardfile

@@ -0,0 +1,17 @@
+guard 'rspec', :cli => '--color', :version => 2 do
+  # Run the corresponding spec (or all specs) when code changes.
+  watch( %r{^lib/(.+)\.rb$} ) do |match|
+    corresponding_spec = "spec/#{match[1]}_spec.rb"
+    if File.file?( File.expand_path( "../#{corresponding_spec}", __FILE__ ))
+      corresponding_spec
+    else
+      'spec'
+    end
+  end
+
+  # Run a spec when it changes.
+  watch %r{^spec/.+_spec\.rb$}
+
+  # Run all specs when the bundle changes.
+  watch( 'Gemfile.lock' ) { 'spec' }
+end

data/History.markdown

@@ -1,5 +1,15 @@
 # Version history for the _Cape_ project
 
+## <a name="v1.2.0"></a>v1.2.0, Mon 1/30/2012
+
+* Add support in the DSL for specifying remote environment variables and Capistrano recipe options
+* Add support for Rake tasks that overlap with (have the same full name as) namespaces
+* Match Rake tasks properly: by the full name of the task rather than a substring thereof
+* Don’t choke on unexpected output from Rake
+* Silence Rake stderr output while enumerating Rake tasks
+* Tweak the wording of generated Capistrano recipe descriptions
+* Tighten RubyGem dependency specifications in an effort to avoid potential compatibility issues
+
 ## <a name="v1.1.0"></a>v1.1.0, Thu 12/29/2011
 
 * Allow environment variables for Rake task arguments to be optional

data/MIT-LICENSE.markdown

@@ -1,6 +1,6 @@
 # The MIT License
 
-Source code for _Cape_ is Copyright © 2011 [Nils Jonsson](mailto:cape@nilsjonsson.com) and [contributors](http://github.com/njonsson/cape/contributors "Cape contributors at GitHub").
+Source code for _Cape_ is Copyright © 2011–2012 [Nils Jonsson](mailto:cape@nilsjonsson.com) and [contributors](http://github.com/njonsson/cape/contributors "Cape contributors at GitHub").
 
 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:
 

data/README.markdown

@@ -29,7 +29,7 @@
             <hNNBNBh=(.                                /   \   `
                ..
 
-# [<img align="right" src="https://secure.travis-ci.org/njonsson/cape.png?branch=master" title="Travis CI build status" />](http://travis-ci.org/njonsson/cape) Cape
+# [<img align="right" src="https://gemnasium.com/njonsson/cape.png" title="Gemnasium build status" />](http://gemnasium.com/njonsson/cape) [<img align="right" src="https://secure.travis-ci.org/njonsson/cape.png?branch=master" title="Travis CI build status" />](http://travis-ci.org/njonsson/cape) Cape
 
 If
 
@@ -124,7 +124,7 @@ Let’s use Capistrano to view the unabbreviated description of a Rake task reci
     ------------------------------------------------------------
     Bags the leaves.
 
-    Set environment variable PAPER_OR_PLASTIC to pass a Rake task argument.
+    Set environment variable PAPER_OR_PLASTIC if you want to pass a Rake task argument.
 
 Here’s how to invoke a task/recipe with arguments. On the local computer, via Rake:
 
@@ -137,7 +137,7 @@ On remote computers, via Capistrano:
 
     $ cap bag_leaves PAPER_OR_PLASTIC=plastic
       * executing `bag_leaves'
-      * executing "cd /path/to/currently/deployed/version/of/your/app && rake bag_leaves[plastic]"
+      * executing "cd /path/to/currently/deployed/version/of/your/app && /usr/bin/env rake bag_leaves[plastic]"
         servers: ["your.server.name"]
         [your.server.name] executing command
      ** [out :: your.server.name] (in /path/to/currently/deployed/version/of/your/app)
@@ -154,13 +154,45 @@ Cape lets you filter the Rake tasks to be mirrored. Note that Cape statements mu
     require 'cape'
 
     Cape do
-      # Create Capistrano recipes for the Rake task 'foo' or for the tasks in the
+      # Create Capistrano recipes for the Rake task 'foo' and/or for the tasks in the
       # 'foo' namespace.
       mirror_rake_tasks :foo
+    end
+
+### Mirror Rake tasks that require Capistrano recipe options and/or environment variables
+
+Cape lets you specify options used for defining Capistrano recipes. You can also specify remote environment variables to be set when running Rake tasks. Note that Cape statements must be executed within a `Cape` block.
+
+    # config/deploy.rb
+
+    require 'cape'
+
+    Cape do
+      # Display defined Rails routes on application server remote machines only.
+      mirror_rake_tasks :routes, :roles => :app
+
+      # Execute database migration on application server remote machines only,
+      # and set the 'RAILS_ENV' environment variable to the value of the
+      # Capistrano variable 'rails_env'.
+      mirror_rake_tasks 'db:migrate', :roles => :app do |env|
+        env['RAILS_ENV'] = rails_env
+      end
+    end
+
+The above is equivalent to the following manually-defined Capistrano recipes.
+
+    # config/deploy.rb
+
+    # These translations to Capistrano are just for illustration.
 
-      # Create Capistrano recipes only for the Rake task 'bar:baz' or for the
-      # tasks in the 'bar:baz' namespace.
-      mirror_rake_tasks 'bar:baz'
+    task :routes, :roles => :app do
+      run "cd #{current_path} && /usr/bin/env rake routes"
+    end
+
+    namespace :db do
+      task :migrate, :roles => :app do
+        run "cd #{current_path} && /usr/bin/env rake db:migrate RAILS_ENV=#{rails_env}"
+      end
     end
 
 ### Mirror Rake tasks into a Capistrano namespace
@@ -195,13 +227,30 @@ Cape lets you enumerate Rake tasks, optionally filtering them by task name or na
         # * t[:description] -- documentation on the task, including parameters
       end
 
-      # Enumerate the Rake task 'foo' or the tasks in the 'foo' namespace.
+      # Enumerate the Rake task 'foo' and/or the tasks in the 'foo' namespace.
       each_rake_task 'foo' do |t|
         # ...
       end
     end
 
-## Limitations
+### Configure Rake execution
+
+Cape lets you specify how Rake should be executed on the local computer and on remote computers. Note that Cape statements must be executed within a `Cape` block.
+
+    # config/deploy.rb
+
+    require 'cape'
+
+    # Configure Cape to execute Rake via Bundler, both locally and remotely.
+    Cape.local_rake_executable  = '/usr/bin/env bundle exec rake'
+    Cape.remote_rake_executable = '/usr/bin/env bundle exec rake'
+
+    Cape do
+      # Create Capistrano recipes for all Rake tasks.
+      mirror_rake_tasks
+    end
+
+## Known issues
 
 For now, only Rake tasks that have descriptions can be mirrored or enumerated.
 

data/Rakefile

@@ -30,7 +30,7 @@ def define_spec_task(name, options={})
         t.rspec_opts << '--debug'
       end
     end
-    t.pattern = "spec/**/*_spec.rb"
+    t.pattern = %w(spec/*_spec.rb spec/**/*_spec.rb)
   end
 end
 

data/cape.gemspec

@@ -5,19 +5,20 @@ require 'cape/version'
 Gem::Specification.new do |s|
   s.name        = 'cape'
   s.version     = Cape::VERSION
+  s.summary     = 'Dynamically generates Capistrano recipes for Rake tasks'
+  s.description = <<-end_description.gsub(/^\s+/, '').chomp
+                  Cape dynamically generates Capistrano recipes for Rake tasks.
+                  It provides a DSL for reflecting on Rake tasks and mirroring
+                  them as documented Capistrano recipes. You can pass Rake task
+                  arguments via environment variables.
+                  end_description
   s.platform    = Gem::Platform::RUBY
   s.authors     = ['Nils Jonsson']
   s.email       = %w(cape@nilsjonsson.com)
-  s.homepage    = ''
-  s.summary     = 'Dynamically generates Capistrano recipes for Rake tasks'
-  s.description = 'Cape provides a simple DSL for selecting Rake tasks to be ' +
-                  'made available as documented Capistrano recipes. You can '  +
-                  'pass required arguments to Rake tasks via environment '     +
-                  'variables.'
+  s.homepage    = 'http://github.com/njonsson/cape'
   s.license     = 'MIT'
 
-  # TODO: Apply for RubyForge project
-  # s.rubyforge_project = 'cape'
+  s.rubyforge_project = 'cape'
 
   s.required_ruby_version = '>= 1.8.7'
 
@@ -29,8 +30,8 @@ Gem::Specification.new do |s|
   s.require_paths = %w(lib)
   s.has_rdoc      = true
 
-  s.add_development_dependency 'aruba'
-  s.add_development_dependency 'capistrano'
-  s.add_development_dependency 'rake'
-  s.add_development_dependency 'rspec',      '~> 2.7'
+  s.add_development_dependency 'aruba',      '~> 0'
+  s.add_development_dependency 'capistrano', '~> 2'
+  s.add_development_dependency 'rake',       '~> 0'
+  s.add_development_dependency 'rspec',      '~> 2'
 end

data/features/dsl/each_rake_task/with_defined_namespace_argument.feature

@@ -17,6 +17,7 @@ Feature: The #each_rake_task DSL method with an argument of a defined namespace
           if t[:description]
             $stdout.puts "Description: #{t[:description].inspect}"
           end
+          $stdout.puts 'Default' if t[:default]
         end
       end
       """
@@ -30,6 +31,13 @@ Feature: The #each_rake_task DSL method with an argument of a defined namespace
     And the output should contain:
       """
 
+      Name: "my_namespace"
+      Description: "A task that shadows a namespace"
+      Default
+      """
+    And the output should contain:
+      """
+
       Name: "my_namespace:in_a_namespace"
       Description: "My task in a namespace"
       """

data/features/dsl/each_rake_task/with_undefined_argument.feature

@@ -4,7 +4,7 @@ Feature: The #each_rake_task DSL method with an undefined argument
   As a developer using Cape,
   I want to use the Cape DSL.
 
-  Scenario: do not enumerate any Rake tasks
+  Scenario: do not enumerate any Rake tasks for a completely unrecognized argument
     Given a full-featured Rakefile
     And a Capfile with:
       """
@@ -27,3 +27,27 @@ Feature: The #each_rake_task DSL method with an undefined argument
       Name: "with_period"
       Description: "Ends with period."
       """
+
+  Scenario: do not enumerate any Rake tasks for a partially recognized argument
+    Given a full-featured Rakefile
+    And a Capfile with:
+      """
+      Cape do
+        each_rake_task :period do |t|
+          $stdout.puts '', "Name: #{t[:name].inspect}"
+          if t[:parameters]
+            $stdout.puts "Parameters: #{t[:parameters].inspect}"
+          end
+          if t[:description]
+            $stdout.puts "Description: #{t[:description].inspect}"
+          end
+        end
+      end
+      """
+    When I run `cap -T`
+    Then the output should not contain:
+      """
+
+      Name: "with_period"
+      Description: "Ends with period."
+      """

data/features/dsl/each_rake_task/without_arguments.feature

@@ -17,6 +17,7 @@ Feature: The #each_rake_task DSL method without arguments
           if t[:description]
             $stdout.puts "Description: #{t[:description].inspect}"
           end
+          $stdout.puts 'Default' if t[:default]
         end
       end
       """
@@ -49,6 +50,13 @@ Feature: The #each_rake_task DSL method without arguments
     And the output should contain:
       """
 
+      Name: "my_namespace"
+      Description: "A task that shadows a namespace"
+      Default
+      """
+    And the output should contain:
+      """
+
       Name: "my_namespace:in_a_namespace"
       Description: "My task in a namespace"
       """

data/features/dsl/mirror_rake_tasks/inside_capistrano_namespace/with_defined_namespace_argument.feature

@@ -16,6 +16,10 @@ Feature: The #mirror_rake_tasks DSL method, inside a Capistrano namespace, with
       """
     When I run `cap -T`
     Then the output should not contain "cap ns:with_period"
+    And the output should contain:
+      """
+      cap ns:my_namespace                                           # A task that shadows a names...
+      """
     And the output should contain:
       """
       cap ns:my_namespace:in_a_namespace                            # My task in a namespace.
@@ -40,6 +44,27 @@ Feature: The #mirror_rake_tasks DSL method, inside a Capistrano namespace, with
       """
       The task `ns:with_period' does not exist.
 
+      """
+
+  Scenario: mirror Rake task 'my_namespace' with its description
+    Given a full-featured Rakefile
+    And a Capfile with:
+      """
+      namespace :ns do
+        Cape do |cape|
+          cape.mirror_rake_tasks :my_namespace
+        end
+      end
+      """
+    When I run `cap -e ns:my_namespace`
+    Then the output should contain exactly:
+      """
+      ------------------------------------------------------------
+      cap ns:my_namespace
+      ------------------------------------------------------------
+      A task that shadows a namespace.
+
+
       """
 
   Scenario: mirror Rake task 'my_namespace:in_a_namespace' with its description

data/features/dsl/mirror_rake_tasks/inside_capistrano_namespace/without_arguments.feature

@@ -31,6 +31,10 @@ Feature: The #mirror_rake_tasks DSL method, inside a Capistrano namespace, witho
       """
       cap ns:with_one_arg                                           # My task with one argument.
       """
+    And the output should contain:
+      """
+      cap ns:my_namespace                                           # A task that shadows a names...
+      """
     And the output should contain:
       """
       cap ns:my_namespace:in_a_namespace                            # My task in a namespace.
@@ -85,6 +89,7 @@ Feature: The #mirror_rake_tasks DSL method, inside a Capistrano namespace, witho
     When I run `cap ns:with_period`
     Then the output should contain:
       """
+        * executing `ns:with_period'
         * executing "cd /path/to/current/deployed/application && /usr/bin/env rake with_period"
       """
 
@@ -150,11 +155,51 @@ Feature: The #mirror_rake_tasks DSL method, inside a Capistrano namespace, witho
       ------------------------------------------------------------
       My task with one argument.
 
-      Set environment variable THE_ARG to pass a Rake task argument.
+      Set environment variable THE_ARG if you want to pass a Rake task argument.
 
 
       """
 
+  Scenario: mirror Rake task 'my_namespace' with its description
+    Given a full-featured Rakefile
+    And a Capfile with:
+      """
+      namespace :ns do
+        Cape do |cape|
+          cape.mirror_rake_tasks
+        end
+      end
+      """
+    When I run `cap -e ns:my_namespace`
+    Then the output should contain exactly:
+      """
+      ------------------------------------------------------------
+      cap ns:my_namespace
+      ------------------------------------------------------------
+      A task that shadows a namespace.
+
+
+      """
+
+  Scenario: mirror Rake task 'my_namespace' with its implementation
+    Given a full-featured Rakefile
+    And a Capfile with:
+      """
+      set :current_path, '/path/to/current/deployed/application'
+
+      namespace :ns do
+        Cape do |cape|
+          cape.mirror_rake_tasks
+        end
+      end
+      """
+    When I run `cap ns:my_namespace`
+    Then the output should contain:
+      """
+        * executing `ns:my_namespace'
+        * executing "cd /path/to/current/deployed/application && /usr/bin/env rake my_namespace"
+      """
+
   Scenario: mirror Rake task 'my_namespace:in_a_namespace' with its description
     Given a full-featured Rakefile
     And a Capfile with:
@@ -215,7 +260,8 @@ Feature: The #mirror_rake_tasks DSL method, inside a Capistrano namespace, witho
       ------------------------------------------------------------
       My task with two arguments.
 
-      Set environment variables MY_ARG1 and MY_ARG2 to pass Rake task arguments.
+      Set environment variables MY_ARG1 and MY_ARG2 if you want to pass Rake task
+      arguments.
 
 
       """
@@ -238,8 +284,8 @@ Feature: The #mirror_rake_tasks DSL method, inside a Capistrano namespace, witho
       ------------------------------------------------------------
       My task with three arguments.
 
-      Set environment variables AN_ARG1, AN_ARG2, and AN_ARG3 to pass Rake task
-      arguments.
+      Set environment variables AN_ARG1, AN_ARG2, and AN_ARG3 if you want to pass Rake
+      task arguments.
 
 
       """