chef 0.9.8.rc.0 → 0.9.8

data/lib/chef/run_context.rb

@@ -23,8 +23,9 @@ require 'chef/role'
 require 'chef/log'
 require 'chef/mixin/language_include_recipe'
 
-# Value object that loads and tracks the context of a Chef run
 class Chef
+  # == Chef::RunContext
+  # Value object that loads and tracks the context of a Chef run
   class RunContext
 
     # Used to load the node's recipes after expanding its run list

data/lib/chef/run_status.rb

@@ -16,6 +16,11 @@
 # limitations under the License.
 #
 
+# == Chef::RunStatus
+# Tracks various aspects of a Chef run, including the Node and RunContext,
+# start and end time, and any Exception that stops the run. RunStatus objects
+# are passed to any notification or exception handlers at the completion of a
+# Chef run.
 class Chef::RunStatus
 
   attr_reader :run_context
@@ -38,14 +43,18 @@ class Chef::RunStatus
     @node
   end
 
+  # sets +start_time+ to the current time.
   def start_clock
     @start_time = Time.now
   end
 
+  # sets +end_time+ to the current time
   def stop_clock
     @end_time = Time.now
   end
 
+  # The elapsed time between +start_time+ and +end_time+. Returns +nil+ if
+  # either value is not set.
   def elapsed_time
     if @start_time && @end_time
       @end_time - @start_time
@@ -54,26 +63,42 @@ class Chef::RunStatus
     end
   end
 
+  # The list of all resources in the current run context's +resource_collection+
   def all_resources
     @run_context && @run_context.resource_collection.all_resources
   end
 
+  # The list of all resources in the current run context's +resource_collection+
+  # that are marked as updated
   def updated_resources
     @run_context && @run_context.resource_collection.select { |r| r.updated }
   end
 
+  # The backtrace from +exception+, if any
   def backtrace
     @exception && @exception.backtrace
   end
 
+  # Did the Chef run fail?
   def failed?
     !success?
   end
 
+  # Did the chef run succeed? returns +true+ if no exception has been set.
   def success?
     @exception.nil?
   end
 
+  # A Hash representation of the RunStatus, with the following (Symbol) keys:
+  # * :node
+  # * :success
+  # * :start_time
+  # * :end_time
+  # * :elapsed_time
+  # * :all_resources
+  # * :updated_resources
+  # * :exception
+  # * :backtrace
   def to_hash
     # use a flat hash here so we can't errors from intermediate values being nil
     { :node => node,
@@ -87,6 +112,8 @@ class Chef::RunStatus
       :backtrace => backtrace}
   end
 
+  # Returns a string of the format "ExceptionClass: message" or +nil+ if no
+  # +exception+ is set.
   def formatted_exception
     @exception && "#{@exception.class.name}: #{@exception.message}"
   end

data/lib/chef/runner.rb

@@ -1,4 +1,4 @@
-#
+#--
 # Author:: Adam Jacob (<adam@opscode.com>)
 # Author:: Christopher Walters (<cw@opscode.com>)
 # Author:: Tim Hinderliter (<tim@opscode.com>)
@@ -23,8 +23,9 @@ require 'chef/node'
 require 'chef/resource_collection'
 require 'chef/platform'
 
-# This class is responsible for executing the steps in a Chef run.
 class Chef
+  # == Chef::Runner
+  # This class is responsible for executing the steps in a Chef run.
   class Runner
     
     attr_reader :run_context
@@ -72,7 +73,8 @@ class Chef
       end
     end
     
-    # Executes a Chef run.
+    # Iterates over the +resource_collection+ in the +run_context+ calling
+    # +run_action+ for each resource in turn.
     def converge
       delayed_actions = Array.new
       

data/lib/chef/shef.rb

@@ -27,7 +27,9 @@ require "chef/config"
 require "chef/shef/shef_session"
 require "chef/shef/ext"
 
-
+# = Shef
+# Shef is Chef in an IRB session. Shef can interact with a Chef server via the
+# REST API, and run and debug recipes interactively.
 module Shef
   LEADERS = Hash.new("")
   LEADERS[Chef::Recipe] = ":recipe"

data/lib/chef/shef/ext.rb

@@ -1,3 +1,4 @@
+#--
 # Author:: Daniel DeLeo (<dan@kallistec.com>)
 # Copyright:: Copyright (c) 2009 Daniel DeLeo
 # License:: Apache License, Version 2.0

data/lib/chef/shef/model_wrapper.rb

@@ -1,4 +1,4 @@
-#
+#--
 # Author:: Daniel DeLeo (<dan@opscode.com>)
 # Copyright:: Copyright (c) 2010 Opscode, Inc.
 # License:: Apache License, Version 2.0

data/lib/chef/shef/shef_rest.rb

@@ -1,4 +1,4 @@
-#
+#--
 # Author:: Daniel DeLeo (<dan@opscode.com>)
 # Copyright:: Copyright (c) 2010 Opscode, Inc.
 # License:: Apache License, Version 2.0

data/lib/chef/shef/shef_session.rb

