buildr 1.3.5-java → 1.4.0-java

data/lib/buildr/core/doc.rb

@@ -0,0 +1,263 @@
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements.  See the NOTICE file distributed with this
+# work for additional information regarding copyright ownership.  The ASF
+# licenses this file to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  See the
+# License for the specific language governing permissions and limitations under
+# the License.
+
+module Buildr
+  module Doc
+    include Extension
+
+    class << self
+      def select_by_lang(lang)
+        fail 'Unable to define doc task for nil language' if lang.nil?
+        engines.detect { |e| e.language.to_sym == lang.to_sym }
+      end
+
+      alias_method :select, :select_by_lang
+
+      def select_by_name(name)
+        fail 'Unable to define doc task for nil' if name.nil?
+        engines.detect { |e| e.to_sym == name.to_sym }
+      end
+
+      def engines
+        @engines ||= []
+      end
+    end
+
+
+    # Base class for any documentation provider.  Defines most
+    # common functionality (things like @into@, @from@ and friends).
+    class Base
+      class << self
+        attr_accessor :language, :source_ext
+
+        def specify(options)
+          @language = options[:language]
+          @source_ext = options[:source_ext]
+        end
+
+        def to_sym
+          @symbol ||= name.split('::').last.downcase.to_sym
+        end
+      end
+
+      attr_reader :project
+
+      def initialize(project)
+        @project = project
+      end
+    end
+
+
+    class DocTask < Rake::Task
+
+      # The target directory for the generated documentation files.
+      attr_reader :target
+
+      # Classpath dependencies.
+      attr_accessor :classpath
+
+      # Additional sourcepaths that are not part of the documented files.
+      attr_accessor :sourcepath
+
+      # Returns the documentation tool options.
+      attr_reader :options
+
+      
+      attr_reader :project # :nodoc:
+
+      def initialize(*args) #:nodoc:
+        super
+        @options = {}
+        @classpath = []
+        @sourcepath = []
+        @files = FileList[]
+        enhance do |task|
+          rm_rf target.to_s
+          mkdir_p target.to_s
+
+          engine.generate(source_files, File.expand_path(target.to_s),
+            options.merge(:classpath => classpath, :sourcepath => sourcepath))
+
+          touch target.to_s
+        end
+      end
+
+      # :call-seq:
+      #   into(path) => self
+      #
+      # Sets the target directory and returns self. This will also set the Javadoc task
+      # as a prerequisite to a file task on the target directory.
+      #
+      # For example:
+      #   package :zip, :classifier=>'docs', :include=>doc.target
+      def into(path)
+        @target = file(path.to_s).enhance([self]) unless @target && @target.to_s == path.to_s
+        self
+      end
+
+      # :call-seq:
+      #   include(*files) => self
+      #
+      # Includes additional source files and directories when generating the documentation
+      # and returns self. When specifying a directory, includes all source files in that directory.
+      def include(*files)
+        @files.include *files.flatten.compact
+        self
+      end
+
+      # :call-seq:
+      #   exclude(*files) => self
+      #
+      # Excludes source files and directories from generating the documentation.
+      def exclude(*files)
+        @files.exclude *files
+        self
+      end
+
+      # :call-seq:
+      #   with(*artifacts) => self
+      #
+      # Adds files and artifacts as classpath dependencies, and returns self.
+      def with(*specs)
+        @classpath |= Buildr.artifacts(specs.flatten).uniq
+        self
+      end
+
+      # :call-seq:
+      #   using(options) => self
+      #
+      # Sets the documentation tool options from a hash and returns self.
+      #
+      # For example:
+      #   doc.using :windowtitle=>'My application'
+      #   doc.using :vscaladoc
+      def using(*args)
+        args.pop.each { |key, value| @options[key.to_sym] = value } if Hash === args.last
+
+        until args.empty?
+          new_engine = Doc.select_by_name(args.pop)
+          @engine = new_engine.new(project) unless new_engine.nil?
+        end
+
+        self
+      end
+
+      def engine
+        @engine ||= guess_engine
+      end
+
+      # :call-seq:
+      #   from(*sources) => self
+      #
+      # Includes files, directories and projects in the documentation and returns self.
+      #
+      # You can call this method with source files and directories containing source files
+      # to include these files in the documentation, similar to #include. You can also call
+      # this method with projects. When called with a project, it includes all the source files compiled
+      # by that project and classpath dependencies used when compiling.
+      #
+      # For example:
+      #   doc.from projects('myapp:foo', 'myapp:bar')
+      def from(*sources)
+        sources.flatten.each do |source|
+          case source
+          when Project
+            self.enhance source.prerequisites
+            self.include source.compile.sources
+            self.with source.compile.dependencies
+          when Rake::Task, String
+            self.include source
+          else
+            fail "Don't know how to generate documentation from #{source || 'nil'}"
+          end
+        end
+        self
+      end
+
+      def prerequisites #:nodoc:
+        super + @files + classpath + sourcepath
+      end
+
+      def source_files #:nodoc:
+        @source_files ||= @files.map(&:to_s).map do |file|
+          File.directory?(file) ? FileList[File.join(file, "**/*.#{engine.class.source_ext}")] : file
+        end.flatten.reject { |file| @files.exclude?(file) }
+      end
+
+      def needed? #:nodoc:
+        return false if source_files.empty?
+        return true unless File.exist?(target.to_s)
+        source_files.map { |src| File.stat(src.to_s).mtime }.max > File.stat(target.to_s).mtime
+      end
+
+    private
+
+      def guess_engine
+        doc_engine = Doc.select project.compile.language
+        fail 'Unable to guess documentation provider for project.' unless doc_engine
+        doc_engine.new project
+      end
+
+      def associate_with(project)
+        @project ||= project
+      end
+    end
+
+
+    first_time do
+      desc 'Create the documentation for this project'
+      Project.local_task :doc
+    end
+
+    before_define do |project|
+      DocTask.define_task('doc').tap do |doc|
+        doc.send(:associate_with, project)
+        doc.into project.path_to(:target, :doc)
+        doc.using :windowtitle=>project.comment || project.name
+      end
+    end
+
+    after_define do |project|
+      project.doc.from project
+    end
+
+    # :call-seq:
+    #   doc(*sources) => JavadocTask
+    #
+    # This method returns the project's documentation task. It also accepts a list of source files,
+    # directories and projects to include when generating the docs.
+    #
+    # By default the doc task uses all the source directories from compile.sources and generates
+    # documentation in the target/doc directory. This method accepts sources and adds them by calling
+    # Buildr::Doc::Base#from.
+    #
+    # For example, if you want to generate documentation for a given project that includes all source files
+    # in two of its sub-projects:
+    #   doc projects('myapp:foo', 'myapp:bar').using(:windowtitle=>'Docs for foo and bar')
+    def doc(*sources, &block)
+      task('doc').from(*sources).enhance &block
+    end
+
+    def javadoc(*sources, &block)
+      warn 'The javadoc method is deprecated and will be removed in a future release.'
+      doc(*sources, &block)
+    end
+  end
+
+
+  class Project
+    include Doc
+  end
+end

