puppet-retrospec 0.7.0 → 0.7.2

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

@@ -0,0 +1,149 @@
+# 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
+  # 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
+
+  # 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
+      raise ArgumentError, 'You must give a rendering format to when_rendering'
+    end
+    if block.nil? then
+      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 intial `-` 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)
+    value.nil? and raise ArgumentError, "You must give a rendering format to render_as"
+
+    formats = Puppet::Network::FormatHandler.formats
+    unless formats.include? value
+      raise ArgumentError, "#{value.inspect} is not a valid rendering format: #{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
+      # Using eval because the argument handling semantics are less awful than
+      # when we use the define_method/block version.  The later warns on older
+      # Ruby versions if you pass the wrong number of arguments, but carries
+      # on, which is totally not what we want. --daniel 2011-04-18
+      eval <<-METHOD
+        def #{property}(value)
+          @action.#{property} = value
+        end
+      METHOD
+    end
+  end
+
+  private
+  def initialize(face, name, &block)
+    @face   = face
+    @action = Puppet::Interface::Action.new(face, name)
+    instance_eval(&block)
+    @action.when_invoked or raise ArgumentError, "actions need to know what to do when_invoked; please add the block"
+  end
+end

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

@@ -0,0 +1,101 @@
+# 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.warning "Redefining action #{name} for #{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
+    if action.default and current = get_default_action
+      raise "Actions #{current.name} and #{name} cannot both be default"
+    end
+
+    @actions[action.name] = action
+  end
+
+  # Defines an action without using ActionBuilder. The block given is
+  # the code that will be executed when the action is invoked.
+  # @api public
+  # @deprecated
+  def script(name, &block)
+    @actions ||= {}
+    Puppet.warning "Redefining action #{name} for #{self}" if action?(name)
+
+    # REVISIT: (#18048) it's possible to create multiple default actions
+    @actions[name] = Puppet::Interface::Action.new(self, name, :when_invoked => block)
+  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.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
+
+  # @api private
+  def action?(name)
+    actions.include?(name.to_sym)
+  end
+end

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

