sprout 1.0.35.pre → 1.1.2.pre

data/lib/sprout/process_runner.rb

@@ -1,30 +1,43 @@
 
-module Sprout #:nodoc:
+module Sprout
 
   # The ProcessRunner is a cross-platform wrapper for executing
   # external executable processes.
   #
-  # As it turns out, Ruby handle differences very well, and 
-  # other process libraries (like win32-open3 and open4.popen4),
-  # do make the experience more consistent on a given platform,
-  # but they don't hide the differences introduced by the 
-  # continuing beligerence of Windows or *nix (depending on 
-  # which side of the fence you're on).
+  # This class is typically accesses via the concrete Sprout::System
+  # classes in order to avoid ugly branching logic in the application
+  # layer.
+  #
+  # An example of this kind of usage might be:
+  #
+  #   Sprout.current_system.execute './some.exe', '--foo=bar --baz=buz'
+  #
+  # To use this class directly, you need to know if you're on
+  # a unix-like system or a dos platform as these two deal with
+  # processes very differently.
+  #
+  # Assuming you know you're on a unix-like system, you could
+  # execute the previous example with:
+  #
+  #   runner = Sprout::ProcessRunner.new
+  #   runner.execute_open4 './some.exe --foo-bar --baz=buz'
+  #   puts runner.read
+  #
   class ProcessRunner
 
     attr_reader :pid
     attr_reader :ruby_version
 
     ##
-    # Read IO (readable)
+    # @return [IO] Read only
     attr_reader :r
 
     ##
-    # Write IO (writeable)
+    # @return [IO] Write only
     attr_reader :w
 
     ##
-    # Error IO (readable)
+    # @return [IO] Error output
     attr_reader :e
 
     def initialize
@@ -32,6 +45,7 @@ module Sprout #:nodoc:
       @ruby_version = RUBY_VERSION
     end
     
+    ##
     # Execute the provided command using the open4.popen4
     # library. This is generally only used by Cygwin and
     # *nix variants (including OS X).
@@ -44,27 +58,36 @@ module Sprout #:nodoc:
       end
     end
     
+    ##
     # Execute the provided command using the win32-open3
-    # library. This is generally used even by 64-bit
-    # Windows installations.
+    # library. This is generally used only only Windows
+    # systems (even 64 bit).
     def execute_win32(*command)
       execute_with_block *command do
         @pid, @w, @r, @e = io_popen_block *command.join(' ')
       end
     end
 
+    ##
+    # @return [Boolean] whether the process is still running.
     def alive?
       @alive = update_status
     end
     
+    ##
+    # Kill the process.
     def kill
       Process.kill(9, pid)
     end
     
+    ##
+    # Close the process
     def close
       update_status
     end
     
+    ##
+    # Send an update signal to the process.
     def update_status
       pid_int = Integer("#{ @pid }")
       begin
@@ -75,42 +98,70 @@ module Sprout #:nodoc:
       end
     end
     
-    def readpartial(count)
-      @r.readpartial(count)
+    ##
+    # Read +count+ characters from the process standard out.
+    #
+    # @param count [Integer] Number of characters to read.
+    # @return [String]
+    def readpartial count
+      @r.readpartial count
     end
     
-    def readlines
-      @r.readlines
+    ##
+    # Read +count+ lines from the process standard out.
+    #
+    # @param count [Integer] Number of lines to read.
+    # @return [String]
+    def readlines count
+      @r.readlines count
     end
     
+    ##
+    # Flush the write IO to the process.
     def flush
       @w.flush
     end
     
+    ##
+    # Get user input on the read stream from the process.
     def getc
       @r.getc
     end
     
-    def print(msg)
+    ##
+    # Print some characters to process without an end of line character.
+    def print msg
       @w.print msg
     end
     
+    ##
+    # Print characters to the process followed by an end of line.
     def puts(msg)
       @w.puts(msg)
     end
     
+    ##
+    # Close the write stream - usually terminates the process.
     def close_write
       @w.close_write
     end
     
+    ##
+    # Wait for the process to end and return the entire standard output.
     def read
       return @r.read
     end
     
+    ##
+    # Wait for the process to end and return the entire standard error.
     def read_err
       return @e.read
     end
 
+    def readpartial_err count
+      return @e.readpartial count
+    end
+
     private
 
     def open4_popen4_block *command

data/lib/sprout/progress_bar.rb

@@ -13,7 +13,7 @@
 require 'singleton'
 
 module Sprout
-  class ProgressBar # :nodoc:[all]
+  class ProgressBar
     VERSION = "0.9"
     @@debug = false
     @@outio = $stderr
@@ -41,7 +41,7 @@ module Sprout
 
   end
 
-  class ProgressBarImpl # :nodoc:[all]
+  class ProgressBarImpl
     
     def initialize (title, total, out = STDERR)
       @title = title
@@ -265,13 +265,13 @@ module Sprout
     end
   end
 
-  class ReversedProgressBar < ProgressBar  # :nodoc:[all]
+  class ReversedProgressBar < ProgressBar
     def do_percentage
       100 - super
     end
   end
 
-  class ProgressBarOutputStream  # :nodoc:[all]
+  class ProgressBarOutputStream
     attr_reader :title
     
     def initialize(mgr)
@@ -293,7 +293,7 @@ module Sprout
     
   end
 
-  class ProgressBarManager # :nodoc:[all]
+  class ProgressBarManager
     include Singleton
     
     def initialize

data/lib/sprout/remote_file_target.rb

@@ -44,7 +44,7 @@ module Sprout
     protected
 
     def logger
-      Sprout::Log
+      Sprout.stdout
     end
 
     def expand_local_path path

data/lib/sprout/system/base_system.rb

@@ -68,13 +68,13 @@ module Sprout::System
     # Raises a +Sprout::Errors::ExecutionError+ if the process writes to stderr
     #
     def execute(tool, options='')
-      Sprout::Log.puts("#{tool} #{options}")
+      Sprout.stdout.puts("#{tool} #{options}")
       runner = get_and_execute_process_runner(tool, options)
       error  = runner.read_err
       result = runner.read
 
       if(result.size > 0)
-        Sprout::Log.puts result
+        Sprout.stdout.puts result
       end
 
       if(error.size > 0)
@@ -216,7 +216,7 @@ module Sprout::System
 
   end
 
-  class ThreadMock # :nodoc:
+  class ThreadMock
     def alive?
       return false
     end

data/lib/sprout/system/unix_system.rb

@@ -50,7 +50,7 @@ module Sprout::System
     def repair_executable path
       content = File.read(path)
       if(content.match(/\r\n/))
-        Sprout::Log.puts "[WARNING] Sprouts is about to replace invalid Windows line endings on an executable at: (#{path})"
+        Sprout.stdout.puts "[WARNING] Sprouts is about to replace invalid Windows line endings on an executable at: (#{path})"
         content.gsub!(/\r\n/, "\n")
         File.open(path, 'w+') do |f|
           f.write content

data/lib/sprout/{test/sprout_test_case.rb → test_helper.rb}

@@ -1,24 +1,74 @@
 
-# Had to make this a module instead of a base class
-# because the ruby test suite kept complaining that 
-# the abstract test case didn't have any test mehods
-# or assertions
-module SproutTestCase # :nodoc:[all]
+##
+# A collection of custom assertions and helper methods
+# to take some of the suck out of testing functionality
+# that is based on Sprout features.
+#
+# Include this module into your test cases to make
+# testing Sprout tools easier.
+#
+#   require 'sprout/test/sprout_test_helper'
+#
+#   class SomeTestCase < Test::Unit::TestCase
+#     include Sprout::TestHelper
+#
+#     def setup
+#       super
+#       # do something
+#     end
+#
+#     def teardown
+#       super
+#       # do something
+#     end
+#
+#     def test_something
+#       assert_file File.join(fixtures, 'some_file') do |f|
+#         assert_matches /Fred/, f
+#       end
+#     end
+#   end
+#
+module Sprout::TestHelper
+
+  ##
+  # The name of the folder that should contain
+  # fixture data.
   FIXTURES_NAME = 'fixtures'
 
   # Gives us the ability to hide RubyGem output from
   # our test results...
   include Gem::DefaultUserInteraction
 
+  ##
+  # Add the skip method that was introduced in Ruby 1.9.1 Test::Unit
+  # This doesn't really work all that well...
+  if(RUBY_VERSION == '1.8.7')
+    def skip message=""
+      puts
+      puts ">> SproutTestCase.skip called from: #{caller[0]} ( #{message} )"
+    end
+  end
+
+  ##
+  # @return [Dir] Path to a fixtures folder that is next to
+  # the text case that calls this method.
   def fixtures from=nil
     @fixtures ||= find_fixtures(from || Sprout.file_from_caller(caller.first))
   end
 
+  ##
+  # Override the setup method in order to record the 
+  # working directory before the test method runs.
   def setup
     super
     @start_path = Dir.pwd
   end
 
+  ##
+  # Override the teardown method in order to perform
+  # systemic cleanup work like, clearing lingering rake tasks,
+  # and removing temporary folders.
   def teardown
     super
     clear_tasks
@@ -35,56 +85,123 @@ module SproutTestCase # :nodoc:[all]
     end
   end
 
+  protected
+
+  ##
+  # Create a temporary folder relative to the
+  # test case that calls this method.
+  # 
+  # @return [Dir] Path to the requested temp folder.
   def temp_path
     caller_file = Sprout.file_from_caller caller.first
     @temp_path ||= make_temp_folder File.dirname(caller_file)
   end
 
+  ##
+  # Create a temporary folder relative to the
+  # provided path.
+  #
+  # @param from [Dir] Folder within which a 'tmp' folder should be added.
+  #
+  # @return [Dir] Path to the requested temp folder.
   def make_temp_folder from
     dir = File.join(fixtures(from), 'tmp')
     FileUtils.mkdir_p dir
     dir
   end
 
+  ##
+  # Invoke a Rake task by name.
+  #
+  # @return [Rake::Task] The task that was invoked.
   def run_task(name)
     t = Rake.application[name]
     t.invoke
     return t
   end
   
+  ##
+  # Retrieve a registered Rake task by name.
+  #
+  # @return [Rake::Task] The task that was found.
   def get_task(name)
     return Rake.application[name]
   end
 
+  ##
+  # Clear all registered Rake tasks.
   def clear_tasks
     CLEAN.delete_if {|a| true }
     Rake::Task.clear
     Rake.application.clear
   end
 
+  ##
+  # Create an empty file at +path+
+  #
+  # @param [File] The path to the file that should be created.
+  # @return [File] The path to the file.
   def create_file path
     dir = File.dirname path
     FileUtils.mkdir_p dir
     FileUtils.touch path
   end
 
+  ##
+  # Remove a file if it exists. If no file exists,
+  # do nothing.
+  #
+  # @param path [File] Path to the file that should be removed.
   def remove_file(path=nil)
     if(path && File.exists?(path))
       FileUtils.rm_rf(path)
     end
   end
 
+  ##
+  # Assert that a file exists at +path+ and display +message+ 
+  # if it does not.
+  #
+  # @param path [File] Path to the file that should exist.
+  # @param message [String] The message that should be displayed if the expected file does not exist.
+  # @yield [String] The contents of the file.
+  #
+  # This method yields the file contents so that you can write 
+  # readable tests like:
+  #
+  #   assert_file File.join(fixtures, 'my_file') do |f|
+  #     assert_matches /Johnny/, f
+  #   end
+  #
   def assert_file(path, message=nil)
     message ||= "Expected file not found at #{path}"
     assert(File.exists?(path), message)
     yield File.read(path) if block_given?
   end
 
+  ##
+  # Assert that a directory exists at +path+ and display +message+
+  # if it does not.
+  #
+  # @param path [Dir] Path to the directory that should exist.
+  # @param message [String] The message that should be displayed if the expected directory does not exist.
+  #
+  #    assert_directory File.join(fixtures, 'SomeDir')
+  #
   def assert_directory(path, message=nil)
     message ||= "Expected directory not found at #{path}"
     assert(File.directory?(path), message)
   end
 
+  ##
+  # Assert that a file exists at +path+ and is not empty. Display
+  # +message+ if the file does not exist or if it is empty.
+  # @param path [File] Path to the file that should exist.
+  # @param message [String] The message that should be displayed if 
+  #   the expected file does not exist or is empty.
+  #
+  #   assert_not_empty File.join(fixtures, 'SomeFile')
+  #
   def assert_not_empty(path, message=nil)
     assert_file path, message
     files = FileList["#{path}/*"]
@@ -92,6 +209,14 @@ module SproutTestCase # :nodoc:[all]
     assert files.size > 0, message
   end
   
+  ##
+  # Assert that an expression matches the provided string.
+  #
+  # This helper mainly makes tests more readable and provides
+  # simpler failure messages without extra work.
+  #
+  #   assert_matches /Fred/, 'Bill, Fred, Bob'
+  #
   def assert_matches(expression, string, message='')
     if(expression.is_a?(String))
       expresion = /#{expression}/
@@ -102,20 +227,52 @@ module SproutTestCase # :nodoc:[all]
   end
 
   ##
-  # Add the skip method that was introduced in Ruby 1.9.1 Test::Unit
-  # This doesn't really work all that well...
-  if(RUBY_VERSION == '1.8.7')
-    def skip message=""
-      puts
-      puts ">> SproutTestCase.skip called from: #{caller[0]} ( #{message} )"
-    end
+  # Update the Sprout::Executable registry so that subsequent
+  # requests for an executable return a fake one instead of
+  # the real one.
+  #
+  # @param exe [Symbol] The executable that will be sent to the load request (e.g. :fdb, :mxmlc, etc.).
+  # @param fake_name [String] The path to the fake executable that should be used.
+  #
+  # Note: Calling this method will set a mocha expectation
+  # that the Sprout::Executable.load method will be called during
+  # the test method run.
+  #
+  def insert_fake_executable fake
+    # Comment the following and install the flashsdk gem
+    # to run test against actual executables instead of fakes:
+    path_response = OpenStruct.new(:path => fake)
+    Sprout::Executable.expects(:load).returns path_response
   end
 
+  ##
+  # Create and/or return sprout/cache directory relative to the
+  # fixtures folder nearest the file that calls this method.
+  # @return [Dir] The path to the cache directory.
   def temp_cache
     dir = File.dirname(Sprout.file_from_caller(caller.first))
     @temp_cache ||= File.join(fixtures(dir), 'sprout', 'cache')
   end
 
+  ##
+  # Execute a block as each available Sprout::System, any code
+  # within this block that calls Sprout.current_user will
+  # receive the currently active Sprout::System.
+  #
+  #    as_each_system do
+  #      puts ">> Sprout.home: #{Sprout.home}"
+  #    end
+  #
+  # This method is primarily used to ensure that we create 
+  # system-appropriate paths and processes.
+  #
+  # NOTE: This process automatically calls Mocha::Mockery.instance.teardown
+  # after the yield. This means that any mocks that have been created will
+  # no longer be available after the provided block is complete.
+  # 
+  # @return [Sprout::System::BaseSystem] The concrete class that was created.
+  # @yield [Sprout::System::BaseSystem] The concrete subclass of BaseSystem
+  #
   def as_each_system
     [
      Sprout::System::VistaSystem.new,
@@ -131,9 +288,19 @@ module SproutTestCase # :nodoc:[all]
       # Doing it anyway b/c we need to get Windows support in place...
       # TODO: Implement this feature without clobbering all stubs/mocks
       Mocha::Mockery.instance.teardown
+      sys
     end
   end
 
+  ##
+  # Execute a block as a UnixSystem.
+  #
+  #   as_a_unix_system do
+  #      puts ">> Sprout.home: #{Sprout.home}"
+  #   end
+  #
+  # @return [Sprout::System::UnixSystem] The Sprout::System that was created.
+  # @yield [Sprout::System::UnixSystem] The current Sprout::System.
   def as_a_unix_system
     sys = Sprout::System::UnixSystem.new
     expectation = Sprout::System.stubs(:create).returns sys
@@ -142,8 +309,18 @@ module SproutTestCase # :nodoc:[all]
     # Doing it anyway b/c we need to get Windows support in place...
     # TODO: Implement this feature without clobbering all stubs/mocks
     #Mocha::Mockery.instance.teardown
+    sys
   end
 
+  ##
+  # Execute a block as a OSXSystem.
+  #
+  #   as_a_mac_system do
+  #      puts ">> Sprout.home: #{Sprout.home}"
+  #   end
+  #
+  # @return [Sprout::System::OSXSystem] The Sprout::System that was created.
+  # @yield [Sprout::System::OSXSystem] The current Sprout::System.
   def as_a_mac_system
     sys = Sprout::System::OSXSystem.new
     Sprout::System.stubs(:create).returns sys
@@ -152,8 +329,18 @@ module SproutTestCase # :nodoc:[all]
     # Doing it anyway b/c we need to get Windows support in place...
     # TODO: Implement this feature without clobbering all stubs/mocks
     #Mocha::Mockery.instance.teardown
+    sys
   end
   
+  ##
+  # Execute a block as a WinSystem.
+  #
+  #   as_a_windows_system do
+  #      puts ">> Sprout.home: #{Sprout.home}"
+  #   end
+  #
+  # @return [Sprout::System::WinSystem] The Sprout::System that was created.
+  # @yield [Sprout::System::WinSystem] The current Sprout::System.
   def as_a_windows_system
     sys = Sprout::System::WinSystem.new
     Sprout::System.stubs(:create).returns sys
@@ -162,8 +349,18 @@ module SproutTestCase # :nodoc:[all]
     # Doing it anyway b/c we need to get Windows support in place...
     # TODO: Implement this feature without clobbering all stubs/mocks
     #Mocha::Mockery.instance.teardown
+    sys
   end
 
+  ##
+  # Execute a block as a WinNixSystem.
+  #
+  #   as_a_win_nix_system do
+  #      puts ">> Sprout.home: #{Sprout.home}"
+  #   end
+  #
+  # @return [Sprout::System::WinNixSystem] The Sprout::System that was created.
+  # @yield [Sprout::System::WinNixSystem] The current Sprout::System.
   def as_a_win_nix_system
     sys = Sprout::System::WinNixSystem.new
     Sprout::System.stubs(:create).returns sys
@@ -172,11 +369,13 @@ module SproutTestCase # :nodoc:[all]
     # Doing it anyway b/c we need to get Windows support in place...
     # TODO: Implement this feature without clobbering all stubs/mocks
     #Mocha::Mockery.instance.teardown
+    sys
   end
 
   
   private
 
+  ##
   # Find the nearest fixtures folder to the provided
   # path by checking each parent directory.
   def find_fixtures path
@@ -225,8 +424,9 @@ end
   #   bare_setup - place this in setup method to create the app_root folder for each test
   #   bare_teardown - place this in teardown method to destroy the TMP_ROOT or app_root folder after each test
 
-
 # Prevent log messages from interrupting the test output:
-Sprout::Log.debug = true
+Sprout.stdout = Sprout.stdout_test
+Sprout.stderr = Sprout.stderr_test
+
 #Sprout::ProgressBar.debug = true
 

data/lib/sprout/version.rb

@@ -1,7 +1,7 @@
 
 module Sprout
   NAME = 'sprout'
-  module VERSION #:nodoc:
+  module VERSION
     STRING      = File.read(File.join(File.dirname(__FILE__), '..', '..', 'VERSION').strip)
     MAJOR       = STRING.split('.')[0]
     MINOR       = STRING.split('.')[1]