buildr 1.1.3 → 1.2.0

data/lib/core/checks.rb

@@ -0,0 +1,358 @@
+require "core/project"
+require "tasks/zip"
+require "spec"
+
+module Buildr
+
+  module BuildChecks #:nodoc:
+
+    module Matchers
+
+      class << self
+
+        # Define matchers that operate by calling a method on the tested object.
+        # For example:
+        #   foo.should contain(bar)
+        # calls:
+        #   foo.contain(bar)
+        def match_using(*names)
+          names.each do |name|
+            matcher = Class.new do
+              # Initialize with expected arguments (i.e. contain(bar) initializes with bar).
+              define_method(:initialize) { |*args| @expects = args }
+              # Matches against actual value (i.e. foo.should exist called with foo).
+              define_method(:matches?) do |actual|
+                @actual = actual
+                return actual.send("#{name}?", *@expects) if actual.respond_to?("#{name}?")
+                return actual.send(name, *@expects) if actual.respond_to?(name)
+                raise "You can't check #{actual}, it doesn't respond to #{name}."
+              end
+              # Some matchers have arguments, others don't, treat appropriately.
+              define_method :failure_message do
+                args = " " + @expects.map{ |arg| "'#{arg}'" }.join(", ") unless @expects.empty?
+                "Expected #{@actual} to #{name}#{args}"
+              end
+              define_method :negative_failure_message do
+                args = " " + @expects.map{ |arg| "'#{arg}'" }.join(", ") unless @expects.empty?
+                "Expected #{@actual} to not #{name}#{args}"
+              end
+            end
+            # Define method to create matcher.
+            define_method(name) { |*args| matcher.new(*args) }
+          end
+        end
+
+      end
+
+      # Define delegate matchers for exist and contain methods.
+      match_using :exist, :contain
+
+    end
+
+
+    # An expectation has subject, description and block. The expectation is validated by running the block,
+    # and can access the subject from the method #it. The description is used for reporting.
+    #
+    # The expectation is run by calling #run_against. You can share expectations by running them against
+    # different projects (or any other context for that matter).
+    #
+    # If the subject is missing, it is set to the argument of #run_against, typically the project itself.
+    # If the description is missing, it is set from the project. If the block is missing, the default behavior
+    # prints "Pending" followed by the description. You can use this to write place holders and fill them later.
+    class Expectation
+
+      attr_reader :description, :subject, :block
+
+      # :call-seq:
+      #   initialize(subject, description?) { .... }
+      #   initialize(description?) { .... }
+      #
+      # First argument is subject (returned from it method), second argument is description. If you omit the
+      # description, it will be set from the subject. If you omit the subject, it will be set from the object
+      # passed to run_against.
+      def initialize(*args, &block)
+        @description = args.pop if String === args.last
+        @subject = args.shift
+        raise ArgumentError, "Expecting subject followed by description, and either one is optional. Not quite sure what to do with this list of arguments." unless args.empty?
+        @block = block || lambda { puts "Pending: #{description}" if verbose }
+      end
+
+      # :call-seq:
+      #   run_against(context)
+      #
+      # Runs this expectation against the context object. The context object is different from the subject,
+      # but used as the subject if no subject specified (i.e. returned from the it method).
+      #
+      # This method creates a new context object modeled after the context argument, but a separate object
+      # used strictly for running this expectation, and used only once. The context object will pass methods
+      # to the context argument, so you can call any method, e.g. package(:jar).
+      #
+      # It also adds all matchers defined in Buildr and RSpec, and two additional methods:
+      # * it() -- Returns the subject.
+      # * description() -- Returns the description.
+      def run_against(context)
+        subject = @subject || context
+        description = @description ? "#{subject} #{@description}" : subject.to_s
+        # Define anonymous class and load it with:
+        # - All instance methods defined in context, so we can pass method calls to the context.
+        # - it() method to return subject, description() method to return description.
+        # - All matchers defined by Buildr and RSpec.
+        klass = Class.new
+        klass.instance_eval do
+          context.class.instance_methods(false).each do |method|
+            define_method(method) { |args| context.send(method, args) }
+          end
+          define_method(:it) { subject }
+          define_method(:description) { description }
+          include Spec::Matchers
+          include Matchers
+        end
+
+        # Run the expectation. We only print the expectation name when tracing (to know they all ran),
+        # or when we get a failure.
+        begin
+          puts description if Rake.application.options.trace
+          klass.new.instance_eval &@block
+        rescue Exception=>error
+          raise error.exception("#{description}\n#{error}").tap { |wrapped| wrapped.set_backtrace(error.backtrace) }
+        end
+      end
+
+    end
+
+  end
+
+
+  class Project
+
+    # :call-seq:
+    #    check(description) { ... }
+    #    check(subject, description) { ... }
+    #
+    # Adds an expectation. The expectation is run against the project by the check task, executed after packaging.
+    # You can access any package created by the project.
+    #
+    # An expectation is written using a subject, description and block to validate the expectation. For example:
+    #
+    # For example:
+    #   check package(:jar), "should exist" do
+    #     it.should exist
+    #   end
+    #   check package(:jar), "should contain a manifest" do
+    #     it.should contain("META-INF/MANIFEST.MF")
+    #   end
+    #   check package(:jar).path("com/acme"), "should contain classes" do
+    #     it.should_not be_empty
+    #   end
+    #   check package(:jar).entry("META-INF/MANIFEST"), "should be a recent license" do
+    #     it.should contain(/Copyright (C) 2007/)
+    #   end
+    #
+    # If you omit the subject, the project is used as the subject. If you omit the description, the subject is
+    # used as description.
+    #
+    # During development you can write placeholder expectations by omitting the block. This will simply report
+    # the expectation as pending.
+    def check(*args, &block)
+      expectations << BuildChecks::Expectation.new(*args, &block)
+    end
+
+    # :call-seq:
+    #   expectations() => Expectation*
+    #
+    # Returns a list of expectations (see #check).
+    def expectations()
+      @expectations ||= []
+    end
+
+  end
+
+  Project.on_define do |project|
+    # The check task can do any sort of interesting things, but the most important is running expectations.
+    project.task("check") do |task|
+      project.expectations.inject(true) do |passed, expect|
+        begin
+          expect.run_against project
+          passed
+        rescue Exception=>error
+          if verbose
+            puts error.backtrace.detect { |line| line =~ /#{Rake.application.rakefile}/ } || ""
+            puts error
+          end
+          false
+        end
+      end or fail "Checks failed for project #{project.name} (see errors above)."
+    end
+    project.task("package").enhance do |task|
+      # Run all actions before checks.
+      task.enhance { project.task("check").invoke }
+    end
+  end
+
+end
+
+
+module Rake #:nodoc:
+  class FileTask
+
+    # :call-seq:
+    #   exist?() => boolean
+    #
+    # Returns true if this file exists.
+    def exist?()
+      File.exist?(name)
+    end
+
+    # :call-seq:
+    #   empty?() => boolean
+    #
+    # Returns true if file/directory is empty.
+    def empty?()
+      File.directory?(name) ? Dir.glob("#{name}/*").empty? : File.read(name).empty?
+    end
+
+    # :call-seq:
+    #   contain(pattern*) => boolean
+    #   contain(file*) => boolean
+    #
+    # For a file, returns true if the file content matches against all the arguments. An argument may be
+    # a string or regular expression.
+    #
+    # For a directory, return true if the directory contains the specified files. You can use relative
+    # file names and glob patterns (using *, **, etc).
+    def contain?(*patterns)
+      if File.directory?(name)
+        patterns.map { |pattern| "#{name}/#{pattern}" }.all? { |pattern| !Dir[pattern].empty? }
+      else
+        contents = File.read(name)
+        patterns.map { |pattern| Regexp === pattern ? pattern : Regexp.new(Regexp.escape(pattern.to_s)) }.
+          all? { |pattern| contents =~ pattern }
+      end
+    end
+
+  end
+end
+
+
+module Zip #:nodoc:
+  class ZipEntry
+
+    # :call-seq:
+    #   exist() => boolean
+    #
+    # Returns true if this entry exists.
+    def exist?()
+      Zip::ZipFile.open(zipfile) { |zip| zip.file.exist?(@name) }
+    end
+
+    # :call-seq:
+    #   empty?() => boolean
+    #
+    # Returns true if this entry is empty.
+    def empty?()
+      Zip::ZipFile.open(zipfile) { |zip| zip.file.read(@name) }.empty?
+    end
+
+    # :call-seq:
+    #   contain(patterns*) => boolean
+    #
+    # Returns true if this ZIP file entry matches against all the arguments. An argument may be
+    # a string or regular expression.
+    def contain?(*patterns)
+      content = Zip::ZipFile.open(zipfile) { |zip| zip.file.read(@name) }
+      patterns.map { |pattern| Regexp === pattern ? pattern : Regexp.new(Regexp.escape(pattern.to_s)) }.
+        all? { |pattern| content =~ pattern }
+    end
+
+  end
+end
+
+
+module Buildr
+  class ZipTask
+
+    class Path
+
+      # :call-seq:
+      #   exist() => boolean
+      #
+      # Returns true if this path exists. This only works if the path has any entries in it,
+      # so exist on path happens to be the opposite of empty.
+      def exist?()
+        !empty?
+      end
+
+      # :call-seq:
+      #   empty?() => boolean
+      #
+      # Returns true if this path is empty (has no other entries inside).
+      def empty?()
+        check { |entries| entries.empty? }
+      end
+
+      # :call-seq:
+      #   contain(file*) => boolean
+      #
+      # Returns true if this ZIP file path contains all the specified files. You can use relative
+      # file names and glob patterns (using *, **, etc).
+      def contain?(*files)
+        check do |entries|
+          files.all? { |file| entries.detect { |entry| File.fnmatch(file, entry.to_s) } }
+        end
+      end
+
+      # :call-seq:
+      #   entry(name) => ZipEntry
+      #
+      # Returns a ZIP file entry. You can use this to check if the entry exists and its contents,
+      # for example:
+      #   package(:jar).path("META-INF").entry("LICENSE").should contain(/Apache Software License/)
+      def entry(name)
+        ::Zip::ZipEntry.new(root.name, "#{@path}#{name}")
+      end
+
+    protected
+
+      def check() #:nodoc:
+        unless @cached_entries
+          if @path
+            base = Regexp.new("^" + Regexp.escape(@path || ""))
+            @cached_entries = root.path("").check.map { |name| name.to_s.sub!(base, "") }.reject(&:nil?)
+          else
+            @cached_entries = Zip::ZipFile.open(root.name) { |zip| zip.entries }
+          end
+        end
+        block_given? ? yield(@cached_entries) : @cached_entries
+      end
+
+    end
+
+    # :call-seq:
+    #   empty?() => boolean
+    #
+    # Returns true if this ZIP file is empty (has no other entries inside).
+    def empty?()
+      path("").empty
+    end
+
+    # :call-seq:
+    #   contain(file*) => boolean
+    #
+    # Returns true if this ZIP file contains all the specified files. You can use absolute
+    # file names and glob patterns (using *, **, etc).
+    def contain?(*files)
+      path("").contain?(*files)
+    end
+
+    # :call-seq:
+    #   entry(name) => Entry
+    #
+    # Returns a ZIP file entry. You can use this to check if the entry exists and its contents,
+    # for example:
+    #   package(:jar).entry("META-INF/LICENSE").should contain(/Apache Software License/)
+    def entry(name)
+      path("").entry(name)
+    end
+
+  end
+end

data/lib/core/common.rb

@@ -1,9 +1,85 @@
 require "tempfile"
 require "pathname"
 require "core/transports"
+require "open-uri"
+require "uri/open-sftp"
+
+
+class Hash
+
+  # :call-seq:
+  #   only(keys*) => hash
+  #
+  # Returns a new hash with only the specified keys.
+  #
+  # For example:
+  #   { :a=>1, :b=>2, :c=>3, :d=>4 }.only(:a, :c)
+  #   => { :b=>2, :d=>4 }
+  def only(*keys)
+    self.inject({}) { |hash, pair| hash[pair[0]] = pair[1] if keys.include?(pair[0]) ; hash }
+  end
+
+
+  # :call-seq:
+  #   except(keys*) => hash
+  #
+  # Returns a new hash without the specified keys.
+  #
+  # For example:
+  #   { :a=>1, :b=>2, :c=>3, :d=>4 }.except(:a, :c)
+  #   => { :a=>1, :c=>3 }
+  def except(*keys)
+    self.inject({}) { |hash, pair| hash[pair[0]] = pair[1] unless keys.include?(pair[0]) ; hash }
+  end
+
+end
+
 
 module Buildr
 
+  # Collection of options for controlling Buildr. For example for running builds without running
+  # test cases, using a proxy server, JVM arguments, etc. You access this object by calling options,
+  # for example:
+  #   options.proxy.http = "http://proxy.acme.com:8080"
+  #   options.java_args = "-Xmx512M"
+  class Options
+
+    # :call-seq:
+    #   proxy() => options
+    #
+    # Returns the proxy options. Currently supported options are:
+    # * :http -- HTTP proxy for use when downloading.
+    #
+    # For example:
+    #   options.proxy.http = "http://proxy.acme.com:8080"
+    # You can also set it using the environment variable HTTP_PROXY.
+    def proxy()
+      @proxy ||= Struct.new(:http).new(ENV['HTTP_PROXY'] || ENV['http_proxy'])
+    end
+
+  end
+
+  class << self
+
+    # :call-seq:
+    #   options() => Options
+    #
+    # Returns the Buildr options. See Options.
+    def options()
+      @options ||= Options.new
+    end
+
+  end
+
+  # :call-seq:
+  #   options() => Options
+  #
+  # Returns the Buildr options. See Options.
+  def options()
+    Buildr.options
+  end
+
+
   # :call-seq:
   #   struct(hash) => Struct
   #
@@ -76,27 +152,30 @@ module Buildr
   # For example:
   #   download "image.jpg"=>"http://example.com/theme/image.jpg"
   def download(args)
-    if String === args || URI === args
+    args = URI.parse(args) if String === args
+    if URI === args
       # Given only a download URL, download into a temporary file.
       # You can infer the file from task name.
-      temp = Tempfile.new(File.basename(args.to_s))
-      task = file_create(temp.path) do |task|
-        Transports.download task.source, task.name
+      temp = Tempfile.open(File.basename(args.to_s))
+      file(temp.path).tap do |task|
+        # Since temporary file exists, force a download.
+        class << task ; def needed?() ; true ; end ; end
+        task.sources << args
+        task.enhance { args.download temp, :proxy=>Buildr.options.proxy }
       end
-      task.sources << args
     else
       # Download to a file created by the task.
       fail unless args.keys.size == 1
-      url = args.values.first
-      task = file_create(args.keys.first) do |task|
-        mkpath File.dirname(task.name), :verbose=>false
-        Transports.download task.source, task.name
+      uri = URI.parse(args.values.first.to_s)
+      file_create(args.keys.first).tap do |task|
+        task.sources << uri
+        task.enhance { uri.download task.name, :proxy=>Buildr.options.proxy }
       end
-      task.sources << url
     end
-    task
+
   end
 
+
   # A filter knows how to copy files from one directory to another, applying mappings to the
   # contents of these files.
   #
@@ -188,37 +267,52 @@ module Buildr
     # For example:
     #   filter.using "version"=>"1.2"
     # will replace all occurrences of "${version}" with "1.2".
-    def using(mapping, &block)
+    def using(mapping = nil, &block)
       self.mapping = mapping || block
       self
     end
 
+    # :call-seq:
+    #    run() => boolean
+    #
     # Runs the filter.
     def run()
-      if needed?
-        unless copy_map.empty?
-          verbose(Rake.application.options.trace || false) do
-            mkpath target.to_s
-            copy_map do |dest, src|
-              mkpath File.dirname(dest) rescue nil
-              case mapping
-              when Proc, Method # Call on input, accept output.
-                mapped = mapping.call(src, File.open(src, "rb") { |file| file.read })
-                File.open(dest, "wb") { |file| file.write mapped }
-              when Hash # Map ${key} to value
-                mapped = File.open(src, "rb") { |file| file.read }.
-                  gsub(/\$\{.*\}/) { |str| mapping[str[2..-2]] || str }
-                File.open(dest, "wb") { |file| file.write mapped }
-              when nil # No mapping.
-                cp src, dest
-              else
-                fail "Filter can be a hash (key=>value), or a proc/method; I don't understand #{mapping}"
-              end
-            end
-            touch target.to_s
+      raise "No source directory specified, where am I going to find the files to filter?" if source.nil?
+      raise "Source directory #{source} doesn't exist" unless File.exist?(source.to_s)
+      raise "No target directory specified, where am I going to copy the files to?" if target.nil?
+
+      includes = @include.empty? ? ["*"] : @include
+      src_base = Pathname.new(source.to_s)
+      copy_map = Dir[File.join(source.to_s, "**/*")].reject { |file| File.directory?(file) }.
+        map { |src| Pathname.new(src).relative_path_from(src_base).to_s }.
+        select { |file| includes.any? { |pattern| File.fnmatch(pattern, file) } }.
+        reject { |file| @exclude.any? { |pattern| File.fnmatch(pattern, file) } }.
+        map { |file| [File.expand_path(file, target.to_s), File.expand_path(file, source.to_s)] }.
+        select { |dest, src| !File.exist?(dest) || File.stat(src).mtime > File.stat(dest).mtime }
+      return false if copy_map.empty?
+
+      verbose(Rake.application.options.trace || false) do
+        mkpath target.to_s
+        copy_map.each do |dest, src|
+          mkpath File.dirname(dest) rescue nil
+          case mapping
+          when Proc, Method # Call on input, accept output.
+            relative = Pathname.new(src).relative_path_from(src_base).to_s
+            mapped = mapping.call(relative, File.open(src, "rb") { |file| file.read })
+            File.open(dest, "wb") { |file| file.write mapped }
+          when Hash # Map ${key} to value
+            mapped = File.open(src, "rb") { |file| file.read }.
+              gsub(/\$\{[^}]*\}/) { |str| mapping[str[2..-2]] || str }
+            File.open(dest, "wb") { |file| file.write mapped }
+          when nil # No mapping.
+            cp src, dest
+          else
+            fail "Filter can be a hash (key=>value), or a proc/method; I don't understand #{mapping}"
           end
         end