@@ -1,3 +1,4 @@
+#--
 # Author:: Daniel DeLeo (<dan@kallistec.com>)
 # Copyright:: Copyright (c) 2009 Daniel DeLeo
 # License:: Apache License, Version 2.0

data/lib/chef/shell_out.rb

@@ -1,4 +1,4 @@
-#
+#--
 # Author:: Daniel DeLeo (<dan@opscode.com>)
 # Copyright:: Copyright (c) 2010 Opscode, Inc.
 # License:: Apache License, Version 2.0
@@ -23,16 +23,17 @@ require 'fcntl'
 require 'chef/exceptions'
 
 class Chef
-  
+
+  # == Chef::ShellOut
   # Provides a simplified interface to shelling out yet still collecting both
   # standard out and standard error and providing full control over environment,
   # working directory, uid, gid, etc.
   # 
   # No means for passing input to the subprocess is provided, nor is there any
   # way to inspect the output of the command as it is being read. If you need 
-  # to do that, you have to use Chef::Mixin::Command.popen4
+  # to do that, you have to use popen4 (in Chef::Mixin::Command)
   #
-  # == Platform Support
+  # === Platform Support
   # Chef::ShellOut uses Kernel.fork() and is therefore unsuitable for Windows
   # or jruby.
   class ShellOut
@@ -58,23 +59,41 @@ class Chef
     # === Options:
     # If the last argument is a Hash, it is removed from the list of args passed
     # to exec and used as an options hash. The following options are available:
-    # * user: the user the commmand should run as. if an integer is given, it is
+    # * +user+: the user the commmand should run as. if an integer is given, it is
     #   used as a uid. A string is treated as a username and resolved to a uid
     #   with Etc.getpwnam
-    # * group: the group the command should run as. works similarly to +user+
-    # * cwd: the directory to chdir to before running the command
-    # * umask: a umask to set before running the command. If given as an Integer,
+    # * +group+: the group the command should run as. works similarly to +user+
+    # * +cwd+: the directory to chdir to before running the command
+    # * +umask+: a umask to set before running the command. If given as an Integer,
     #   be sure to use two leading zeros so it's parsed as Octal. A string will
     #   be treated as an octal integer
-    # * returns:  one or more Integer values to use as valid exit codes for the
+    # * +returns+:  one or more Integer values to use as valid exit codes for the
     #   subprocess. This only has an effect if you call +error!+ after
     #   +run_command+.
-    # * environment: a Hash of environment variables to set before the command
+    # * +environment+: a Hash of environment variables to set before the command
     #   is run. By default, the environment will *always* be set to 'LC_ALL' => 'C'
     #   to prevent issues with multibyte characters in Ruby 1.8. To avoid this,
     #   use :environment => nil for *no* extra environment settings, or
     #   :environment => {'LC_ALL'=>nil, ...} to set other environment settings
     #   without changing the locale.
+    # * +timeout+: a Numeric value for the number of seconds to wait on the
+    #   child process before raising an Exception. This is calculated as the
+    #   total amount of time that ShellOut waited on the child process without
+    #   receiving any output (i.e., IO.select returned nil). Default is 60
+    #   seconds. Note: the stdlib Timeout library is not used.
+    # === Examples:
+    # Invoke find(1) to search for .rb files:
+    #   find = Chef::ShellOut.new("find . -name '*.rb'")
+    #   find.run_command
+    #   # If all went well, the results are on +stdout+
+    #   puts find.stdout
+    #   # find(1) prints diagnostic info to STDERR:
+    #   puts "error messages" + find.stderr
+    #   # Raise an exception if it didn't exit with 0
+    #   find.error!
+    # Run a command as the +www+ user with no extra ENV settings from +/tmp+
+    #   cmd = Chef::ShellOut.new("apachectl", "start", :user => 'www', :env => nil, :cwd => '/tmp')
+    #   cmd.run_command # etc.
     def initialize(*command_args)
       @stdout, @stderr = '', ''
       @environment = DEFAULT_ENVIRONMENT
@@ -106,6 +125,9 @@ class Chef
       @timeout || DEFAULT_READ_TIMEOUT
     end
     
+    # Creates a String showing the output of the command, including a banner
+    # showing the exact command executed. Used by +invalid!+ to show command
+    # results when the command exited with an unexpected status.
     def format_for_exception
       msg = ""
       msg << "---- Begin output of #{command} ----\n"
@@ -126,11 +148,11 @@ class Chef
     # returns   +self+; +stdout+, +stderr+, +status+, and +exitstatus+ will be
     # populated with results of the command
     # === Raises
-    # * Errno::EACCES   when you are not privileged to execute the command
-    # * Errno::ENOENT   when the command is not available on the system (or not
+    # * Errno::EACCES  when you are not privileged to execute the command
+    # * Errno::ENOENT  when the command is not available on the system (or not
     #   in the current $PATH)
-    # * Chef::Exceptions::CommandTimeout when the command does not complete
-    #                                  within +timeout+ seconds (default: 60s)
+    # * Chef::Exceptions::CommandTimeout  when the command does not complete
+    #   within +timeout+ seconds (default: 60s)
     def run_command
       Chef::Log.debug("sh(#{@command})")
       @child_pid = fork_subprocess
