puppet-retrospec 0.7.0 → 0.7.2

data/vendor/gems/puppet-3.7.3/lib/puppet/interface.rb

@@ -0,0 +1,235 @@
+require 'puppet'
+require 'puppet/util/autoload'
+require 'prettyprint'
+require 'semver'
+
+# @api public
+class Puppet::Interface
+  require 'puppet/interface/documentation'
+  require 'puppet/interface/face_collection'
+
+  require 'puppet/interface/action'
+  require 'puppet/interface/action_builder'
+  require 'puppet/interface/action_manager'
+
+  require 'puppet/interface/option'
+  require 'puppet/interface/option_builder'
+  require 'puppet/interface/option_manager'
+
+
+  include FullDocs
+
+  include Puppet::Interface::ActionManager
+  extend Puppet::Interface::ActionManager
+
+  include Puppet::Interface::OptionManager
+  extend Puppet::Interface::OptionManager
+
+  include Puppet::Util
+
+  class << self
+    # This is just so we can search for actions.  We only use its
+    # list of directories to search.
+
+    # @api private
+    # @deprecated
+    def autoloader
+      Puppet.deprecation_warning("Puppet::Interface.autoloader is deprecated; please use Puppet::Interface#loader instead")
+      @autoloader ||= Puppet::Util::Autoload.new(:application, "puppet/face")
+    end
+
+    # Lists all loaded faces
+    # @return [Array<Symbol>] The names of the loaded faces
+    def faces
+      Puppet::Interface::FaceCollection.faces
+    end
+
+    # Register a face
+    # @param instance [Puppet::Interface] The face
+    # @return [void]
+    # @api private
+    def register(instance)
+      Puppet::Interface::FaceCollection.register(instance)
+    end
+
+    # Defines a new Face.
+    # @todo Talk about using Faces DSL inside the block
+    #
+    # @param name [Symbol] the name of the face
+    # @param version [String] the version of the face (this should
+    #   conform to {http://semver.org/ Semantic Versioning})
+    # @overload define(name, version, {|| ... })
+    # @return [Puppet::Interface] The created face
+    # @api public
+    # @dsl Faces
+    def define(name, version, &block)
+      face = Puppet::Interface::FaceCollection[name, version]
+      if face.nil? then
+        face = self.new(name, version)
+        Puppet::Interface::FaceCollection.register(face)
+        # REVISIT: Shouldn't this be delayed until *after* we evaluate the
+        # current block, not done before? --daniel 2011-04-07
+        face.load_actions
+      end
+
+      face.instance_eval(&block) if block_given?
+
+      return face
+    end
+
+    # Retrieves a face by name and version. Use `:current` for the
+    # version to get the most recent available version.
+    #
+    # @param name [Symbol] the name of the face
+    # @param version [String, :current] the version of the face
+    #
+    # @return [Puppet::Interface] the face
+    #
+    # @api public
+    def face?(name, version)
+      Puppet::Interface::FaceCollection[name, version]
+    end
+
+    # Retrieves a face by name and version
+    #
+    # @param name [Symbol] the name of the face
+    # @param version [String] the version of the face
+    #
+    # @return [Puppet::Interface] the face
+    #
+    # @api public
+    def [](name, version)
+      unless face = Puppet::Interface::FaceCollection[name, version]
+        # REVISIT (#18042) no sense in rechecking if version == :current -- josh
+        if Puppet::Interface::FaceCollection[name, :current]
+          raise Puppet::Error, "Could not find version #{version} of #{name}"
+        else
+          raise Puppet::Error, "Could not find Puppet Face #{name.to_s}"
+        end
+      end
+
+      face
+    end
+
+    # Retrieves an action for a face
+    # @param name [Symbol] The face
+    # @param action [Symbol] The action name
+    # @param version [String, :current] The version of the face
+    # @return [Puppet::Interface::Action] The action
+    def find_action(name, action, version = :current)
+      Puppet::Interface::FaceCollection.get_action_for_face(name, action, version)
+    end
+  end
+
+  ########################################################################
+  # Documentation.  We currently have to rewrite both getters because we share
+  # the same instance between build-time and the runtime instance.  When that
+  # splits out this should merge into a module that both the action and face
+  # include. --daniel 2011-04-17
+
+
+  # Returns the synopsis for the face. This shows basic usage and global
+  # options.
+  # @return [String] usage synopsis
+  # @api private
+  def synopsis
+    build_synopsis self.name, '<action>'
+  end
+
+
+  ########################################################################
+
+  # The name of the face
+  # @return [Symbol]
+  # @api private
+  attr_reader :name
+
+  # The version of the face
+  # @return [SemVer]
+  attr_reader :version
+
+  # The autoloader instance for the face
+  # @return [Puppet::Util::Autoload]
+  # @api private
+  attr_reader :loader
+  private :loader
+
+  # @api private
+  def initialize(name, version, &block)
+    unless SemVer.valid?(version)
+      raise ArgumentError, "Cannot create face #{name.inspect} with invalid version number '#{version}'!"
+    end
+
+    @name    = Puppet::Interface::FaceCollection.underscorize(name)
+    @version = SemVer.new(version)
+
+    # The few bits of documentation we actually demand.  The default license
+    # is a favour to our end users; if you happen to get that in a core face
+    # report it as a bug, please. --daniel 2011-04-26
+    @authors  = []
+    @license  = 'All Rights Reserved'
+
+    @loader = Puppet::Util::Autoload.new(@name, "puppet/face/#{@name}")
+    instance_eval(&block) if block_given?
+  end
+
+  # Loads all actions defined in other files.
+  #
+  # @return [void]
+  # @api private
+  def load_actions
+    loader.loadall
+  end
+
+  # Returns a string representation with the face's name and version
+  # @return [String]
+  def to_s
+    "Puppet::Face[#{name.inspect}, #{version.inspect}]"
+  end
+
+  ########################################################################
+  # Action decoration, whee!  You are not expected to care about this code,
+  # which exists to support face building and construction.  I marked these
+  # private because the implementation is crude and ugly, and I don't yet know
+  # enough to work out how to make it clean.
+  #
+  # Once we have established that these methods will likely change radically,
+  # to be unrecognizable in the final outcome.  At which point we will throw
+  # all this away, replace it with something nice, and work out if we should
+  # be making this visible to the outside world... --daniel 2011-04-14
+  private
+  # @return [void]
+  # @api private
+  def __invoke_decorations(type, action, passed_args = [], passed_options = {})
+    [:before, :after].member?(type) or fail "unknown decoration type #{type}"
+
+    # Collect the decoration methods matching our pass.
+    methods = action.options.select do |name|
+      passed_options.has_key? name
+    end.map do |name|
+      action.get_option(name).__decoration_name(type)
+    end
+
+    methods.reverse! if type == :after
+
+    # Exceptions here should propagate up; this implements a hook we can use
+    # reasonably for option validation.
+    methods.each do |hook|
+      respond_to? hook and self.__send__(hook, action, passed_args, passed_options)
+    end
+  end
+
+  # @return [void]
+  # @api private
+  def __add_method(name, proc)
+    meta_def(name, &proc)
+    method(name).unbind
+  end
+
+  # @return [void]
+  # @api private
+  def self.__add_method(name, proc)
+    define_method(name, proc)
+    instance_method(name)
+  end
+end

data/vendor/gems/puppet-3.7.3/lib/puppet/interface/action.rb

@@ -0,0 +1,374 @@
+require 'puppet/util/methodhelper'
+require 'prettyprint'
+
+# This represents an action that is attached to a face. Actions should
+# be constructed by calling {Puppet::Interface::ActionManager#action},
+# which is available on {Puppet::Interface}, and then calling methods of
+# {Puppet::Interface::ActionBuilder} in the supplied block.
+# @api private
+class Puppet::Interface::Action
+  include Puppet::Util::MethodHelper
+  extend  Puppet::Interface::DocGen
+  include Puppet::Interface::FullDocs
+
+  # @api private
+  def initialize(face, name, attrs = {})
+    raise "#{name.inspect} is an invalid action name" unless name.to_s =~ /^[a-z]\w*$/
+    @face    = face
+    @name    = name.to_sym
+
+    # The few bits of documentation we actually demand.  The default license
+    # is a favour to our end users; if you happen to get that in a core face
+    # report it as a bug, please. --daniel 2011-04-26
+    @authors = []
+    @license  = 'All Rights Reserved'
+
+    set_options(attrs)
+
+    # @options collects the added options in the order they're declared.
+    # @options_hash collects the options keyed by alias for quick lookups.
+    @options        = []
+    @display_global_options = []
+    @options_hash   = {}
+    @when_rendering = {}
+  end
+
+  # This is not nice, but it is the easiest way to make us behave like the
+  # Ruby Method object rather than UnboundMethod.  Duplication is vaguely
+  # annoying, but at least we are a shallow clone. --daniel 2011-04-12
+
+  # @return [void]
+  # @api private
+  def __dup_and_rebind_to(to)
+    bound_version = self.dup
+    bound_version.instance_variable_set(:@face, to)
+    return bound_version
+  end
+
+  def to_s() "#{@face}##{@name}" end
+
+  # The name of this action
+  # @return [Symbol]
+  attr_reader   :name
+
+  # The face this action is attached to
+  # @return [Puppet::Interface]
+  attr_reader   :face
+
+  # Whether this is the default action for the face
+  # @return [Boolean]
+  # @api private
+  attr_accessor :default
+  def default?
+    !!@default
+  end
+
+  ########################################################################
+  # Documentation...
+  attr_doc :returns
+  attr_doc :arguments
+  def synopsis
+    build_synopsis(@face.name, default? ? nil : name, arguments)
+  end
+
+  ########################################################################
+  # Support for rendering formats and all.
+
+
+  # @api private
+  def when_rendering(type)
+    unless type.is_a? Symbol
+      raise ArgumentError, "The rendering format must be a symbol, not #{type.class.name}"
+    end
+    # Do we have a rendering hook for this name?
+    return @when_rendering[type].bind(@face) if @when_rendering.has_key? type
+
+    # How about by another name?
+    alt = type.to_s.sub(/^to_/, '').to_sym
+    return @when_rendering[alt].bind(@face) if @when_rendering.has_key? alt
+
+    # Guess not, nothing to run.
+    return nil
+  end
+
+  # @api private
+  def set_rendering_method_for(type, proc)
+    unless proc.is_a? Proc
+      msg = "The second argument to set_rendering_method_for must be a Proc"
+      msg += ", not #{proc.class.name}" unless proc.nil?
+      raise ArgumentError, msg
+    end
+
+    if proc.arity != 1 and proc.arity != (@positional_arg_count + 1)
+      msg =  "the when_rendering method for the #{@face.name} face #{name} action "
+      msg += "takes either just one argument, the result of when_invoked, "
+      msg += "or the result plus the #{@positional_arg_count} arguments passed "
+      msg += "to the when_invoked block, not "
+      if proc.arity < 0 then
+        msg += "a variable number"
+      else
+        msg += proc.arity.to_s
+      end
+      raise ArgumentError, msg
+    end
+    unless type.is_a? Symbol
+      raise ArgumentError, "The rendering format must be a symbol, not #{type.class.name}"
+    end
+    if @when_rendering.has_key? type then
+      raise ArgumentError, "You can't define a rendering method for #{type} twice"
+    end
+    # Now, the ugly bit.  We add the method to our interface object, and
+    # retrieve it, to rotate through the dance of getting a suitable method
+    # object out of the whole process. --daniel 2011-04-18
+    @when_rendering[type] =
+      @face.__send__( :__add_method, __render_method_name_for(type), proc)
+  end
+
+  # @return [void]
+  # @api private
+  def __render_method_name_for(type)
+    :"#{name}_when_rendering_#{type}"
+  end
+  private :__render_method_name_for
+
+
+  # @api private
+  # @return [Symbol]
+  attr_accessor :render_as
+  def render_as=(value)
+    @render_as = value.to_sym
+  end
+
+
+  ########################################################################
+  # Initially, this was defined to allow the @action.invoke pattern, which is
+  # a very natural way to invoke behaviour given our introspection
+  # capabilities.   Heck, our initial plan was to have the faces delegate to
+  # the action object for invocation and all.
+  #
+  # It turns out that we have a binding problem to solve: @face was bound to
+  # the parent class, not the subclass instance, and we don't pass the
+  # appropriate context or change the binding enough to make this work.
+  #
+  # We could hack around it, by either mandating that you pass the context in
+  # to invoke, or try to get the binding right, but that has probably got
+  # subtleties that we don't instantly think of – especially around threads.
+  #
+  # So, we are pulling this method for now, and will return it to life when we
+  # have the time to resolve the problem.  For now, you should replace...
+  #
+  #     @action = @face.get_action(name)
+  #     @action.invoke(arg1, arg2, arg3)
+  #
+  # ...with...
+  #
+  #     @action = @face.get_action(name)
+  #     @face.send(@action.name, arg1, arg2, arg3)
+  #
+  # I understand that is somewhat cumbersome, but it functions as desired.
+  # --daniel 2011-03-31
+  #
+  # PS: This code is left present, but commented, to support this chunk of
+  # documentation, for the benefit of the reader.
+  #
+  # def invoke(*args, &block)
+  #   @face.send(name, *args, &block)
+  # end
+
+
+  # We need to build an instance method as a wrapper, using normal code, to be
+  # able to expose argument defaulting between the caller and definer in the
+  # Ruby API.  An extra method is, sadly, required for Ruby 1.8 to work since
+  # it doesn't expose bind on a block.
+  #
+  # Hopefully we can improve this when we finally shuffle off the last of Ruby
+  # 1.8 support, but that looks to be a few "enterprise" release eras away, so
+  # we are pretty stuck with this for now.
+  #
+  # Patches to make this work more nicely with Ruby 1.9 using runtime version
+  # checking and all are welcome, provided that they don't change anything
+  # outside this little ol' bit of code and all.
+  #
+  # Incidentally, we though about vendoring evil-ruby and actually adjusting
+  # the internal C structure implementation details under the hood to make
+  # this stuff work, because it would have been cleaner.  Which gives you an
+  # idea how motivated we were to make this cleaner.  Sorry.
+  # --daniel 2011-03-31
+
+
+  # The arity of the action
+  # @return [Integer]
+  attr_reader   :positional_arg_count
+
+  # The block that is executed when the action is invoked
+  # @return [block]
+  attr_accessor :when_invoked
+  def when_invoked=(block)
+
+    internal_name = "#{@name} implementation, required on Ruby 1.8".to_sym
+
+    arity = @positional_arg_count = block.arity
+    if arity == 0 then
+      # This will never fire on 1.8.7, which treats no arguments as "*args",
+      # but will on 1.9.2, which treats it as "no arguments".  Which bites,
+      # because this just begs for us to wind up in the horrible situation
+      # where a 1.8 vs 1.9 error bites our end users. --daniel 2011-04-19
+      raise ArgumentError, "when_invoked requires at least one argument (options) for action #{@name}"
+    elsif arity > 0 then
+      range = Range.new(1, arity - 1)
+      decl = range.map { |x| "arg#{x}" } << "options = {}"
+      optn = ""
+      args = "[" + (range.map { |x| "arg#{x}" } << "options").join(", ") + "]"
+    else
+      range = Range.new(1, arity.abs - 1)
+      decl = range.map { |x| "arg#{x}" } << "*rest"
+      optn = "rest << {} unless rest.last.is_a?(Hash)"
+      if arity == -1 then
+        args = "rest"
+      else
+        args = "[" + range.map { |x| "arg#{x}" }.join(", ") + "] + rest"
+      end
+    end
+
+    file    = __FILE__ + "+eval[wrapper]"
+    line    = __LINE__ + 2 # <== points to the same line as 'def' in the wrapper.
+    wrapper = <<WRAPPER
+def #{@name}(#{decl.join(", ")})
+  #{optn}
+  args    = #{args}
+  action  = get_action(#{name.inspect})
+  args   << action.validate_and_clean(args.pop)
+  __invoke_decorations(:before, action, args, args.last)
+  rval = self.__send__(#{internal_name.inspect}, *args)
+  __invoke_decorations(:after, action, args, args.last)
+  return rval
+end
+WRAPPER
+
+    if @face.is_a?(Class)
+      @face.class_eval do eval wrapper, nil, file, line end
+      @face.send(:define_method, internal_name, &block)
+      @when_invoked = @face.instance_method(name)
+    else
+      @face.instance_eval do eval wrapper, nil, file, line end
+      @face.meta_def(internal_name, &block)
+      @when_invoked = @face.method(name).unbind
+    end
+  end
+
+  def add_option(option)
+    option.aliases.each do |name|
+      if conflict = get_option(name) then
+        raise ArgumentError, "Option #{option} conflicts with existing option #{conflict}"
+      elsif conflict = @face.get_option(name) then
+        raise ArgumentError, "Option #{option} conflicts with existing option #{conflict} on #{@face}"
+      end
+    end
+
+    @options << option.name
+
+    option.aliases.each do |name|
+      @options_hash[name] = option
+    end
+
+    option
+  end
+
+  def option?(name)
+    @options_hash.include? name.to_sym
+  end
+
+  def options
+    @face.options + @options
+  end
+
+  def add_display_global_options(*args)
+    @display_global_options ||= []
+    [args].flatten.each do |refopt|
+      raise ArgumentError, "Global option #{refopt} does not exist in Puppet.settings" unless Puppet.settings.include? refopt
+      @display_global_options << refopt
+    end
+    @display_global_options.uniq!
+    @display_global_options
+  end
+
+  def display_global_options(*args)
+    args ? add_display_global_options(args) : @display_global_options + @face.display_global_options
+  end
+  alias :display_global_option :display_global_options
+
+  def get_option(name, with_inherited_options = true)
+    option = @options_hash[name.to_sym]
+    if option.nil? and with_inherited_options
+      option = @face.get_option(name)
+    end
+    option
+  end
+
+  def validate_and_clean(original)
+    # The final set of arguments; effectively a hand-rolled shallow copy of
+    # the original, which protects the caller from the surprises they might
+    # get if they passed us a hash and we mutated it...
+    result = {}
+
+    # Check for multiple aliases for the same option, and canonicalize the
+    # name of the argument while we are about it.
+    overlap = Hash.new do |h, k| h[k] = [] end
+    unknown = []
+    original.keys.each do |name|
+      if option = get_option(name) then
+        canonical = option.name
+        if result.has_key? canonical
+          overlap[canonical] << name
+        else
+          result[canonical] = original[name]
+        end
+      elsif Puppet.settings.include? name
+        result[name] = original[name]
+      else
+        unknown << name
+      end
+    end
+
+    unless overlap.empty?
+      msg = overlap.map {|k, v| "(#{k}, #{v.sort.join(', ')})" }.join(", ")
+      raise ArgumentError, "Multiple aliases for the same option passed: #{msg}"
+    end
+
+    unless unknown.empty?
+      msg = unknown.sort.join(", ")
+      raise ArgumentError, "Unknown options passed: #{msg}"
+    end
+
+    # Inject default arguments and check for missing mandating options.
+    missing = []
+    options.map {|x| get_option(x) }.each do |option|
+      name = option.name
+      next if result.has_key? name
+
+      if option.has_default?
+        result[name] = option.default
+      elsif option.required?
+        missing << name
+      end
+    end
+
+    unless missing.empty?
+      msg = missing.sort.join(', ')
+      raise ArgumentError, "The following options are required: #{msg}"
+    end
+
+    # All done.
+    return result
+  end
+
+  ########################################################################
+  # Support code for action decoration; see puppet/interface.rb for the gory
+  # details of why this is hidden away behind private. --daniel 2011-04-15
+  private
+  # @return [void]
+  # @api private
+  def __add_method(name, proc)
+    @face.__send__ :__add_method, name, proc
+  end
+end