sprout 1.0.32.pre → 1.0.35.pre

data/lib/sprout/generators/generator/generator_generator.rb

@@ -2,14 +2,48 @@
 module Sprout
   class GeneratorGenerator < Generator::Base
 
+    ##
+    # The default module that classes will be added
+    # to.
     add_param :namespace, String, { :default  => ''}
+
+    ##
+    # The name of the folder where external libraries
+    # will be installed.
     add_param :lib, String, { :default => 'lib' }
+
+    ##
+    # The name of the folder where custom generators and templates
+    # will be found.
     add_param :generators, String, { :default => 'generators' }
+
+    ##
+    # The name of the folder where tests should be generated.
     add_param :test, String, { :default => 'test' }
+
+    ##
+    # The name of the child folder of the test folder where 
+    # unit tests should be generated.
     add_param :unit, String, { :default => 'unit' }
+
+    ##
+    # The name of the child folder of the test folder where
+    # fixtures should be generated.
     add_param :fixtures, String, { :default => 'fixtures' }
-    add_param :vendor, String, { :default => 'vendor' }    
+
+    ##
+    # The name of the folder where external source code
+    # should be placed.
+    add_param :vendor, String, { :default => 'vendor' }
+
+    ##
+    # The name of the folder where binary or executable
+    # artifacts should be created by compiler tasks.
     add_param :bin, String, { :default => 'bin' }
+
+    ##
+    # The default (primary) file extension for generated source
+    # files. This should hint at the project type.
     add_param :extension, String, { :default => '.as' }
 
     def manifest  

data/lib/sprout/generators/generator/templates/generator_class.rb

@@ -4,13 +4,13 @@ module Sprout
     
     ##
     # This is how you add a parameter to your generator
-    # add_param :fwee, String, { :default => "fwee" }
-
+    #
+    #   add_param :fwee, String, :default => "fwee"
+    #
     def manifest
       directory input.snake_case do
         template "#{input.camel_case}<%= extension %>"
       end
-      
     end
 
   end

data/lib/sprout/library.rb

@@ -1,5 +1,80 @@
 
 module Sprout
+
+  ##
+  # Sprout Libraries provide support for sharing and versioning raw or 
+  # pre-compiled source code across projects.
+  #
+  # Sprout Libraries give us the ability to include raw (or pre-compiled) source
+  # code directly within a Ruby Gem, or to refer to an archive somewhere on
+  # the internet.
+  #
+  # A Sprout Library is made up of two components:
+  #
+  # * Specification: The description of the library
+  # * Source Code: Raw or pre-compiled (swc, jar, abc)
+  #
+  # = Specification
+  # Libraries can be added to local or remote file targets in a 
+  # Sprout::Specification. When calling add_library, one must provide the 
+  # library name (symbol that will be used from Rake) and a relative path (or 
+  # Array of paths) from the Specification to the library file or directory.
+  #
+  # Following is an example of a Sprout::Specification that registers a SWC 
+  # that will be distributed directly within a Ruby Gem:
+  #
+  #   Sprout::Specification.new do |s|
+  #     s.name = "asunit4"
+  #     s.version = "4.4.2"
+  #     s.add_file_target do |f|
+  #       f.add_library :swc, File.join('bin', "AsUnit-4.4.2.swc")
+  #     end
+  #   end
+  #
+  # Following is an example of a Sprout::Specification that registers a ZIP
+  # archive that will be distributed separately from the Ruby Gem:
+  #
+  #   Sprout::Specification.new do |s|
+  #     s.name = "asunit3"
+  #     s.version = "3.0.0"
+  #     s.add_remote_file_target do |f|
+  #       f.url = "https://github.com/patternpark/asunit/tree/3.0.0"
+  #       f.md5 = "abcdefghijklmnopqrstuvwxyz"
+  #       f.add_library :swc, "bin/AsUnit-3.0.1.zip"
+  #     end
+  #   end
+  #
+  # Libraries can be consumed from any Rakefile without concern for how
+  # the source code is distributed. Following is an example Rake task
+  # that uses the AsUnit 4.0 Library:
+  #
+  #   # Define the library Rake::Task:
+  #   library :asunit4
+  #
+  #   # Add the library as a dependency from another task
+  #   # that should know how to properly associate the files:
+  #   mxmlc 'bin/SomeProject.swf' => :asunit4 do |t|
+  #     t.input = 'src/SomeProject.as'
+  #   end
+  #
+  # When the library task is executed, the library should be resolved and 
+  # expanded into the project. When the mxmlc task is executed, the installed 
+  # library should be associated with the compilation command.
+  #   
+  # ---
+  # 
+  # Previous Topic: {Sprout::Generator}
+  #
+  # Next Topic: {Sprout::Executable}
+  #
+  # ---
+  # 
+  # @see Sprout::Generator
+  # @see Sprout::Executable
+  # @see Sprout::Specification
+  # @see Sprout::RubyFeature
+  # @see Sprout::System
+  #
   class Library
     include RubyFeature
 