@@ -184,6 +206,13 @@ class Chef
       close_all_pipes
     end
     
+    # Checks the +exitstatus+ against the set of +valid_exit_codes+. If 
+    # +exitstatus+ is not in the list of +valid_exit_codes+, calls +invalid!+,
+    # which raises an Exception.
+    # === Returns
+    # nil::: always returns nil when it does not raise
+    # === Raises
+    # Chef::Exceptions::ShellCommandFailed::: via +invalid!+
     def error!
       unless Array(valid_exit_codes).include?(exitstatus)
         invalid!("Expected process to exit 0, but it exited with #{exitstatus}")
@@ -193,9 +222,9 @@ class Chef
     # Raises a Chef::Exceptions::ShellCommandFailed exception, appending the
     # command's stdout, stderr, and exitstatus to the exception message.
     # === Arguments
-    # +msg+     A String to use as the basis of the exception message. The 
-    #           default explanation is very generic, providing a more 
-    #           informative message is highly encouraged.
+    # +msg+:  A String to use as the basis of the exception message. The
+    # default explanation is very generic, providing a more informative message
+    # is highly encouraged.
     # === Raises
     # Chef::Exceptions::ShellCommandFailed  always
     def invalid!(msg=nil)
@@ -280,12 +309,11 @@ class Chef
       child_stdout.close  unless child_stdout.closed?
       child_stderr.close  unless child_stderr.closed?
       child_process_status.close unless child_process_status.closed?
-    #rescue NoMethodError # we blew up before IPC was setup
     end
     
     # replace stdout, and stderr with pipes to the parent, and close the
     # reader side of the error marshaling side channel. Close STDIN so when we
-    # exec, the new program will no it's never getting input ever.
+    # exec, the new program will know it's never getting input ever.
     def configure_subprocess_file_descriptors
       process_status_pipe.first.close
       

data/lib/chef/version.rb

@@ -17,5 +17,5 @@
 
 class Chef
   CHEF_ROOT = File.dirname(File.expand_path(File.dirname(__FILE__)))
-  VERSION = '0.9.8.rc.0'
+  VERSION = '0.9.8'
 end

metadata

@@ -1,15 +1,12 @@
 --- !ruby/object:Gem::Specification 
 name: chef
 version: !ruby/object:Gem::Version 
-  hash: 15424197
-  prerelease: true
+  prerelease: false
   segments: 
   - 0
   - 9
   - 8
-  - rc
-  - 0
-  version: 0.9.8.rc.0
+  version: 0.9.8
 platform: ruby
 authors: 
 - Adam Jacob
@@ -17,7 +14,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-07-30 00:00:00 -07:00
+date: 2010-08-05 00:00:00 -07:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -28,7 +25,6 @@ dependencies:
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
-        hash: 19
         segments: 
         - 1
         - 1
@@ -44,7 +40,6 @@ dependencies:
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
-        hash: 19
         segments: 
         - 1
         - 1
@@ -60,7 +55,6 @@ dependencies:
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
-        hash: 19
         segments: 
         - 1
         - 1
@@ -76,7 +70,6 @@ dependencies:
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
-        hash: 19
         segments: 
         - 1
         - 1
@@ -92,7 +85,6 @@ dependencies:
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
-        hash: 7
         segments: 
         - 0
         - 5
@@ -108,7 +100,6 @@ dependencies:
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
-        hash: 31
         segments: 
         - 1
         - 0
@@ -116,7 +107,6 @@ dependencies:
         version: 1.0.4
     - - <=
       - !ruby/object:Gem::Version 
-        hash: 1
         segments: 
         - 1
         - 5
@@ -132,7 +122,6 @@ dependencies:
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
-        hash: 7
         segments: 
         - 0
         - 6
@@ -148,7 +137,6 @@ dependencies:
     requirements: 
     - - <=
       - !ruby/object:Gem::Version 
-        hash: 3
         segments: 
         - 1
         - 4
@@ -164,7 +152,6 @@ dependencies:
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
-        hash: 3
         segments: 
         - 0
         version: "0"
@@ -178,7 +165,6 @@ dependencies:
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
-        hash: 3
         segments: 
         - 0
         version: "0"
@@ -192,7 +178,6 @@ dependencies:
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
-        hash: 3
         segments: 
         - 0
         version: "0"
@@ -206,7 +191,6 @@ dependencies:
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
-        hash: 3
         segments: 
         - 0
         version: "0"
@@ -220,7 +204,6 @@ dependencies:
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
-        hash: 3
         segments: 
         - 0
         version: "0"
@@ -589,21 +572,17 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
-      hash: 3
       segments: 
       - 0
       version: "0"
 required_rubygems_version: !ruby/object:Gem::Requirement 
   none: false
   requirements: 
-  - - ">"
+  - - ">="
     - !ruby/object:Gem::Version 
-      hash: 25
       segments: 
-      - 1
-      - 3
-      - 1
-      version: 1.3.1
+      - 0
+      version: "0"
 requirements: []
 
 rubyforge_project: