dia 2.0.2 → 2.1.0

data/Changelog

@@ -0,0 +1,17 @@
+2010-08-12  Robert Gleeson <rob@flowof.info> (v2.1.0)
+
+	* Implemented Dia::RubyBlock#value.
+
+	* Dia::RubyBlock#exception_raised? is deprecated.
+	  Dia::RubyBlock#exception_rescued? should be used instead.
+
+	* Dia::Rubyblock#redirect_stdout=, Dia::RubyBlock#redirect_stderr=,
+	  and Dia::RubyBlock#rescue_exception= are now documented as setters.
+
+	* Correct inconsistencies in the documentation for
+	  Dia::RubyBlock#redirect_stdout= , Dia::RubyBlock#redirect_stderr=,
+	  Dia::RubyBlock#exception_rescued? (formerly Dia::RubyBlock#exception_raised?), 
+	  Dia::RubyBlock#rescue_exception?, Dia::RubyBlock#rescue_exception=, 
+	  Dia::RubyBlock#exception.
+
+	* Added Changelog to track changes.

data/dia.gemspec

@@ -15,15 +15,11 @@ Gem::Specification.new do |s|
                      The Ruby API was designed to be simple, and a joy to use. 
                      I hope you feel the same way :-)}
 
-  s.summary     = %q{Through the use of technology found on Apple's Leopard and Snow Leopard 
-                     operating systems, Dia can create dynamic and robust sandbox environments 
-                     for applications and for blocks of ruby code. 
-                     The Ruby API was designed to be simple, and a joy to use. 
-                     I hope you feel the same way :-)}
-
+  s.summary     = s.description
  
   s.require_paths = ["lib"]
-  s.files         = Dir["lib/**/*.rb"] + Dir["test/**/*.rb"] + %w(COPYING README.mkd dia.gemspec)
+  s.files         = Dir["lib/**/*.rb"] + Dir["test/**/*.rb"] + %w(COPYING Changelog README.mkd 
+                                                                  dia.gemspec)
   s.test_files    = Dir["test/**/*.rb"]
   
 

data/lib/dia.rb

@@ -11,5 +11,5 @@ require(File.expand_path('dia/exception_struct' , File.dirname(__FILE__)))
 
 # The Dia module provides a namespace for all classes and modules Dia needs to operate.
 module Dia
-  VERSION = '2.0.2'
+  VERSION = '2.1.0'
 end

data/lib/dia/ruby_block.rb

@@ -11,6 +11,10 @@ module Dia
     attr_reader :stdout
     attr_reader :exception
 
+    attr_writer :redirect_stderr
+    attr_writer :redirect_stdout
+    attr_writer :rescue_exception
+
     alias_method :e, :exception
 
     # @param  [String] Profile Accepts one of five profiles which can be found
@@ -34,9 +38,8 @@ module Dia
     end
 
 
-    # Provides access to the Standard Output stream of the process last used to execute
-    # your sandbox.  
-    # This feature is disabled by default. 
+    # Provides access to the Standard Output stream of the process that was last used to execute 
+    # a sandbox. This feature is disabled by default. 
     #
     # @return [String]        Returns the contents of stdout as a String.  
     #
@@ -59,7 +62,7 @@ module Dia
       @stdout
     end
 
-    # This method can enable or disable a feature that will capture Standard Output
+    # This method can enable or disable a feature that will redirect Standard Output
     # in the process that is spawned to execute a sandbox.
     #
     # @param  [true]   Enable     Passing true will enable the redirection of Standard Output.
@@ -90,9 +93,8 @@ module Dia
       !!@redirect_stdout
     end
 
-    # Provides access to the Standard Error stream of the process last used to execute
-    # a sandbox.  
-    # This feature is disabled by default. 
+    # Provides access to the Standard Error stream of the process that was last used to execute
+    # a sandbox. This feature is disabled by default. 
     #
     # @return [String]       Returns the contents of stderr as a String.
     #
@@ -114,7 +116,7 @@ module Dia
       @stderr
     end
 
-    # This method can enable or disable a feature that will capture Standard Error output
+    # This method can enable or disable a feature that will redirect Standard Error output
     # in the process that is spawned to execute a sandbox.
     #
     # @param  [true]   Enable   Passing true will enable the redirection of Standard Error output.
@@ -145,44 +147,52 @@ module Dia
       !!@redirect_stderr
     end
 
-    # This method will tell you if an exception has been raised in the process
+    # This method will tell you if an exception has been rescued in the process that is
     # spawned to execute a sandbox.   
     # 
-    # @return [true]              Returns true when an exception has been rasied.
+    # @return [true]              Returns true when an exception has been rescued.
     #
-    # @return [false]             Returns false when an exception has not been raised.
+    # @return [false]             Returns false when an exception has not been rescued.
     #
-    # @return [false]             Returns false if Dia was not set to capture exceptions
+    # @return [false]             Returns false if Dia was not set to rescue exceptions
     #                             before a call to {#run} or {#run_nonblock}. 
     #
-    # @see    #rescue_exception=  The capture of exceptions can be enabled or disabled through 
+    # @see    #rescue_exception=  The rescue of exceptions can be enabled or disabled through 
     #                             #rescue_exception=
     #
     # @see    #exception          An exception can be accessed through the #exception 
     #                             method.
+    def exception_rescued?
+      !!exception
+    end
+
+    # @return     [Boolean]
     #
-    #
+    # @deprecated                 This method is deprecated. {Dia::RubyBlock#exception_rescued?} 
+    #                             should be used instead. 
     def exception_raised?
+      $stderr.puts 'WARNING: Dia::RubyBlock#exception_raised? is deprecated and will be ' \
+                   'removed from Dia in a future release.'
       !!exception
     end
 
-    # This method will tell you if an exception raised in the process spawned to 
-    # spawn a sandbox will be captured/rescued.
-    #
-    # @return [true]              Returns true when exceptions are being captured.
+    # This method will tell you if an exception will be rescued in the process that is
+    # spawned to execute a sandbox.
+    #   
+    # @return [true]              Returns true when exceptions are being rescued.
     #
     # @return [false]             Returns false when are exceptions are not being 
-    #                             captured.
+    #                             rescued.
     # @since  2.0.0
     #
-    # @see    #rescue_exception=  The capture of exceptions can be enabled or disabled through 
+    # @see    #rescue_exception=  The rescue of exceptions can be enabled or disabled through 
     #                             #rescue_exception=
     def rescue_exception?
       !!@rescue
     end
 
-    # This method can enable or disable a feature that will capture/rescue 
-    # exceptions that are raised in the process spawned to execute your sandbox.
+    # This method can enable or disable a feature that will try to rescue exceptions 
+    # that are raised in the process that is spawned to execute a sandbox.
     #
     # @param  [true]   Enable     Passing true will enable the capture of exceptions.
     #
@@ -198,22 +208,22 @@ module Dia
     end
 
 
-    # Provides access to the data of an exception object raised in the process last used to 
-    # execute a sandbox.  
-    # This feature is disabled by default.  
-    # 
+    # Provides access to the data of an exception object that has been rescued in the process 
+    # that was last used to execute a sandbox. This feature is disabled by default.  
+    #
     # @return [Dia::ExceptionStruct] Returns an instance of {ExceptionStruct} when an
-    #                                exception has been captured.
+    #                                exception has been rescued.
     # 
     # @return [nil]                  Returns nil when there is no exception available.  
     # 
-    # @return [nil]                  Returns nil if Dia was not set to capture exceptions before a
+    # @return [nil]                  Returns nil if Dia was not set to rescue exceptions before a
     #                                call to {#run} or {#run_nonblock}. 
     #
-    # @see    #rescue_exception=     The capture of exceptions can be enabled or disabled through 
+    # @see    #rescue_exception=     The rescue of exceptions can be enabled or disabled through 
     #                                #rescue_exception=
     #
-    # @see    Dia::ExceptionStruct   Dia::ExceptionStruct.
+    # @see    Dia::ExceptionStruct   Dia::ExceptionStruct
+    # 
     # @since 1.5
     def exception
       if pipes_readable?(@pipes[:exception_reader], @pipes[:exception_writer]) 
@@ -226,6 +236,21 @@ module Dia
       @e
     end
 
+    # Provides access to the return value of the block that has been supplied to the constructor.
+    #
+    # @return [String] Returns the result of #inspect on the return value of the block 
+    #                  that has been executed.
+    #           
+    # @return [nil]    Returns nil if {#run} or {#run_nonblock} has not been called yet.
+    def value
+      if pipes_readable?(@pipes[:return_reader], @pipes[:return_writer])
+        @pipes[:return_writer].close
+        @return = @pipes[:return_reader].read
+        @pipes[:return_reader].close
+      end
+      @return
+    end
+
     # The run method will spawn a child process and execute the block supplied to the constructor
     # in a sandbox.  
     # This method will block. See {#run_nonblock} for the non-blocking form of this method.  
@@ -233,7 +258,7 @@ module Dia
     # **Side Effects:**  
     #
     # * When this method is called, it will reset the instance variables returned by {#exception},
-    #   {#stdout}, and {#stderr} to nil.
+    #   {#stdout}, {#stderr}, and {#value} to nil.
     #
     # @param  [Arguments] Arguments   A variable amount of arguments that will be passed onto the
     #                                 the block supplied to the constructor.
@@ -268,7 +293,7 @@ module Dia
     private
       # @api private
       def launch(*args)
-        @e = @stdout = @stderr =  nil
+        @e = @stdout = @stderr = @return = nil
         close_pipes_if_needed
         open_pipes_if_needed
 
@@ -278,7 +303,7 @@ module Dia
           if @rescue
             begin
               initialize_sandbox
-              @proc.call(*args)
+              write_return_value(@proc.call(*args))
             rescue SystemExit, SignalException, NoMemoryError => e 
               raise(e)
             rescue Exception => e
@@ -296,7 +321,7 @@ module Dia
           else
             begin
               initialize_sandbox
-              @proc.call(*args)
+              write_return_value(@proc.call(*args))
             ensure
               write_stdout_and_stderr_if_needed
               close_pipes_if_needed
@@ -305,6 +330,12 @@ module Dia
         end
       end
 
+      def write_return_value(result)
+        @pipes[:return_reader].close
+        @pipes[:return_writer].write(result.inspect)
+        @pipes[:return_writer].close
+      end
+
       # @api private
       def write_stdout_and_stderr_if_needed
         if @redirect_stdout
@@ -333,6 +364,7 @@ module Dia
 
       # @api private
       def open_pipes_if_needed
+        @pipes[:return_reader]   , @pipes[:return_writer]    = IO.pipe
         @pipes[:exception_reader], @pipes[:exception_writer] = IO.pipe if @rescue
         @pipes[:stdout_reader]   , @pipes[:stdout_writer]    = IO.pipe if @redirect_stdout
         @pipes[:stderr_reader]   , @pipes[:stderr_writer]    = IO.pipe if @redirect_stderr
@@ -341,8 +373,8 @@ module Dia
       # @api private
       def write_exception(e)
         @pipes[:exception_writer].write(Marshal.dump({ :klass     => e.class.to_s    ,
-                                    :backtrace => e.backtrace.join("\n"),
-                                    :message   => e.message.to_s }) )
+                                                       :backtrace => e.backtrace.join("\n"),
+                                                       :message   => e.message.to_s }) )
       end
 
       # @api private

data/test/suite/lib/dia/RubyBlock#exception_raised?.rb

@@ -1,17 +1,17 @@
 suite('RubyBlock') do
-  suite('#exception_raised?') do
+  suite('#exception_rescued?') do
     suite('Return values') do
    
-      exercise('When an exception has been raised.') do
+      exercise('When an exception has been rescued.') do
         dia = Dia::RubyBlock.new(Dia::Profiles::NO_INTERNET) do
           raise(StandardError, "raised") 
         end
         dia.rescue_exception = true
         dia.run
-        @result = dia.exception_raised?
+        @result = dia.exception_rescued?
       end
 
-      verify('#exception_raised? returns true.') do
+      verify('#exception_rescued? returns true.') do
         @result == true
       end
 
@@ -19,10 +19,10 @@ suite('RubyBlock') do
         dia = Dia::RubyBlock.new(Dia::Profiles::NO_INTERNET) { }
         dia.rescue_exception = true
         dia.run
-        @result = dia.exception_raised?
+        @result = dia.exception_rescued?
       end
 
