svn commit: r641090 - in /incubator/buildr/trunk/lib: buildr/xmlbeans.rb java/artifact_namespace.rb java/groovyc.rb

[vb...@apache.org]

Author: vborja
Date: Tue Mar 25 17:12:34 2008
New Revision: 641090

URL: http://svn.apache.org/viewvc?rev=641090&view=rev
Log:
More documentation  ArtifactNamespace#for

Modified:
    incubator/buildr/trunk/lib/buildr/xmlbeans.rb
    incubator/buildr/trunk/lib/java/artifact_namespace.rb
    incubator/buildr/trunk/lib/java/groovyc.rb

Modified: incubator/buildr/trunk/lib/buildr/xmlbeans.rb
URL: http://svn.apache.org/viewvc/incubator/buildr/trunk/lib/buildr/xmlbeans.rb?rev=641090&r1=641089&r2=641090&view=diff
==============================================================================
--- incubator/buildr/trunk/lib/buildr/xmlbeans.rb (original)
+++ incubator/buildr/trunk/lib/buildr/xmlbeans.rb Tue Mar 25 17:12:34 2008
@@ -32,10 +32,10 @@
     #
     #   require 'buildr/xmlbeans'
     #   artifacts[Buildr::XMLBeans].use :xmlbeans => '2.2.0'
-    REQUIREMENTS = {
+    REQUIRES = ArtifactNamespace.for self, {
       'stax:stax-api:jar:>=1' => '1.0.1',
       'org.apache.xmlbeans:xmlbeans:jar:>2' => '2.3.0'
-    }.tap { |reqs| Buildr.artifacts[self].need reqs }
+    }
     
     class << self
 
@@ -57,7 +57,7 @@
       end
 
       def requires
-        Buildr.artifacts[XMLBeans].each { |artifact| artifact.invoke }
+        REQUIRES.each { |artifact| artifact.invoke }
       end
     end
 

Modified: incubator/buildr/trunk/lib/java/artifact_namespace.rb
URL: http://svn.apache.org/viewvc/incubator/buildr/trunk/lib/java/artifact_namespace.rb?rev=641090&r1=641089&r2=641090&view=diff
==============================================================================
--- incubator/buildr/trunk/lib/java/artifact_namespace.rb (original)
+++ incubator/buildr/trunk/lib/java/artifact_namespace.rb Tue Mar 25 17:12:34 2008
@@ -19,12 +19,27 @@
 
   #
   # ArtifactNamespace allows users to control artifact versions to be
-  # used by their projects and Buildr modules/addons. See Buildr::XMLBeans
-  # as an example for modules/addon writers.
-  # 
+  # used by their projects or addons. 
   # A namespace is a hierarchical dictionary that allows to specify
   # artifact version requirements (see ArtifactNamespace#need).
   #
+  #
+  # Addon/extension authors expecting their users to customize an artifact
+  # version, need to document the namespace where users can do so.
+  # The following example illustrates how to do this. See the source for 
+  # Buildr::XMLBeans for real-world example.
+  #   
+  #   # Document this addon/extension features
+  #   module Some::Extension
+  #     # Document this constant for users to know the version requirements
+  #     REQUIRES = ArtifactNamespace.for self, 'arti:fact:jar:>1' => '1.0.1'
+  #
+  #     def some_stuff
+  #        REQUIRES.requirement(:fact)[:version].satisfied_by?('0.9') # -> false
+  #        REQUIRES.each { |artifact| artifact.invoke } # get them!
+  #     end
+  #   end
+  # 
   # Every project can have it's own namespace inheriting the one for
   # their parent projects. 
   #
@@ -145,10 +160,13 @@
       # :call-seq:
       #   Buildr.artifacts { |ns| ... } -> namespace
       #   Buildr.artifacts(name) { |ns| ... } -> namespace
+      #   ArtifactNamespace.for(name, requirements) { |ns| ... } -> namespace
       # 
       # Obtain the namespace for the given +name+ or for the currently
       # running project. If a block is given, the namespace is yielded to it.
-      def instance(name = nil, &block)
+      #
+      # See the class level documentation for ArtifactNamespace.
+      def instance(name = nil, needs = nil, &block)
         case name
         when Array then name = name.join(':')
         when Module, Project then name = name.name
@@ -166,6 +184,7 @@
         name = ROOT if name.to_s.blank?
         @instances ||= Hash.new { |h, k| h[k] = new(k) }
         instance = @instances[name.to_sym]
+        instance.need(needs) if needs
         yield(instance) if block
         instance
       end
@@ -296,7 +315,7 @@
     #     need name => requirement
     #     need requirement => default_version
     #   end
-    # 
+    #
     # Establish an artifact +requirement+ on the current namespace.
     # A +requirement+ is simply an artifact spec whose version part
     # contains comparision operators. If no +name+ is specified, 

Modified: incubator/buildr/trunk/lib/java/groovyc.rb
URL: http://svn.apache.org/viewvc/incubator/buildr/trunk/lib/java/groovyc.rb?rev=641090&r1=641089&r2=641090&view=diff
==============================================================================
--- incubator/buildr/trunk/lib/java/groovyc.rb (original)
+++ incubator/buildr/trunk/lib/java/groovyc.rb Tue Mar 25 17:12:34 2008
@@ -48,16 +48,21 @@
     # * :target            -- Bytecode compatibility.
     # * :javac             -- Hash of options passed to the ant javac task
     #
-    # ArtifactNamespace for this module is 
-    # 
     class Groovyc < Base
       
-      REQUIREMENTS = {
+      # The groovyc compiler jars are added to classpath at load time,
+      # if you want to customize the artifact versions to use, you must use
+      # the
+      #
+      #      artifacts['Buildr::Compiler::Groovyc']
+      #
+      # namespace before this file is required.
+      REQUIRES = ArtifactNamespace.for self, {
         'org.codehaus.groovy:groovy:jar:>=1.5.3' => '1.5.3',
         'commons-cli:commons-cli:jar:>=1.0' => '1.0',
         'asm:asm:jar:>=2.2' => '2.2.3',
         'antlr:antlr:jar:>=2.7.7' => '2.7.7'
-      }.tap { |reqs| Buildr.artifacts[self].need reqs }
+      }
       
       ANT_TASK = 'org.codehaus.groovy.ant.Groovyc'
       GROOVYC_OPTIONS = [:encoding, :verbose, :fork, :memoryInitialSize, :memoryMaximumSize, :listfiles, :stacktrace]
@@ -66,7 +71,7 @@
 
       class << self
         def dependencies #:nodoc:
-          Buildr.artifacts[self].values
+          REQUIRES.values
         end
 
         def applies_to?(project, task) #:nodoc: