shoe 0.6.1 → 0.6.2

data/CHANGELOG.rdoc

@@ -1,3 +1,13 @@
+== Git
+
+* Generated C extension actually works now.
+* `rake test` now properly depends on `rake compile`.
+* Run Gem::Validator tests via Test::Unit::AutoRunner, so that redgreen has a chance to color the dots as well as the result line.
+* Generated gemspec now selects files with Dir.glob instead of `git ls-files`.
+* Always generate a section 3 manpage.
+* `rake clean` now preserves <tt>.bundle/</tt> and <tt>.rvmrc</tt>.
+* Include C extensions in RDoc.
+
 == 0.6.1 -- 2010 April 22
 
 * Reformat warning messages.

data/README.rdoc

@@ -38,7 +38,8 @@ Shoe is an ecosystem-friendly library of Rake tasks for your gem.
 Shoe::Tasks accept no direct configuration. Instead, they rely on your project environment:
 
 Shoe::Tasks::Clean::
-  calls <tt>`git clean -fdX`</tt>.
+  calls something like <tt>`git clean -fdX`</tt>, but preserves
+  <tt>.bundle/</tt> and <tt>.rvmrc</tt>.
 
 Shoe::Tasks::Compile::
   builds the
@@ -102,9 +103,6 @@ Or, if you have <tt>{gem-man}[http://github.com/defunkt/gem-man]</tt> installed:
 
  $ gem man shoe
 
-Also, if you're using {Bundler}[http://gembundler.com], see
-<tt>BUNDLER.rdoc</tt> for some helpful tips.
-
 
 == Contribute
 

data/TODO.rdoc

@@ -1,6 +1,12 @@
 = Next Up
 
+* Remove Launchy? (Follow hub's lead.)
+* Start running on 1.9: Gem::Validator uses MiniTest::Unit.
+
+= Someday Maybe
+
+* Re-think focus: probably want to ditch cucumber, since I'm not using it for shoe?
+* Document rake task hooks prepare:execute and prepare:release.
+* Use a generator framework?
 * Generator should do the right thing when the base directory has a dash in it.
-* Find a better way to clean; I don't want to whack .bundler and .rvmrc.
 * Add :only/:except options to Shoe::Tasks.define.
-* Port cucumber features to Test::Unit so they'll be run under `gem check --test shoe`.

data/data/shoe/templates/extension.erb

@@ -3,7 +3,23 @@
 static VALUE m<%= module_name %>;
 static VALUE m<%= extension_module_name %>;
 
-void Init_ext() {
+/*
+ * Document-class: <%= extension_module_name %>
+ * Document-method: run
+ *
+ * call-seq:
+ *   run -> nil
+ *
+ */
+static VALUE run(VALUE self) {
+  return Qnil;
+}
+
+/*
+ * Documentation for <%= extension_module_name %>.
+ */
+void Init_extension() {
   m<%= module_name %> = rb_define_module("<%= module_name %>");
-  m<%= extension_module_name %> = rb_define_module_under("<%= module_name %>", "<%= extension_module_name %>");
+  m<%= extension_module_name %> = rb_define_module_under(m<%= module_name %>, "<%= extension_module_name %>");
+  rb_define_method(m<%= extension_module_name %>, "run", run, 0);
 }

data/data/shoe/templates/gemspec.erb

@@ -26,22 +26,14 @@ Gem::Specification.new do |spec|
   # spec.add_development_dependency 'ronn'
   spec.add_development_dependency 'shoe'
 
-  # This may not be the best way to select files for inclusion in your gem, but
-  # it does at least honor your .gitignore, keeping that bit of your
-  # configuration DRY. Alternatively, you could use more explicit Dir.glob
-  # patterns or even try reading a Manifest file, hoe-style.
-  def spec.git_files(glob=nil)
-    `git ls-files -z --cached --other --exclude-standard #{glob}`.split("\0")
-  end
-
   # The kooky &File.method(:basename) trick keeps us from accidentally
   # shadowing a variable named "file" in the context that evaluates this
   # gemspec. I actually ran into this problem with Bundler!
-  spec.files            = spec.git_files
-  spec.executables      = spec.git_files('bin/*').map &File.method(:basename)
-  spec.extensions       = spec.git_files('ext/**/extconf.rb')
-  spec.extra_rdoc_files = spec.git_files('{,**/}*.rdoc')
-  spec.test_files       = spec.git_files('test/{,**/}*_test.rb')
+  spec.files            = Dir['**/*.rdoc', 'bin/*', 'data/**/*', 'ext/**/*.{rb,c}', 'lib/**/*.rb', 'man/**/*', 'test/**/*.rb']
+  spec.executables      = Dir['bin/*'].map &File.method(:basename)
+  spec.extensions       = Dir['ext/**/extconf.rb']
+  spec.extra_rdoc_files = Dir['**/*.rdoc', 'ext/**/*.c']
+  spec.test_files       = Dir['test/**/*_test.rb']
 
   spec.rdoc_options = %W(
     --main README.rdoc

data/data/shoe/templates/{manpage.erb → manpage_1.erb}

@@ -18,13 +18,12 @@ Write your description here.
 
 * `-v`, `--version`[=all]:
   Print `<%= name %>`'s version number and exit. If `=all` is given, also print
-  version numbers of `<%= name %>`'s dependencies. (This is standard `optparse` behavior
-  that deserves more attention!)
+  version numbers of `<%= name %>`'s dependencies.
 
 ## AUTHOR
 
-<%= `git config --get user.name`.chomp %> <<%= `git config --get user.email`.chomp %>>
+<%= `git config --get user.name`.chomp %>, [<%= `git config --get github.user`.chomp %>](http://github.com/<%= `git config --get github.user`.chomp %>) on GitHub.
 
 ## SEE ALSO
 
-ruby(1)
+<%= name %>(3)

data/data/shoe/templates/manpage_3.erb

@@ -0,0 +1,19 @@
+<%= name %>(3) --
+=================
+
+## SYNOPSIS
+
+`require '<%= name %>'`
+<%= module_name %>.somthing(_parameter_)
+
+## DESCRIPTION
+
+Write your description here.
+
+## AUTHOR
+
+<%= `git config --get user.name`.chomp %>, [<%= `git config --get github.user`.chomp %>](http://github.com/<%= `git config --get github.user`.chomp %>) on GitHub.
+
+## SEE ALSO
+
+ruby(1)

data/lib/shoe.rb

@@ -3,7 +3,7 @@ require 'rbconfig'
 require 'rbconfig/datadir'
 
 module Shoe
-  VERSION = '0.6.1'
+  VERSION = '0.6.2'
 
   autoload :Extensions, 'shoe/extensions'
   autoload :Generator,  'shoe/generator'

data/lib/shoe/extensions.rb

@@ -5,6 +5,7 @@ module Shoe
     autoload :Pathname,      'shoe/extensions/pathname'
     autoload :SourceIndex,   'shoe/extensions/source_index'
     autoload :Specification, 'shoe/extensions/specification'
+    autoload :TestRunner,    'shoe/extensions/test_runner'
     autoload :Validator,     'shoe/extensions/validator'
   end
 end

data/lib/shoe/extensions/option_parser.rb

@@ -13,7 +13,7 @@ module Shoe
     # To use:
     #   parser = OptionsParser.new do |opts|
     #              opts.extend(Shoe::Extensions::OptionParser)
-    #              opts.defaults = %w(--foo --no-bar --baz=5)
+    #              opts.defaults = %w(--foo --no-bar --baz=42)
     #              # ... and so on ...
     #            end
     #
@@ -26,11 +26,9 @@ module Shoe
       end
 
       def order(*args, &block)
-        begin
-          super(*defaults.followed_by(*args), &block)
-        rescue ::OptionParser::ParseError
-          abort($!)
-        end
+        super(*defaults.followed_by(*args), &block)
+      rescue ::OptionParser::ParseError
+        abort($!)
       end
 
       def help
@@ -41,7 +39,7 @@ module Shoe
 
       module Defaults #:nodoc:
         def followed_by(*args)
-          dup.concat(*args)
+          dup.concat(args.flatten)
         end
 
         def help(before, indent)

data/lib/shoe/extensions/test_runner.rb

@@ -0,0 +1,28 @@
+module Shoe
+  module Extensions
+
+    module TestRunner
+      # Conforms the normal TestRunner interface to the slightly different form
+      # called by Gem::Validator.
+      #
+      # Note that we use Test::Unit::AutoRunner (rather than going directly for
+      # Test::Unit::UI::Console::TestRunner) in order to give redgreen a chance
+      # to register itself, should it have been required in one of the
+      # test_files.
+      def self.run(suite, ui)
+        runner = Test::Unit::AutoRunner.new(false)
+        runner.collector = lambda { suite }
+        runner.run.extend(BooleanPassed)
+      end
+
+      private
+
+      module BooleanPassed #:nodoc:
+        def passed?
+          self
+        end
+      end
+    end
+
+  end
+end

data/lib/shoe/extensions/validator.rb

@@ -2,12 +2,24 @@ module Shoe
   module Extensions
 
     module Validator
-      def alert_error(*args)
-        # no-op
+      def self.extended(base)
+        base.send :include, InstanceMethods
+        base.test_runner = TestRunner
       end
 
-      def unit_test(*args)
-        exit(1) unless super.passed?
+      def test_runner=(klass)
+        remove_const :TestRunner
+        const_set    :TestRunner, klass
+      end
+
+      module InstanceMethods #:nodoc:
+        def alert_error(*args)
+          # no-op
+        end
+
+        def unit_test(*args)
+          exit(1) unless super.passed?
+        end
       end
     end
 

data/lib/shoe/generator.rb

@@ -52,11 +52,12 @@ module Shoe
         install('rakefile.erb',  'Rakefile')
         install('gemspec.erb',   "#{name}.gemspec")
         install('module.erb',    "lib/#{name}.rb")
+        install('manpage_3.erb', "man/#{name}.3.ronn")
 
         if application?
           install('executable.erb',  "bin/#{name}", 0755)
           install('application.erb', "lib/#{name}/application.rb")
-          install('manpage.erb',     "man/#{name}.1.ronn")
+          install('manpage_1.erb',   "man/#{name}.1.ronn")
         end
 
         if data?

data/lib/shoe/tasks/clean.rb

@@ -4,7 +4,9 @@ module Shoe
     # Defines <tt>`rake clean`</tt> to remove <tt>.gitignore</tt>d files and
     # directories.
     #
-    # Uses <tt>`{git clean}[http://www.kernel.org/pub/software/scm/git/docs/git-clean.html] -fdX`</tt>.
+    # Uses something like <tt>`{git
+    # clean}[http://www.kernel.org/pub/software/scm/git/docs/git-clean.html]
+    # -fdX`</tt>, except preserves <tt>.bundle/</tt> and <tt>.rvmrc</tt>.
     #
     # To enable, version your project with git[http://git-scm.com].
     #
@@ -16,11 +18,26 @@ module Shoe
       end
 
       def define
-        desc 'Remove ignored files'
+        desc <<-END.gsub(/^ */, '')
+          Remove ignored files.
+          Configure via your .gitignore file. Uses something like `git clean -fdX`,
+          except preserves .bundle/ and .rvmrc.
+        END
+
         task :clean do
-          sh 'git clean -fdX'
+          rm_r ignored_files - preserved_files
         end
       end
+
+      private
+
+      def ignored_files
+        `git ls-files -z --exclude-standard --ignored --others --directory`.split("\0")
+      end
+
+      def preserved_files
+        %w( .bundle/ .rvmrc )
+      end
     end
 
   end

data/lib/shoe/tasks/compile.rb

@@ -19,7 +19,11 @@ module Shoe
       end
 
       def define
-        desc 'Compile C extensions'
+        desc <<-END.gsub(/^ */, '')
+          Compile C extensions.
+          Configure via the `extensions` field in #{spec.name}.gemspec.
+        END
+
         task :compile do
           top_level_path   = File.expand_path('.')
           destination_path = File.join(top_level_path, spec.require_paths.first)

data/lib/shoe/tasks/cucumber.rb

@@ -48,7 +48,7 @@ module Shoe
           task :execute
         end
 
-        ::Cucumber::Rake::Task.new({ :cucumber => 'prepare:execute' }, 'Run features') do |task|
+        ::Cucumber::Rake::Task.new({ :cucumber => 'prepare:execute' }, "Run features.\nConfigure via the default profile in cucumber.yml.") do |task|
           task.profile = 'default'
         end
 
@@ -61,7 +61,7 @@ module Shoe
         end
 
         namespace :cucumber do
-          ::Cucumber::Rake::Task.new({ profile => 'prepare:execute' }, "Run #{profile} features") do |task|
+          ::Cucumber::Rake::Task.new({ profile => 'prepare:execute' }, "Run #{profile} features.\nConfigure via the #{profile} profile in cucumber.yml.") do |task|
             task.profile = profile
           end
         end

data/lib/shoe/tasks/rdoc.rb

@@ -29,7 +29,12 @@ module Shoe
       end
 
       def define
-        desc 'Generate documentation'
+        desc <<-END.gsub(/^ */, '')
+          Generate documentation.
+          Configure via the `rdoc_options` and `extra_rdoc_files` fields in
+          #{spec.name}.gemspec. Open in a different browser by setting the
+          BROWSER environment variable.
+        END
         task :rdoc do
           Gem::DocManager.new(spec).extend(Extensions::DocManager).generate_rdoc
           Launchy::Browser.run('rdoc/index.html')

data/lib/shoe/tasks/release.rb

@@ -33,7 +33,7 @@ module Shoe
       end
 
       def define
-        desc "Release #{spec.full_name}"
+        desc "Release #{spec.full_name}."
         task :release do
           sh "git commit -a -m 'Release #{spec.version}'"
           sh "git tag #{version_tag(spec.version)}"

data/lib/shoe/tasks/ronn.rb

@@ -14,9 +14,8 @@ module Shoe
     #
     # == Notes
     #
-    # * It's best to check the generated man pages into version control so
-    #   they'll be included in your gem for
-    #   {gem-man}[http://github.com/defunkt/gem-man].
+    # * It's best to include the generated man pages in your gem, so that
+    #   {gem-man}[http://github.com/defunkt/gem-man] can get to them.
     #
     # * Ronn becomes a prerequisite for Release, so your man pages are sure to
     #   be up-to-date.
@@ -42,7 +41,12 @@ module Shoe
       private
 
       def define_tasks
-        desc 'Generate man pages'
+        desc <<-END.gsub(/^ */, '')
+          Generate man pages.
+          Configure via the `date` and `authors` fields in #{spec.name}.gemspec.
+          Uses ronn sources in man/*.ronn.
+        END
+
         task :ronn => 'ronn:build' do
           sh 'man', *man_files
         end

data/lib/shoe/tasks/test.rb

@@ -44,45 +44,62 @@ module Shoe
     # <tt>{dependencies}[http://docs.rubygems.org/read/chapter/20#dependencies]</tt>
     # are on the <tt>$LOAD_PATH</tt>.
     #
-    # <b>Bad:</b>
+    # <b>Wrong:</b>
     #
     #  # Don't do this; test_helper's not in the $LOAD_PATH
     #  require 'test_helper'
     #
-    # <b>Good:</b>
+    # <b>Right:</b>
     #
     #  require 'test/test_helper'
     #
+    # = Pretty Colors
+    #
+    # If you like pretty colors (I do!), just <tt>require
+    # '{redgreen}[http://rubygems.org/gems/redgreen]'</tt> in your tests. The
+    # <tt>Gem::Validator</tt> has been configured to play nicely with it.
+    #
+    # <b>Wrong:</b>
+    #
+    #  # Don't do this; it breaks `gem check --test` if redgreen's not installed.
+    #  require 'redgreen' if $stdout.tty?
+    #
+    # <b>Right:</b>
+    #
+    #  begin
+    #    require 'redgreen' if $stdout.tty?
+    #  rescue LoadError
+    #    # No colors, but `gem check --test` is golden!
+    #  end
+    #
     class Test < Abstract
       def active?
         !spec.test_files.empty?
       end
 
       def define
-        desc 'Run tests'
+        desc <<-END.gsub(/^ */, '')
+          Run tests.
+          Configure via the `test_files` field in #{spec.name}.gemspec.
+        END
+
         task :test do
           Gem.source_index.extend(Extensions::SourceIndex)
           Gem.source_index.local_gemspec = spec
 
-          Gem::Validator.send(:remove_const, :TestRunner)
-          Gem::Validator.const_set(:TestRunner, LocalTestRunner)
-          Gem::Validator.new.extend(Extensions::Validator).unit_test(spec)
+          Gem::Validator.extend(Extensions::Validator)
+          Gem::Validator.new.unit_test(spec)
         end
 
-        task :prepare
-        task :test => :prepare
+        namespace :prepare do
+          task :execute
+        end
+
+        task :test => 'prepare:execute'
 
         task :default
         Rake.application[:default].prerequisites.unshift(Rake.application[:test])
       end
-
-      private
-
-      class LocalTestRunner < ::Test::Unit::UI::Console::TestRunner #:nodoc:
-        def self.run(*args)
-          new(args.first, ::Test::Unit::UI::NORMAL).start
-        end
-      end
     end
 
   end