+        touch target.to_s 
       end
+      true
     end
 
     # Returns the target directory. 
@@ -226,34 +320,6 @@ module Buildr
       @target.to_s
     end    
     
-  private
-
-    def needed?()
-      return false if target.nil? || source.nil? || !File.exist?(source.to_s)
-      return true unless File.exist?(target.to_s)
-      !copy_map.empty?
-    end
-
-    # Return a copy map of all the files that need copying: the key is the file to copy to,
-    # the value is the source file. If called with a block, yields with each dest/source pair.
-    def copy_map(&block)
-      unless @copy_map
-        @include = ["*"] if @include.empty?
-        base = Pathname.new(source.to_s)
-        @copy_map = Dir[File.join(source.to_s, "**/*")].reject { |file| File.directory?(file) }.
-          map { |src| Pathname.new(src).relative_path_from(base).to_s }.
-          select { |file| @include.any? { |pattern| File.fnmatch(pattern, file) } }.
-          reject { |file| @exclude.any? { |pattern| File.fnmatch(pattern, file) } }.
-          map { |file| [File.expand_path(file, target.to_s), File.expand_path(file, source.to_s)] }.
-          select { |dest, src| !File.exist?(dest) || File.stat(src).mtime > File.stat(dest).mtime }
-      end
-      if block_given?
-        @copy_map.each(&block)
-      else
-        @copy_map
-      end
-    end
-
   end
 
   # :call-seq:
@@ -273,5 +339,38 @@ module Buildr
   def filter(source)
     Filter.new.from(source)
   end
-  
+
 end
+
+
+# Add a touch of colors (red) to warnings.
+HighLine.use_color = PLATFORM !~ /win32/
+module Kernel #:nodoc:
+
+  def warn_with_color(message)
+    warn_without_color $terminal.color(message.to_s, :red)
+  end
+  alias_method_chain :warn, :color
+
+  # :call-seq:
+  #   warn_deprecated(message)
+  #
+  # Use with deprecated methods and classes. This method automatically adds the file name and line number,
+  # and the text "Deprecated" before the message, and eliminated duplicate warnings. It only warns when
+  # running in verbose mode.
+  #
+  # For example:
+  #   warn_deprecated "Please use new_foo instead of foo."
+  def warn_deprecated(message) #:nodoc:
+    return unless verbose
+    "#{caller[1]}: Deprecated: #{message}".tap do |message|
+      @deprecated ||= {}
+      unless @deprecated[message]
+        @deprecated[message] = true
+        warn message
+      end
+    end
+  end
+
+end
+