olag 0.1.10

data/lib/olag/change_log.rb

@@ -0,0 +1,59 @@
+module Olag
+
+  # Create ChangeLog files based on the Git revision history.
+  class ChangeLog
+
+    # Write a changelog based on the Git log.
+    def initialize(path)
+      @subjects_by_id = {}
+      @sorted_ids = []
+      read_log_lines
+      File.open(path, "w") do |file|
+        @log_file = file
+        write_log_file
+      end
+    end
+
+  protected
+
+    # Read all the log lines from Git's revision history.
+    def read_log_lines
+      IO.popen("git log --pretty='format:%ci::%an <%ae>::%s'", "r").each_line do |log_line|
+        load_log_line(log_line)
+      end
+    end
+
+    # Load a single Git log line into memory.
+    def load_log_line(log_line)
+      id, subject = ChangeLog.parse_log_line(log_line)
+      @sorted_ids << id
+      @subjects_by_id[id] ||= []
+      @subjects_by_id[id] << subject
+    end
+
+    # Extract the information we need (ChangeLog entry id and subject) from a
+    # Git log line.
+    def self.parse_log_line(log_line)
+      date, author, subject = log_line.chomp.split("::")
+      date, time, zone = date.split(" ")
+      id = "#{date}\t#{author}"
+      return id, subject
+    end
+
+    # Write a ChangeLog file based on the read Git log lines.
+    def write_log_file
+      @sorted_ids.uniq.each do |id|
+        write_log_entry(id, @subjects_by_id[id])
+      end
+    end
+
+    # Write a single ChaneLog entry.
+    def write_log_entry(id, subjects)
+      @log_file.puts "#{id}\n\n"
+      @log_file.puts subjects.map { |subject| "\t* #{subject}" }.join("\n")
+      @log_file.puts "\n"
+    end
+
+  end
+
+end

data/lib/olag/data_files.rb

@@ -0,0 +1,20 @@
+module Olag
+
+  # Provide access to data files packaged with the gem.
+  module DataFiles
+
+    # Given the name of a data file packaged in some gem, return the absolute
+    # disk path for accessing that data file. This is similar to what +require+
+    # does internally, but here we just want the path for reading data, rather
+    # than load the Ruby code in the file.
+    def self.expand_path(relative_path)
+      $LOAD_PATH.each do |load_directory|
+        absolute_path = File.expand_path(load_directory + "/" + relative_path)
+        return absolute_path if File.exist?(absolute_path)
+      end
+      return relative_path # This will cause "file not found error" down the line.
+    end
+
+  end
+
+end

data/lib/olag/errors.rb

@@ -0,0 +1,44 @@
+module Olag
+
+  # Collect a list of errors.
+  class Errors < Array
+
+    # Create an empty errors collection.
+    def initialize
+      @path = nil
+      @line = nil
+    end
+
+    # Associate all errors collected by a block with a specific disk file.
+    def in_path(path, &block)
+      prev_path, prev_line = @path, @line
+      @path, @line = path, nil
+      result = block.call
+      @path, @line = prev_path, prev_line
+      return result
+    end
+
+    # Set the line number for any errors collected from here on.
+    def at_line(line)
+      @line = line
+    end
+
+    # Add a single error to the collection, with automatic context annotation
+    # (current disk file and line). Other methods (push, += etc.) do not
+    # automatically add the context annotation.
+    def <<(message)
+      push(annotate_error_message(message))
+    end
+
+  protected
+
+    # Annotate an error message with the context (current file and line).
+    def annotate_error_message(message)
+      return "#{$0}: #{message}" unless @path
+      return "#{$0}: #{message} in file: #{@path}" unless @line
+      return "#{$0}: #{message} in file: #{@path} at line: #{@line}"
+    end
+
+  end
+
+end

data/lib/olag/gem_specification.rb

