dia 2.0.0 → 2.0.1

data/dia.gemspec

@@ -37,12 +37,14 @@ Gem::Specification.new do |s|
   
   Thanks for installing Dia, #{Dia::VERSION}! 
 
-  >=2.0.0 releases include public API changes that are not backward
-  compatiable with older releases. Be sure to check the docs!
+  The >=2.0.0 releases are not backward compatiable with the 1.5 
+  releases.
+
+  Details of this release can be read at the mailing list:
+  http://groups.google.com/group/ruby-dia/browse_thread/thread/fc255eeee8c59eeb
  
   [Github]             http://github.com/robgleeson/dia
   [API Documentation]  http://yardoc.org/docs/robgleeson-dia/
-  [Mailing List (new)] http://groups.google.com/group/ruby-dia
   --------------------------------------------------------------------  
   MESSAGE
 

data/lib/dia.rb

@@ -9,6 +9,7 @@ require(File.expand_path('dia/application'      , File.dirname(__FILE__)))
 require(File.expand_path('dia/exceptions'       , File.dirname(__FILE__)))
 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.0'
+  VERSION = '2.0.1'
 end

data/lib/dia/application.rb

@@ -1,5 +1,6 @@
 module Dia
 
+  # The Application class provides an interface for executing an application in a sandbox.
   class Application
     include Dia::SharedFeatures
 
@@ -9,20 +10,24 @@ module Dia
     #
     # @param [String] Application Accepts a path to an application.
     #
-    # @raise [ArgumentError]      It may raise an ArgumentError if it isn't possible to use a
-    #                             particular profile with this type of sandbox.
+    # @raise [ArgumentError]      It isn't possible to launch an application with the 
+    #                             {Dia::Profiles::NO_OS_SERVICES} profile, and an ArgumentError will
+    #                             be raised if you try to.
     def initialize(profile, app)
       @profile = profile
       @app     = app
-      raise(ArgumentError, "Dia::Profiles::NO_OS_SERVICES is not applicable to the Application " \
-                           "sandbox.") if Dia::Profiles::NO_OS_SERVICES == @profile
+      raise(ArgumentError, "It is not possible to launch an application with the " \
+                           "Dia::Profiles::NO_OS_SERVICES profile at this time") \
+                            if @profile == Dia::Profiles::NO_OS_SERVICES
     end
 
-    # This method will spawn a child process, initialize a sandbox environment, and call exec()
-    # to start your application.
+    # This method will spawn a child process, and execute an application in a sandbox.
     # 
-    # @return [Fixnum]  Returns the Process ID(PID) of the child process used to execute an 
-    #                   application in a sandbox.
+    # @raise  [Dia::Exceptions::SandboxException] It will raise {Dia::Exceptions::SandboxException}
+    #                                             in a child process if it is not possible to
+    #                                             initialize a sandbox.
+    #
+    # @return [Fixnum]                            Returns the Process ID of the spawned process.
     def run
       @pid = fork do 
         initialize_sandbox
@@ -33,7 +38,8 @@ module Dia
       @pid
     end
 
-    # An identical but non-blocking form of {#run}.
+    # An identical but non-blocking form of {Dia::Application#run}.
+    # @return [Fixnum]
     def run_nonblock
       @pid = fork do
         initialize_sandbox

data/lib/dia/exception_struct.rb

@@ -1,4 +1,11 @@
+
 module Dia
+
+ # The instance methods available on this class represent data extracted from an Exception-derived
+ # object.   
+ # An instance of this class is returned by {Dia::RubyBlock#exception Dia::RubyBlock#exception}.  
+ # This class shouldn't be initialized directly by you.
+ #
  # @attr_reader [String] klass     Returns Exception#class as a String.
  # @attr_reader [String] message   Returns Exception#message as a String.
  # @attr_reader [String] backtrace Returns Exception#backtrace as a String.

data/lib/dia/exceptions.rb

@@ -1,5 +1,10 @@
 module Dia
+
+  # The Exceptions module provides a namespace for exceptions that can be raised by Dia.
   module Exceptions
+
+    # The SandboxException is raised if it is not possible to initialize a sandbox when using
+    # {Dia::Application Dia::Application} or {Dia::RubyBlock Dia::RubyBlock}.
     SandboxException = Class.new(StandardError)
   end
 end

data/lib/dia/functions.rb

@@ -1,4 +1,6 @@
 module Dia
+
+  # The Functions module exposes C functions which are used to initialize a sandbox.
   module Functions
     extend(FFI::Library)
     ffi_lib(%w(system))

data/lib/dia/profiles.rb

@@ -1,16 +1,38 @@
 module Dia
+
+  # The Profiles module provides a list of profiles which can be passed to the constructor of
+  # {Dia::Application Dia::Application} or {Dia::RubyBlock Dia::RubyBlock} to create sandboxes
+  # with different kinds of restrictions. 
   module Profiles
     extend(FFI::Library)
     ffi_lib(%w(system))
-    
+   
+    # The NO_INTERNET profile restricts access to the internet. 
+    # @return [String]
     NO_INTERNET                    = attach_variable(:kSBXProfileNoInternet,
                                                      :string).read_string
+
+    # The NO_NETWORKING profile restricts all kinds of networking.
+    # @return [String]
     NO_NETWORKING                  = attach_variable(:kSBXProfileNoNetwork,
                                                       :string).read_string
+
+    # The NO_FILESYSTEM_WRITE profile restricts any attempt to write 
+    # to the filesystem.
+    # @return [String]
     NO_FILESYSTEM_WRITE            = attach_variable(:kSBXProfileNoWrite, 
                                                      :string).read_string
+
+    # The NO_FILESYSTEM_WRITE_EXCEPT_TMP profile restricts any attempt to 
+    # write to the filesystem, excluding writes to /var/tmp and the directory
+    # specified by _CS_DARWIN_USER_TEMP_DIR. 
+    # @return [String]
     NO_FILESYSTEM_WRITE_EXCEPT_TMP = attach_variable(:kSBXProfileNoWriteExceptTemporary,
                                                      :string).read_string
+
+    # The NO_OS_SERVICES is the most restrictive profile, and denies access to all 
+    # operating system resources(Internet, Networking, FileSystem writes, etc).
+    # @return [String]
     NO_OS_SERVICES                 = attach_variable(:kSBXProfilePureComputation,
                                                      :string).read_string
   end

data/lib/dia/ruby_block.rb

@@ -1,11 +1,17 @@
 module Dia
 
+  # The RubyBlock class provides an interface for executing a block of ruby code in a sandbox.
   class RubyBlock
 
     require('io/wait') 
     require('stringio') 
     include Dia::SharedFeatures
 
+    attr_reader :stderr
+    attr_reader :stdout
+    attr_reader :exception
+
+    alias_method :e, :exception
 
     # @param  [String] Profile Accepts one of five profiles which can be found
     #                          under the {Dia::Profiles} module.
@@ -28,14 +34,21 @@ module Dia
     end
 
 
-    # When the "capture stdout" feature is enabled, this method will return the contents
-    # of the standard output stream for the child process used to execute your sandbox.
+    # Provides access to the Standard Output stream of the process last used to execute
+    # your sandbox.  
+    # This feature is disabled by default. 
+    #
+    # @return [String]        Returns the contents of stdout as a String.  
+    #
+    # @return [nil]           Returns nil when no data is available on stdout.
+    #
+    # @return [nil]           Returns nil if Dia was not set to redirect stdout before a call
+    #                         to {#run} or {#run_nonblock}. 
     #
-    # @return [String, nil]       Returns the contents of stdout.   
-    #                             Returns nil when no data is available on stdout, or when the 
-    #                             "capture stdout" feature is disabled.
+    # @see #redirect_stdout=  Redirection of stdout can be enabled through #redirect_stdout=
     #
