lib/cmds/result.rb in cmds-0.2.6 vs lib/cmds/result.rb in cmds-0.2.7

@@ -1,31 +1,46 @@
 require 'nrser/refinements'
 
 class Cmds
-  # a simple data structure returned from calling {Cmds#capture} 
+  # A simple data structure returned from calling {Cmds#capture}
   # on a {Cmds} instance.
   # 
-  # it contains the exit status code, standard output and standard error,
+  # It contains the exit status code, standard output and standard error,
   # as well as the actual string command issued (after all substitutions).
   #
-  # instances also have a few convenience methods.
-  #
-  # @!attribute [r] cmd
-  #   @return [String] the command string that was executed.
-  #
-  # @!attribute [r] status
-  #   @return [Fixnum] the command process' exit status code.
-  #
-  # @!attribute [r] out
-  #   @return [String] the command process' standard output.
-  #
-  # @!attribute [r] err
-  #   @return [String] the command process' standard error.
-  #
+  # Instances also have a few convenience methods.
+  # 
   class Result
-    attr_reader :cmd, :status, :out, :err
     
+    # The command string that was executed.
+    # 
+    # @return [String]
+    #     
+    attr_reader :cmd
+    
+    
+    # The command process' exit status code.
+    # 
+    # @return [Fixnum]
+    #     
+    attr_reader :status
+    
+    
+    # The command process' standard output.
+    # 
+    # @return [String]
+    #     
+    attr_reader :out
+    
+    
+    # The command process' standard error.
+    # 
+    # @return [String]
+    #     
+    attr_reader :err
+    
+    
     # @param cmd [String] {#cmd} attribute.
     # @param status [Fixnum] {#status} attribute.
     # @param out [String] {#out} attribute.
     # @param err [String] {#err} attribute.
     def initialize cmd, status, out, err
@@ -33,28 +48,50 @@
       @status = status
       @out = out
       @err = err
     end
     
-    # @return [Boolean] true if {#status} is `0`.
+    
+    # @return [Boolean]
+    #   `true` if {#status} is `0`.
     def ok?
       @status == 0
     end
     
-    # @return [Boolean] true if {#status} is not `0`.
+    
+    # @return [Boolean]
+    #   `true` if {#status} is not `0`.
     def error?
       ! ok?
     end
     
-    # raises an error if the command failed (exited with a {#status} other 
+    
+    # Raises an error if the command failed (exited with a {#status} other
     # than `0`).
     #
     # @return [Result] it's self (so that it can be chained).
     #
     # @raise [SystemCallError] if the command failed.
     #
     def assert
       Cmds.check_status @cmd, @status, @err
       self
     end # raise_error
+    
+    
+    # Get a {Hash} containing the instance variable values for easy logging,
+    # JSON dumping, etc.
+    # 
+    # @example
+    #   Cmds( "echo %s", "hey" ).to_h
+    #   # => {:cmd=>"echo hey", :status=>0, :out=>"hey\n", :err=>""}
+    # 
+    # @return [Hash<Symbol, V>]
+    # 
+    def to_h
+      instance_variables.map { |name|
+        [name.to_s.sub('@', '').to_sym, instance_variable_get( name )]
+      }.to_h
+    end
+    
   end # Result
 end # Cmds