puppet 3.0.2 → 3.1.0.rc1

data/lib/puppet/util/constant_inflector.rb

@@ -5,6 +5,8 @@
 
 # A common module for converting between constants and
 # file names.
+
+
 module Puppet
   module Util
     module ConstantInflector

data/lib/puppet/util/execution.rb

@@ -6,16 +6,31 @@ module Puppet
   class ExecutionFailure < Puppet::Error
   end
 
+# This module defines methods for execution of system commands. It is intented for inclusion
+# in classes that needs to execute system commands.
+# @api public
 module Util::Execution
 
-  # Execute the provided command with STDIN connected to a pipe, yielding the
-  # pipe object.  That allows data to be fed to that subprocess.
+  # Executes the provided command with STDIN connected to a pipe, yielding the
+  # pipe object.
+  # This allows data to be fed to the subprocess.
   #
   # The command can be a simple string, which is executed as-is, or an Array,
-  # which is treated as a set of command arguments to pass through.#
+  # which is treated as a set of command arguments to pass through.
   #
   # In all cases this is passed directly to the shell, and STDOUT and STDERR
   # are connected together during execution.
+  # @param command [String, Array<String>] the command to execute as one string, or as parts in an array.
+  #   the parts of the array are joined with one separating space between each entry when converting to
+  #   the command line string to execute.
+  # @param failonfail [Boolean] (true) if the execution should fail with Exception on failure or not.
+  # @yield [pipe] to a block executing a subprocess
+  # @yieldparam pipe [IO] the opened pipe
+  # @yieldreturn [String] the output to return
+  # @raise [ExecutionFailure] if the executed chiled process did not exit with status == 0 and `failonfail` is
+  #   `true`.
+  # @return [String] a string with the output from the subprocess executed by the given block
+  #
   def self.execpipe(command, failonfail = true)
     if respond_to? :debug
       debug "Executing '#{command}'"
@@ -44,6 +59,9 @@ module Util::Execution
     output
   end
 
+  # Wraps execution of {execute} with mapping of exception to given exception (and output as argument).
+  # @raise [exception] under same conditions as {execute}, but raises the given `exception` with the output as argument
+  # @return (see execute)
   def self.execfail(command, exception)
     output = execute(command)
     return output
@@ -51,35 +69,37 @@ module Util::Execution
     raise exception, output
   end
 
+  # Default empty options for {execute}
+  NoOptionsSpecified = {}
 
-  # Execute the desired command, and return the status and output.
+  # Executes the desired command, and return the status and output.
   # def execute(command, options)
-  # [command] an Array or String representing the command to execute. If it is
+  # @param command [Array<String>, String] the command to execute. If it is
   #   an Array the first element should be the executable and the rest of the
   #   elements should be the individual arguments to that executable.
-  # [options] a Hash optionally containing any of the following keys:
-  #   :failonfail (see below) -- if this value is set to true, then this method will raise an error if the
-  #      command is not executed successfully.
-  #   :uid (default nil) -- the user id of the user that the process should be run as
-  #   :gid (default nil) -- the group id of the group that the process should be run as
-  #   :combine (see below) -- sets whether or not to combine stdout/stderr in the output
-  #   :stdinfile (default nil) -- sets a file that can be used for stdin. Passing a string for stdin is not currently
-  #      supported.
-  #   :squelch (default false) -- if true, ignore stdout / stderr completely
-  #   :override_locale (default true) -- by default (and if this option is set to true), we will temporarily override
-  #     the user/system locale to "C" (via environment variables LANG and LC_*) while we are executing the command.
-  #     This ensures that the output of the command will be formatted consistently, making it predictable for parsing.
-  #     Passing in a value of false for this option will allow the command to be executed using the user/system locale.
-  #   :custom_environment (default {}) -- a hash of key/value pairs to set as environment variables for the duration
-  #     of the command
+  # @param options [Hash] a Hash of options
+  # @option options [Boolean]  :failonfail if this value is set to true, then this method will raise an error if the
+  #   command is not executed successfully.
+  # @option options [?] :uid (nil) the user id of the user that the process should be run as
+  # @option options [?] :gid (nil) the group id of the group that the process should be run as
+  # @option options [Boolean] :combine sets whether or not to combine stdout/stderr in the output
+  # @option options [String] :stdinfile (nil) sets a file that can be used for stdin. Passing a string for stdin is not currently
+  #   supported.
+  # @option options [Boolean] :squelch (true) if true, ignore stdout / stderr completely.
+  # @option options [Boolean] :override_locale (true) by default (and if this option is set to true), we will temporarily override
+  #   the user/system locale to "C" (via environment variables LANG and LC_*) while we are executing the command.
+  #   This ensures that the output of the command will be formatted consistently, making it predictable for parsing.
+  #   Passing in a value of false for this option will allow the command to be executed using the user/system locale.
+  # @option options [Hash<{String => String}>] :custom_environment ({}) a hash of key/value pairs to set as environment variables for the duration
+  #   of the command.
+  # @return [String] output as specified by options
+  # @note Unfortunately, the default behavior for failonfail and combine (since
+  #   0.22.4 and 0.24.7, respectively) depend on whether options are specified
+  #   or not. If specified, then failonfail and combine default to false (even
+  #   when the options specified are neither failonfail nor combine). If no
+  #   options are specified, then failonfail and combine default to true.
+  # @comment See commits efe9a833c and d32d7f30
   #