@@ -0,0 +1,77 @@
+# Monkey-patch within the Gem module.
+module Gem
+
+  # Enhanced automated gem specification.
+  class Specification
+
+    # The title of the gem for documentation (by default, the capitalized
+    # name).
+    attr_accessor :title
+
+    # The name of the file containing the gem's version (by default,
+    # <tt>lib/_name_/version.rb</tt>).
+    attr_accessor :version_file
+
+    alias_method :original_initialize, :initialize
+
+    # Create the gem specification. Requires a block to set up the basic gem
+    # information (name, version, author, email, description). In addition, the
+    # block may override default properties (e.g. title).
+    def initialize(&block)
+      original_initialize(&block)
+      setup_default_members
+      add_development_dependencies
+      setup_file_members
+      setup_rdoc
+    end
+
+    # Set the new data members to their default values, unless they were
+    # already set by the gem specification block.
+    def setup_default_members
+      name = self.name
+      @title ||= name.capitalize
+      @version_file ||= "lib/#{name}/version.rb"
+    end
+
+    # Add dependencies required for developing the gem.
+    def add_development_dependencies
+      add_dependency("olag") unless self.name == "olag"
+      %w(Saikuro codnar fakefs flay rake rcov rdoc reek roodi test-spec).each do |gem|
+        add_development_dependency(gem)
+      end
+    end
+
+    # Initialize the standard gem specification file list members.
+    def setup_file_members
+      # These should cover all the gem's files, except for the extra rdoc
+      # files.
+      setup_file_member(:files, "{lib,doc}/**/*")
+      self.files << "Rakefile" << "codnar.html"
+      setup_file_member(:executables, "bin/*") { |path| path.sub("bin/", "") }
+      setup_file_member(:test_files, "test/**/*")
+    end
+
+    # Initialize a standard gem specification file list member to the files
+    # matching a pattern. If a block is given, it is used to map the file
+    # paths. This will append to the file list member if it has already been
+    # set by the gem specification block.
+    def setup_file_member(member, pattern, &block)
+      old_value = instance_variable_get("@#{member}")
+      new_value = FileList[pattern].find_all { |path| File.file?(path) }
+      new_value.map!(&block) if block
+      instance_variable_set("@#{member}", old_value + new_value)
+    end
+
+    # Setup RDOC options in the gem specification.
+    def setup_rdoc
+      self.extra_rdoc_files = [ "README.rdoc", "LICENSE", "ChangeLog" ]
+      self.rdoc_options << "--title" << "#{title} #{version}" \
+                        << "--main" << "README.rdoc" \
+                        << "--line-numbers" \
+                        << "--all" \
+                        << "--quiet"
+    end
+
+  end
+
+end

data/lib/olag/globals.rb

@@ -0,0 +1,43 @@
+module Olag
+
+  # Save and restore the global variables when running an application inside a
+  # test.
+  class Globals
+
+    # Run some code without affecting the global state.
+    def self.without_changes(&block)
+      state = Globals.new
+      begin
+        return block.call
+      ensure
+        state.restore
+      end
+    end
+
+    # Restore the relevant global variables.
+    def restore
+      $stdin = Globals.restore_file($stdin, @original_stdin)
+      $stdout = Globals.restore_file($stdout, @original_stdout)
+      $stderr = Globals.restore_file($stderr, @original_stderr)
+      ARGV.replace(@original_argv)
+    end
+
+  protected
+
+    # Take a snapshot of the relevant global variables.
+    def initialize
+      @original_stdin = $stdin
+      @original_stdout = $stdout
+      @original_stderr = $stderr
+      @original_argv = ARGV.dup
+    end
+
+    # Restore a specific global file variable to its original state.
+    def self.restore_file(current, original)
+      current.close unless current == original
+      return original
+    end
+
+  end
+
+end

data/lib/olag/hash_struct.rb

@@ -0,0 +1,12 @@
+# Extend the core Hash class.
+class Hash
+
+  # Provide OpenStruct/JavaScript-like implicit <tt>.key</tt> and
+  # <tt>.key=</tt> methods.
+  def method_missing(method, *arguments)
+    method = method.to_s
+    key = method.chomp("=")
+    return method == key ? self[key] : self[key] = arguments[0]
+  end
+
+end

data/lib/olag/rake.rb

@@ -0,0 +1,263 @@
+require "codnar/rake"
+require "olag/change_log"
+require "olag/gem_specification"
+require "olag/update_version"
+require "olag/version"
+require "rake/clean"
+require "rake/gempackagetask"
+require "rake/rdoctask"
+require "rake/testtask"
+require "rcov/rcovtask"
+require "reek/rake/task"
+require "roodi"
+
+module Olag
+
+  # Automate Rake task creation for a gem.
+  class Rake
+
+    # Define all the Rake tasks.
+    def initialize(spec)
+      @spec = spec
+      @ruby_sources = @spec.files.find_all { |file| file =~ /^Rakefile$|\.rb$/ }
+      @weave_configurations = [ :weave_include, :weave_named_chunk_with_containers ]
+      task(:default => :all)
+      define_all_task
+      CLOBBER << "saikuro"
+    end
+
+  protected
+
+    # Define a task that does "everything".
+    def define_all_task
+      define_desc_task("Version, verify, document, package", :all => [ :version, :verify, :doc, :package ])
+      define_verify_task
+      define_doc_task
+      define_commit_task
+      # This is a problem. If the version number gets updated, GemPackageTask
+      # fails. This is better than if it used the old version number, I
+      # suppose, but not as nice as if it just used @spec.version everywhere.
+      # The solution for this is to do a dry run before doing the final +rake+
+      # +commit+, which is a good idea in general.
+      ::Rake::GemPackageTask.new(@spec) { |package| }
+    end
+
+    # {{{ Verify gem functionality
+
+    # Define a task to verify everything is OK.
+    def define_verify_task
+      define_desc_task("Test, coverage, analyze code", :verify => [ :coverage, :analyze ])
+      define_desc_class("Test code covarage with RCov", Rcov::RcovTask, "coverage") { |task| Rake.configure_coverage_task(task) }
+      define_desc_class("Test code without coverage", ::Rake::TestTask, "test") { |task| Rake.configure_test_task(task) }
+      define_analyze_task
+    end
+
+    # Configure a task to run all tests and verify 100% coverage. This is
+    # cheating a bit, since it will not complain about files that are not
+    # reached at all from any of the tests.
+    def self.configure_coverage_task(task)
+      task.test_files = FileList["test/*.rb"]
+      task.libs << "lib" << "test/lib"
+      task.rcov_opts << "--failure-threshold" << "100" \
+                     << "--exclude" << "^/"
+      # Strangely, on some occasions, RCov crazily tries to compute coverage
+      # for files inside Ruby's gem repository. Excluding all absolute paths
+      # prevents this.
+    end
+
+    # Configure a task to just run the tests without verifying coverage.
+    def self.configure_test_task(task)
+      task.test_files = FileList["test/*.rb"]
+      task.libs << "lib" << "test/lib"
+    end
+
+    # }}}
+
+    # {{{ Analyze the source code
+
+    # Define a task to verify the source code is clean.
+    def define_analyze_task
+      define_desc_task("Analyze source code", :analyze => [ :reek, :roodi, :flay, :saikuro ])
+      define_desc_class("Check for smelly code with Reek", Reek::Rake::Task) { |task| configure_reek_task(task) }
+      define_desc_task("Check for smelly code with Roodi", :roodi) { run_roodi_task }
+      define_desc_task("Check for duplicated code with Flay", :flay) { run_flay_task }
+      define_desc_task("Check for complex code with Saikuro", :saikuro) { run_saikuro_task }
+    end
+
+    # Configure a task to ensure there are no code smells using Reek.
+    def configure_reek_task(task)
+      task.reek_opts << "--quiet"
+      task.source_files = @ruby_sources
+    end
+
+    # Run Roodi to ensure there are no code smells.
+    def run_roodi_task
+      runner = Roodi::Core::Runner.new
+      runner.config = "roodi.config" if File.exist?("roodi.config")
+      @ruby_sources.each { |ruby_source| runner.check_file(ruby_source) }
+      (errors = runner.errors).each { |error| puts(error) }
+      raise "Roodi found #{errors.size} errors." unless errors.empty?
+    end
+
+    # Run Flay to ensure there are no duplicated code fragments.
+    def run_flay_task
+      dirs = %w(bin lib test/lib).find_all { |dir| File.exist?(dir) }
+      result = IO.popen("flay " + dirs.join(' '), "r").read.chomp
+      return if result == "Total score (lower is better) = 0\n"
+      puts(result)
+      raise "Flay found code duplication."
+    end
+
+    # Run Saikuro to ensure there are no overly complex functions.
+    def run_saikuro_task
+      dirs = %w(bin lib test).find_all { |dir| File.exist?(dir) }
+      system("saikuro -c -t -y 0 -e 10 -o saikuro/ -i #{dirs.join(' -i ')} > /dev/null")
+      result = File.read("saikuro/index_cyclo.html")
+      raise "Saikuro found complicated code." if result.include?("Errors and Warnings")
+    end
+
+    # }}}
+
+    # {{{ Generate RDoc documentation
+
+    # Define a task to build all the documentation.
+    def define_doc_task
+      desc "Generate all documentation"
+      task :doc => [ :rdoc, :codnar ]
+      ::Rake::RDocTask.new { |task| configure_rdoc_task(task) }
+      define_codnar_task
+    end
+
+    # Configure a task to build the RDoc documentation.
+    def configure_rdoc_task(task)
+      task.rdoc_files += @ruby_sources.reject { |file| file =~ /^test|Rakefile/ } + [ "LICENSE", "README.rdoc" ]
+      task.main = "README.rdoc"
+      task.rdoc_dir = "rdoc"
+      task.options = @spec.rdoc_options
+    end
+
+    # }}}
+
+    # {{{ Generate Codnar documentation
+
+    # A set of file Regexp patterns and their matching Codnar configurations.
+    # All the gem files are matched agains these patterns, in order, and a
+    # Codnar::SplitTask is created for the first matching one. If the matching
+    # configuration list is empty, the file is not split. However, the file
+    # must match at least one of the patterns. The gem is expected to modify
+    # this array, if needed, before creating the Rake object.
+    CODNAR_CONFIGURATIONS = [
+      [
+        # Exclude the ChangeLog and generated codnar.html files from the
+        # generated documentation.
+        "ChangeLog|codnar\.html",
+      ], [
+        # Configurations for splitting Ruby files. Using Sunlight makes for
+        # fast splitting but slow viewing. Using GVim is the reverse.
+        "Rakefile|.*\.rb|bin/.*",
+        "classify_source_code:ruby",
+        "format_code_gvim_css:ruby",
+        "classify_shell_comments",
+        "format_rdoc_comments",
+        "chunk_by_vim_regions",
+      ], [
+        # Configurations for HTML documentation files.
+        ".*\.html",
+        "split_html_documentation",
+      ], [
+        # Configurations for Markdown documentation files.
+        ".*\.markdown|.*\.md",
+        "split_markdown_documentation",
+      ], [
+        # Configurations for RDOC documentation files.
+        "LICENSE|.*\.rdoc",
+        "split_rdoc_documentation",
+      ],
+    ]
+
+    # Define a task to build the Codnar documentation.
+    def define_codnar_task
+      @spec.files.each do |file|
+        configurations = Rake.split_configurations(file)
+        Codnar::Rake::SplitTask.new([ file ], configurations) unless configurations == []
+      end
+      Codnar::Rake::WeaveTask.new("doc/root.html", [ :weave_include, :weave_named_chunk_with_containers ])
+    end
+
+    # Find the Codnar split configurations for a file.
+    def self.split_configurations(file)
+      CODNAR_CONFIGURATIONS.each do |configurations|
+        regexp = configurations[0] = convert_to_regexp(configurations[0])
+        return configurations[1..-1] if regexp.match(file)
+      end
+      abort("No Codnar configuration for file: #{file}")
+    end
+
+    # Convert a string configuration pattern to a real Regexp.
+    def self.convert_to_regexp(regexp)
+      return regexp if Regexp == regexp
+      begin
+        return Regexp.new("^(#{regexp})$")
+      rescue
+        abort("Invalid pattern regexp: ^(#{regexp})$ error: #{$!}")
+      end
+    end
+
+    # }}}
+
+    # {{{ Automate Git commit process
+
+    # Define a task that commit changes to Git.
+    def define_commit_task
+      define_desc_task("Git commit process", :commit => [ :all, :first_commit, :changelog, :second_commit ])
+      define_desc_task("Update version file from Git", :version) { update_version_file }
+      define_desc_task("Perform the 1st (main) Git commit", :first_commit) { run_git_first_commit }
+      define_desc_task("Perform the 2nd (amend) Git commit", :second_commit) { run_git_second_commit }
+      define_desc_task("Update ChangeLog from Git", :changelog) { Olag::ChangeLog.new("ChangeLog") }
+    end
+
+    # Update the content of the version file to contain the correct Git-derived
+    # build number.
+    def update_version_file
+      version_file = @spec.version_file
+      updated_version = Olag::Version::update(version_file)
+      abort("Updated gem version; re-run rake") if @spec.version.to_s != updated_version
+    end
+
+    # Run the first Git commit. The user will be given an editor to review the
+    # commit and enter a commit message.
+    def run_git_first_commit
+      raise "Git 1st commit failed" unless system("set +x; git commit")
+    end
+
+    # Run the second Git commit. This amends the first commit with the updated
+    # ChangeLog.
+    def run_git_second_commit
+      raise "Git 2nd commit failed" unless system("set +x; EDITOR=true git commit --amend ChangeLog")
+    end
+
+    # }}}
+
+    # {{{ Task utilities
+
+    # Define a new task with a description.
+    def define_desc_task(description, *parameters)
+      desc(description)
+      task(*parameters) do
+        yield(task) if block_given?
+      end
+    end
+
+    # Define a new task using some class.
+    def define_desc_class(description, klass, *parameters)
+      desc(description)
+      klass.new(*parameters) do |task|
+        yield(task) if block_given?
+      end
+    end
+
+    # }}}
+
+  end
+
+end