data/lib/buildr/core/environment.rb

@@ -21,19 +21,19 @@ module Buildr
 
     # We use this to present environment variable as arrays.
     class EnvArray < Array #:nodoc:
-    
+
       def initialize(name)
         @name = name.upcase
         replace((ENV[@name] || ENV[@name.downcase] || '').split(/\s*,\s*/).reject(&:empty?))
       end
 
-      (Array.instance_methods - Object.instance_methods - Enumerable.instance_methods).sort.each do |method|
-        class_eval %{def #{method}(*args, &block) ; result = super ; write ; result ; end}
+      (Array.instance_methods - Object.instance_methods - Enumerable.instance_methods - ['each']).sort.each do |method|
+        class_eval %{def #{method}(*args, &block) ; result = super ; write_envarray ; result ; end}
       end
 
     private
 
-      def write
+      def write_envarray
         ENV[@name.downcase] = nil
         ENV[@name] = map(&:to_s).join(',')
       end
@@ -57,7 +57,7 @@ module Buildr
         ENV['http_proxy'] = nil
         ENV['HTTP_PROXY'] = url
       end
-   
+
       # Returns the HTTPS_PROXY URL.
       def https
         ENV['HTTPS_PROXY'] || ENV['https_proxy']
@@ -69,7 +69,7 @@ module Buildr
         ENV['HTTPS_PROXY'] = url
       end
 
-      # Returns list of hosts to exclude from proxying (NO_PROXY). 
+      # Returns list of hosts to exclude from proxying (NO_PROXY).
       def exclude
         @exclude ||= EnvArray.new('NO_PROXY')
       end

data/lib/buildr/core/filter.rb

@@ -41,6 +41,9 @@ module Buildr
   # relative to the source directories, so:
   #   filter.include '*.png'
   # will only include PNG files from any of the source directories.
+  # In the same way, you can use regular expressions, so:
+  #   filter.include /picture_.*\.png/
+  # will only include PNG files starting with picture_ from any of the sources directories.
   #
   # See Buildr#filter.
   class Filter
@@ -52,9 +55,9 @@ module Buildr
     # Returns the list of source directories (each being a file task).
     attr_reader :sources
 
-    # :call-seq: 
+    # :call-seq:
     #   clear => self
-    # 
+    #
     # Clear filter sources and include/exclude patterns
     def clear
       @include = []
@@ -77,7 +80,16 @@ module Buildr
     end
 
     # The target directory as a file task.
-    attr_reader :target
+    def target
+      return nil unless @target_dir
+      unless @target
+        @target = file(File.expand_path(@target_dir)) { |task| run if @target == task }
+        @target.enhance @include.select {|f| f.is_a?(Rake::FileTask)}
+        @target.enhance @exclude.select {|f| f.is_a?(Rake::FileTask)}
+        @target.enhance copy_map.values
+      end
+      @target
+    end
 
     # :call-seq:
     #   into(dir) => self
@@ -87,7 +99,8 @@ module Buildr
     # For example:
     #   filter.from('src').into('target').using('build'=>Time.now)
     def into(dir)
-      @target = file(File.expand_path(dir.to_s)) { |task| run if target == task }
+      @target_dir = dir.to_s
+      @target = nil
       self
     end
 
@@ -99,17 +112,17 @@ module Buildr
     # By default all files are included. You can use this method to only include specific
     # files from the source directory.
     def include(*files)
-      @include += files
+      @include += files.flatten
       self
     end
-    alias :add :include 
+    alias :add :include
 
     # :call-seq:
     #   exclude(*files) => self
     #
     # Specifies files to exclude and returns self. See FileList#exclude.
     def exclude(*files)
-      @exclude += files
+      @exclude += files.flatten
       self
     end
 
@@ -159,21 +172,8 @@ module Buildr
     #
     # Runs the filter.
     def run
-      sources.each { |source| 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?
+      copy_map = copy_map()
 
-      copy_map = sources.flatten.map(&:to_s).inject({}) do |map, source|
-        files = Util.recursive_with_dot_files(source).
-          map { |file| Util.relative_path(file, source) }.
-          select { |file| @include.empty? || @include.any? { |pattern| File.fnmatch(pattern, file) } }.
-          reject { |file| @exclude.any? { |pattern| File.fnmatch(pattern, file) } }
-        files.each do |file|
-          src, dest = File.expand_path(file, source), File.expand_path(file, target.to_s)
-          map[file] = src if !File.exist?(dest) || File.stat(src).mtime >= File.stat(dest).mtime
-        end
-        map
-      end
-        
       mkpath target.to_s
       return false if copy_map.empty?
 
@@ -196,30 +196,71 @@ module Buildr
       true
     end
 
-    # Returns the target directory. 
+    # Returns the target directory.
     def to_s
-      @target.to_s
+      target.to_s
+    end
+
+  protected
+  
+    # :call-seq:
+    #   pattern_match(file, pattern) => boolean
+    # 
+    # This method returns true if the file name matches the pattern.
+    # The pattern may be a String, a Regexp or a Proc.
+    #
+    def pattern_match(file, pattern)
+      case
+      when pattern.is_a?(Regexp)
+        return file.match(pattern)
+      when pattern.is_a?(String)
+        return File.fnmatch(pattern, file)
+      when pattern.is_a?(Proc)
+        return pattern.call(file)
+      when pattern.is_a?(Rake::FileTask)
+        return pattern.to_s.match(file)
+      else
+        raise "Cannot interpret pattern #{pattern}"
+      end
+    end
+    
+  private
+    def copy_map
+      sources.each { |source| 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?
+
+      sources.flatten.map(&:to_s).inject({}) do |map, source|
+        files = Util.recursive_with_dot_files(source).
+          map { |file| Util.relative_path(file, source) }.
+          select { |file| @include.empty? || @include.any? { |pattern| pattern_match(file, pattern) } }.
+          reject { |file| @exclude.any? { |pattern| pattern_match(file, pattern) } }
+        files.each do |file|
+          src, dest = File.expand_path(file, source), File.expand_path(file, target.to_s)
+          map[file] = src if !File.exist?(dest) || File.stat(src).mtime >= File.stat(dest).mtime
+        end
+        map
+      end
     end
 
     # This class implements content replacement logic for Filter.
     #
-    # To register a new template engine @:foo@, extend this class with a method like: 
-    # 
+    # To register a new template engine @:foo@, extend this class with a method like:
+    #
     #   def foo_transform(content, path = nil)
     #      # if this method yields a key, the value comes from the mapping hash
     #      content.gsub(/world/) { |str| yield :bar }
     #   end
     #
     # Then you can use :foo mapping type on a Filter
-    #   
+    #
     #   filter.using :foo, :bar => :baz
     #
     # Or all by your own, simply
     #
     #   Mapper.new(:foo, :bar => :baz).transform("Hello world") # => "Hello baz"
-    # 
+    #
     # You can handle configuration arguments by providing a @*_config@ method like:
-    # 
+    #
     #   # The return value of this method is available with the :config accessor.
     #   def moo_config(*args, &block)
     #      raise ArgumentError, "Expected moo block" unless block_given?
@@ -235,7 +276,7 @@ module Buildr
     #   end
     #
     # Usage for the @:moo@ mapper would be something like:
-    # 
+    #
     #   mapper = Mapper.new(:moo, 'ooone', 'twoo') do |str|
     #     i = nil; str.capitalize.gsub(/\w/) { |s| s.send( (i = !i) ? 'upcase' : 'downcase' ) }
     #   end
@@ -247,7 +288,7 @@ module Buildr
       def initialize(*args, &block) #:nodoc:
         using(*args, &block)
       end
-      
+
       def using(*args, &block)
         case args.first
         when Hash # Maven hash mapping
@@ -285,7 +326,8 @@ module Buildr
           @config = configurer.call(*args, &block)
         else
           raise ArgumentError, "Missing hash argument after :#{mapper_type}" unless args.size == 1 && Hash === args[0]
-          @config = args.first
+          @config = {} unless Hash === @config
+          args.first.each_pair { |k, v| @config[k] = v.to_s }
         end
         @mapper_type = mapper_type
       end
@@ -293,15 +335,15 @@ module Buildr
       def maven_transform(content, path = nil)
         content.gsub(/\$\{.*?\}/) { |str| yield(str[2..-2]) || str }
       end
-      
+
       def ant_transform(content, path = nil)
         content.gsub(/@.*?@/) { |str| yield(str[1..-2]) || str }
       end
-      
+
       def ruby_transform(content, path = nil)
         content.gsub(/#\{.*?\}/) { |str| yield(str[2..-2]) || str }
       end
-      
+
       def regexp_transform(content, path = nil)
         content.gsub(mapper_type) { |str| yield(str.scan(mapper_type).join) || str }
       end
@@ -309,7 +351,7 @@ module Buildr
       def callback_transform(content, path = nil)
         config.call(path, content)
       end
-      
+
       def erb_transform(content, path = nil)
         case config
         when Binding