inochi 0.3.0 → 1.0.0

data/lib/inochi.rb

@@ -1,9 +1,15 @@
+#--
+# Copyright 2008 Suraj N. Kurapati
+# See the LICENSE file for details.
+#++
+
 require 'rubygems'
 
 module Inochi
+  libs = File.dirname(__FILE__)
+  $LOAD_PATH << libs unless $LOAD_PATH.include? libs
 end
 
-$LOAD_PATH << File.dirname(__FILE__)
 require 'inochi/init'
 require 'inochi/main'
 require 'inochi/rake'
@@ -11,19 +17,25 @@ require 'inochi/book'
 require 'inochi/util'
 
 Inochi.init :Inochi,
-  :version => '0.3.0',
-  :release => '2009-02-12',
+  :version => '1.0.0',
+  :release => '2009-05-03',
   :website => 'http://snk.tuxfamily.org/lib/inochi',
   :tagline => 'Gives life to RubyGems-based software',
   :require => {
-    'rake'        => '~> 0',
-    'rubyforge'   => '~> 1',              # for publishing gems to RubyForge
-    'mechanize'   => '~> 0',              # for automating web browsing
-    'trollop'     => '~> 1',              # for parsing command-line options
-    'erbook'      => '~> 6',              # for processing the user manual
-    'launchy'     => '~> 0',              # for launching a web browser
-    'yard'        => nil,                 # for generating API documentation
-    'addressable' => '~> 2',              # for parsing URIs properly
-    'minitest'    => ['>= 1.3.1', '< 2'], # for unit testing
-    'babelfish'   => '~> 0',              # for human language translation
+    'trollop'        => '~> 1',      # for parsing command-line options
+    'launchy'        => '>= 0.3.3',  # for launching a web browser
+  },
+  :develop => {
+    'rake'           => '>= 0.8.4',
+    'rubyforge'      => '~> 1',      # for publishing gems to RubyForge
+    'mechanize'      => '~> 0',      # for automating web browsing
+    'voloko-sdoc'    => '>= 0.2.10', # for generating API documentation
+    'addressable'    => '~> 2',      # for parsing URIs properly
+    'erbook'         => '~> 7',      # for processing the user manual
+    'babelfish'      => '~> 0',      # for human language translation
+    'spicycode-rcov' => nil,         # for code coverage statistics
+    'flay'           => nil,         # for code quality analysis
+    'reek'           => nil,         # for code quality analysis
+    'roodi'          => nil,         # for code quality analysis
+    'ZenTest'        => '~> 4',      # for the `multiruby` tool
   }

data/lib/inochi/book.rb

@@ -1,4 +1,9 @@
-class << Inochi
+#--
+# Copyright 2008 Suraj N. Kurapati
+# See the LICENSE file for details.
+#++
+
+module Inochi
   ##
   # Provides a common configuration for the project's user manual:
   #
@@ -25,14 +30,16 @@ class << Inochi
   # It is assumed that this method is called
   # from within the Inochi.rake() environment.
   #
-  # @param [Symbol] project_symbol
+  # ==== Parameters
+  #
+  # [project_symbol]
   #   Name of the Ruby constant which serves
   #   as a namespace for the entire project.
   #
-  # @param [ERBook::Document::Template] book_template
+  # [book_template]
   #   The eRuby template which serves as the documentation for the project.
   #
-  def book project_symbol, book_template
+  def Inochi.book project_symbol, book_template
     project_module = fetch_project_module(project_symbol)
 
     # provide project constants as global variables to the user manual
@@ -60,7 +67,7 @@ class << Inochi
     ##
     # Defines a brief summary of this project.
     #
-    def project_summary
+    def project
       raise ArgumentError, 'block must be given' unless block_given?
 
       node do
@@ -72,7 +79,7 @@ class << Inochi
     ##
     # Contains release notes for all project releases.
     #
-    def project_history
+    def history
       raise ArgumentError, 'block must be given' unless block_given?
 
       node do

data/lib/inochi/init.rb

@@ -1,6 +1,11 @@
+#--
+# Copyright 2008 Suraj N. Kurapati
+# See the LICENSE file for details.
+#++
+
 require 'yaml'
 
-class << Inochi
+module Inochi
   ##
   # Establishes your project in Ruby's runtime environment by defining
   # the project module (which serves as a namespace for all code in the
@@ -17,63 +22,76 @@ class << Inochi
   # within any of its descendant directories) the project lib/ directory.
   # Ideally, this method would be invoked from the main project library.
   #
-  # @param [Symbol] project_symbol
+  # ==== Parameters
+  #
+  # [project_symbol]
   #   Name of the Ruby constant which serves
   #   as a namespace for the entire project.
   #
-  # @param [Hash] project_config
-  #   Project configuration parameters:
+  # [project_config]
+  #   Optional hash of project configuration parameters:
   #
-  #   [String] :project =>
+  #   [:project]
   #     Name of the project.
   #
   #     The default value is the value of the project_symbol parameter.
   #
-  #   [String] :tagline =>
+  #   [:tagline]
   #     An enticing, single line description of the project.
   #
   #     The default value is an empty string.
   #
-  #   [String] :website =>
+  #   [:website]
   #     URL of the published project website.
   #
   #     The default value is an empty string.
   #
-  #   [String] :docsite =>
+  #   [:docsite]
   #     URL of the published user manual.
   #
   #     The default value is the same value as the :website parameter.
   #
-  #   [String] :program =>
+  #   [:program]
   #     Name of the main project executable.
   #
   #     The default value is the value of the :project parameter
   #     in lowercase and CamelCase converted into snake_case.
   #
-  #   [String] :version =>
+  #   [:version]
   #     Version of the project.
   #
   #     The default value is "0.0.0".
   #
-  #   [String] :release =>
+  #   [:release]
   #     Date when this version was released.
   #
   #     The default value is the current time.
   #
-  #   [String] :display =>
+  #   [:display]
   #     How the project name should be displayed.
   #
   #     The default value is the project name and version together.
   #
-  #   [String] :install =>
+  #   [:install]
   #     Path to the directory which contains the project.
   #
   #     The default value is one directory above the parent
   #     directory of the file from which this method was called.
   #
-  #   [Hash] :require =>
-  #     The names and version constraints of ruby gems required by
-  #     this project.  This information must be expressed as follows:
+  #   [:require]
+  #     Hash containing the names and version constraints of RubyGems required
+  #     to run this project.  This information must be expressed as follows:
+  #
+  #     * Each hash key must be the name of a ruby gem.
+  #
+  #     * Each hash value must be either +nil+, a single version number
+  #       requirement string (see Gem::Requirement) or an Array thereof.
+  #
+  #     The default value is an empty Hash.
+  #
+  #   [:develop]
+  #     Hash containing the names and version constraints of RubyGems required
+  #     to build this project.  This information must be expressed as follows:
   #
   #     * Each hash key must be the name of a ruby gem.
   #
@@ -82,9 +100,11 @@ class << Inochi
   #
   #     The default value is an empty Hash.
   #
-  # @return [Module] The newly configured project module.
+  # ==== Returns
+  #
+  # The newly configured project module.
   #
-  def init project_symbol, project_config = {}
+  def Inochi.init project_symbol, project_config = {}
     project_module = fetch_project_module(project_symbol)
 
     # this method is not re-entrant
@@ -93,7 +113,7 @@ class << Inochi
       @already_seen << project_module
 
     # put project on Ruby load path
-      project_file = File.expand_path(first_caller_file)
+      project_file = first_caller_file
       project_libs = File.dirname(project_file)
       $LOAD_PATH << project_libs unless $LOAD_PATH.include? project_libs
 
@@ -108,6 +128,7 @@ class << Inochi
       project_config[:program] ||= calc_program_name(project_symbol)
       project_config[:install] ||= File.dirname(project_libs)
       project_config[:require] ||= {}
+      project_config[:develop] ||= {}
 
     # establish gem version dependencies and
     # sanitize the values while we're at it
@@ -115,11 +136,7 @@ class << Inochi
       dst = project_config[:require].clear
 
       src.each_pair do |gem_name, version_reqs|
-        gem_name     = gem_name.to_s
-        version_reqs = [version_reqs].flatten.compact
-
-        dst[gem_name] = version_reqs
-        gem gem_name, *version_reqs
+        dst[gem_name] = require_gem_version(gem_name, version_reqs)
       end
 
     # make configuration parameters available as constants

data/lib/inochi/main.rb

@@ -1,3 +1,8 @@
+#--
+# Copyright 2008 Suraj N. Kurapati
+# See the LICENSE file for details.
+#++
+
 ##
 # Provides a common configuration for the main project executable:
 #
@@ -14,17 +19,19 @@
 # It is assumed that this method is invoked from only within
 # the main project executable (in the project bin/ directory).
 #
-# @param [Symbol] project_symbol
+# ==== Parameters
+#
+# [project_symbol]
 #   Name of the Ruby constant which serves
 #   as a namespace for the entire project.
 #
-# @param trollop_args
-#   Optional arguments for Trollop::options().
+# [trollop_args]
+#   Optional array of arguments for Trollop::options().
 #
-# @param trollop_config
-#   Optional block argument for Trollop::options().
+# [trollop_config]
+#   Optional block parameter passed to Trollop::options().
 #
-# @return The result of Trollop::options().
+# Returns the result of Trollop::options().
 #
 def Inochi.main project_symbol, *trollop_args, &trollop_config
   program_file = first_caller_file
@@ -63,7 +70,10 @@ def Inochi.main project_symbol, *trollop_args, &trollop_config
 
     if options[:manual]
       require 'launchy'
-      Launchy::Browser.run "#{project_module::INSTALL}/doc/index.xhtml"
+
+      manual = File.join(project_module::INSTALL, 'doc', 'index.xhtml')
+      Launchy::Browser.run manual
+
       exit
     end
 

data/lib/inochi/rake.rb

@@ -1,3 +1,8 @@
+#--
+# Copyright 2008 Suraj N. Kurapati
+# See the LICENSE file for details.
+#++
+
 ##
 # Provides Rake tasks for packaging, publishing, and announcing your project.
 #
@@ -18,69 +23,89 @@
 #   when the copyright holder first began working on the project, and
 #   EMAIL is (optional) the email address of the copyright holder.
 #
-# @param [Symbol] project_symbol
+# ==== Parameters
+#
+# [project_symbol]
 #   Name of the Ruby constant which serves
 #   as a namespace for the entire project.
 #
-# @param [Hash] options
-#   Additional method parameters, which are all optional:
+# [options]
+#   Optional hash of configuration parameters:
+#
+#   [:test_with]
+#     Names of Ruby libraries inside the "inochi/test/"
+#     namespace to load before running the test suite.
 #
-#   [Array] :authors =>
+#     The default value is an empty Array.
+#
+#   [:authors]
 #     A list of project authors and their contact information.  This
 #     list must have the form "[[name, info]]" where "name" is the name
 #     of a project author and "info" is their contact information.
 #
-#   [String] :license_file =>
+#     The default value is automatically extracted from
+#     your project's license file (see description above).
+#
+#   [:license_file]
 #     Path (relative to the main project directory which contains the
-#     project Rakefile) to the file which contains the project license.
+#     project rakefile) to the file which contains the project license.
 #
 #     The default value is "LICENSE".
 #
-#   [String] :logins_file =>
+#   [:logins_file]
 #     Path to the YAML file which contains login
 #     information for publishing release announcements.
 #
 #     The default value is "~/.config/inochi/logins.yaml"
 #     where "~" is the path to your home directory.
 #
-#   [String] :rubyforge_project =>
+#   [:rubyforge_project]
 #     Name of the RubyForge project where
 #     release packages will be published.
 #
 #     The default value is the value of the PROGRAM constant.
 #
-#   [String] :rubyforge_section =>
+#   [:rubyforge_section]
 #     Name of the RubyForge project's File Release System
 #     section where release packages will be published.
 #
 #     The default value is the value of the :rubyforge_project parameter.
 #
-#   [String] :raa_project =>
+#   [:raa_project]
 #     Name of the RAA (Ruby Application Archive) entry for this project.
 #
 #     The default value is the value of the PROGRAM constant.
 #
-#   [String] :upload_target =>
+#   [:upload_target]
 #     Where to upload the project documentation.
 #     See "destination" in the rsync manual.
 #
 #     The default value is nil.
 #
-#   [String] :upload_delete =>
+#   [:upload_delete]
 #     Delete unknown files at the upload target location?
 #
 #     The default value is false.
 #
-#   [Array] :upload_options =>
-#     Additional command-line arguments to the rsync command.
+#   [:upload_options]
+#     Array of command-line arguments to the rsync command.
 #
 #     The default value is an empty array.
 #
-# @param gem_config
-#   Block that is passed to Gem::specification.new()
-#   for additonal gem configuration.
+#   [:inochi_consumer]
+#     Add Inochi as a runtime dependency to the created gem?
 #
-# @yieldparam [Gem::Specification] gem_spec the gem specification
+#     The default value is true.
+#
+#   [:inochi_producer]
+#     Add Inochi as a development dependency to the created gem?
+#
+#     The default value is true.
+#
+# [gem_config]
+#   Optional block that is passed
+#   to Gem::specification.new() for
+#   additonal gem configuration.
 #
 def Inochi.rake project_symbol, options = {}, &gem_config
   program_file = first_caller_file
@@ -94,6 +119,8 @@ def Inochi.rake project_symbol, options = {}, &gem_config
     project_module = fetch_project_module(project_symbol)
 
   # supply default options
+    options[:test_with]         ||= []
+
     options[:rubyforge_project] ||= program_name
     options[:rubyforge_section] ||= program_name
     options[:raa_project]       ||= program_name
@@ -104,9 +131,11 @@ def Inochi.rake project_symbol, options = {}, &gem_config
                                       '.config', 'inochi', 'logins.yaml'
                                     )
 
-    options[:upload_delete]     ||= false
     options[:upload_options]    ||= []
 
+    options[:inochi_consumer]   = true unless options.key? :inochi_consumer
+    options[:inochi_producer]   = true unless options.key? :inochi_producer
+
   # add AUTHORS constant to the project module
     copyright_holders = options[:authors] ||
       File.read(options[:license_file]).
@@ -115,6 +144,13 @@ def Inochi.rake project_symbol, options = {}, &gem_config
 
     project_module.const_set :AUTHORS, copyright_holders
 
+  # establish development gem dependencies
+    [project_module, Inochi].uniq.each do |mod|
+      mod::DEVELOP.each_pair do |gem_name, version_reqs|
+        require_gem_version gem_name, version_reqs
+      end
+    end
+
   require 'rake/clean'
 
   hide_rake_task = lambda do |name|
@@ -186,31 +222,39 @@ def Inochi.rake project_symbol, options = {}, &gem_config
     end
 
   # testing
-    desc 'Run all unit tests.'
-    task :test do
-      ruby '-w', '-I.', '-Ilib', '-r', program_name, '-e', %q{
+    test_runner = lambda do |interpreter|
+      require 'tempfile'
+      script = Tempfile.new($$).path # will be deleted on program exit
+
+      libs = [program_name] + # load the project-under-test's library FIRST!
+        Array(options[:test_with]).map {|lib| "inochi/test/#{lib}" }
+
+      File.write script, %{
+        # the "-I." option lets us load helper libraries inside
+        # the test suite via "test/PROJECT_NAME/LIBRARY_NAME"
+        $LOAD_PATH.unshift '.', 'lib'
+
+        #{libs.inspect}.each do |lib|
+          require lib
+        end
+
+        # set title of test suite
+        $0 = #{project_module.to_s.inspect}
+
         # dump language phrases *after* exercising all code (and
         # thereby populating the phrases cache) in the project
         at_exit do
           if ENV['dump_lang_phrases'] == '1'
-            file = %s
-            list = %s::PHRASES.phrases
+            file = #{File.expand_path(lang_dump_file).inspect}
+            list = eval(#{project_symbol.to_s.inspect})::PHRASES.phrases
             data = list.map {|s| s + ':' }.join("\n")
 
             File.write file, data
 
-            puts "Extracted #{list.length} language phrases into #{file.inspect}"
+            puts "Extracted \#{list.length} language phrases into \#{file.inspect}"
           end
         end
 
-        # set title of test suite
-        $0 = File.basename(Dir.pwd)
-
-        require 'minitest/unit'
-        require 'minitest/spec'
-        require 'minitest/mock'
-        MiniTest::Unit.autorun
-
         Dir['test/**/*.rb'].sort.each do |test|
           unit = test.sub('test/', 'lib/')
 
@@ -225,10 +269,73 @@ def Inochi.rake project_symbol, options = {}, &gem_config
             require unit_path
             require test_path
           else
-            warn "Skipped test #{test.inspect} because it lacks a corresponding #{unit.inspect} unit."
+            warn "Skipped test \#{test.inspect} because it lacks a corresponding \#{unit.inspect} unit."
           end
         end
-      } % [lang_dump_file.inspect, project_symbol]
+      }
+
+      command = [interpreter.to_s]
+
+      if interpreter == :rcov
+        command.push '--output', 'cov'
+
+        # omit internals from coverage analysis
+        command.push '--exclude-only', script
+        command.push '--exclude', Inochi::INSTALL
+
+        require 'rbconfig'
+        ruby_internals = File.dirname(Config::CONFIG['rubylibdir'])
+        command.push '--exclude', /^#{Regexp.quote ruby_internals}/.to_s
+
+        # show results summary after execution
+        command.push '-T'
+      else
+        # enable Ruby warnings during execution
+        command << '-w'
+      end
+
+      command << script
+
+      require 'shellwords'
+      command.concat Shellwords.shellwords(ENV['opts'].to_s)
+
+      sh(*command)
+    end
+
+    desc 'Run tests.'
+    task :test do
+      test_runner.call :ruby
+    end
+
+    desc 'Run tests with code coverage analysis.'
+    task 'test:cov' do
+      test_runner.call :rcov
+    end
+
+    CLEAN.include 'cov'
+
+    desc 'Run tests with multiple Ruby versions.'
+    task 'test:ruby' do
+      test_runner.call :multiruby
+    end
+
+    desc 'Report code quality statistics.'
+    task 'lint' do
+      separator = '-' * 80
+
+      linter = lambda do |*command|
+        name = command.first
+
+        puts "\n\n", separator, name, separator
+        system(*command)
+      end
+
+      ruby_files = Dir['**/*.rb']
+
+      linter.call 'sloccount', '.'
+      linter.call 'flay' # operates on all .rb & .erb files by default
+      linter.call 'reek', *ruby_files
+      linter.call 'roodi', *ruby_files
     end
 
   # documentation
@@ -264,20 +371,32 @@ def Inochi.rake project_symbol, options = {}, &gem_config
       doc_api_dst = 'doc/api'
 
       desc 'Build API reference.'
-      task 'doc:api' => doc_api_dst
+      task 'doc:api' => 'doc:api:rdoc'
 
-      require 'yard'
-      YARD::Rake::YardocTask.new doc_api_dst do |t|
-        t.options.push '--protected',
-          '--output-dir', doc_api_dst,
-          '--readme', options[:license_file]
+      namespace :doc do
+        namespace :api do
+          require 'sdoc'
+          require 'rake/rdoctask'
 
-        task doc_api_dst => options[:license_file]
-      end
+          Rake::RDocTask.new do |t|
+            t.rdoc_dir = doc_api_dst
+            t.template = 'direct' # lighter template used on railsapi.com
+            t.options.push '--fmt', 'shtml' # explictly set shtml generator
+            t.rdoc_files.include '[A-Z]*', 'lib/**/*.rb', 'ext/**/*.{rb,c*}'
 
-      hide_rake_task[doc_api_dst]
+            # regen when sources change
+            task t.name => t.rdoc_files
+
+            t.main = options[:license_file]
+            task t.name => t.main
+          end
+
+          %w[rdoc clobber_rdoc rerdoc].each do |inner|
+            hide_rake_task["doc:api:#{inner}"]
+          end
+        end
+      end
 
-      CLEAN.include '.yardoc'
       CLOBBER.include doc_api_dst
 
   # announcements
@@ -479,15 +598,15 @@ def Inochi.rake project_symbol, options = {}, &gem_config
 
   # packaging
     desc 'Build a release.'
-    task :pak => [:clobber, :doc] do
-      sh $0, 'package'
+    task :gem => [:clobber, :doc] do
+      sh $0, 'gem:package'
     end
     CLEAN.include 'pkg'
 
     # ruby gem
       require 'rake/gempackagetask'
 
-      gem = Gem::Specification.new do |gem|
+      gem_spec = Gem::Specification.new do |gem|
         authors = project_module::AUTHORS
 
         if author = authors.first
@@ -521,29 +640,49 @@ def Inochi.rake project_symbol, options = {}, &gem_config
         gem.description = gem.summary
         gem.homepage    = project_module::WEBSITE
         gem.files       = FileList['**/*'].exclude('_darcs') - CLEAN
-        gem.executables = project_module::PROGRAM
         gem.has_rdoc    = true
 
-        unless project_module == Inochi
-          gem.add_dependency 'inochi', Inochi::VERSION.requirement
+        executable      = project_module::PROGRAM
+        executable_path = File.join(gem.bindir, executable)
+        gem.executables = executable if File.exist? executable_path
+
+        project_module::DEVELOP.each_pair do |gem_name, version_reqs|
+          version_reqs = Array(version_reqs).compact
+          gem.add_development_dependency gem_name, *version_reqs
         end
 
         project_module::REQUIRE.each_pair do |gem_name, version_reqs|
+          version_reqs = Array(version_reqs).compact
           gem.add_dependency gem_name, *version_reqs
         end
 
+        unless project_module == Inochi
+          if options[:inochi_producer]
+            gem.add_development_dependency Inochi::PROGRAM, Inochi::VERSION.requirement
+          end
+
+          if options[:inochi_consumer]
+            gem.add_dependency Inochi::PROGRAM, Inochi::VERSION.requirement
+          end
+        end
+
         # additional configuration is done by user
         yield gem if gem_config
       end
 
-      Rake::GemPackageTask.new(gem).define
+      namespace :gem do
+        Rake::GemPackageTask.new(gem_spec).define
 
-      # XXX: hide the tasks defined by the above gem packaging library
-      %w[gem package repackage clobber_package].each {|t| hide_rake_task[t] }
+        %w[gem package repackage clobber_package].each do |t|
+          hide_rake_task.call "gem:#{t}"
+        end
+      end
+
+      task :clobber => "gem:clobber_package"
 
   # releasing
     desc 'Publish a release.'
-    task 'pub' => %w[ pub:pak pub:doc pub:ann ]
+    task 'pub' => %w[ pub:gem pub:doc pub:ann ]
 
     # connect to RubyForge services
       pub_forge = nil
@@ -683,10 +822,12 @@ def Inochi.rake project_symbol, options = {}, &gem_config
             form['post[subject]'] = ann_subject
             form['post[text]'] = ann_text
 
-            form.checkboxes.first.check # enable email notification
+            # enable email notification
+            form.field_with(:name => 'post[subscribed_by_author]').value = '1'
+
             page = form.submit
+            errors = Array(page/'//div[@class="error"]/text()')
 
-            errors = [page/'//div[@class="error"]/text()'].flatten
             if errors.empty?
               puts 'Successfully announced to ruby-talk mailing list:', page.uri
             else
@@ -737,7 +878,7 @@ def Inochi.rake project_symbol, options = {}, &gem_config
 
     # release packages
       desc 'Publish release packages to RubyForge.'
-      task 'pub:pak' => :pub_forge do
+      task 'pub:gem' => :pub_forge do
         # check if this release was already published
         version = project_module::VERSION
         packages = pub_forge.autoconfig['release_ids'][pub_forge_section]
@@ -755,7 +896,7 @@ def Inochi.rake project_symbol, options = {}, &gem_config
             pub_forge.__send__ command, pub_forge_project, pub_forge_section, version, *files
           end
 
-          Rake::Task[:pak].invoke
+          Rake::Task[:gem].invoke
           packages = Dir['pkg/*.[a-z]*']
 
           unless packages.empty?