iconara-java_tools 0.1.1 → 0.1.2

data/{README.textile → README.rdoc}

@@ -1,12 +1,11 @@
-h1. Java Tools
+= Java Tools
 
 Ruby wrappers for javac and jar that don't just exec.
 
-Ant is a nice tool for writing Java build scripts, but Rake is nicer. The only thing missing from Rake is a way to run javac and jar, and although it's easy to run these with exec you have to wait for the JVM to start for each invocation. In combination with JRuby this gem lets you run @javac@ and @jar@ in your Rake scripts without exec'ing, by using the programmatic interface to Javac and Java's ZIP file creation capabilities.
+Ant is a nice tool for writing Java build scripts, but Rake is nicer. The only thing missing from Rake is a way to run javac and jar, and although it's easy to run these with exec you have to wait for the JVM to start for each invocation. In combination with JRuby this gem lets you run +javac+ and +jar+ in your Rake scripts without exec'ing, by using the programmatic interface to Javac and Java's ZIP file creation capabilities.
 
-h2. Example
+== Example
 
-<pre><code>
   require 'java_tools'
 
 
@@ -17,35 +16,32 @@ h2. Example
   task :dist => :compile do
     jar 'dist/my-awsome-app.jar', FileList['build/**/*.class'], :base_dir => 'build'
   end
-</code></pre>
 	
-There are more examples in the @examples@ directory.
+There are more examples in the +examples+ directory.
 
-h2. Command style
+== Command style
 
 Many Rake add-ons look like this:
 
-<pre><code>
   Spec::Rake::SpecTask.new(:spec) do |spec|
     spec.spec_opts << '--options' << 'spec/spec.opts'
     # ...
   end
-</code></pre>
 
-I think it ruins the DSL illusion, and I prefer to write tasks that contain commands, more like how @cp@, @rm@ and @sh@ work in Rake.
+I think it ruins the DSL illusion, and I prefer to write tasks that contain commands, more like how +cp+, +rm+ and +sh+ work in Rake.
 
-h2. Nailgun
+== Nailgun
 
 Don't forget that since JRuby 1.3 you can minimize the startup by using the built-in Nailgun support. Run
 
-@jruby --ng-server &@
+  jruby --ng-server &
 
 to start a Nailgun server and then run Rake with this command
 
-@jruby --ng -S rake@
+  jruby --ng -S rake
 
-you'll notice that the startup time decreases significantly the second time you run it. To avoid having to write all that every time you want to build create an alias, I call mine @jrk@.
+you'll notice that the startup time decreases significantly the second time you run it. To avoid having to write all that every time you want to build create an alias, I call mine +jrk+.
 
-h2. Upcomming
+== Upcomming
 
-Even though the whole rationale behind Java Tools is to avoid exec it wouldn't be much effort to support non-JRuby runtimes since at least the @javac@ command needs to build the command string anyway.
+Even though the whole rationale behind Java Tools is to avoid exec it wouldn't be much effort to support non-JRuby runtimes since at least the +javac+ command needs to build the command string anyway.

data/java_tools.gemspec

@@ -2,18 +2,18 @@
 
 Gem::Specification.new do |s|
   s.name = %q{java_tools}
