openvox 7.37.1

data/lib/puppet/interface/action.rb

@@ -0,0 +1,406 @@
+# coding: utf-8
+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
+  extend  Puppet::Interface::DocGen
+  include Puppet::Interface::FullDocs
+
+  # @api private
+  def initialize(face, name)
+    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'
+
+    # @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 %{class_name}") % { class_name: 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 = if proc.nil?
+              #TRANSLATORS 'set_rendering_method_for' and 'Proc' should not be translated
+              _("The second argument to set_rendering_method_for must be a Proc")
+            else
+              #TRANSLATORS 'set_rendering_method_for' and 'Proc' should not be translated
+              _("The second argument to set_rendering_method_for must be a Proc, not %{class_name}") %
+                  { class_name: proc.class.name }
+            end
+      raise ArgumentError, msg
+    end
+
+    if proc.arity != 1 and proc.arity != (@positional_arg_count + 1)
+      msg = if proc.arity < 0 then
+              #TRANSLATORS 'when_rendering', 'when_invoked' are method names and should not be translated
+              _("The when_rendering method for the %{face} face %{name} action takes either just one argument,"\
+                  " the result of when_invoked, or the result plus the %{arg_count} arguments passed to the"\
+                  " when_invoked block, not a variable number") %
+                  { face: @face.name, name: name, arg_count: @positional_arg_count }
+            else
+              #TRANSLATORS 'when_rendering', 'when_invoked' are method names and should not be translated
+              _("The when_rendering method for the %{face} face %{name} action takes either just one argument,"\
+                  " the result of when_invoked, or the result plus the %{arg_count} arguments passed to the"\
+                  " when_invoked block, not %{string}") %
+                  { face: @face.name, name: name, arg_count: @positional_arg_count, string: proc.arity.to_s }
+            end
+      raise ArgumentError, msg
+    end
+    unless type.is_a? Symbol
+      raise ArgumentError, _("The rendering format must be a symbol, not %{class_name}") % { class_name: type.class.name }
+    end
+    if @when_rendering.has_key? type then
+      raise ArgumentError, _("You can't define a rendering method for %{type} twice") % { type: type }
+    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_reader :render_as
+  def render_as=(value)
+    @render_as = value.to_sym
+  end
+
+  # @api private
+  # @return [void]
+  def deprecate
+    @deprecated = true
+  end
+
+  # @api private
+  # @return [Boolean]
+  def deprecated?
+    @deprecated
+  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_reader :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
+      #TRANSLATORS 'when_invoked' should not be translated
+      raise ArgumentError, _("when_invoked requires at least one argument (options) for action %{name}") % { name: @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
+
+    # It should be possible to rewrite this code to use `define_method`
+    # instead of `class/instance_eval` since Ruby 1.8 is long dead.
+    if @face.is_a?(Class)
+      @face.class_eval do eval wrapper, nil, file, line end # rubocop:disable Security/Eval
+      @face.send(:define_method, internal_name, &block)
+      @when_invoked = @face.instance_method(name)
+    else
+      @face.instance_eval do eval wrapper, nil, file, line end # rubocop:disable Security/Eval
+      @face.meta_def(internal_name, &block)
+      @when_invoked = @face.method(name).unbind
+    end
+  end
+
+  def add_option(option)
+    option.aliases.each do |name|
+      conflict = get_option(name)
+      if conflict
+        raise ArgumentError, _("Option %{option} conflicts with existing option %{conflict}") %
+            { option: option, conflict: conflict }
+      else
+        conflict = @face.get_option(name)
+        if conflict
+          raise ArgumentError, _("Option %{option} conflicts with existing option %{conflict} on %{face}") %
+              { option: option, conflict: conflict, face: @face }
+        end
+      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|
+      unless Puppet.settings.include? refopt
+        #TRANSLATORS 'Puppet.settings' should not be translated
+        raise ArgumentError, _("Global option %{option} does not exist in Puppet.settings") % { option: refopt }
+      end
+      @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|
+      option = get_option(name)
+      if option
+        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?
+      overlap_list = overlap.map {|k, v| "(#{k}, #{v.sort.join(', ')})" }.join(", ")
+      raise ArgumentError, _("Multiple aliases for the same option passed: %{overlap_list}") %
+          { overlap_list: overlap_list }
+    end
+
+    unless unknown.empty?
+      unknown_list = unknown.sort.join(", ")
+      raise ArgumentError, _("Unknown options passed: %{unknown_list}") % { unknown_list: unknown_list }
+    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?
+      missing_list = missing.sort.join(', ')
+      raise ArgumentError, _("The following options are required: %{missing_list}") % { missing_list: missing_list }
+    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

data/lib/puppet/interface/action_builder.rb

@@ -0,0 +1,161 @@
+# This class is used to build {Puppet::Interface::Action actions}.
+# When an action is defined with
+# {Puppet::Interface::ActionManager#action} the block is evaluated
+# within the context of a new instance of this class.
+# @api public
+class Puppet::Interface::ActionBuilder
+  extend Forwardable
+
+  # The action under construction
+  # @return [Puppet::Interface::Action]
+  # @api private
+  attr_reader :action
+
+  # Builds a new action.
+  # @return [Puppet::Interface::Action]
+  # @api private
+  def self.build(face, name, &block)
+    raise "Action #{name.inspect} must specify a block" unless block
+    new(face, name, &block).action
+  end
+
+  # Deprecates the action
+  # @return [void]
+  # @api private
+  # @dsl Faces
+  def deprecate
+    @action.deprecate
+  end
+
+  # Ideally the method we're defining here would be added to the action, and a
+  # method on the face would defer to it, but we can't get scope correct, so
+  # we stick with this. --daniel 2011-03-24
+
+  # Sets what the action does when it is invoked. This takes a block
+  # which will be called when the action is invoked. The action will
+  # accept arguments based on the arity of the block. It should always
+  # take at least one argument for options. Options will be the last
+  # argument.
+  #
+  # @overload when_invoked({|options| ... })
+  #   An action with no arguments
+  # @overload when_invoked({|arg1, arg2, options| ... })
+  #   An action with two arguments
+  # @return [void]
+  # @api public
+  # @dsl Faces
+  def when_invoked(&block)
+    @action.when_invoked = block
+  end
+
+  # Sets a block to be run at the rendering stage, for a specific
+  # rendering type (eg JSON, YAML, console), after the block for
+  # when_invoked gets run. This manipulates the value returned by the
+  # action. It makes it possible to work around limitations in the
+  # underlying object returned, and should be avoided in favor of
+  # returning a more capable object.
+  # @api private
+  # @todo this needs more
+  # @dsl Faces
+  def when_rendering(type = nil, &block)
+    if type.nil? then           # the default error message sucks --daniel 2011-04-18
+      #TRANSLATORS 'when_rendering' is a method name and should not be translated
+      raise ArgumentError, _('You must give a rendering format to when_rendering')
+    end
+    if block.nil? then
+      #TRANSLATORS 'when_rendering' is a method name and should not be translated
+      raise ArgumentError, _('You must give a block to when_rendering')
+    end
+    @action.set_rendering_method_for(type, block)
+  end
+
+  # Declare that this action can take a specific option, and provide the
+  # code to do so.  One or more strings are given, in the style of
+  # OptionParser (see example). These strings are parsed to derive a
+  # name for the option. Any `-` characters within the option name (ie
+  # excluding the initial `-` or `--` for an option) will be translated
+  # to `_`.The first long option will be used as the name, and the rest
+  # are retained as aliases. The original form of the option is used
+  # when invoking the face, the translated form is used internally.
+  #
+  # When the action is invoked the value of the option is available in
+  # a hash passed to the {Puppet::Interface::ActionBuilder#when_invoked
+  # when_invoked} block, using the option name in symbol form as the
+  # hash key.
+  #
+  # The block to this method is used to set attributes for the option
+  # (see {Puppet::Interface::OptionBuilder}).
+  #
+  # @param declaration [String] Option declarations, as described above
+  #   and in the example.
+  #
+  # @example Say hi
+  #   action :say_hi do
+  #     option "-u USER", "--user-name USER" do
+  #       summary "Who to say hi to"
+  #     end
+  #
+  #     when_invoked do |options|
+  #       "Hi, #{options[:user_name]}"
+  #     end
+  #   end
+  # @api public
+  # @dsl Faces
+  def option(*declaration, &block)
+    option = Puppet::Interface::OptionBuilder.build(@action, *declaration, &block)
+    @action.add_option(option)
+  end
+
+  # Set this as the default action for the face.
+  # @api public
+  # @dsl Faces
+  # @return [void]
+  def default(value = true)
+    @action.default = !!value
+  end
+
+  # @api private
+  def display_global_options(*args)
+    @action.add_display_global_options args
+  end
+  alias :display_global_option :display_global_options
+
+  # Sets the default rendering format
+  # @api private
+  def render_as(value = nil)
+    if value.nil?
+      #TRANSLATORS 'render_as' is a method name and should not be translated
+      raise ArgumentError, _("You must give a rendering format to render_as")
+    end
+
+    formats = Puppet::Network::FormatHandler.formats
+    unless formats.include? value
+      raise ArgumentError, _("%{value} is not a valid rendering format: %{formats_list}") %
+          { value: value.inspect, formats_list: formats.sort.join(", ")}
+    end
+
+    @action.render_as = value
+  end
+
+  # Metaprogram the simple DSL from the target class.
+  Puppet::Interface::Action.instance_methods.grep(/=$/).each do |setter|
+    next if setter =~ /^=/
+    property = setter.to_s.chomp('=')
+
+    unless method_defined? property
+      # ActionBuilder#<property> delegates to Action#<setter>
+      def_delegator :@action, setter, property
+    end
+  end
+
+  private
+  def initialize(face, name, &block)
+    @face   = face
+    @action = Puppet::Interface::Action.new(face, name)
+    instance_eval(&block)
+    unless @action.when_invoked
+      #TRANSLATORS 'when_invoked' is a method name and should not be translated and 'block' is a Ruby code block
+      raise ArgumentError, _("actions need to know what to do when_invoked; please add the block")
+    end
+  end
+end

data/lib/puppet/interface/action_manager.rb

@@ -0,0 +1,98 @@
+# This class is not actually public API, but the method
+# {Puppet::Interface::ActionManager#action action} is public when used
+# as part of the Faces DSL (i.e. from within a
+# {Puppet::Interface.define define} block).
+# @api public
+module Puppet::Interface::ActionManager
+  # Declare that this app can take a specific action, and provide
+  # the code to do so.
+
+  # Defines a new action. This takes a block to build the action using
+  # the methods on {Puppet::Interface::ActionBuilder}.
+  # @param name [Symbol] The name that will be used to invoke the
+  #   action
+  # @overload action(name, {|| block})
+  # @return [void]
+  # @api public
+  # @dsl Faces
+  def action(name, &block)
+    @actions ||= {}
+    Puppet.debug _("Redefining action %{name} for %{self}") % { name: name, self: self } if action?(name)
+
+    action = Puppet::Interface::ActionBuilder.build(self, name, &block)
+
+    # REVISIT: (#18042) doesn't this mean we can't redefine the default action? -- josh
+    current = get_default_action if action.default
+    if current
+      raise "Actions #{current.name} and #{name} cannot both be default"
+    end
+
+    @actions[action.name] = action
+  end
+
+  # Returns the list of available actions for this face.
+  # @return [Array<Symbol>] The names of the actions for this face
+  # @api private
+  def actions
+    @actions ||= {}
+    result = @actions.keys
+
+    if self.is_a?(Class) and superclass.respond_to?(:actions)
+      result += superclass.actions
+    elsif self.class.respond_to?(:actions)
+      result += self.class.actions
+    end
+    # We need to uniq the result, because we duplicate actions when they are
+    # fetched to ensure that they have the correct bindings; they shadow the
+    # parent, and uniq implements that. --daniel 2011-06-01
+    (result - @deactivated_actions.to_a).uniq.sort
+  end
+
+  # Retrieves a named action
+  # @param name [Symbol] The name of the action
+  # @return [Puppet::Interface::Action] The action object
+  # @api private
+  def get_action(name)
+    @actions ||= {}
+    result = @actions[name.to_sym]
+    if result.nil?
+      if self.is_a?(Class) and superclass.respond_to?(:get_action)
+        found = superclass.get_action(name)
+      elsif self.class.respond_to?(:get_action)
+        found = self.class.get_action(name)
+      end
+
+      if found then
+        # This is not the nicest way to make action equivalent to the Ruby
+        # Method object, rather than UnboundMethod, but it will do for now,
+        # and we only have to make this change in *one* place. --daniel 2011-04-12
+        result = @actions[name.to_sym] = found.__dup_and_rebind_to(self)
+      end
+    end
+    return result
+  end
+
+  # Retrieves the default action for the face
+  # @return [Puppet::Interface::Action]
+  # @api private
+  def get_default_action
+    default = actions.map {|x| get_action(x) }.select {|x| x.default }
+    if default.length > 1
+      raise "The actions #{default.map(&:name).join(", ")} cannot all be default"
+    end
+    default.first
+  end
+
+  # Deactivate a named action
+  # @return [Puppet::Interface::Action]
+  # @api public
+  def deactivate_action(name)
+    @deactivated_actions ||= Set.new
+    @deactivated_actions.add name.to_sym
+  end
+
+  # @api private
+  def action?(name)
+    actions.include?(name.to_sym)
+  end
+end