data/lib/sprout/log.rb

@@ -1,44 +1,43 @@
 
-module Sprout #:nodoc:
-  
-  class Log #:nodoc:
+module Sprout
+  class Log
     @@debug = false
     @@output = ''
     @@printout = ''
-    
+
     def Log.debug=(debug)
       @@debug = debug
     end
-    
+
     def Log.debug
       return @@debug
     end
-    
+
     def Log.puts(msg)
       @@output << msg + "\n"
       Log.flush
     end
-    
+
     def Log.print(msg)
       @@printout << msg
       Log.flush_print
     end
-    
+
     def Log.printf(msg)
       @@printout << msg
       Log.flush_print
     end
-    
+
     def Log.flush_print
       if(!Log.debug)
-        $stdout.print @@printout
+        $stdout.printf @@printout
         @@printout = ''
       end
     end
-    
+
     def Log.flush
       if(!Log.debug)
-        $stdout.puts @@output
+        $stdout.printf @@output
         @@output = ''
       end
     end

data/lib/sprout/process_runner.rb

@@ -11,10 +11,26 @@ module Sprout #:nodoc:
   # continuing beligerence of Windows or *nix (depending on 
   # which side of the fence you're on).
   class ProcessRunner
-    attr_reader :pid,
-                :r,
-                :w,
-                :e
+
+    attr_reader :pid
+    attr_reader :ruby_version
+
+    ##
+    # Read IO (readable)
+    attr_reader :r
+
+    ##
+    # Write IO (writeable)
+    attr_reader :w
+
+    ##
+    # Error IO (readable)
+    attr_reader :e
+
+    def initialize
+      super
+      @ruby_version = RUBY_VERSION
+    end
     
     # Execute the provided command using the open4.popen4
     # library. This is generally only used by Cygwin and
@@ -103,18 +119,22 @@ module Sprout #:nodoc:
     end
 
     def io_popen_block *command
-      if(RUBY_VERSION == '1.8.6' || RUBY_VERSION == '1.8.7')
+      if(ruby_version == '1.8.6' || ruby_version == '1.8.7')
         win32_open3_block *command
       else
-        require 'open3'
-        write, read, error, wait_thread = Open3.popen3(*command)
-        [wait_thread[:pid], write, read, error]
+        open3_popen3_block *command
       end
     end
 
+    def open3_popen3_block *command
+      require 'open3'
+      write, read, error, wait_thread = Open3.popen3(*command)
+      [wait_thread[:pid], write, read, error]
+    end
+
     def win32_open3_block *command
       write, read, error, pid = nil
-      gem 'win32-open3', '0.2.5'
+      gem 'win32-open3'
       require 'win32/open3'
       Open3.popen3(*command) do |w, r, e, p|
             pid   = p

data/lib/sprout/remote_file_target.rb

@@ -21,14 +21,6 @@ module Sprout
       self
     end
 
-    protected
-
-    def expand_local_path path
-      File.join unpacked_file, path
-    end
-
-    private
-
     ##
     # Do not cache this value...
     #
@@ -40,9 +32,27 @@ module Sprout
     end
 
     def unpacked_file
-      @unpacked_file ||= File.join(Sprout.cache, pkg_name, pkg_version)
+      upcased_pkg = pkg_name.upcase
+      upcased_version = pkg_version.upcase.gsub /\./, '_'
+        ENV["SPROUT_#{upcased_pkg}_#{upcased_version}"] ||
+        ENV["SPROUT_#{upcased_pkg}"] ||
+        ENV["#{upcased_pkg}_#{upcased_version}"] ||
+        ENV[upcased_pkg] ||
+        File.join(Sprout.cache, pkg_name, pkg_version)
+    end
+
+    protected
+
+    def logger
+      Sprout::Log
     end
 
+    def expand_local_path path
+      File.join unpacked_file, path
+    end
+
+    private
+
     def load_unpack_or_ignore_archive
       if(!unpacked_files_exist?)
         if(!File.exists?(downloaded_file))
@@ -101,6 +111,7 @@ module Sprout
     end
 
     def unpack_archive
+      logger.puts "Unpacking archive at #{downloaded_file} now. This can take anywhere from a few seconds to many minutes depending on your OS and the size of the archive.\n\nIf you're on windows, consider using this ample time to look into improving the zip utils in Ruby..."
       FileUtils.mkdir_p unpacked_file
       unpacker = Sprout::ArchiveUnpacker.new
       unpacker.unpack downloaded_file, unpacked_file, archive_type

