cape 1.0.0

data/.gitignore

@@ -0,0 +1,6 @@
+.bundle
+.rvmrc
+.yardoc
+Gemfile.lock
+doc
+pkg

data/.travis.yml

@@ -0,0 +1,7 @@
+bundler_args: --without development
+rvm:
+  - 1.8.7
+  - 1.9.2
+  - 1.9.3
+  - ree
+script: "bundle exec rake test"

data/.yardopts

@@ -0,0 +1 @@
+--file MIT-LICENSE.markdown --file History.markdown --no-private --protected --title "Cape"

data/Gemfile

@@ -0,0 +1,18 @@
+source 'http://rubygems.org'
+
+gemspec
+
+gem 'jruby-openssl',          :platforms => :jruby
+
+group :development 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 'yard',                 :platforms => [:ruby, :mswin, :mingw]
+  gem 'rdiscount',            :platforms => [:ruby, :mswin, :mingw]
+end

data/History.markdown

@@ -0,0 +1,7 @@
+Version history for the _Cape_ project
+======================================
+
+<a name="v1.0.0"></a>v1.0.0, Mon 11/28/2011
+-------------------------------------------
+
+(First release)

data/MIT-LICENSE.markdown

@@ -0,0 +1,10 @@
+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").
+
+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,157 @@
+                    _____     __
+                   / ___/___ / /_  __ _____ __ ______
+                  / (_ // -_) __/ / // / _ | // / __/
+                  \___/ \__/\__/  \_, /\___|_,_/_/
+          '-(+++++...            /___/ ............  s++++++++.
+       .(++++++++++++(      -+++~~~~~  'N++++++++++= B++++++++s
+      '+++++++++++++++(     DN=++++++< -NB+++++++++s Bz++++++++
+      +++++++++++++++++.   'NNN=++++++(-BNB+++++++++'BN========-
+     =B=+++++++++sDBBBBs<. +NNNN=+++++(<NNNBDBDBNNNNDBNNBBBBBBBz
+    'NN+s+++++=BBBh=+((+sB=DNNNNNBBBNNDhNNNN'   ..  -BNs      (z
+    sN+N+z+++sBs-        .hNNNNBNh(-'   NNNN.  .NB-  <Ns   +BBBz
+    D+N+N+z=Bs.   .~.     'NNNNNB~      DNNN   .NN+  (Ns   =B+~
+    BN+N+NNB+    ~NBD      BNNNBN   h'  hNNN   .Bs<  <Ns   =Dz~
+    BNNNN+ND     +BhB      DNNNBz  'N~  sNNN   'ND'  hNs    -(z-
+    NNNNNNB(     sDDN      hNNNB(  +N~  +NNN    ..-<hBNs    ~=h-
+    NNNNNNB-     sDBN     'DNNNN.  DN~  <BNN   'NNhs(NNs   =NN-
+    NNNNNNB'     zNNN(+sDNNBNNNz  .NB(  ~BNN   'D    NNs   =Bh~
+    NNNNNNN.     zNNNBNBBNNNNNB(  <NB~  'BNB   'D    <Bs   =NNNN
+    NNNNNNN.     zNNNNNNNNNNBNN.  .     .NDB   -D     hs       N
+    NNNNNNN.     zNNNNNhBNBN=+z   +BN-   NDB  '(D     <BhhhhhhhN
+    BNNNNNN.     zNNNh=<~. h-s<   D~D'.-~B<NBNBDs     ''``
+    DNNNNNN.     zNNN      D-B-~(+B DNBDzs-`
+    sNNNNNN.     zNNN      B(NDhs=(  ''`
+    (BNNNNN'     zNDB     ~D.
+     sNNNNB-     +hsz     h<                             O___
+      <NNNB(     -=s'   'hz      ___  ___              < s > \____
+        ~BNh          .+B+      / _ \/ _ \               = \    /
+          ~Dz~.   .~+zB='       \___/_//_/              / \ \__/
+            <hNNBNBh=(.                                /   \   `
+               ..
+
+Cape
+====
+
+If
+
+* **You use [Capistrano](http://capify.org)** to deploy your application, and
+* **You have [Rake](http://rake.rubyforge.org) tasks you want to run remotely** — but you don’t want to hand-code Capistrano recipes for each Rake task —
+
+Then
+
+* **You can invoke [Cape](http://github.com/njonsson/cape)** to dynamically add Capistrano recipes for each of your application’s Rake tasks, and
+* **You can run your Rake tasks on your deployed servers,** friction-free, and look like a superhero. _[cue fanfare]_
+
+Features
+--------
+
+* **Mirror Rake tasks** as Capistrano recipes, optionally filtered by namespace or name
+* **Embed Rake tasks** in a Capistrano namespace
+* **Pass arguments** to Rake tasks by setting environment variables with the same names
+* **Override the default executables** for local and remote Rake installations (`/usr/bin/env rake` is the default)
+* **Enumerate Rake tasks** for your own purposes
+
+Examples
+--------
+
+Assume we have the following _Rakefile_.
+
+    desc 'Rakes the leaves'
+    task :leaves do
+      # (Raking action goes here.)
+    end
+
+    desc 'Rakes and bags the leaves'
+    task :bag_leaves, [:paper_or_plastic] => :leaves do
+      # (Bagging action goes here.)
+    end
+
+Rake lists these tasks in the expected fashion.
+
+    $ rake --tasks
+    rake bag_leaves[paper_or_plastic]  # Rakes and bags the leaves
+    rake leaves                        # Rakes the leaves
+
+Put the following in your _config/deploy.rb_. **Note that Cape statements must be executed within a `Cape` block.**
+
+    require 'cape'
+
+    Cape do
+      # Create Capistrano recipes for all Rake tasks.
+      mirror_rake_tasks
+    end
+
+Now all your Rake tasks can be invoked as Capistrano recipes. Capistrano lists the recipes in the following fashion.
+
+    $ cap --tasks
+    cap deploy               # Deploys your project.
+    ...
+    [other built-in Capistrano recipes]
+    ...
+    cap bag_leaves           # Rakes and bags the leaves.
+    cap leaves               # Rakes the leaves.
+    Some tasks were not listed, either because they have no description,
+    or because they are only used internally by other tasks. To see all
+    tasks, type `cap -vT'.
+
+    Extended help may be available for these tasks.
+    Type `cap -e taskname' to view it.
+
+Let’s use Capistrano to view the unabbreviated description of a Rake task recipe, including instructions for how to pass arguments to it. Note that Rake task parameters are automatically converted to environment variables.
+
+    $ cap --explain bag_leaves
+    ------------------------------------------------------------
+    cap bag_leaves
+    ------------------------------------------------------------
+    Bags the leaves.
+
+    You must set environment variable PAPER_OR_PLASTIC.
+
+Cape lets you filter the Rake tasks to be mirrored:
+
+    Cape do
+      # Create Capistrano recipes for the Rake task 'foo' or for the tasks in a
+      # 'foo' namespace.
+      mirror_rake_tasks :foo
+
+      # Create Capistrano recipes only for the Rake task 'bar:baz' or for the
+      # tasks in the 'bar:baz' namespace.
+      mirror_rake_tasks 'bar:baz'
+    end
+
+Cape plays friendly with the Capistrano DSL for organizing Rake tasks in Capistrano namespaces.
+
+    # Use an argument with the Cape block, if you want to or need to.
+    namespace :rake_tasks do
+      Cape do |cape|
+        cape.mirror_rake_tasks
+      end
+    end
+
+Cape lets you enumerate Rake tasks, optionally filtering them by task name or namespace.
+
+    Cape do
+      each_rake_task do |t|
+        # Do something interesting with this hash:
+        # * t[:name] -- the full name of the task
+        # * t[:parameters] -- the names of task arguments
+        # * t[:description] -- documentation on the task, including parameters
+      end
+    end
+
+Limitations
+-----------
+
+For now, only Rake tasks that have descriptions can be mirrored or enumerated.
+
+Contributing
+------------
+
+Report defects and feature requests on [GitHub Issues](http://github.com/njonsson/cape/issues).
+
+Your patches are welcome, and you will receive attribution here for good stuff.
+
+License
+-------
+
+Released under the [MIT License](http://github.com/njonsson/cape/blob/master/MIT-LICENSE.markdown).

data/Rakefile

@@ -0,0 +1,49 @@
+require 'bundler/gem_tasks'
+require 'cucumber'
+require 'cucumber/rake/task'
+require 'rspec/core/rake_task'
+
+begin
+  require 'yard'
+rescue LoadError
+else
+  namespace :build do
+    YARD::Rake::YardocTask.new :doc
+  end
+end
+
+Cucumber::Rake::Task.new :features, 'Test features'
+
+def define_spec_task(name, options={})
+  RSpec::Core::RakeTask.new name do |t|
+    t.rspec_opts = ['--color']
+    unless options[:debug] == false
+      begin
+        require 'ruby-debug'
+      rescue LoadError
+      else
+        t.rspec_opts << '--debug'
+      end
+    end
+    t.pattern = "spec/**/*_spec.rb"
+  end
+end
+
+desc 'Run all specs'
+define_spec_task :spec
+
+desc 'Run all specs and test features'
+task ''       => [:spec, :features]
+task :default => [:spec, :features]
+
+# Support the 'gem test' command.
+namespace :test do
+  desc ''
+  define_spec_task :specs, :debug => false
+
+  Cucumber::Rake::Task.new :features, '' do |t|
+    t.bundler = false
+    t.cucumber_opts = '--backtrace'
+  end
+end
+task :test => %w(test:specs test:features)

data/cape.gemspec

@@ -0,0 +1,36 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path('../lib', __FILE__)
+require 'cape/version'
+
+Gem::Specification.new do |s|
+  s.name        = 'cape'
+  s.version     = Cape::VERSION
+  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.license     = 'MIT'
+
+  # TODO: Apply for RubyForge project
+  # s.rubyforge_project = 'cape'
+
+  s.required_ruby_version = '>= 1.8.7'
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map do |f|
+                      File.basename f
+                    end
+  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'
+end

data/features/dsl/each_rake_task/with_defined_namespace_argument.feature

@@ -0,0 +1,43 @@
+Feature: The #each_rake_task DSL method with an argument of a defined namespace
+
+  In order to use the metadata of Rake tasks in my Capistrano recipes,
+  As a developer using Cape,
+  I want to use the Cape DSL.
+
+  Scenario: enumerate only the Rake tasks in the matching namespace
+    Given a full-featured Rakefile
+    And a file named "Capfile" with:
+      """
+      require 'cape'
+
+      Cape do
+        each_rake_task :my_namespace 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."
+      """
+    And the output should contain:
+      """
+
+      Name: "my_namespace:in_a_namespace"
+      Description: "My task in a namespace"
+      """
+    And the output should contain:
+      """
+
+      Name: "my_namespace:my_nested_namespace:in_a_nested_namespace"
+      Description: "My task in a nested namespace"
+      """

data/features/dsl/each_rake_task/with_defined_task_argument.feature

@@ -0,0 +1,37 @@
+Feature: The #each_rake_task DSL method with an argument of a defined task
+
+  In order to use the metadata of Rake tasks in my Capistrano recipes,
+  As a developer using Cape,
+  I want to use the Cape DSL.
+
+  Scenario: enumerate only the matching Rake task
+    Given a full-featured Rakefile
+    And a file named "Capfile" with:
+      """
+      require 'cape'
+
+      Cape do
+        each_rake_task 'with_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 contain:
+      """
+
+      Name: "with_period"
+      Description: "Ends with period."
+      """
+    And the output should not contain:
+      """
+
+      Name: "without_period"
+      Description: "Ends without period"
+      """

data/features/dsl/each_rake_task/with_undefined_argument.feature

@@ -0,0 +1,31 @@
+Feature: The #each_rake_task DSL method with an undefined argument
+
+  In order to use the metadata of Rake tasks in my Capistrano recipes,
+  As a developer using Cape,
+  I want to use the Cape DSL.
+
+  Scenario: do not enumerate any Rake tasks
+    Given a full-featured Rakefile
+    And a file named "Capfile" with:
+      """
+      require 'cape'
+
+      Cape do
+        each_rake_task :this_does_not_exist 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

@@ -0,0 +1,81 @@
+Feature: The #each_rake_task DSL method without arguments
+
+  In order to use the metadata of Rake tasks in my Capistrano recipes,
+  As a developer using Cape,
+  I want to use the Cape DSL.
+
+  Scenario: enumerate all non-hidden Rake tasks
+    Given a full-featured Rakefile
+    And a file named "Capfile" with:
+      """
+      require 'cape'
+
+      Cape do
+        each_rake_task 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 contain:
+      """
+
+      Name: "with_period"
+      Description: "Ends with period."
+      """
+    And the output should contain:
+      """
+
+      Name: "without_period"
+      Description: "Ends without period"
+      """
+    And the output should contain:
+      """
+
+      Name: "long"
+      Description: "My long task -- it has a very, very, very, very, very, very, very, very, very, very, very, very, very, very, very, very, very, very, very, very, very, very, very, very, very, very long description"
+      """
+    And the output should contain:
+      """
+
+      Name: "with_one_arg"
+      Parameters: ["the_arg"]
+      Description: "My task with one argument"
+      """
+    And the output should contain:
+      """
+
+      Name: "my_namespace:in_a_namespace"
+      Description: "My task in a namespace"
+      """
+    And the output should contain:
+      """
+
+      Name: "my_namespace:my_nested_namespace:in_a_nested_namespace"
+      Description: "My task in a nested namespace"
+      """
+    And the output should contain:
+      """
+
+      Name: "with_two_args"
+      Parameters: ["my_arg1", "my_arg2"]
+      Description: "My task with two arguments"
+      """
+    And the output should contain:
+      """
+
+      Name: "with_three_args"
+      Parameters: ["an_arg1", "an_arg2", "an_arg3"]
+      Description: "My task with three arguments"
+      """
+    And the output should not contain:
+      """
+
+      Name: "hidden_task"
+      """