-  # Unfortunately, the default behavior for failonfail and combine (since
-  # 0.22.4 and 0.24.7, respectively) depend on whether options are specified
-  # or not. If specified, then failonfail and combine default to false (even
-  # when the options specified are neither failonfail nor combine). If no
-  # options are specified, then failonfail and combine default to true. See
-  # commits efe9a833c and d32d7f30
-  NoOptionsSpecified = {}
   def self.execute(command, options = NoOptionsSpecified)
     # specifying these here rather than in the method signature to allow callers to pass in a partial
     # set of overrides without affecting the default values for options that they don't pass in
@@ -147,9 +167,10 @@ module Util::Execution
     output
   end
 
-  # get the path to the ruby executable (available via Config object, even if
-  # it's not in the PATH... so this is slightly safer than just using
-  # Puppet::Util.which)
+  # Returns the path to the ruby executable (available via Config object, even if
+  # it's not in the PATH... so this is slightly safer than just using Puppet::Util.which)
+  # @return [String] the path to the Ruby executable
+  #
   def self.ruby_path()
     File.join(RbConfig::CONFIG['bindir'],
               RbConfig::CONFIG['ruby_install_name'] + RbConfig::CONFIG['EXEEXT']).
@@ -162,7 +183,10 @@ module Util::Execution
   end
 
 
-  # this is private method, see call to private_class_method after method definition
+  # This is private method.
+  # @comment see call to private_class_method after method definition
+  # @api private
+  #
   def self.execute_posix(command, options, stdin, stdout, stderr)
     child_pid = Puppet::Util.safe_posix_fork(stdin, stdout, stderr) do
 
@@ -208,7 +232,10 @@ module Util::Execution
   private_class_method :execute_posix
 
 
-  # this is private method, see call to private_class_method after method definition
+  # This is private method.
+  # @comment see call to private_class_method after method definition
+  # @api private
+  #
   def self.execute_windows(command, options, stdin, stdout, stderr)
     command = command.map do |part|
       part.include?(' ') ? %Q["#{part.gsub(/"/, '\"')}"] : part
@@ -222,7 +249,10 @@ module Util::Execution
   private_class_method :execute_windows
 
 
-  # this is private method, see call to private_class_method after method definition
+  # This is private method.
+  # @comment see call to private_class_method after method definition
+  # @api private
+  #
   def self.wait_for_output(stdout)
     # Make sure the file's actually been written.  This is basically a race
     # condition, and is probably a horrible way to handle it, but, well, oh

data/lib/puppet/util/filetype.rb

@@ -181,7 +181,7 @@ class Puppet::Util::FileType
 
     # Remove a specific @path's cron tab.
     def remove
-      if %w{Darwin FreeBSD}.include?(Facter.value("operatingsystem"))
+      if %w{Darwin FreeBSD DragonFly}.include?(Facter.value("operatingsystem"))
         %x{/bin/echo yes | #{cmdbase} -r 2>/dev/null}
       else
         %x{#{cmdbase} -r 2>/dev/null}

data/lib/puppet/util/manifest_filetype_helper.rb

@@ -0,0 +1,22 @@
+module Puppet
+  module Util
+
+    ##
+    # Module that gathers helper functions for determining type of manifests.
+    ##
+    module ManifestFiletypeHelper
+      extend self
+
+      def is_ruby_filename?(file)
+        !!(file =~ /\.rb\z/i)
+      end
+
+      def is_puppet_filename?(file)
+        !!(file =~ /\.pp\z/i)
+      end
+
+    end
+  end
+end
+
+

data/lib/puppet/util/methodhelper.rb

@@ -1,5 +1,7 @@
 # Where we store helper methods related to, um, methods.
 module Puppet::Util::MethodHelper
+  extend self
+
   def requiredopts(*names)
     names.each do |name|
       devfail("#{name} is a required option for #{self.class}") if self.send(name).nil?
@@ -29,4 +31,21 @@ module Puppet::Util::MethodHelper
       hash
     end
   end
+
+  ##
+  # Helper to validate options. Example:
+  #
+  #   validate_options [:arguments, :inherits], options
+  #
+  # It expects list of valid options and a hash to validate as a last
+  # argument.
+  ##
+  def validate_options(allow, options = {})
+    options.each do |k, _|
+      unless Array(allow).include? k
+        raise ArgumentError, "unrecognized option #{k}"
+      end
+    end
+  end
+
 end

data/lib/puppet/util/monkey_patches.rb

@@ -310,3 +310,49 @@ if RUBY_VERSION == '1.8.5'
     module_function :move
   end
 end
+
+# Ruby 1.8.6 doesn't have it either
+# From https://github.com/puppetlabs/hiera/pull/47/files:
+# In ruby 1.8.5 Dir does not have mktmpdir defined, so this monkey patches
+# Dir to include the 1.8.7 definition of that method if it isn't already defined.
+# Method definition borrowed from ruby-1.8.7-p357/lib/ruby/1.8/tmpdir.rb
+unless Dir.respond_to?(:mktmpdir)
+  def Dir.mktmpdir(prefix_suffix=nil, tmpdir=nil)
+    case prefix_suffix
+    when nil
+      prefix = "d"
+      suffix = ""
+    when String
+      prefix = prefix_suffix
+      suffix = ""
+    when Array
+      prefix = prefix_suffix[0]
+      suffix = prefix_suffix[1]
+    else
+      raise ArgumentError, "unexpected prefix_suffix: #{prefix_suffix.inspect}"
+    end
+    tmpdir ||= Dir.tmpdir
+    t = Time.now.strftime("%Y%m%d")
+    n = nil
+    begin
+      path = "#{tmpdir}/#{prefix}#{t}-#{$$}-#{rand(0x100000000).to_s(36)}"
+      path << "-#{n}" if n
+      path << suffix
+      Dir.mkdir(path, 0700)
+    rescue Errno::EEXIST
+      n ||= 0
+      n += 1
+      retry
+    end
+
+    if block_given?
+      begin
+        yield path
+      ensure
+        FileUtils.remove_entry_secure path
+      end
+    else
+      path
+    end
+  end
+end

data/lib/puppet/util/plugins.rb

@@ -25,8 +25,8 @@
 # Note that the instance variables are local to this Puppet::Plugin (and so may be used
 #   for maintaining state, etc.) but the plugin system does not provide any thread safety
 #   assurances, so they may not be adequate for some complex use cases.
-#
-#
+
+
 module Puppet
   class Plugins
     Paths  = [] # Where we might find plugin initialization code

data/lib/puppet/util/provider_features.rb

@@ -2,10 +2,15 @@
 require 'puppet/util/methodhelper'
 require 'puppet/util/docs'
 require 'puppet/util'
+# This module models provider features and handles checking whether the features
+# are present.
+# @todo Unclear what is api and what is private in this module.
+#
 module Puppet::Util::ProviderFeatures
   include Puppet::Util::Docs
-  # The class that models the features and handles checking whether the features
+  # This class models provider features and handles checking whether the features
   # are present.
+  # @todo Unclear what is api and what is private in this class
   class ProviderFeature
     include Puppet::Util
     include Puppet::Util::MethodHelper
@@ -13,6 +18,9 @@ module Puppet::Util::ProviderFeatures
     attr_accessor :name, :docs, :methods
 
     # Are all of the requirements met?
+    # Requirements are checked by checking if feature predicate methods have been generated - see {#methods_available?}.
+    # @param obj [Object, Class] the object or class to check if requirements are met
+    # @return [Boolean] whether all requirements for this feature are met or not.
     def available?(obj)
       if self.methods
         return !!methods_available?(obj)
@@ -33,7 +41,9 @@ module Puppet::Util::ProviderFeatures
 
     private
 
-    # Are all of the required methods available?
+    # Checks whether all feature predicate methods are available.
+    # @param obj [Object, Class] the object or class to check if feature predicates are available or not.
+    # @return [Boolean] Returns whether all of the required methods are available or not in the given object.
     def methods_available?(obj)
       methods.each do |m|
         if obj.is_a?(Class)
@@ -46,9 +56,11 @@ module Puppet::Util::ProviderFeatures
     end
   end
 
-  # Define one or more features.  At a minimum, features require a name
+  # Defines one feature.
+  # At a minimum, a feature requires a name
   # and docs, and at this point they should also specify a list of methods
   # required to determine if the feature is present.
+  # @todo How methods that determine if the feature is present are specified.
   def feature(name, docs, hash = {})
     @features ||= {}
     raise(Puppet::DevError, "Feature #{name} is already defined") if @features.include?(name)
@@ -64,7 +76,7 @@ module Puppet::Util::ProviderFeatures
     end
   end
 
-  # Return a hash of all feature documentation.
+  # @return [String] Returns a string with documentation covering all features.
   def featuredocs
     str = ""
     @features ||= {}
@@ -94,14 +106,14 @@ module Puppet::Util::ProviderFeatures
     str
   end
 
-  # Return a list of features.
+  # @return [Array<String>] Returns a list of features.
   def features
     @features ||= {}
     @features.keys
   end
 
-  # Generate a module that sets up the boolean methods to test for given
-  # features.
+  # Generates a module that sets up the boolean predicate methods to test for given features.
+  # 
   def feature_module
     unless defined?(@feature_module)
       @features ||= {}
@@ -158,7 +170,11 @@ module Puppet::Util::ProviderFeatures
     @feature_module
   end
 
-  # Return the actual provider feature instance.  Really only used for testing.
+  # @return [ProviderFeature] Returns a provider feature instance by name.
+  # @param name [String] the name of the feature to return
+  # @note Should only be used for testing.
+  # @api private
+  #
   def provider_feature(name)
     return nil unless defined?(@features)
 

data/lib/puppet/util/rubygems.rb

@@ -2,9 +2,12 @@ require 'puppet/util'
 
 module Puppet::Util::RubyGems
 
-  #Base/factory class for rubygems source
+  # Base/factory class for rubygems source. These classes introspec into
+  # rubygems to in order to list where the rubygems system will look for files
+  # to load.
   class Source
     class << self
+      # @api private
       def has_rubygems?
         # Gems are not actually available when Bundler is loaded, even
         # though the Gem constant is defined. This is because Bundler
@@ -15,6 +18,7 @@ module Puppet::Util::RubyGems
         defined? ::Gem and not defined? ::Bundler
       end
 
+      # @api private
       def source
         if has_rubygems?
           Gem::Specification.respond_to?(:latest_specs) ? Gems18Source : OldGemsSource
@@ -32,6 +36,7 @@ module Puppet::Util::RubyGems
   end
 
   # For RubyGems >= 1.8.0
+  # @api private
   class Gems18Source < Source
     def directories
       Gem::Specification.latest_specs.collect do |spec|
@@ -41,12 +46,14 @@ module Puppet::Util::RubyGems
   end
 
   # RubyGems < 1.8.0
+  # @api private
   class OldGemsSource < Source
     def directories
       @paths ||= Gem.latest_load_paths
     end
   end
 
+  # @api private
   class NoGemsSource < Source
     def directories
       []

data/lib/puppet/util/zaml.rb

@@ -376,7 +376,7 @@ class Time
   def to_zaml(z)
     # 2008-12-06 10:06:51.373758 -07:00
     ms = ("%0.6f" % (usec * 1e-6))[2..-1]
-    offset = "%+0.2i:%0.2i" % [utc_offset / 3600, (utc_offset / 60) % 60]
+    offset = "%+0.2i:%0.2i" % [utc_offset / 3600.0, (utc_offset / 60) % 60]
     z.emit(self.strftime("%Y-%m-%d %H:%M:%S.#{ms} #{offset}"))
   end
 end

data/lib/puppet/version.rb

@@ -4,15 +4,86 @@
 #
 # The version is programatically settable because we want to allow the
 # Raketasks and such to set the version based on the output of `git describe`
-#
+
+
 module Puppet
-  PUPPETVERSION = '3.0.2'
+  PUPPETVERSION = '3.1.0-rc1'
 
+  ##
+  # version is a public API method intended to always provide a fast and
+  # lightweight way to determine the version of Puppet.
+  #
+  # The intent is that software external to Puppet be able to determine the
+  # Puppet version with no side-effects.  The expected use is:
+  #
+  #     require 'puppet/version'
+  #     version = Puppet.version
+  #
+  # This function has the following ordering precedence.  This precedence list
+  # is designed to facilitate automated packaging tasks by simply writing to
+  # the VERSION file in the same directory as this source file.
+  #
+  #  1. If a version has been explicitly assigned using the Puppet.version=
+  #     method, return that version.
+  #  2. If there is a VERSION file, read the contents, trim any
+  #     trailing whitespace, and return that version string.
+  #  3. Return the value of the Puppet::PUPPETVERSION constant hard-coded into
+  #     the source code.
+  #
+  # If there is no VERSION file, the method must return the version string of
+  # the nearest parent version that is an officially released version.  That is
+  # to say, if a branch named 3.1.x contains 25 patches on top of the most
+  # recent official release of 3.1.1, then the version method must return the
+  # string "3.1.1" if no "VERSION" file is present.
+  #
+  # By design the version identifier is _not_ intended to vary during the life
+  # a process.  There is no guarantee provided that writing to the VERSION file
+  # while a Puppet process is running will cause the version string to be
+  # updated.  On the contrary, the contents of the VERSION are cached to reduce
+  # filesystem accesses.
+  #
+  # The VERSION file is intended to be used by package maintainers who may be
+  # applying patches or otherwise changing the software version in a manner
+  # that warrants a different software version identifier.  The VERSION file is
+  # intended to be managed and owned by the release process and packaging
+  # related tasks, and as such should not reside in version control.  The
+  # PUPPETVERSION constant is intended to be version controlled in history.
+  #
+  # Ideally, this behavior will allow package maintainers to precisely specify
+  # the version of the software they're packaging as in the following example:
+  #
+  #     $ git describe --match "3.0.*" > lib/puppet/VERSION
+  #     $ ruby -r puppet -e 'puts Puppet.version'
+  #     3.0.1-260-g9ca4e54
+  #
+  # @api public
+  #
+  # @return [String] containing the puppet version, e.g. "3.0.1"
   def self.version
-    @puppet_version || PUPPETVERSION
+    version_file = File.join(File.dirname(__FILE__), 'VERSION')
+    return @puppet_version if @puppet_version
+    if version = read_version_file(version_file)
+      @puppet_version = version
+    end
+    @puppet_version ||= PUPPETVERSION
   end
 
   def self.version=(version)
     @puppet_version = version
   end
+
+  ##
+  # read_version_file reads the content of the "VERSION" file that lives in the
+  # same directory as this source code file.
+  #
+  # @api private
+  #
+  # @return [String] for example: "1.6.14-6-gea42046" or nil if the VERSION
+  #   file does not exist.
+  def self.read_version_file(path)
+    if File.exists?(path)
+      File.read(path).chomp
+    end
+  end
+  private_class_method :read_version_file
 end