-  s.version = "0.1.1"
+  s.version = "0.1.2"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Theo Hultberg"]
-  s.date = %q{2009-08-05}
+  s.date = %q{2009-08-06}
   s.description = %q{Ant is a nice tool for writing Java build scripts, but Rake is nicer. The only thing missing from Rake is a way to run javac and jar, and although it's easy to run these as shell scripts you have to wait for the JVM to start. In combination with JRuby this gem lets you run javac and jar in your Rake scripts without exec'ing.}
   s.email = %q{theo@iconara.net}
   s.extra_rdoc_files = [
-    "README.textile"
+    "README.rdoc"
   ]
   s.files = [
-    "README.textile",
+    "README.rdoc",
      "Rakefile",
      "VERSION",
      "examples/compile/Rakefile",
@@ -31,6 +31,7 @@ Gem::Specification.new do |s|
      "spec/spec.opts",
      "spec/spec_helper.rb",
      "tasks/gem.rake",
+     "tasks/rdoc.rake",
      "tasks/spec.rake"
   ]
   s.homepage = %q{http://github.com/iconara/java_tools}

data/lib/java_tools.rb

@@ -5,9 +5,9 @@ require File.expand_path(File.dirname(__FILE__)) + '/java_tools/javac'
 require File.expand_path(File.dirname(__FILE__)) + '/java_tools/jar'
 
 
-module JavaTools
+module JavaTools # :nodoc:
   
-  def self.version
+  def self.version # :nodoc:
     version_file = File.join(File.dirname(__FILE__), '..', 'VERSION')
     
     File.open(version_file) do |f|
@@ -15,7 +15,7 @@ module JavaTools
     end
   end
 
-  def self.configure_command( command, options )
+  def self.configure_command( command, options ) # :nodoc:
     options.each do |option, value|
       setter_name = "#{option}="
       
@@ -29,6 +29,31 @@ module JavaTools
   
 end
 
+# Javac can be run in either command or yield mode: command mode
+# looks roughly like this:
+#
+#   javac [file1, file2], :destination => 'build'
+#
+# and yield mode like this:
+#
+#   javac(file1, file2) do |conf|
+#     conf.destination = 'build'
+#   end
+#
+# In command mode you pass a hash with the configuration directives
+# (listed below) and in yield mode an object is passed to the block,
+# and the configuration directives should be set on that.
+#
+# The possible configuration directives are:
+# * source_path
+# * destination
+# * class_path
+# * deprecation_warnings
+# * warnings
+# * encoding
+# * verbose
+#
+# The directives are the same as the properties of JavaTools::Javac.
 def javac( source_files, options = nil )
   obj = JavaTools::Javac.new(*source_files)
   
@@ -41,6 +66,27 @@ def javac( source_files, options = nil )
   obj.execute
 end
 
+# Jar can be run in either command or yield mode: command mode
+# looks roughly like this:
+#
+#   jar 'output.jar', [file1, file2], :base_dir => 'build'
+#
+# and yield mode like this:
+#
+#   jar('output.jar', [file1, file2]) do |conf|
+#     conf.base_dir = 'build'
+#   end
+#
+# In command mode you pass a hash with the configuration directives
+# (listed below) and in yield mode an object is passed to the block,
+# and the configuration directives should be set on that.
+#
+# The possible configuration directives are:
+# * base_dir
+# * compression
+# * verbose
+#
+# The directives are the same as the properties of JavaTools::Javac.
 def jar( output, files = nil, options = nil )
   base_dir = nil
   

data/lib/java_tools/jar.rb

@@ -10,16 +10,26 @@ module JavaTools
 
   class Jar
   
-    attr_accessor :base_dir,    # string
-                  :compression, # number (0-9)
-                  :verbose      # boolean
-                  
+    # The path to the directory which should be considered the root of the archive.
+    #
+    # If you set +base_dir+ to "build" and add the file "build/Main.class", that file
+    # will be put in the archive as "Main.class". 
+    attr_accessor :base_dir
+    
+    # The ZIP compression rate from 0 (no compression) to 9 (maximal compression)
+    attr_accessor :compression
+    
+    # Whether or not to print the equivalent command string to the output (see #execute)
+    attr_accessor :verbose
+    
+    # The path to the JAR file that will be generated
     attr_reader :output
-                
+     
+    
     def initialize( output, files = nil, base_dir = nil )
       @output      = output
       @base_dir    = base_dir
-      @entries     = { } # archive_path => JarEntry
+      @entries     = { } # archive_path => IO
       @verbose     = false
       @compression = 1
       
@@ -28,6 +38,16 @@ module JavaTools
       add_files(files) unless files.nil? || files.empty?
     end
   
+    # Sets the attributes that will end up in the JAR manifest.
+    #
+    # Attribute names are treated case insensitively, so setting
+    # both Main-Class and main-class will result in only one being used.
+    #
+    # Will raise an error on malformed attribute names (must start with a
+    # letter or digit and contain only letter, digits, dashes and underscores).
+    # 
+    # The manifest you set will be merged with a set of default attributes (but
+    # yours will override).
     def manifest=( manifest_hash )
       @manifest = default_manifest
       
@@ -40,12 +60,14 @@ module JavaTools
       end
     end
     
-    def remove_manifest_attribute( name )
+    # Removes a manifest attribute, the comparison is case insensitive.
+    def remove_manifest_attribute( name ) # :nodoc:
       @manifest.delete_if do |key, value|
         key.downcase == name.downcase
       end      
     end
     
+    # Convenience method for setting the Main-Class manifest attribute
     def main_class=( class_name )
       if class_name
         @manifest['Main-Class'] = class_name
@@ -54,23 +76,25 @@ module JavaTools
       end
     end
     
-    def default_manifest
+    def default_manifest # :nodoc:
       {
         'Built-By' => "JavaTools v#{JavaTools::version}",
         'Manifest-Version' => '1.0'
       }
     end
     
-    def manifest_string
+    def manifest_string # :nodoc:
       @manifest.keys.inject("") do |str, key|
         str + "#{key}: #{@manifest[key]}\n"
       end
     end
     
-    def commit_manifest
+    def commit_manifest # :nodoc:
       add_blob(manifest_string, 'META-INF/MANIFEST.MF')
     end
     
+    # Adds the file at +file_path+ to the archive and put it at +archive_path+
+    # (the same as +file_path+ by default) inside the archive.
     def add_file( file_path, archive_path = nil )
       archive_path = find_archive_path(file_path, @base_dir) unless archive_path
       
@@ -83,24 +107,30 @@ module JavaTools
       @entries[archive_path || file_path] = File.new(file_path)
     end
     
+    # Adds a list of files to the archive, at paths relative to +base_dir+
+    # (defaults to #base_dir) inside the archive.
     def add_files( files, base_dir = nil )
       files.each do |file|
         add_file(file, find_archive_path(file, base_dir || @base_dir))
       end
     end
     
+    # Adds a string to the archive at +archive_path+.
     def add_blob( str, archive_path )
       @entries[archive_path] = StringIO.new(str)
     end
     
-    def remove_entry( archive_path )
+    def remove_entry( archive_path ) # :nodoc:
       @entries.delete(archive_path)
     end
     
-    def entries
+    def entries # :nodoc:
       @entries.keys
     end
     
+    # Creates the archive. If #verbose is true the equivalent command string
+    # for the +jar+ command will be printed to the stream passed as +io+ (or
+    # +$stdout+ by default)
     def execute( io = $stderr )
       raise "Output not set" unless @output
       
@@ -112,7 +142,7 @@ module JavaTools
       create_zipfile
     end
     
-    def create_zipfile
+    def create_zipfile # :nodoc:
       buffer_size = 65536
       
       zipstream = ZipOutputStream.new(FileOutputStream.new(@output))
@@ -130,7 +160,7 @@ module JavaTools
       zipstream.close
     end
     
-    def find_archive_path( path, base_dir )
+    def find_archive_path( path, base_dir ) # :nodoc:
       if base_dir
         prefix = base_dir + (base_dir =~ /\/$/ ? '' : '/')
       

data/lib/java_tools/javac.rb

@@ -10,14 +10,30 @@ module JavaTools
 
   class Javac
 
-    attr_accessor :source_files,         # array
-                  :source_path,          # array
-                  :destination,          # string
-                  :class_path,           # array
-                  :deprecation_warnings, # boolean
-                  :warnings,             # boolean
-                  :encoding,             # string
-                  :verbose               # boolean
+    # The files to compile.
+    attr_accessor :source_files
+    
+    # Additional directories where source files can be found.
+    attr_accessor :source_path
+                  
+    # The directory where the generated class files should be written, defaults to "build"
+    attr_accessor :destination
+  
+    # The compilation class path
+    attr_accessor :class_path
+    
+    # Show deprecation warnings, true by default
+    attr_accessor :deprecation_warnings
+    
+    # Generate warnings, true by default
+    attr_accessor :warnings
+    
+    # The encoding of the source files
+    attr_accessor :encoding
+    
+    # Whether or not to print the equivalent command string to the output (see #execute)
+    attr_accessor :verbose
+    
 
     def initialize( *source_files )
       @source_files = source_files || [ ]
@@ -31,7 +47,7 @@ module JavaTools
       @verbose              = false
     end
 
-    def command_args
+    def command_args # :nodoc:
       args = [ ]
       args << '-sourcepath' << @source_path.join(':') unless @source_path.empty?
       args << '-d' << @destination unless (@destination.nil? || @destination =~ /^\s*$/)
@@ -42,7 +58,7 @@ module JavaTools
       args + @source_files
     end
   
-    def command_string
+    def command_string # :nodoc:
       args = [ ]
       args << '-sourcepath' << @source_path.join(':') unless @source_path.empty?
       args << '-d' << @destination unless (@destination.nil? || @destination =~ /^\s*$/)
@@ -54,6 +70,9 @@ module JavaTools
       "javac #{args.join(' ')} …"
     end
 
+    # Run javac. If #verbose is true the equivalent command string for
+    # the +javac+ command will be printed to the stream passed as +io+ (or
+    # +$stdout+ by default)
     def execute( io = $stderr )
       output_writer = StringWriter.new
   

data/tasks/rdoc.rake

@@ -0,0 +1,10 @@
+require 'rake/rdoctask'
+
+  
+Rake::RDocTask.new do |rd|
+  rd.rdoc_dir = 'docs'
+  rd.title    = 'Java Tools'
+  rd.main     = 'README.rdoc'
+  
+  rd.rdoc_files.include('README.rdoc', 'lib/**/*.rb')
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: iconara-java_tools
 version: !ruby/object:Gem::Version 
-  version: 0.1.1
+  version: 0.1.2
 platform: ruby
 authors: 
 - Theo Hultberg
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-08-05 00:00:00 -07:00
+date: 2009-08-06 00:00:00 -07:00
 default_executable: 
 dependencies: []
 
@@ -20,9 +20,9 @@ executables: []
 extensions: []
 
 extra_rdoc_files: 
-- README.textile
+- README.rdoc
 files: 
-- README.textile
+- README.rdoc
 - Rakefile
 - VERSION
 - examples/compile/Rakefile
@@ -40,6 +40,7 @@ files:
 - spec/spec.opts
 - spec/spec_helper.rb
 - tasks/gem.rake
+- tasks/rdoc.rake
 - tasks/spec.rake
 has_rdoc: false
 homepage: http://github.com/iconara/java_tools