sprout 1.0.32.pre → 1.0.35.pre

data/lib/sprout/base.rb

@@ -15,6 +15,7 @@ require 'sprout/process_runner'
 require 'sprout/system'
 require 'sprout/ruby_feature'
 
+##
 # This is a fix for Issue #106
 # http://code.google.com/p/projectsprouts/issues/detail?id=106
 # Which is created because the new version (1.0.1) of RubyGems
@@ -36,36 +37,64 @@ require 'sprout/remote_file_target'
 require 'sprout/rdoc_parser'
 require 'sprout/specification'
 require 'sprout/executable'
+require 'sprout/daemon'
 
 # Generators
-require 'sprout/generator/command'
-require 'sprout/generator/manifest'
-require 'sprout/generator/file_manifest'
-require 'sprout/generator/template_manifest'
-require 'sprout/generator/directory_manifest'
-require 'sprout/generator/base'
+require 'sprout/generator'
 
 # Libraries
 require 'sprout/library'
 
 module Sprout
+
+  ##
+  # This is the badly-named module that we use to hang our globally-accessible
+  # interface from.
+  #
+  # @see: Sprout::Base::ClassMethods
   module Base
     extend Concern
 
     module ClassMethods
 
+      ##
+      # Returns the system-specific path to the writeable cache directory
+      # where Sprouts will look for downloaded archives.
+      #
+      #   puts ">> Sprout Cache: #{Sprout::Base.cache}"
+      #
       def cache
         File.join(sprout_home, 'cache')
       end
 
+      ##
+      # Returns the location where the currently-running version of Sprouts
+      # will write files and generators and their templates.
+      #
+      #   puts ">> Sprout home: #{Sprout::Base.sprout_home}"
+      #
       def sprout_home
         File.join(current_system.application_home('sprouts'), Sprout::VERSION::MAJOR_MINOR)
       end
 
+      ##
+      # Returns the location where Sprouts will look for generators and their
+      # templates.
+      #
+      #   puts ">> Generator Cache: #{Sprout::Base.generator_cache}"
+      #
       def generator_cache
         File.join cache, 'generators'
       end
 
+      ##
+      # Return the Sprout::System that is currently being used to 
+      # determine features like the cache path and how external processes
+      # are executed.
+      #
+      #   system = Sprout::Base.current_system
+      #   puts ">> System: #{system.inspect}"
+      #
       def current_system
         Sprout::System.create
       end
@@ -74,8 +103,9 @@ module Sprout
       # Get the file name from the 'caller' property of
       # a Ruby exception.
       #
-      # Note: It's a bummer that this string is colon delimited -
-      # The value on Windows can include a colon...
+      # Note: It's a real bummer that this string is colon delimited -
+      # The value on Windows often includes a colon...
+      # Once again, Windows is dissed by fundamental Ruby decisions.
       def file_from_caller caller_string
         parts = caller_string.split(':')
         str   = parts.shift
@@ -89,6 +119,3 @@ module Sprout
   end
 end
 
-# TODO: the included 'files' should get modified by the following expressions:
-      #included_files = FileList["**/*"].exclude /.DS_Store|generated|.svn|.git|airglobal.swc|airframework.swc/
-

data/lib/sprout/concern.rb

@@ -1,9 +1,35 @@
 module Sprout
+
+  ##
+  # This class was copied from Rails source code and provides
+  # our RubyFeature with the ability to more clearly mix in
+  # functionality against a class and behave as if inheritance
+  # works at the class mixin level.
+  #
+  # TODO: I'd like to update our system so that this
+  # functionality is no longer necessary - if you have ideas
+  # or opinions about this code, please let me know!
   module Concern
+
+    ##
+    # Callback handler when a class is extended. This
+    # handler will set the @_dependencies array on the
+    # concrete class that just extended a 
+    # 'Concern'.
+    #
+    # This callback is often triggered with:
+    #
+    #   class Foo
+    #     extend Concern
+    #   end
+    #
     def self.extended(base)
       base.instance_variable_set("@_dependencies", [])
     end
 
+    ##
+    # Apply both class and instance features found in the 
+    # base class to the new subclass.
     def append_features(base)
       if base.instance_variable_defined?("@_dependencies")
         base.instance_variable_get("@_dependencies") << self
@@ -18,6 +44,8 @@ module Sprout
       end
     end
 
+    ##
+    # Handle inclusion of this module.
     def included(base = nil, &block)
       if base.nil?
         @_included_block = block
@@ -28,3 +56,26 @@ module Sprout
   end
 end
 
+=begin
+Copyright (c) 2004-2010 David Heinemeier Hansson
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+=end
+

data/lib/sprout/daemon.rb

