gemma 0.0.2

data/README.rdoc

@@ -0,0 +1,150 @@
+= gemma
+
+http://github.com/jdleesmiller/gemma
+
+== DESCRIPTION
+
+If you are using .gemspecs as intended
+(http://yehudakatz.com/2010/04/02/using-gemspecs-as-intended/), gemma generates
+common rake tasks with default settings extracted from your .gemspec file.
+
+== SYNOPSIS
+
+To create a gem called +mygem+, first create <tt>mygem.gemspec</tt> as
+described in http://yehudakatz.com/2010/04/02/using-gemspecs-as-intended/.
+
+For more information about the gemspec, see the Gem::Specification Reference
+(http://docs.rubygems.org/read/chapter/20).
+
+Then put the following at the top of your <tt>Rakefile.rb</tt>:
+  begin
+    require 'rubygems'
+    require 'gemma'
+
+    Gemma::RakeTasks.with_gemspec_file 'mygem.gemspec'
+  rescue LoadError
+    # Gemma is not installed; print an (optional) message:
+    puts "Install gemma (sudo gem install gemma) for standard rake tasks."
+  end
+
+This gives you a list of standard rake tasks with settings based on your
+gemspec, in addition to any that you define yourself. (Note that the yard task
+only appears if you have the yard gem installed.)
+
+  rake clean         # Remove any temporary products.
+  rake clobber       # Remove any generated file.
+  rake clobber_rcov  # Remove rcov products for rcov
+  rake clobber_rdoc  # Remove rdoc products
+  rake rcov          # Analyze code coverage with tests
+  rake rdoc          # Build the rdoc HTML Files
+  rake rerdoc        # Force a rebuild of the RDOC files
+  rake test          # Run tests
+  rake yard          # Generate YARD Documentation
+
+You can customize the generated tasks by passing a block to
++with_gemspec_file+:
+
+  Gemma::RakeTasks.with_gemspec_file 'mygem.gemspec' do |g|
+    g.rdoc.title = 'My Gem Is Great'
+  end
+
+See the gemma API docs for more information.
+
+== REQUIREMENTS
+
+You must have ruby, rubygems and rake installed. Tasks are also included for
+rcov (http://eigenclass.org/hiki.rb?rcov) and yard (http://yardoc.org/).
+
+Gemma has been tested on:
+* x86-linux (Ubuntu 10.04) with Ruby 1.8.7p249
+* x86-linux (rvm) with Ruby 1.9.2p0 (2010-08-18 revision 29034)
+* x86_64-linux (CentOS) with Ruby 1.8.7p72
+* with yard 0.5.8 and 0.6.1
+* with rcov 0.9.6 and 0.9.9
+Gemma has not yet been tested on Windows.
+
+== INSTALL
+
+You should be able to install with
+
+  gem install gemma
+
+Alternatively, you can get the source with
+
+  git clone git://github.com/jdleesmiller/gemma.git
+
+and run
+
+  gem build gemma.gemspec
+  gem install gemma-<version>.gem
+
+== RELATED PROJECTS
+
+There are many projects that make gem development easier.
+Hoe and Jeweler are the most popular; they generate the gemspec and tasks using
+a configuration specified in the Rakefile, which is the opposite to what gemma
+does. Mr Bones is a gem template generator that appears to be similar to Hoe
+and Jeweler, but I haven't used it myself.
+
+* http://seattlerb.rubyforge.org/hoe/
+* http://github.com/technicalpickles/jeweler 
+* http://codeforpeople.rubyforge.org/bones/ 
+
+gemesis provides tasks for building, releasing and installing gems based on the
+gemspec, but (at the time of writing) it doesn't provide tasks for tests and
+documentation, etc.
+
+* http://github.com/markryall/gemesis/tree/master/lib/gemesis
+
+rake-compiler provides support for compiling native extensions from a
+gemspec, and it looks like it should work fairly well with gemma.
+
+* http://github.com/luislavena/rake-compiler
+
+Other helpful articles:
+
+* http://rubygems.rubyforge.org/rubygems-update/Gem/Version.html
+* http://jeffkreeftmeijer.com/2010/why-arent-you-using-git-flow/ 
+
+== TODO
+
+* make it easier to add custom tasks and / or new task generators, as in
+    # DOES NOT WORK YET
+    Gemma::RakeTasks.with_gemspec_file 'mygem.gemspec' do |g|
+      g.yard_dev = Gemma::RakeTasks::YardTasks.new(g.gemspec, :yard_dev)
+      g.yard_dev.output = 'dev_docs'
+      g.yard_dev.options.push('--protected', '--private')
+    end
+* more tasks (e.g. to publish docs)
+* generate gem skeletons
+* tasks for version control? (see http://github.com/nvie/gitflow)
+* contributions welcome!
+
+== HISTORY
+
+<em>0.0.1</em>
+* first release
+
+== LICENSE
+
+Copyright (c) 2010 John Lees-Miller
+
+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/lib/gemma.rb

@@ -0,0 +1,21 @@
+require 'gemma/version'
+require 'gemma/options'
+require 'gemma/rake_tasks'
+
+# Load default Rakefile plugins:
+require 'gemma/rake_tasks/plugin'
+require 'gemma/rake_tasks/gem_tasks'
+require 'gemma/rake_tasks/rcov_tasks'
+require 'gemma/rake_tasks/rdoc_tasks'
+require 'gemma/rake_tasks/yard_tasks'
+require 'gemma/rake_tasks/test_unit_tasks'
+
+#require 'gemma/utility'
+
+# Load default Rakefile plugins:
+#require 'gemma/rakefile/rdoc'
+#require 'gemma/rakefile/yard'
+#require 'gemma/rakefile/test_unit'
+#require 'gemma/rakefile/rcov'
+#require 'gemma/rakefile/gem'
+

data/lib/gemma/options.rb

@@ -0,0 +1,97 @@
+module Gemma
+  module Options
+    #
+    # @attr [String, nil] argument
+    # @attr [Array<String>] remaining_options
+    #
+    ExtractResult = Struct.new(:argument, :remaining_options)
+
+    #
+    # Extract the last option with one of the given `names` from `input`.
+    #
+    # Long form options of the form `--foo`, `--foo bar` and `--foo=bar` are
+    # supported (where `--foo` is the option name and `bar` is the argument in
+    # the last two forms).
+    #
+    # Short form options of the form `-f`, `-fbar` and `-f bar` are supported
+    # (where `-f` is the option name and `bar` is the argument in the last two
+    # forms). However concatenated short forms are not supported; that is, the
+    # option `-fg` is interpreted as `-f g` (option `f` with argument `g`)
+    # rather than `-f -g` (options `f` and `g` with no arguments).
+    #
+    # Abbreviated long form options (e.g. `--ex` for `--example`) are not
+    # supported, because this method doesn't know the full set of acceptable
+    # options, so it can't resolve ambiguities.
+    #
+    # If an option appears more than once, the argument for the last one is
+    # returned, and the previous matching options and arguments are deleted
+    # (i.e. not returned in {ExtractResult#remaining_options}).
+    #
+    # Matching options that appear after a `--` terminator are not extracted;
+    # they remain in the {ExtractResult#remaining_options} list.
+    #
+    # @example
+    #   Gemma::Options.extract(%w(-a), %w(-a foo bar.txt))
+    #   #=> #<struct Gemma::Options::ExtractResult argument="foo",
+    #   #     remaining_options=["bar.txt"]>
+    #
+    # @param [Array<String>] names one or more names for the option to extract
+    # (`['--file','-f']`, for example)
+    #
+    # @param [Array<String>] options to extract from; you should ensure that
+    # there isn't leading/trailing whitespace (strip), because this method
+    # doesn't detect it
+    #
+    # @return [ExtractResult] contains the argument for the given option and the
+    # rest of the options
+    #
+    def self.extract names, options
+      options = options.dup
+      result = nil
+      done = []
+
+      until options.empty?
+        x = options.shift
+        if x == '--' then
+          # Stop at the '--' terminator.
+          done << x
+          break
+        elsif x =~ /^(--[^=]+)/ then
+          if names.member?($1) then
+            # Found a long style option; look for its argument (if any).
+            if x =~ /=(.*)$/ then
+              result = $1
+            elsif !options.empty? && options.first !~ /^-./
+              result = options.shift
+            else
+              result = ''
+            end
+          else
+            done << x
+          end
+        elsif x =~ /^(-(.))(.*)/ then
+          # Found a short style option; this may actually represent several
+          # options; look for matching short options.
+          name, letter, rest = $1, $2, $3
+          if names.member?(name)
+            if rest.length > 0
+              result = rest
+            elsif !options.empty? && options.first !~ /^-./
+              result = options.shift
+            else
+              result = ''
+            end
+          else
+            done << x
+          end
+        else
+          # Not an option; just let it pass through.
+          done << x
+        end
+      end
+
+      ExtractResult.new(result, done + options)
+    end
+  end
+end
+

data/lib/gemma/rake_tasks.rb

@@ -0,0 +1,120 @@
+require 'rake/clean'
+
+module Gemma
+  #
+  # Generate standard gem development tasks; the tasks are configured using
+  # the settings in the given gemspec file.
+  #
+  # @example To create the default tasks based on your _mygem_.gemspec file:
+  #   # At the top of Rakefile.rb.
+  #   require 'rubygems'
+  #   require 'gemma'
+  #
+  #   Gemma::RakeTasks.with_gemspec_file 'mygem.gemspec'
+  #
+  #   # ... other tasks ...
+  #
+  class RakeTasks
+
+    # Alias for new.
+    class <<self
+      alias :with_gemspec_file :new
+    end
+
+    #
+    # Constructor for internal use; you should usually use the
+    # `with_gemspec_file` alias (see examples in {RakeTasks}).
+    #
+    # @param [String, Gem::Specification] gemspec either the name of a gemspec
+    # file or a gemspec object; the latter is intended mainly for testing
+    #
+    # @yield [tasks] used to customize the tasks to be created
+    #
+    # @yieldparam [Gemma::RakeTasks] tasks self
+    #
+    # @private
+    #
+    def initialize gemspec, &block
+      # Load gemspec.
+      if gemspec.is_a?(String)
+        @gemspec_file_name = gemspec
+        @gemspec = Gem::Specification::load(gemspec_file_name)
+      elsif gemspec.is_a?(Gem::Specification)
+        @gemspec_file_name = nil
+        @gemspec = gemspec
+      else
+        raise ArgumentError
+      end
+
+      @plugins = {}
+      create_default_plugins
+
+      # Let the user add more plugins and alter settings.
+      block.call(self) if block_given?
+
+      @plugins.values.each do |plugin|
+        plugin.create_rake_tasks
+      end
+    end
+
+    #
+    # File from which the {#gemspec} was loaded.
+    #
+    # @return [String] not nil if a gemspec file name was passed to the
+    # constructor; otherwise, nil
+    #
+    attr_reader :gemspec_file_name
+
+    #
+    # The specification used to configure the rake tasks.
+    #
+    # @return [Gem::Specification] not nil; you should not modify this object
+    # (make the changes in the gemspec file instead).
+    # 
+    attr_reader :gemspec
+
+    #
+    # @return [Hash<Symbol, Plugin>]
+    #
+    attr_reader :plugins
+
+    #
+    # @return [RcovTasks] 
+    #
+    def rcov; @plugins[:rcov] end
+
+    #
+    # @return [RDocTasks] 
+    #
+    def rdoc; @plugins[:rdoc] end
+
+    #
+    # @return [TestUnitTasks]
+    #
+    def test; @plugins[:test] end
+
+    #
+    # @return [YardTasks]
+    #
+    def yard; @plugins[:yard] end
+
+    #
+    # @return [GemTasks]
+    #
+    #def gem; @plugins[:gem] end
+
+    protected
+
+    def create_default_plugins
+      @plugins[:rcov] = Gemma::RakeTasks::RcovTasks.new(gemspec)
+      @plugins[:rdoc] = Gemma::RakeTasks::RDocTasks.new(gemspec)
+      @plugins[:test] = Gemma::RakeTasks::TestUnitTasks.new(gemspec)
+      @plugins[:yard] = Gemma::RakeTasks::YardTasks.new(gemspec)
+
+      # not that helpful yet
+      # @plugins[:gem]  = Gemma::RakeTasks::GemTasks.new(gemspec,
+      #   gemspec_file_name)
+    end
+
+  end
+end

data/lib/gemma/rake_tasks/gem_tasks.rb

@@ -0,0 +1,74 @@
+module Gemma
+  class RakeTasks
+    #
+    # Create tasks to build and release (push) gems.
+    #
+    # TODO not done yet
+    #
+    class GemTasks < Plugin
+      #
+      # @param [Gem::Specification] gemspec
+      # @param [String, nil] gemspec_file_name
+      #
+      def initialize gemspec, gemspec_file_name
+        super(gemspec)
+
+        @gemspec_file_name = gemspec_file_name
+
+        # Defaults.
+        @output = 'pkg'
+      end
+
+      #
+      # Name of the gemspec file to be built; if this is nil, no gem tasks are
+      # generated. 
+      #
+      # @return [String, nil] 
+      #
+      attr_accessor :gemspec_file_name
+
+      #
+      # Name of directory in which gem files are placed; defaults to pkg.
+      #
+      # @return [String]
+      #
+      attr_accessor :output
+
+      #
+      # Full path to gem file.
+      #
+      # @return [String]
+      #
+      def gem_file
+        File.join(output, gemspec.file_name)
+      end
+
+      #
+      # Internal method; see {Plugin#create_rake_tasks}.
+      #
+      # @return [nil]
+      #
+      # @private
+      #
+      def create_rake_tasks
+        if gemspec_file_name
+          directory output
+
+          desc "gem build"
+          task :build => output do
+            sh "gem build #{gemspec_file_name}"
+            mv gemspec.file_name, gem_file
+          end
+          CLOBBER.include(gem_file)
+           
+          desc "gem release"
+          task :release => :build do
+            sh "gem push #{gem_file}"
+          end
+        end
+
+        nil
+      end
+    end
+  end
+end

data/lib/gemma/rake_tasks/plugin.rb

@@ -0,0 +1,36 @@
+module Gemma
+  class RakeTasks
+    # 
+    # Plugins generate rake tasks based on the content of the gemspec.
+    #
+    # The intention is that the plugin processes the gemspec and sets
+    # (intelligent) default values when it is created. The {RakeTasks} object
+    # then calls {#create_rake_tasks} on every plugin that it knows about, after
+    # it has run its configuration block. The configuration block gives the
+    # caller a chance to customize the inputs to all of the plugins before they
+    # are generated.
+    #
+    class Plugin
+      def initialize gemspec
+        @gemspec = gemspec
+      end
+
+      #
+      # @return [Gem::Specification]
+      #
+      attr_reader :gemspec
+
+      #
+      # Internal method called by {RakeTasks} after the configuration block
+      # has executed; overriden by plugins to create rake tasks.
+      #
+      # @return [nil]
+      #
+      # @abstract
+      #
+      def create_rake_tasks
+        raise NotImplementedError
+      end
+    end
+  end
+end

data/lib/gemma/rake_tasks/rcov_tasks.rb

@@ -0,0 +1,78 @@
+module Gemma
+  class RakeTasks
+    #
+    # Create tasks to run test coverage using the built-in `rcov` tool. By
+    # default, the `test_files` given in the gemspec are used to measure
+    # coverage.
+    #
+    # This plugin is based on the `Rcov::RcovTask` that comes bundled with rcov.
+    # If you need an option that isn't exposed by the plugin, you can modify the
+    # `RcovTask` object directly in a block passed to {#with_rcov_task}. 
+    #
+    class RcovTasks < Plugin
+      #
+      # @param [Gem::Specification] gemspec
+      #
+      def initialize gemspec
+        super(gemspec)
+
+        # Defaults.
+        @task_name = :rcov
+        @output = 'rcov'
+        @with_rcov_task = nil
+      end
+
+      #
+      # Name of rake task; defaults to rcov.
+      #
+      # @return [Symbol]    
+      # 
+      attr_accessor :task_name
+
+      #
+      # Output directory for the XHTML report; defaults to rcov.
+      #
+      # @return [String] 
+      #
+      attr_accessor :output
+   
+      #
+      # Customize the rcov task.
+      #
+      # @yield [rcov] called after the defaults are set but before the rcov task
+      # is generated
+      #
+      # @yieldparam [Rcov::RcovTask] rcov
+      #
+      # @return [nil]
+      #
+      def with_rcov_task &block
+        @with_rcov_task = block
+        nil
+      end
+
+      #
+      # Internal method; see {Plugin#create_rake_tasks}.
+      #
+      # @return [nil]
+      #
+      # @private
+      #
+      def create_rake_tasks 
+        begin
+          require 'rcov/rcovtask'
+          Rcov::RcovTask.new(self.task_name) do |rcov|
+            rcov.libs       = gemspec.require_paths
+            rcov.test_files = gemspec.test_files
+            rcov.warning    = true
+            rcov.rcov_opts << "-x ^/"
+            rcov.output_dir = self.output
+            @with_rcov_task.call(rcov) if @with_rcov_task
+          end
+        rescue LoadError
+          # Assume rcov is not installed.
+        end
+      end
+    end
+  end
+end

data/lib/gemma/rake_tasks/rdoc_tasks.rb

@@ -0,0 +1,159 @@
+module Gemma
+  class RakeTasks
+    #
+    # Create tasks for generating `rdoc` API documentation with settings from
+    # the gemspec.
+    #
+    # The default settings are based on the `files`, `rdoc_options` and
+    # `extra_rdoc_files` data in the gemspec. By default, test cases (which
+    # might be included in `files`) are not documented.
+    #
+    # If an rdoc gem is installed, it will be used; otherwise, the built-in
+    # rdoc will be used.
+    #
+    # This plugin is based on the `Rake::RDocTask` that comes bundled with rake.
+    # If you need an option that isn't exposed by the plugin, you can modify the
+    # `RDocTask` object directly in a block passed to {#with_rdoc_task}. 
+    #
+    class RDocTasks < Plugin
+      #
+      # @param [Gem::Specification] gemspec
+      #
+      def initialize gemspec
+        super(gemspec)
+
+        # Defaults.
+        @use_gem_if_available = true
+        @task_name = :rdoc
+        @with_rdoc_task = nil
+
+        # I'm not sure whether it's a good idea to pass -o in the gemspec, but
+        # for now we'll handle it, because it's needed in the Rakefile.
+        @options = gemspec.rdoc_options
+        @output, @options = Options.extract(%w(-o --output --op), @options).to_a
+        @output ||= 'rdoc'
+
+        # Extract --main, --title and --template so RDocTask can have them.
+        @main, @options  = Options.extract(%w(-m --main), @options).to_a
+        @title, @options = Options.extract(%w(-t --title), @options).to_a
+        @template, @options = Options.extract(%w(-T --template), @options).to_a
+
+        # Don't include the test files by default.
+        @files = gemspec.files - gemspec.test_files
+      end
+
+      #
+      # Name of rake task used to generate these docs; defaults to rdoc.
+      #
+      # @return [Symbol]    
+      # 
+      attr_accessor :task_name
+
+      #
+      # Name of output directory (the rdoc option --output); extracted from
+      # gemspec; defaults to rdoc.
+      #
+      # @return [String] 
+      #
+      attr_accessor :output
+
+      #
+      # Name of file to display in index.html (the rdoc option --main);
+      # extracted from gemspec; defaults to nil (none).
+      #
+      # @return [String, nil] 
+      #
+      attr_accessor :main
+
+      #
+      # Title for HTML output (the rdoc option --title); extracted from gemspec;
+      # defaults to nil (unspecified).
+      #
+      # @return [String, nil] 
+      #
+      attr_accessor :title
+
+      #
+      # Name of template used to generate html output (the rdoc option
+      # --template); extracted from gemspec; defaults to nil (unspecified).
+      #
+      # @return [String, nil] 
+      #
+      attr_accessor :template
+
+      #
+      # If an rdoc gem is installed, use it instead of the rdoc from the
+      # standard library (default true). 
+      #
+      # While rdoc is part of the ruby standard library, newer versions are
+      # available as gems.
+      # 
+      # @return [Boolean]
+      #
+      attr_accessor :use_gem_if_available
+
+      #
+      # Files to be processed by rdoc; extracted from gemspec; test files are
+      # not included by default.
+      #
+      # @return [Array<String>] 
+      #
+      attr_accessor :files
+
+      #
+      # Options to be passed to rdoc; extracted from gemspec; note that
+      # the {#output}, {#main}, {#title} and {#template} options and the
+      # {#files} list are handled separately.
+      #
+      # @return [Array<String>] 
+      #
+      attr_accessor :options
+
+      #
+      # Customize the rdoc task.
+      #
+      # @yield [rd] called after the defaults are set but before the rdoc tasks
+      # are generated
+      #
+      # @yieldparam [Rake::RDocTask] rd
+      #
+      # @return [nil]
+      #
+      def with_rdoc_task &block
+        @with_rdoc_task = block
+        nil
+      end
+
+      #
+      # Internal method; see {Plugin#create_rake_tasks}.
+      #
+      # @return [nil]
+      #
+      # @private
+      #
+      def create_rake_tasks
+        if use_gem_if_available
+          begin
+            gem('rdoc')
+          rescue LoadError
+            # ignore -- just use the standard library one
+          end
+        end
+
+        require 'rake/rdoctask'
+        Rake::RDocTask.new(self.task_name) do |rd|
+          rd.rdoc_dir      = self.output
+          rd.rdoc_files    = self.files
+          rd.title         = self.title
+          rd.main          = self.main
+          rd.template      = self.template
+          rd.options       = self.options
+          rd.inline_source = false # doesn't seem to work on 1.8.7
+          @with_rdoc_task.call(rd) if @with_rdoc_task
+        end
+
+        nil
+      end
+    end
+  end
+end

data/lib/gemma/rake_tasks/test_unit_tasks.rb

@@ -0,0 +1,64 @@
+module Gemma
+  class RakeTasks
+    #
+    # Create tasks to run Test::Unit tests using the built-in (standard library)
+    # `test/unit`. By default, the `test_files` given in the gemspec are tested.
+    #
+    # This plugin is based on the `Rake::TestTask` that comes bundled with rake.
+    # If you need an option that isn't exposed by the plugin, you can modify the
+    # `TestTask` object directly in a block passed to {#with_test_task}. 
+    #
+    class TestUnitTasks < Plugin
+      #
+      # @param [Gem::Specification] gemspec
+      #
+      def initialize gemspec
+        super(gemspec)
+
+        # Defaults.
+        @task_name = :test
+        @with_test_task = nil
+      end
+
+      #
+      # Name of rake task used to generate these docs; defaults to test.
+      #
+      # @return [Symbol]    
+      # 
+      attr_accessor :task_name
+
+      #
+      # Customize the test task.
+      #
+      # @yield [tt] called after the defaults are set but before the test task
+      # is generated
+      #
+      # @yieldparam [Rake::TestTask] tt
+      #
+      # @return [nil]
+      #
+      def with_test_task &block
+        @with_test_task = block
+        nil
+      end
+
+      #
+      # Internal method; see {Plugin#create_rake_tasks}.
+      #
+      # @return [nil]
+      #
+      # @private
+      #
+      def create_rake_tasks
+        require 'rake/testtask'
+        Rake::TestTask.new(self.task_name) do |tt|
+          tt.libs        = gemspec.require_paths
+          tt.test_files  = gemspec.test_files
+          tt.warning     = true
+          @with_test_task.call(tt) if @with_test_task
+        end
+        nil
+      end
+    end
+  end
+end

data/lib/gemma/rake_tasks/yard_tasks.rb

@@ -0,0 +1,165 @@
+module Gemma
+  class RakeTasks
+    #
+    # Create tasks to generate documentation with yard (yardoc) if it is
+    # available.
+    #
+    # The files to document are extracted from the gemspec's `files` and
+    # `extra_rdoc_files` members.
+    #
+    # Unfortunately, yardoc's command line options are largely incompatible with
+    # those for rdoc, but the `--main` and `--title` options from `rdoc_options`
+    # are also passed through to yardoc by default. The short forms `-m` and
+    # `-t` of these arguments are also passed on as `--main` and `--title` to
+    # yardoc (note that `-m` and `-t` mean different things to yardoc than to
+    # rdoc!). Note that any files (that is, non-options) in `rdoc_options` are
+    # also ignored.
+    #
+    # If you want to further customize your yardoc output, you can add options
+    # in the {Gemma::RakeTasks.with_gemspec_file} configuration block.
+    #
+    # This plugin is based on the `YARD::Rake::YardocTask` that comes bundled
+    # with yard.  If you need an option that isn't exposed by the plugin, you
+    # can modify the `YardocTask` object directly in a block passed to
+    # {#with_yardoc_task}. 
+    #
+    class YardTasks < Plugin
+      #
+      # @param [Gem::Specification] gemspec
+      #
+      def initialize gemspec
+        super(gemspec)
+
+        # Defaults.
+        @task_name = :yard
+        @output = 'yard'
+        @with_yardoc_task = nil
+
+        # Extract supported rdoc options and add to the default yard options.
+        # Keep track of main, if it is given, because we have to remove it from
+        # the extra files list (otherwise it shows up twice in the output).
+        @main = Options.extract(%w(-m --main), gemspec.rdoc_options).argument
+        @title = Options.extract(%w(-t --title), gemspec.rdoc_options).argument
+
+        @options = []
+
+        # Don't document the test files.
+        # Yard splits up the ruby files from the 'extra' files.
+        @files = gemspec.files - gemspec.test_files - gemspec.extra_rdoc_files
+        @extra_files = gemspec.extra_rdoc_files.dup
+        @extra_files.delete(main) if main
+      end
+
+      #
+      # Name of rake task used to generate these docs; defaults to yard.
+      #
+      # @return [Symbol] 
+      #
+      attr_accessor :task_name
+
+      #
+      # Name of output directory (the yard option --output); defaults to yard.
+      #
+      # @return [String] 
+      #
+      attr_accessor :output
+
+      #
+      # Name of file to display in index.html (the yard option --main);
+      # extracted from gemspec; defaults to nil (none).
+      #
+      # @return [String, nil] 
+      #
+      attr_accessor :main
+
+      #
+      # Title for HTML output (the yard option --title); extracted from gemspec;
+      # defaults to nil (unspecified).
+      #
+      # @return [String, nil] 
+      #
+      attr_accessor :title
+
+      #
+      # Ruby files to be processed by yard; these are extracted from the
+      # gemspec; test files are not included by default.
+      #
+      # @return [Array<String>] 
+      #
+      attr_accessor :files
+
+      #
+      # Extra files (e.g. FAQ, LICENSE) to be processed by yard; these are
+      # extracted from the gemspec.
+      #
+      # @return [Array<String>] 
+      #
+      attr_accessor :extra_files
+
+      #
+      # Options to be passed to yard; note that the {#output} option and the
+      # {#files} and {#extra_files} lists are handled separately.
+      #
+      # @return [Array<String>]
+      #
+      attr_accessor :options
+
+      #
+      # Customize the yardoc task (e.g. to add blocks to run before or after the
+      # docs are generated).
+      #
+      # @yield [yd] called after the defaults are set but before the yard task
+      # is generated
+      #
+      # @yieldparam [YARD::Rake::YardocTask] yd
+      #
+      # @return [nil]
+      #
+      def with_yardoc_task &block
+        @with_yardoc_task = block
+        nil
+      end
+
+      #
+      # Internal method; see {Plugin#create_rake_tasks}.
+      #
+      # @return [nil]
+      #
+      # @private
+      #
+      def create_rake_tasks
+        begin
+          require 'yard'
+          YARD::Rake::YardocTask.new do |yd|
+            yd.name    = self.task_name
+            yd.options = complete_options
+            yd.files   = self.files
+            yd.files.push('-', *self.extra_files) unless self.extra_files.empty?
+            @with_yardoc_task.call(yd) if @with_yardoc_task
+          end
+          CLOBBER.include(self.output)
+          CLOBBER.include('.yardoc')
+        rescue LoadError
+          # Assume yard is not installed.
+        end
+        nil
+      end
+
+      private 
+
+      # 
+      # Options to be passed to yardoc; this includes {#options} and the
+      # {#main}, {#title} and {#output} options.
+      #
+      # @return [Array<String>]
+      # 
+      def complete_options
+        opts = self.options.dup
+        opts.push('--main', self.main) if self.main
+        opts.push('--title', self.title) if self.title
+        opts.push('--output', self.output)
+        opts
+      end
+    end
+  end
+end

data/lib/gemma/version.rb

@@ -0,0 +1,3 @@
+module Gemma
+  VERSION = '0.0.2'
+end

data/test/test_gemma.rb

@@ -0,0 +1,137 @@
+require "test/unit"
+require "rubygems"
+require "gemma"
+require "set"
+
+class TestGemma < Test::Unit::TestCase
+  def test_empty_spec
+    s = Gem::Specification.new
+    Gemma::RakeTasks.new(s)
+  end
+
+  def test_rdoc
+    s = Gem::Specification.new
+    s.files = %w(lib/a.rb lib/b.rb)
+    s.test_files = %w(test/test_a.rb test/test_a.rb)
+    s.rdoc_options = ['--main', 'README.md']
+    s.extra_rdoc_files = ['README.md', 'FAQ']
+
+    Gemma::RakeTasks.new(s) do |g|
+      assert_equal %w(lib/a.rb lib/b.rb README.md FAQ).to_set,
+        g.rdoc.files.to_set
+      assert_equal [], g.rdoc.options
+      assert_equal 'README.md', g.rdoc.main
+      assert_equal nil, g.rdoc.title
+
+      g.rdoc.with_rdoc_task do |rd|
+        assert_equal rd.rdoc_files, g.rdoc.files
+      end
+    end
+  end
+
+  def test_yard
+    s = Gem::Specification.new
+    s.files = %w(lib/a.rb)
+    s.test_files = %w(test/test_a.rb)
+    s.rdoc_options = ['--main', 'README.rdoc']
+    s.extra_rdoc_files = ['README.rdoc']
+ 
+    # Just one option.
+    # A file should not be passed as an extra file if it's the --main file.
+    # Test files should not be documented.
+    Gemma::RakeTasks.new(s) do |g|
+      assert_equal %w(lib/a.rb), g.yard.files
+      assert_equal [], g.yard.extra_files
+      assert_equal 'README.rdoc', g.yard.main
+      assert_equal [], g.yard.options
+      assert_equal 'yard', g.yard.output
+      assert_equal :yard, g.yard.task_name
+      assert_equal nil, g.yard.title
+
+      g.yard.with_yardoc_task do |yd|
+        assert_equal %w(lib/a.rb), yd.files
+        assert_equal 4, yd.options.size
+        assert_equal 'README.rdoc',
+          Gemma::Options.extract(%w(--main), yd.options).argument
+        assert_equal 'yard',
+          Gemma::Options.extract(%w(--output), yd.options).argument
+      end
+    end
+
+    # Add some extra files (that aren't the --main file).
+    s.extra_rdoc_files << 'FAQ'
+    Gemma::RakeTasks.new(s) do |g|
+      assert_equal %w(lib/a.rb), g.yard.files
+      assert_equal %w(FAQ), g.yard.extra_files
+      assert_equal 'README.rdoc', g.yard.main
+      assert_equal [], g.yard.options
+    end
+
+    # Make sure extra options are ignored.
+    s.rdoc_options = ['--main', 'README.rdoc', '--diagram']
+    Gemma::RakeTasks.new(s) do |g|
+      assert_equal %w(lib/a.rb), g.yard.files
+      assert_equal %w(FAQ), g.yard.extra_files
+      assert_equal 'README.rdoc', g.yard.main
+      assert_equal [], g.yard.options
+    end
+    s.rdoc_options = ['--diagram', '--main', 'README.rdoc']
+    Gemma::RakeTasks.new(s) do |g|
+      assert_equal %w(lib/a.rb), g.yard.files
+      assert_equal %w(FAQ), g.yard.extra_files
+      assert_equal 'README.rdoc', g.yard.main
+      assert_equal [], g.yard.options
+    end
+
+    # Some more complicated options.
+    # Note that we ignore things that could be files ('bat').
+    s.rdoc_options = ['foo bar', '--baz', 'bat', '--title', 'a b c',
+      '--diagram', '--main', 'README.rdoc', 'ABCD']
+    Gemma::RakeTasks.new(s) do |g|
+      assert_equal 'a b c', g.yard.title
+      assert_equal [], g.yard.options
+
+      g.yard.with_yardoc_task do |yd|
+        assert_equal %w(lib/a.rb - FAQ), yd.files
+        assert_equal 6, yd.options.size
+        assert_equal 'README.rdoc',
+          Gemma::Options.extract(%w(--main), yd.options).argument
+        assert_equal 'yard',
+          Gemma::Options.extract(%w(--output), yd.options).argument
+        assert_equal 'a b c',
+          Gemma::Options.extract(%w(--title), yd.options).argument
+      end
+    end
+  end
+
+  def test_test_unit
+    s = Gem::Specification.new
+    s.files = %w(lib/a.rb lib/b.rb)
+    s.test_files = %w(test/test_a.rb test/test_b.rb)
+    s.require_paths << 'ext'
+
+    Gemma::RakeTasks.new(s) do |g|
+      g.test.with_test_task do |tt|
+        assert_equal %w(lib ext).to_set, tt.libs.to_set
+        assert_equal %w(test/test_a.rb test/test_b.rb).to_set,
+          tt.file_list.to_a.to_set
+      end
+    end
+  end
+
+  def test_rcov
+    s = Gem::Specification.new
+    s.files = %w(lib/a.rb lib/b.rb)
+    s.test_files = %w(test/test_a.rb test/test_b.rb)
+    s.require_paths << 'ext'
+
+    Gemma::RakeTasks.new(s) do |g|
+      g.rcov.with_rcov_task do |rcov|
+        assert_equal %w(lib ext).to_set, rcov.libs.to_set
+        assert_equal %w(test/test_a.rb test/test_b.rb).to_set,
+          rcov.file_list.to_a.to_set
+      end
+    end
+  end
+end
+

data/test/test_options.rb

@@ -0,0 +1,101 @@
+require "test/unit"
+require "rubygems"
+require "gemma"
+
+class TestOptions < Test::Unit::TestCase
+  include Gemma
+
+  def test_empty 
+    # empty input
+    assert_equal Options::ExtractResult.new(nil, []),
+      Options.extract(%w(--a), [])
+  end
+
+  def test_long_form
+    input = %w(--a av --b --c=cv)
+
+    # option a has an argument
+    assert_equal Options::ExtractResult.new('av', %w(--b --c=cv)),
+      Options.extract(%w(--a), input)
+
+    # option b has no argument; result is ''
+    assert_equal Options::ExtractResult.new('', %w(--a av --c=cv)),
+      Options.extract(%w(--b), input)
+
+    # option c also has argument
+    assert_equal Options::ExtractResult.new('cv', %w(--a av --b)),
+      Options.extract(%w(--c), input)
+
+    # there is no option d; result is nil
+    assert_equal Options::ExtractResult.new(nil, input),
+      Options.extract(%w(--d), input)
+  end
+
+  def test_terminator
+    # just the -- terminator
+    assert_equal Options::ExtractResult.new(nil, ['--']),
+      Options.extract(%w(--a), ['--'])
+
+    # should keep content before and after the -- terminator
+    assert_equal Options::ExtractResult.new(nil, %w(a -- b)),
+      Options.extract(%w(--a), %w(a -- b))
+  end
+
+  def test_terminator_2
+    input = %w(foo --a av  -- --b bv)
+
+    # should not be able to find options after the -- terminator 
+    assert_equal Options::ExtractResult.new('av', %w(foo -- --b bv)),
+      Options.extract(%w(--a), input)
+    assert_equal Options::ExtractResult.new(nil, input),
+      Options.extract(%w(--b), input)
+    assert_equal Options::ExtractResult.new('', %w(-- --b)),
+      Options.extract(%w(--a), %w(--a -- --b))
+    assert_equal Options::ExtractResult.new(nil, %w(--a -- --b)),
+      Options.extract(%w(--b), %w(--a -- --b))
+  end
+
+  def test_short_form
+    # should be able to find -a but not -b
+    input = %w(foo -a av  -- -b bv)
+    assert_equal Options::ExtractResult.new('av', %w(foo -- -b bv)),
+      Options.extract(%w(-a), input)
+    assert_equal Options::ExtractResult.new(nil, input),
+      Options.extract(%w(-b), input)
+
+    # the -aav and -b bv forms
+    input = %w(-aav -b bv)
+    assert_equal Options::ExtractResult.new('av', %w(-b bv)),
+      Options.extract(%w(-a), input)
+    assert_equal Options::ExtractResult.new('bv', %w(-aav)),
+      Options.extract(%w(-b), input)
+
+    # short form with no argument
+    assert_equal Options::ExtractResult.new('', %w(-a av)),
+      Options.extract(%w(-b), %w(-a av -b))
+
+    # missing short form argument
+    assert_equal Options::ExtractResult.new(nil, %w(-a av -b foo bar.txt)),
+      Options.extract(%w(-c), %w(-a av -b foo bar.txt))
+  end
+
+  def test_multiple_options
+    # single -a means we pick up a1
+    assert_equal Options::ExtractResult.new('a1', []),
+      Options.extract(%w(-a), %w(-a a1))
+
+    # the second -a means that we pick up a2
+    assert_equal Options::ExtractResult.new('a2', []),
+      Options.extract(%w(-a), %w(-a a1 -a a2))
+    assert_equal Options::ExtractResult.new('a2', %w(hi -bfoo)),
+      Options.extract(%w(-a), %w(hi -a a1 -a a2 -bfoo))
+
+    # mixing long and short forms doesn't affect this
+    assert_equal Options::ExtractResult.new('a2', []),
+      Options.extract(%w(-a --a), %w(-a a1 --a a2))
+
+    # a duplicate option after the -- terminator makes no difference
+    assert_equal Options::ExtractResult.new('a1', %w(-- -aa2)),
+      Options.extract(%w(-a), %w(-a a1 -- -aa2))
+  end
+end

metadata

@@ -0,0 +1,86 @@
+--- !ruby/object:Gem::Specification 
+name: gemma
+version: !ruby/object:Gem::Version 
+  hash: 27
+  prerelease: false
+  segments: 
+  - 0
+  - 0
+  - 2
+  version: 0.0.2
+platform: ruby
+authors: 
+- John Lees-Miller
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-09-20 00:00:00 +01:00
+default_executable: 
+dependencies: []
+
+description: |
+  If you are using .gemspecs as intended
+  (http://yehudakatz.com/2010/04/02/using-gemspecs-as-intended/), gemma generates
+  common rake tasks with default settings extracted from your .gemspec file.
+
+email: 
+- jdleesmiller@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README.rdoc
+files: 
+- lib/gemma/rake_tasks/gem_tasks.rb
+- lib/gemma/rake_tasks/rcov_tasks.rb
+- lib/gemma/rake_tasks/yard_tasks.rb
+- lib/gemma/rake_tasks/rdoc_tasks.rb
+- lib/gemma/rake_tasks/test_unit_tasks.rb
+- lib/gemma/rake_tasks/plugin.rb
+- lib/gemma/options.rb
+- lib/gemma/rake_tasks.rb
+- lib/gemma/version.rb
+- lib/gemma.rb
+- README.rdoc
+- test/test_options.rb
+- test/test_gemma.rb
+has_rdoc: true
+homepage: http://github.com/jdleesmiller/gemma
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --main
+- README.rdoc
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.7
+signing_key: 
+specification_version: 3
+summary: Generate helpful rake tasks from your gemspec.
+test_files: 
+- test/test_options.rb
+- test/test_gemma.rb