@@ -0,0 +1,342 @@
+class Puppet::Interface
+  # @api private
+  module DocGen
+    require 'puppet/util/docs'
+
+    # @api private
+    def self.strip_whitespace(text)
+      # I don't want no...
+      Puppet::Util::Docs.scrub(text)
+    end
+
+    # The documentation attributes all have some common behaviours; previously
+    # we open-coded them across the set of six things, but that seemed
+    # wasteful - especially given that they were literally the same, and had
+    # the same bug hidden in them.
+    #
+    # This feels a bit like overkill, but at least the common code is common
+    # now. --daniel 2011-04-29
+
+    # @api private
+    def attr_doc(name, &validate)
+      # Now, which form of the setter do we want, validated or not?
+      get_arg = "value.to_s"
+      if validate
+        define_method(:"_validate_#{name}", validate)
+        get_arg = "_validate_#{name}(#{get_arg})"
+      end
+
+      # We use module_eval, which I don't like much, because we can't have an
+      # argument to a block with a default value in Ruby 1.8, and I don't like
+      # the side-effects (eg: no argument count validation) of using blocks
+      # without as metheds.  When we are 1.9 only (hah!) you can totally
+      # replace this with some up-and-up define_method. --daniel 2011-04-29
+      module_eval(<<-EOT, __FILE__, __LINE__ + 1)
+        def #{name}(value = nil)
+          self.#{name} = value unless value.nil?
+          @#{name}
+        end
+
+        def #{name}=(value)
+          @#{name} = Puppet::Interface::DocGen.strip_whitespace(#{get_arg})
+        end
+      EOT
+    end
+  end
+
+  # This module can be mixed in to provide a minimal set of
+  # documentation attributes.
+  # @api public
+  module TinyDocs
+    extend Puppet::Interface::DocGen
+
+    # @!method summary(summary)
+    # Sets a summary of this object.
+    # @api public
+    # @dsl Faces
+    attr_doc :summary do |value|
+      value =~ /\n/ and
+        raise ArgumentError, "Face summary should be a single line; put the long text in 'description' instead."
+      value
+    end
+
+    # @!method description(description)
+    # Sets the long description of this object.
+    # @param description [String] The description of this object.
+    # @api public
+    # @dsl Faces
+    attr_doc :description
+
+    # @api private
+    def build_synopsis(face, action = nil, arguments = nil)
+      PrettyPrint.format do |s|
+        s.text("puppet #{face}")
+        s.text(" #{action}") unless action.nil?
+        s.text(" ")
+
+        options.each do |option|
+          option = get_option(option)
+          wrap = option.required? ? %w{ < > } : %w{ [ ] }
+
+          s.group(0, *wrap) do
+            option.optparse.each do |item|
+              unless s.current_group.first?
+                s.breakable
+                s.text '|'
+                s.breakable
+              end
+              s.text item
+            end
+          end
+
+          s.breakable
+        end
+
+        display_global_options.sort.each do |option|
+          wrap = %w{ [ ] }
+          s.group(0, *wrap) do
+            type = Puppet.settings.setting(option).default
+            type ||= Puppet.settings.setting(option).type.to_s.upcase
+            s.text "--#{option} #{type}"
+            s.breakable
+          end
+          s.breakable
+        end
+
+        if arguments then
+          s.text arguments.to_s
+        end
+      end
+    end
+
+  end
+
+  # This module can be mixed in to provide a full set of documentation
+  # attributes. It is intended to be used for {Puppet::Interface}.
+  # @api public
+  module FullDocs
+    extend Puppet::Interface::DocGen
+    include TinyDocs
+
+    # @!method examples
+    # @overload examples(text)
+    #   Sets examples.
+    #   @param text [String] Example text
+    #   @api public
+    #   @return [void]
+    #   @dsl Faces
+    # @overload examples
+    #   Returns documentation of examples
+    #   @return [String] The examples
+    #   @api private
+    attr_doc :examples
+
+    # @!method notes(text)
+    # @overload notes(text)
+    #   Sets optional notes.
+    #   @param text [String] The notes
+    #   @api public
+    #   @return [void]
+    #   @dsl Faces
+    # @overload notes
+    #   Returns any optional notes
+    #   @return [String] The notes
+    #   @api private
+    attr_doc :notes
+
+    # @!method license(text)
+    # @overload license(text)
+    #   Sets the license text
+    #   @param text [String] the license text
+    #   @api public
+    #   @return [void]
+    #   @dsl Faces
+    # @overload license
+    #   Returns the license
+    #   @return [String] The license
+    #   @api private
+    attr_doc :license
+
+    attr_doc :short_description
+    # @overload short_description(value)
+    #   Sets a short description for this object.
+    #   @param value [String, nil] A short description (about a paragraph)
+    #     of this component. If `value` is `nil` the short_description
+    #     will be set to the shorter of the first paragraph or the first
+    #     five lines of {description}.
+    #   @return [void]
+    #   @api public
+    #   @dsl Faces
+    # @overload short_description
+    #   Get the short description for this object
+    #   @return [String, nil] The short description of this object. If none is
+    #     set it will be derived from {description}. Returns `nil` if
+    #     {description} is `nil`.
+    #   @api private
+    def short_description(value = nil)
+      self.short_description = value unless value.nil?
+      if @short_description.nil? then
+        return nil if @description.nil?
+        lines = @description.split("\n")
+        first_paragraph_break = lines.index('') || 5
+        grab  = [5, first_paragraph_break].min
+        @short_description = lines[0, grab].join("\n")
+        @short_description += ' [...]' if (grab < lines.length and first_paragraph_break >= 5)
+      end
+      @short_description
+    end
+
+    # @overload author(value)
+    #   Adds an author to the documentation for this object. To set
+    #   multiple authors, call this once for each author.
+    #   @param value [String] the name of the author
+    #   @api public
+    #   @dsl Faces
+    # @overload author
+    #   Returns a list of authors
+    #   @return [String, nil] The names of all authors separated by
+    #     newlines, or `nil` if no authors have been set.
+    #   @api private
+    def author(value = nil)
+      unless value.nil? then
+        unless value.is_a? String
+          raise ArgumentError, 'author must be a string; use multiple statements for multiple authors'
+        end
+
+        if value =~ /\n/ then
+          raise ArgumentError, 'author should be a single line; use multiple statements for multiple authors'
+        end
+        @authors.push(Puppet::Interface::DocGen.strip_whitespace(value))
+      end
+      @authors.empty? ? nil : @authors.join("\n")
+    end
+
+    # Returns a list of authors. See {author}.
+    # @return [String] The list of authors, separated by newlines.
+    # @api private
+    def authors
+      @authors
+    end
+
+    # @api private
+    def author=(value)
+      # I think it's a bug that this ends up being the exposed
+      # version of `author` on ActionBuilder
+      if Array(value).any? {|x| x =~ /\n/ } then
+        raise ArgumentError, 'author should be a single line; use multiple statements'
+      end
+      @authors = Array(value).map{|x| Puppet::Interface::DocGen.strip_whitespace(x) }
+    end
+    alias :authors= :author=
+
+    # Sets the copyright owner and year. This returns the copyright
+    # string, so it can be called with no arguments retrieve that string
+    # without side effects.
+    # @param owner [String, Array<String>] The copyright owner or an
+    #   array of owners
+    # @param years [Integer, Range<Integer>, Array<Integer,Range<Integer>>]
+    #   The copyright year or years. Years can be specified with integers,
+    #   a range of integers, or an array of integers and ranges of
+    #   integers.
+    # @return [String] A string describing the copyright on this object.
+    # @api public
+    # @dsl Faces
+    def copyright(owner = nil, years = nil)
+      if years.nil? and not owner.nil? then
+        raise ArgumentError, 'copyright takes the owners names, then the years covered'
+      end
+      self.copyright_owner = owner unless owner.nil?
+      self.copyright_years = years unless years.nil?
+
+      if self.copyright_years or self.copyright_owner then
+        "Copyright #{self.copyright_years} by #{self.copyright_owner}"
+      else
+        "Unknown copyright owner and years."
+      end
+    end
+
+    # Sets the copyright owner
+    # @param value [String, Array<String>] The copyright owner or
+    #   owners.
+    # @return [String] Comma-separated list of copyright owners
+    # @api private
+    attr_accessor :copyright_owner
+    def copyright_owner=(value)
+      case value
+      when String then @copyright_owner = value
+      when Array  then @copyright_owner = value.join(", ")
+      else
+        raise ArgumentError, "copyright owner must be a string or an array of strings"
+      end
+      @copyright_owner
+    end
+
+    # Sets the copyright year
+    # @param value [Integer, Range<Integer>, Array<Integer, Range>] The
+    #   copyright year or years.
+    # @return [String]
+    # @api private
+    attr_accessor :copyright_years
+    def copyright_years=(value)
+      years = munge_copyright_year value
+      years = (years.is_a?(Array) ? years : [years]).
+        sort_by do |x| x.is_a?(Range) ? x.first : x end
+
+      @copyright_years = years.map do |year|
+        if year.is_a? Range then
+          "#{year.first}-#{year.last}"
+        else
+          year
+        end
+      end.join(", ")
+    end
+
+    # @api private
+    def munge_copyright_year(input)
+      case input
+      when Range then input
+      when Integer then
+        if input < 1970 then
+          fault = "before 1970"
+        elsif input > (future = Time.now.year + 2) then
+          fault = "after #{future}"
+        end
+        if fault then
+          raise ArgumentError, "copyright with a year #{fault} is very strange; did you accidentally add or subtract two years?"
+        end
+
+        input
+
+      when String then
+        input.strip.split(/,/).map do |part|
+          part = part.strip
+          if part =~ /^\d+$/ then
+            part.to_i
+          elsif found = part.split(/-/) then
+            unless found.length == 2 and found.all? {|x| x.strip =~ /^\d+$/ }
+              raise ArgumentError, "#{part.inspect} is not a good copyright year or range"
+            end
+            Range.new(found[0].to_i, found[1].to_i)
+          else
+            raise ArgumentError, "#{part.inspect} is not a good copyright year or range"
+          end
+        end
+
+      when Array then
+        result = []
+        input.each do |item|
+          item = munge_copyright_year item
+          if item.is_a? Array
+            result.concat item
+          else
+            result << item
+          end
+        end
+        result
+
+      else
+        raise ArgumentError, "#{input.inspect} is not a good copyright year, set, or range"
+      end
+    end
+  end
+end