@@ -0,0 +1,256 @@
+
+module Sprout
+
+  ##
+  # The Sprout::Daemon module exposes the Domain Specific Language
+  # provided by the Sprout::Executable module, but with
+  # enhancements (and modifications) to support long-lived processes
+  # (like FDB and FCSH).
+  #
+  # NOTE: Any class that includes Sprout::Daemon should first include 
+  # Sprout::Executable. This is an admittedly smelly constraint, but it works
+  # for now.
+  #
+  #   class Foo
+  #     include Sprout::Executable
+  #     include Sprout::Daemon
+  #
+  #     ##
+  #     # Keep in mind that we're still working
+  #     # with Executable, so add_param is available
+  #     # for the initialization of the process.
+  #     add_param :input, File
+  #
+  #     ##
+  #     # Expose the do_something action after
+  #     # the process is started.
+  #     add_action :do_something
+  #
+  #     ##
+  #     # Expose the do_something_else action after
+  #     # the process is started.
+  #     add_action :do_something_else
+  #   end
+  #
+  # You can also create a globally-accessible rake task to expose
+  # your new Daemon instance to Rake by creating a method like the following:
+  #
+  #   def foo *args, &block
+  #     foo_tool = Foo.new
+  #     foo_tool.to_rake *args, &block
+  #   end
+  #
+  # Note: The aforementioned rake helper is usually written at the bottom of 
+  # the class file that is referenced.
+  # 
+  # The aforementioned Rake task could be used like:
+  #
+  #   foo :bar do |t|
+  #     t.do_something
+  #     t.do_something_else
+  #   end
+  #
+  # @see: Sprout::Daemon::ClassMethods
+  # @see: Sprout::Daemon::InstanceMethods
+  #
+  module Daemon
+
+    extend Concern
+
+    ##
+    # These are the methods that will be available
+    # on any class that includes Sprout::Daemon.
+    module ClassMethods
+
+      ##
+      # Add an action that can be called while
+      # the long-lived process is active.
+      #
+      # This method should raise a Sprout::Errors::UsageError
+      # if the provided action name is already defined for 
+      # the provided instance.
+      def add_action name, arguments=nil, options=nil
+        options ||= {}
+        options[:name] = name
+        options[:arguments] = arguments
+        create_action_method options
+      end
+
+      ##
+      # Create an (often shorter) alias to another
+      # action name.
+      def add_action_alias alias_name, source_name
+        define_method(alias_name) do |*params|
+          self.send(source_name, params)
+        end
+      end
+
+      private
+
+      ##
+      # Actually create the method for a provided
+      # action.
+      #
+      # This method should explode if the method name
+      # already exists.
+      def create_action_method options
+        name = options[:name]
+        accessor_can_be_defined_at name
+
+        define_method(name) do |*params|
+          action = name.to_s
+          action = "y" if name == :confirm # Convert affirmation
+          action << " #{params.join(' ')}" unless params.nil?
+          action_stack << action
+        end
+      end
+
+      ##
+      # TODO: Raise an exception if the name is 
+      # already taken?
+      def accessor_can_be_defined_at name
+      end
+
+    end
+
+    ##
+    # Instance methods that will be available on any
+    # class that includes Sprout::Daemon.
+    module InstanceMethods
+
+      ##
+      # The prompt expression for this daemon process.
+      #
+      # When executing a series of commands, the
+      # wrapper will wait until it matches this expression
+      # on stdout before continuing the series.
+      #
+      # For FDB, this value is set like:
+      #
+      #   set :prompt, /^\(fdb\) /
+      #
+      # Most processes can trigger a variety of different
+      # prompts, these can be expressed here using the | (or) operator.
+      #
+      # FDB actually uses the following:
+      #
+      #   set :prompt, /^\(fdb\) |\(y or n\) /
+      #
+      attr_accessor :prompt
+
+      ##
+      # This is the array of actions that have
+      # been provided at the class level to this instance.
+      attr_reader :action_stack
+
+      def initialize
+        super
+        @action_stack = []
+      end
+
+      ##
+      # Execute the Daemon executable, followed
+      # by the collection of stored actions in 
+      # the order they were called.
+      #
+      # If none of the stored actions result in
+      # terminating the process, the underlying
+      # daemon will be connected to the terminal
+      # for user (manual) input.
+      def execute
+        runner = super
+        execute_actions runner
+        handle_user_session runner
+        Process.wait runner.pid
+      end
+
+      protected
+
+      ##
+      # This is the override of the underlying
+      # Sprout::Executable template method so that we
+      # create a 'task' instead of a 'file' task.
+      def create_outer_task *args
+        task *args do
+          execute
+        end
+      end
+
+      ##
+      # This is the override of the underlying
+      # Sprout::Executable template method so that we
+      # are NOT added to the CLEAN collection.
+      # (Work performed in the Executable)
+      def update_rake_task_name_from_args *args
+        self.rake_task_name = parse_rake_task_arg args.last
+      end
+
+      ##
+      # This is the override of the underlying
+      # Sprout::Executable template method so that we
+      # create the process in a thread 
+      # in order to read and write to it.
+      def system_execute binary, params
+        Sprout.current_system.execute_thread binary, params
+      end
+
+      private
+
+      ##
+      # Execute the collection of provided actions.
+      def execute_actions runner
+        action_stack.each do |action|
+          if wait_for_prompt runner
+            Sprout::Log.puts action
+            execute_action runner, action
+          end
+        end
+      end
+
+      ##
+      # Execute a single action.
+      def execute_action runner, action
+        runner.puts action.strip
+      end
+
+      ##
+      # Expose the running process to manual
+      # input on the terminal, and write stdout
+      # back to the user.
+      def handle_user_session runner
+        while !runner.r.eof?
+          if wait_for_prompt runner
+            input = $stdin.gets.chomp!
+            execute_action runner, input
+          end
+        end
+      end
+
+      ##
+      # Wait for the underlying process to present
+      # an input prompt, so that another action
+      # can be submitted, or user input can be
+      # collected.
+      def wait_for_prompt runner, expected_prompt=nil
+        ##
+        # TODO: This should also check for a variety of prompts...
+        expected_prompt = expected_prompt || prompt
+        line = ''
+
+        while runner.alive? do
+          Sprout::Log.flush
+          return false if runner.r.eof?
+          char = runner.readpartial 1
+          line << char
+          if char == "\n"
+            line = ''
+          end
+          Sprout::Log.printf char
+          return true if line.match expected_prompt
+        end
+      end
+
+    end
+  end
+end
+

data/lib/sprout/executable.rb

@@ -27,7 +27,7 @@ module Sprout
   # Following is an example of how one could define an executable Ruby
   # application using this module:
   #
-  #   :include: ../../test/fixtures/examples/echo_inputs.rb
+  # :include: ../../test/fixtures/examples/echo_inputs.rb
   #
   module Executable
     include RubyFeature
@@ -77,7 +77,7 @@ module Sprout
       # in the order they are defined using +add_param+.
       #
       def add_param(name, type, options=nil) # :yields: Sprout::Executable::Param
-        raise Sprout::Errors::UsageError.new("[DEPRECATED] add_param no longer uses closures, you can provide the same values as a hash in the optional last argument.") if block_given?
+        raise Sprout::Errors::UsageError.new "[DEPRECATED] add_param no longer uses closures, you can provide the same values as a hash in the optional last argument." if block_given?
         raise Sprout::Errors::UsageError.new "The first parameter (name:SymbolOrString) is required" if name.nil?
         raise Sprout::Errors::UsageError.new "The second parameter (type:Class) is required" if type.nil?
         raise Sprout::Errors::UsageError.new "The type parameter must be a Class by reference" if !type.is_a?(Class)
@@ -295,8 +295,7 @@ module Sprout
       # This method is generally called from Rake task wrappers.
       #
       def execute_delegate
-        exe = Sprout::Executable.load(executable, pkg_name, pkg_version).path
-        Sprout.current_system.execute exe, to_shell
+        system_execute binary_path, to_shell
       end
 
       def prepare
@@ -308,9 +307,7 @@ module Sprout
       def to_rake *args
         # Define the file task first - so that
         # desc blocks hook up to it...
-        file_task = file *args do
-          execute
-        end
+        outer_task = create_outer_task *args
         update_rake_task_name_from_args *args
         yield self if block_given?
         prepare
@@ -318,15 +315,15 @@ module Sprout
         # TODO: Tried auto-updating with library
         # prerequisites, but this led to strange
         # behavior with multiple registrations.
-        handle_library_prerequisites file_task.prerequisites
+        handle_library_prerequisites outer_task.prerequisites
 
         # Add the library resolution rake task
         # as a prerequisite
-        file_task.prerequisites << task(Sprout::Library::TASK_NAME)
+        outer_task.prerequisites << task(Sprout::Library::TASK_NAME)
         prerequisites.each do |prereq|
-          file_task.prerequisites << prereq
+          outer_task.prerequisites << prereq
         end
-        file_task
+        outer_task
       end
 
       ##
@@ -382,9 +379,33 @@ module Sprout
 
       protected
 
+      ##
+      # Create the outer rake task. 
+      # For most executables, this will be a Rake::File task,
+      # This is a template method that should be overridden
+      # for executables that do not result in the creation of
+      # a file.
+      #
+      # @see update_rake_task_name_from_args
+      def create_outer_task *args
+        file *args do
+          execute
+        end
+      end
+
+      ##
+      # This method will add the current task to the Rake CLEAN
+      # collection.
+      # 
+      # Any Executable that does not create a Rake::File task
+      # should also override this method and prevent it from
+      # calling +CLEAN.add+.
+      #
+      # @see create_outer_task
       def update_rake_task_name_from_args *args
         self.rake_task_name = parse_rake_task_arg args.last
         CLEAN.add(self.rake_task_name)
+        self.rake_task_name
       end
 
       def parse_rake_task_arg arg
@@ -417,8 +438,16 @@ module Sprout
       def library_added path_or_paths
       end
 
+      def system_execute binary, params
+        Sprout.current_system.execute binary, params
+      end
+
       private
 
+      def binary_path
+        Sprout::Executable.load(executable, pkg_name, pkg_version).path
+      end
+
       def handle_library_prerequisites items
         items.each do |task_name|
           t = Rake.application[task_name]