-      verify('#exception_raised? returns false.') do
+      verify('#exception_rescued? returns false.') do
         @result == false
       end
 
@@ -33,10 +33,10 @@ suite('RubyBlock') do
         dia.rescue_exception = false # default, but lets be explicit.
         dia.redirect_stderr = true   # I don't want the tests to be flooded with a backtrace.
         dia.run
-        @result = dia.exception_raised?
+        @result = dia.exception_rescued?
       end
 
-      verify('#exception_raised? returns false') do
+      verify('#exception_rescued? returns false') do
         @result == false
       end
 

data/test/suite/lib/dia/RubyBlock#value.rb

@@ -0,0 +1,30 @@
+suite('RubyBlock') do
+  suite('#value') do
+    suite('Return values') do
+
+      exercise('When #value has finished executing.') do
+        dia = Dia::RubyBlock.new(Dia::Profiles::NO_INTERNET) do
+          1
+        end
+        dia.run
+        @result = dia.value
+      end
+
+      verify('#value returns the return value of the executed block.') do
+        @result == "1"
+      end
+
+      exercise('When #run or #run_nonblock has not been called.') do
+        dia = Dia::RubyBlock.new(Dia::Profiles::NO_INTERNET) do
+          1
+        end
+        @result = dia.value
+      end
+
+      verify('#value returns nil.') do
+        @result == nil
+      end
+
+    end
+  end
+end

metadata

@@ -4,9 +4,9 @@ version: !ruby/object:Gem::Version
   prerelease: false
   segments: 
   - 2
+  - 1
   - 0
-  - 2
-  version: 2.0.2
+  version: 2.1.0
 platform: ruby
 authors: 
 - Robert Gleeson
@@ -14,7 +14,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-07-31 00:00:00 +01:00
+date: 2010-08-12 00:00:00 +01:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -80,18 +80,20 @@ files:
 - test/suite/lib/dia/RubyBlock#run_nonblock.rb
 - test/suite/lib/dia/RubyBlock#stderr.rb
 - test/suite/lib/dia/RubyBlock#stdout.rb
+- test/suite/lib/dia/RubyBlock#value.rb
 - test/suite/lib/dia/SharedFeatures#exit_status.rb
 - test/suite/lib/dia/SharedFeatures#pid.rb
 - test/suite/lib/dia/SharedFeatures#running?.rb
 - test/suite/lib/dia/SharedFeatures#terminate.rb
 - COPYING
+- Changelog
 - README.mkd
 - dia.gemspec
 has_rdoc: yard
 homepage: 
 licenses: []
 
-post_install_message: "  -------------------------------------------------------------------------------- \n  Thanks for installing Dia, 2.0.2! \n  The >=2.0.0 releases are not backward compatiable with the 1.0 series.\n  \n  Resources: \n  * API Documentation    http://yardoc.org/docs/robgleeson-Dia/\n  * Github               http://github.com/robgleeson/dia    \n  * Mailing List         http://groups.google.com/group/ruby-dia\n\n  Release notes are available at the mailing list.\n\n  Happy Hacking!\n  --------------------------------------------------------------------------------  \n"
+post_install_message: "  -------------------------------------------------------------------------------- \n  Thanks for installing Dia, 2.1.0! \n  The >=2.0.0 releases are not backward compatiable with the 1.0 series.\n  \n  Resources: \n  * API Documentation    http://yardoc.org/docs/robgleeson-Dia/\n  * Github               http://github.com/robgleeson/dia    \n  * Mailing List         http://groups.google.com/group/ruby-dia\n\n  Release notes are available at the mailing list.\n\n  Happy Hacking!\n  --------------------------------------------------------------------------------  \n"
 rdoc_options: []
 
 require_paths: 
@@ -133,6 +135,7 @@ test_files:
 - test/suite/lib/dia/RubyBlock#run_nonblock.rb
 - test/suite/lib/dia/RubyBlock#stderr.rb
 - test/suite/lib/dia/RubyBlock#stdout.rb
+- test/suite/lib/dia/RubyBlock#value.rb
 - test/suite/lib/dia/SharedFeatures#exit_status.rb
 - test/suite/lib/dia/SharedFeatures#pid.rb
 - test/suite/lib/dia/SharedFeatures#running?.rb