-    # @see #redirect_stdout= This feature is disabled by default. See how to enable it.
+    # @see #redirect_stdout?  #redirect_stdout? can tell you if Standard Output is being 
+    #                         redirected.
     #   
     def stdout
       if pipes_readable?(@pipes[:stdout_reader], @pipes[:stdout_writer])
@@ -46,55 +59,52 @@ module Dia
       @stdout
     end
 
-    # This method can enable or disable a feature that will capture standard output
-    # in the child process that is spawned to execute a sandbox.
+    # This method can enable or disable a feature that will capture Standard Output
+    # in the process that is spawned to execute a sandbox.
+    #
+    # @param  [true]   Enable     Passing true will enable the redirection of Standard Output.
+    #
+    # @param  [false]  Disable    Passing false will disable the redirection of Standard Output.
+    #
+    # @return [void]
     #
-    # @param  [Boolean] Boolean Accepts a true(-ish) or false(-ish) value.
-    # @return [Boolean] Returns the calling argument.
-    # @see    #stdout   See #stdout for accessing the contents of stdout.
+    # @see    #stdout             Standard Output can be accessed through #stdout.
+    #
+    # @see    #redirect_stdout?   #redirect_stdout? can tell you if Standard Output is 
+    #                             being redirected.
     def redirect_stdout=(boolean)
       @redirect_stdout = boolean
     end
 
-    # This method will tell you if standatd output is being redirected in the child
-    # process used to execute your sandbox.
+    # This method will tell you if Standard Output is being redirected in the
+    # process spawned to execute a sandbox.
     #
-    # @see    #redirect_stdout=   See how to enable the "redirect stdout" feature.
+    # @return [true]             Returns true when Standard Output is being redirected.
     #
-    # @return [Boolean] Returns true or false.
-    def redirect_stdout?
-      !!@rescue_stdout
-    end
-
-    # This method will tell you if standard error is being redirected in the child process
-    # used to execute your sandbox.
+    # @return [false]            Returns false when Standard Output is not being redirected.
     #
-    # @see    #redirect_stderr= See how to enable the "redirect stderr" feature. 
-    # @return [Boolean] returns true or false.
-    def redirect_stderr?
-      !!@rescue_stderr
-    end
-
-    # This method can enable or disable a feature that will capture standard error output
-    # in the child process that is spawned to execute a sandbox.
+    # @see    #redirect_stdout=  Redirection of stdout can be enabled through #redirect_stdout=.  
     #
-    # @param  [Boolean] Boolean Accepts a true(-ish) or false(-ish) value.
-    # @return [Boolean] Returns the calling argument.
-    # @see    #stdout   See #stderr for accessing the contents of stderr.
-    def redirect_stderr=(boolean)
-      @redirect_stderr = boolean
+    # @see    #stdout            Standard Ouput can be accessed through #stdout.
+    def redirect_stdout?
+      !!@redirect_stdout
     end
 
-
-    # When the "capture stderr" feature is enabled, this method will return the contents
-    # of the standard error stream for the child process used to execute your sandbox.
+    # Provides access to the Standard Error stream of the process last used to execute
+    # a sandbox.  
+    # This feature is disabled by default. 
     #
-    # @return [String, nil]       Returns the contents of stderr.   
-    #                             Returns nil when no data is available on stderr, or when the 
-    #                             "capture stderr" feature is disabled.
+    # @return [String]       Returns the contents of stderr as a String.
     #
-    # @see #redirect_stderr= This feature is disabled by default. See how to enable it.
-    #   
+    # @return [nil]          Returns nil when no data is available on stderr.
+    # 
+    # @return [nil]          Returns nil if Dia was not set to redirect stderr before a call
+    #                        to {#run} or {#run_nonblock}. 
+    #
+    # @see #redirect_stderr= Redirection of stderr can be enabled through #redirect_stderr=
+    # 
+    # @see #redirect_stderr? #redirect_stderr? can tell you if Standard Error output is being
+    #                        redirected.
     def stderr
       if pipes_readable?(@pipes[:stderr_reader], @pipes[:stderr_writer])
         @pipes[:stderr_writer].close
@@ -104,67 +114,106 @@ module Dia
       @stderr
     end
 
-    # This method will tell you if an exception has been raised in the child process
-    # used to execute your sandbox.   
-    # The "capture exception" feature must be enabled for this method to ever
-    # return true. 
+    # This method can enable or disable a feature that will capture 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.
+    #
+    # @param  [false]  Disable  Passing false will disable the redirection of Standard Error output.
+    #
+    # @return [void]
+    #
+    # @see    #stderr           Standard Error output can be accessed through #stderr.
+    #
+    # @see    #redirect_stderr? #redirect_stderr? can tell you if Standard Error output is being
+    #                           redirected.
+    def redirect_stderr=(boolean)
+      @redirect_stderr = boolean
+    end
+
+    # This method will tell you if Standard Error output is being redirected in the process
+    # spawned to execute a sandbox.
     # 
-    # @see    #rescue_exception= See #rescue_exception= for enabling the capture
-    #                            of raised exceptions in your sandbox.
+    # @return [true]            Returns true when Standard Error output is being redirected.
+    #
+    # @return [false]           Returns false when Standard Error output is not being redirected.
+    #
+    # @see    #redirect_stderr= Redirection of stderr can be enabled through #redirect_stderr=.
+    #
+    # @see    #stderr           Standard Error output can be accessed through #stderr.
+    def redirect_stderr?
+      !!@redirect_stderr
+    end
+
+    # This method will tell you if an exception has been raised in the process
+    # spawned to execute a sandbox.   
+    # 
+    # @return [true]              Returns true when an exception has been rasied.
+    #
+    # @return [false]             Returns false when an exception has not been raised.
+    #
+    # @return [false]             Returns false if Dia was not set to capture exceptions
+    #                             before a call to {#run} or {#run_nonblock}. 
+    #
+    # @see    #rescue_exception=  The capture of exceptions can be enabled or disabled through 
+    #                             #rescue_exception=
+    #
+    # @see    #exception          An exception can be accessed through the #exception 
+    #                             method.
     #
-    # @see    #exception         See the #exception method for accessing an 
-    #                            exception raised in your sandbox.
     #
-    # @return [Boolean]          Returns true or false.
     def exception_raised?
       !!exception
     end
 
-    # This method will tell you if the {#rescue_exception=} feature is enabled by
-    # returning a boolean.
+    # This method will tell you if an exception raised in the process spawned to 
+    # spawn a sandbox will be captured/rescued.
     #
-    # @see    #rescue_exception= See #rescue_exception= for enabling the capture
-    #                            of raised exceptions in your sandbox.
+    # @return [true]              Returns true when exceptions are being captured.
     #
-    # @see    #exception         See the #exception method for accessing an 
-    #                            exception raised in your sandbox.
-    #
-    # @return [Boolean] Returns true or false.
+    # @return [false]             Returns false when are exceptions are not being 
+    #                             captured.
     # @since  2.0.0
+    #
+    # @see    #rescue_exception=  The capture 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 try to capture 
-    # raised exceptions in the child process that is spawned to execute a sandbox.
+    # This method can enable or disable a feature that will capture/rescue 
+    # exceptions that are raised in the process spawned to execute your sandbox.
     #
-    # @param  [Boolean] Boolean Accepts a true(-ish) or false(-ish) value. 
+    # @param  [true]   Enable     Passing true will enable the capture of exceptions.
     #
-    # @return [Boolean] Returns the calling argument.
+    # @param  [false]  Disable    Passing false will disable the capture of exceptions.
     #
-    # @see    #exception See #exception for information on how to access 
-    #                    the data of an exception raised in your sandbox.
+    # @return [void]         
     #
+    # @see    #exception          An exception can be accessed through the #exception 
+    #                             method.
     # @since 2.0.0
     def rescue_exception=(boolean)
       @rescue = boolean
     end
 
-    # When the "capture exceptions" feature is enabled and an exception has been raised in
-    # the child process used to execute your sandbox, this method will return a subclass
-    # of Struct whose attributes represent the exception data. 
-    #
-    # Every call {#run} or {#run_nonblock} will reset the instance variable referencing the
-    # object storing exception data to nil.
+
+    # 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.  
     # 
-    # @return [Dia::ExceptionStruct, nil] Returns an instance of {Dia::ExceptionStruct} or nil 
-    #                                     when there is no exception available.  
-    #
-    # @see #rescue_exception=             The "capture exception" feature is disabled by default.  
-    #                                     See how to enable it.
+    # @return [Dia::ExceptionStruct] Returns an instance of {ExceptionStruct} when an
+    #                                exception has been captured.
+    # 
+    # @return [nil]                  Returns nil when there is no exception available.  
+    # 
+    # @return [nil]                  Returns nil if Dia was not set to capture exceptions before a
+    #                                call to {#run} or {#run_nonblock}. 
     #
-    # @see Dia::ExceptionStruct           The documentation for Dia::ExceptionStruct.
+    # @see    #rescue_exception=     The capture of exceptions can be enabled or disabled through 
+    #                                #rescue_exception=
     #
+    # @see    Dia::ExceptionStruct   Dia::ExceptionStruct.
     # @since 1.5
     def exception
       if pipes_readable?(@pipes[:exception_reader], @pipes[:exception_writer]) 
@@ -177,26 +226,28 @@ module Dia
       @e
     end
 
-    # The run method will spawn a child process to execute the block supplied to the constructer 
-    # in a sandbox.   
-    # This method will block. See {#run_nonblock} for the non-blocking form of
-    # this method.
+    # 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.  
+    #
+    # **Side Effects:**  
+    #
+    # * When this method is called, it will reset the instance variables returned by {#exception},
+    #   {#stdout}, and {#stderr} to nil.
     #
-    # @param  [Arguments] Arguments   A variable amount of arguments that will 
-    #                                 be passed onto the block supplied to the 
-    #                                 constructer. Optional.
+    # @param  [Arguments] Arguments   A variable amount of arguments that will be passed onto the
+    #                                 the block supplied to the constructor.
     #
-    # @raise  [SystemCallError]       It may raise a number of subclasses of SystemCallError 
+    # @raise  [SystemCallError]       It will raise a number of subclasses of SystemCallError 
     #                                 in a child process if a sandbox violates imposed 
     #                                 restrictions.   
     #
-    # @raise  [Dia::SandboxException] It may raise 
+    # @raise  [Dia::SandboxException] It will raise 
     #                                 {Dia::Exceptions::SandboxException}
     #                                 in a child process if it was not possible
-    #                                 to initialize a sandbox environment. 
+    #                                 to initialize a sandbox. 
     #
-    # @return [Fixnum]                The Process ID(PID) that the sandbox has
-    #                                 been launched under.
+    # @return [Fixnum]                It returns the Process ID of the spawned process
     def run(*args)
       launch(*args) 
 
@@ -205,7 +256,8 @@ module Dia
       @pid
     end
 
-    # An identical, but non-blocking form of {#run}.
+    # An identical, but non-blocking form of {Dia::RubyBlock#run}.
+    # @return [Fixnum]
     def run_nonblock(*args)  
       launch(*args)
 
@@ -216,7 +268,7 @@ module Dia
     private
       # @api private
       def launch(*args)
-        @e = @stdout = nil
+        @e = @stdout = @stderr =  nil
         close_pipes_if_needed
         open_pipes_if_needed