data/lib/sprout/system/base_system.rb

@@ -91,16 +91,24 @@ module Sprout::System
     # long-lived CLI processes like FCSH or FDB.
     #
     def execute_silent(tool, options='')
-      return get_and_execute_process_runner(tool, options)
+      get_and_execute_process_runner(tool, options)
     end
 
     ##
     # Execute a new process in a separate thread.
     #
     def execute_thread(tool, options='')
-      return Thread.new do
-        execute(tool, options)
+      runner = nil
+      Thread.new do
+        runner = execute_silent(tool, options)
       end
+      # Wait for the runner to be created
+      # before returning a nil reference
+      # that never gets populated...
+      while runner.nil? do
+        sleep(0.1)
+      end
+      runner
     end
 
     ##

data/lib/sprout/test/sprout_test_case.rb

@@ -57,6 +57,7 @@ module SproutTestCase # :nodoc:[all]
   end
 
   def clear_tasks
+    CLEAN.delete_if {|a| true }
     Rake::Task.clear
     Rake.application.clear
   end

data/lib/sprout/version.rb

@@ -1,17 +1,13 @@
 
 module Sprout
   NAME = 'sprout'
-
-  if(!defined? Sprout::VERSION)
-    module VERSION #:nodoc:
-      MAJOR = 1
-      MINOR = 0
-      TINY  = 32
-      RELEASE = 'pre'
-
-      STRING = [MAJOR, MINOR, TINY, RELEASE].join('.')
-      MAJOR_MINOR = [MAJOR, MINOR].join('.')
-    end
+  module VERSION #:nodoc:
+    STRING      = File.read(File.join(File.dirname(__FILE__), '..', '..', 'VERSION').strip)
+    MAJOR       = STRING.split('.')[0]
+    MINOR       = STRING.split('.')[1]
+    TINY        = STRING.split('.')[2]
+    RELEASE     = STRING.split('.')[3]
+    MAJOR_MINOR = [MAJOR, MINOR].join('.')
   end
 end
 

data/rakefile.rb

@@ -3,25 +3,20 @@ require 'bundler'
 
 # Hack this dir onto path for Ruby 1.9.2
 # support:
-test_package = File.join(File.dirname(__FILE__), 'test')
+test_package = File.expand_path(File.join(File.dirname(__FILE__), 'test'))
 $: << test_package unless $:.include? test_package
 
 Bundler.require
 
 require 'rake/clean'
 require 'rake/testtask'
-require 'rake/rdoctask'
 
-require File.dirname(__FILE__) + '/lib/sprout/version'
-
-Rake::RDocTask.new do |rdoc|
-  rdoc.title = "Project Sprouts v.#{Sprout::VERSION::STRING}"
-  rdoc.rdoc_dir = 'rdoc'
-  rdoc.main = "Sprout::Sprout"
-  rdoc.rdoc_files.include("README.textile", "lib/**/*.rb")
-end
-
-CLEAN.add('rdoc')
+##
+# NOTE, to generate documentation, simply run:
+#
+#   bundle install
+#   yard
+#
 
 namespace :test do
   Rake::TestTask.new(:units) do |t|

data/script/add_param_handler.rb

@@ -0,0 +1,43 @@
+
+class AddParamHandler < YARD::Handlers::Ruby::MethodHandler
+
+  handles method_call(:add_param)
+
+  def process
+    name = statement[1][0].source.gsub(/^:/, '')
+    class_name = statement[1][1].source
+
+    case class_name
+      when "Strings"
+        class_name = "Array<String>"
+      when "Files"
+        class_name = "Array<String> [Files]"
+      when "Paths"
+        class_name = "Array<String> [Paths]"
+      when "Urls"
+        class_name = "Array<String> [Urls]"
+    end
+
+    namespace.attributes[scope][name] ||= SymbolHash[:read => nil, :write => nil]
+
+    {:read => name, :write => "#{name}="}.each do |type, meth|
+        namespace.attributes[scope][name][type] = MethodObject.new(namespace, meth, scope) do |o|
+
+          o.source = statement.source
+          o.signature = method_signature(meth)
+          o.docstring = statement.comments
+
+          if type == :write
+            o.parameters = [['value', nil]]
+          else
+            new_tag = YARD::Tags::Tag.new(:return, "An instance of #{class_name}", class_name)
+            o.docstring.add_tag(new_tag) 
+          end
+
+          o.visibility = visibility
+        end
+    end
+  end
+
+end
+