openvox 8.19.0

data/lib/puppet/interface/documentation.rb

@@ -0,0 +1,363 @@
+# frozen_string_literal: true
+
+class Puppet::Interface
+  # @api private
+  module DocGen
+    require_relative '../../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 methods.  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)                 # def attribute(value=nil)
+          self.#{name} = value unless value.nil? #   self.attribute = value unless value.nil?
+          @#{name}                               #   @value
+        end                                      # end
+
+        def #{name}=(value)                                                 # def attribute=(value)
+          @#{name} = Puppet::Interface::DocGen.strip_whitespace(#{get_arg}) #   @value = Puppet::Interface::DocGen.strip_whitespace(#{get_arg})
+        end                                                                 # 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
+        # TRANSLATORS 'Face' refers to a programming API in Puppet, 'summary' and 'description' are specifc attribute names and should not be translated
+        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
+          # TRANSLATORS 'author' is an attribute name and should not be translated
+          raise ArgumentError, _('author must be a string; use multiple statements for multiple authors')
+        end
+
+        if value =~ /\n/ then
+          # TRANSLATORS 'author' is an attribute name and should not be translated
+          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
+        # TRANSLATORS 'author' is an attribute name and should not be translated
+        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 !owner.nil? then
+        # TRANSLATORS 'copyright' is an attribute name and should not be translated
+        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 copyright_years or copyright_owner then
+        "Copyright #{copyright_years} by #{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_reader :copyright_owner
+
+    def copyright_owner=(value)
+      case value
+      when String then @copyright_owner = value
+      when Array  then @copyright_owner = value.join(", ")
+      else
+        # TRANSLATORS 'copyright' is an attribute name and should not be translated
+        raise ArgumentError, _("copyright owner must be a string or an array of strings")
+      end
+    end
+
+    # Sets the copyright year
+    # @param value [Integer, Range<Integer>, Array<Integer, Range>] The
+    #   copyright year or years.
+    # @return [String]
+    # @api private
+    attr_reader :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
+          # TRANSLATORS 'copyright' is an attribute name and should not be translated
+          raise ArgumentError, _("copyright with a year %{value} is very strange; did you accidentally add or subtract two years?") %
+                               { value: fault }
+        end
+
+        input
+
+      when String then
+        input.strip.split(/,/).map do |part|
+          part = part.strip
+          if part =~ /^\d+$/
+            part.to_i
+          else
+            found = part.split(/-/)
+            if found
+              unless found.length == 2 and found.all? { |x| x.strip =~ /^\d+$/ }
+                # TRANSLATORS 'copyright' is an attribute name and should not be translated
+                raise ArgumentError, _("%{value} is not a good copyright year or range") % { value: part.inspect }
+              end
+
+              Range.new(found[0].to_i, found[1].to_i)
+            else
+              # TRANSLATORS 'copyright' is an attribute name and should not be translated
+              raise ArgumentError, _("%{value} is not a good copyright year or range") % { value: part.inspect }
+            end
+          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
+        # TRANSLATORS 'copyright' is an attribute name and should not be translated
+        raise ArgumentError, _("%{value} is not a good copyright year, set, or range") % { value: input.inspect }
+      end
+    end
+  end
+end

data/lib/puppet/interface/face_collection.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+module Puppet::Interface::FaceCollection
+  @faces = Hash.new { |hash, key| hash[key] = {} }
+
+  @loader = Puppet::Util::Autoload.new(:application, 'puppet/face')
+
+  def self.faces
+    unless @loaded
+      @loaded = true
+      names = @loader.files_to_load(Puppet.lookup(:current_environment)).map do |fn|
+        ::File.basename(fn, '.rb')
+      end.uniq
+      names.each { |name| self[name, :current] }
+    end
+    @faces.keys.select { |name| @faces[name].length > 0 }
+  end
+
+  def self.[](name, version)
+    name = underscorize(name)
+    get_face(name, version) or load_face(name, version)
+  end
+
+  def self.get_action_for_face(name, action_name, version)
+    name = underscorize(name)
+
+    # If the version they request specifically doesn't exist, don't search
+    # elsewhere.  Usually this will start from :current and all...
+    face = self[name, version]
+    return nil unless face
+
+    action = face.get_action(action_name)
+    unless action
+      # ...we need to search for it bound to an o{lder,ther} version.  Since
+      # we load all actions when the face is first references, this will be in
+      # memory in the known set of versions of the face.
+      (@faces[name].keys - [:current]).sort.reverse_each do |vers|
+        action = @faces[name][vers].get_action(action_name)
+        break if action
+      end
+    end
+
+    action
+  end
+
+  # get face from memory, without loading.
+  def self.get_face(name, pattern)
+    return nil unless @faces.has_key? name
+    return @faces[name][:current] if pattern == :current
+
+    versions = @faces[name].keys - [:current]
+    range = pattern.is_a?(SemanticPuppet::Version) ? SemanticPuppet::VersionRange.new(pattern, pattern) : SemanticPuppet::VersionRange.parse(pattern)
+    found = find_matching(range, versions)
+    @faces[name][found]
+  end
+
+  def self.find_matching(range, versions)
+    versions.select { |v| range === v }.max
+  end
+
+  # try to load the face, and return it.
+  def self.load_face(name, version)
+    # We always load the current version file; the common case is that we have
+    # the expected version and any compatibility versions in the same file,
+    # the default.  Which means that this is almost always the case.
+    #
+    # We use require to avoid executing the code multiple times, like any
+    # other Ruby library that we might want to use.  --daniel 2011-04-06
+    if safely_require name then
+      # If we wanted :current, we need to index to find that; direct version
+      # requests just work as they go. --daniel 2011-04-06
+      if version == :current then
+        # We need to find current out of this.  This is the largest version
+        # number that doesn't have a dedicated on-disk file present; those
+        # represent "experimental" versions of faces, which we don't fully
+        # support yet.
+        #
+        # We walk the versions from highest to lowest and take the first version
+        # that is not defined in an explicitly versioned file on disk as the
+        # current version.
+        #
+        # This constrains us to only ship experimental versions with *one*
+        # version in the file, not multiple, but given you can't reliably load
+        # them except by side-effect when you ignore that rule this seems safe
+        # enough...
+        #
+        # Given those constraints, and that we are not going to ship a versioned
+        # interface that is not :current in this release, we are going to leave
+        # these thoughts in place, and just punt on the actual versioning.
+        #
+        # When we upgrade the core to support multiple versions we can solve the
+        # problems then; as lazy as possible.
+        #
+        # We do support multiple versions in the same file, though, so we sort
+        # versions here and return the last item in that set.
+        #
+        # --daniel 2011-04-06
+        latest_ver = @faces[name].keys.max
+        @faces[name][:current] = @faces[name][latest_ver]
+      end
+    end
+
+    unless version == :current or get_face(name, version)
+      # Try an obsolete version of the face, if needed, to see if that helps?
+      safely_require name, version
+    end
+
+    get_face(name, version)
+  end
+
+  def self.safely_require(name, version = nil)
+    path = @loader.expand(version ? ::File.join(version.to_s, name.to_s) : name)
+    require path
+    true
+  rescue LoadError => e
+    raise unless e.message =~ /-- #{path}$/
+
+    # ...guess we didn't find the file; return a much better problem.
+    nil
+  rescue SyntaxError => e
+    raise unless e.message =~ /#{path}\.rb:\d+: /
+
+    Puppet.err _("Failed to load face %{name}:\n%{detail}") % { name: name, detail: e }
+    # ...but we just carry on after complaining.
+    nil
+  end
+
+  def self.register(face)
+    @faces[underscorize(face.name)][face.version] = face
+  end
+
+  def self.underscorize(name)
+    unless name.to_s =~ /^[-_a-z][-_a-z0-9]*$/i then
+      # TRANSLATORS 'face' refers to a programming API in Puppet
+      raise ArgumentError, _("%{name} (%{class_name}) is not a valid face name") %
+                           { name: name.inspect, class_name: name.class }
+    end
+
+    name.to_s.downcase.split(/[-_]/).join('_').to_sym
+  end
+end

data/lib/puppet/interface/option.rb

@@ -0,0 +1,184 @@
+# frozen_string_literal: true
+
+# This represents an option on an action or face (to be globally applied
+# to its actions). Options should be constructed by calling
+# {Puppet::Interface::OptionManager#option}, which is available on
+# {Puppet::Interface}, and then calling methods of
+# {Puppet::Interface::OptionBuilder} in the supplied block.
+# @api public
+class Puppet::Interface::Option
+  include Puppet::Interface::TinyDocs
+
+  # @api private
+  def initialize(parent, *declaration, &block)
+    @parent   = parent
+    @optparse = []
+    @default  = nil
+
+    # Collect and sort the arguments in the declaration.
+    dups = {}
+    declaration.each do |item|
+      if item.is_a? String and item.to_s =~ /^-/ then
+        unless item =~ /^-[a-z]\b/ or item =~ /^--[^-]/ then
+          raise ArgumentError, _("%{option}: long options need two dashes (--)") % { option: item.inspect }
+        end
+
+        @optparse << item
+
+        # Duplicate checking...
+        # for our duplicate checking purpose, we don't make a check with the
+        # translated '-' -> '_'. Right now, we do that on purpose because of
+        # a duplicated option made publicly available on certificate and ca
+        # faces for dns alt names. Puppet defines 'dns_alt_names', those
+        # faces include 'dns-alt-names'.  We can't get rid of 'dns-alt-names'
+        # yet, so we need to do our duplicate checking on the untranslated
+        # version of the option.
+        # jeffweiss 17 april 2012
+        name = optparse_to_optionname(item)
+        if Puppet.settings.include? name then
+          raise ArgumentError, _("%{option}: already defined in puppet") % { option: item.inspect }
+        end
+
+        dup = dups[name]
+        if dup
+          raise ArgumentError, _("%{option}: duplicates existing alias %{duplicate} in %{parent}") %
+                               { option: item.inspect, duplicate: dup.inspect, parent: @parent }
+        else
+          dups[name] = item
+        end
+      else
+        raise ArgumentError, _("%{option} is not valid for an option argument") % { option: item.inspect }
+      end
+    end
+
+    if @optparse.empty? then
+      raise ArgumentError, _("No option declarations found while building")
+    end
+
+    # Now, infer the name from the options; we prefer the first long option as
+    # the name, rather than just the first option.
+    @name = optparse_to_name(@optparse.find do |a| a =~ /^--/ end || @optparse.first)
+    @aliases = @optparse.map { |o| optparse_to_name(o) }
+
+    # Do we take an argument?  If so, are we consistent about it, because
+    # incoherence here makes our life super-difficult, and we can more easily
+    # relax this rule later if we find a valid use case for it. --daniel 2011-03-30
+    @argument = @optparse.any? { |o| o =~ /[ =]/ }
+    if @argument and !@optparse.all? { |o| o =~ /[ =]/ } then
+      raise ArgumentError, _("Option %{name} is inconsistent about taking an argument") % { name: @name }
+    end
+
+    # Is our argument optional?  The rules about consistency apply here, also,
+    # just like they do to taking arguments at all. --daniel 2011-03-30
+    @optional_argument = @optparse.any? { |o| o =~ /[ =]\[/ }
+    if @optional_argument
+      raise ArgumentError, _("Options with optional arguments are not supported")
+    end
+    if @optional_argument and !@optparse.all? { |o| o =~ /[ =]\[/ } then
+      raise ArgumentError, _("Option %{name} is inconsistent about the argument being optional") % { name: @name }
+    end
+  end
+
+  # to_s and optparse_to_name are roughly mirrored, because they are used to
+  # transform options to name symbols, and vice-versa.  This isn't a full
+  # bidirectional transformation though. --daniel 2011-04-07
+
+  def to_s
+    @name.to_s.tr('_', '-')
+  end
+
+  # @api private
+  def optparse_to_optionname(declaration)
+    found = declaration.match(/^-+(?:\[no-\])?([^ =]+)/)
+    unless found
+      raise ArgumentError, _("Can't find a name in the declaration %{declaration}") % { declaration: declaration.inspect }
+    end
+
+    found.captures.first
+  end
+
+  # @api private
+  def optparse_to_name(declaration)
+    name = optparse_to_optionname(declaration).tr('-', '_')
+    unless name.to_s =~ /^[a-z]\w*$/
+      raise _("%{name} is an invalid option name") % { name: name.inspect }
+    end
+
+    name.to_sym
+  end
+
+  def takes_argument?
+    !!@argument
+  end
+
+  def optional_argument?
+    !!@optional_argument
+  end
+
+  def required?
+    !!@required
+  end
+
+  def has_default?
+    !!@default
+  end
+
+  def default=(proc)
+    if required
+      raise ArgumentError, _("%{name} can't be optional and have a default value") % { name: self }
+    end
+
+    unless proc.is_a? Proc
+      # TRANSLATORS 'proc' is a Ruby block of code
+      raise ArgumentError, _("default value for %{name} is a %{class_name}, not a proc") %
+                           { name: self, class_name: proc.class.name.inspect }
+    end
+    @default = proc
+  end
+
+  def default
+    @default and @default.call
+  end
+
+  attr_reader :parent, :name, :aliases, :optparse, :required
+
+  def required=(value)
+    if has_default?
+      raise ArgumentError, _("%{name} can't be optional and have a default value") % { name: self }
+    end
+
+    @required = value
+  end
+
+  attr_reader :before_action
+
+  def before_action=(proc)
+    unless proc.is_a? Proc
+      # TRANSLATORS 'proc' is a Ruby block of code
+      raise ArgumentError, _("before action hook for %{name} is a %{class_name}, not a proc") %
+                           { name: self, class_name: proc.class.name.inspect }
+    end
+    @before_action =
+      @parent.__send__(:__add_method, __decoration_name(:before), proc)
+  end
+
+  attr_reader :after_action
+
+  def after_action=(proc)
+    unless proc.is_a? Proc
+      # TRANSLATORS 'proc' is a Ruby block of code
+      raise ArgumentError, _("after action hook for %{name} is a %{class_name}, not a proc") %
+                           { name: self, class_name: proc.class.name.inspect }
+    end
+    @after_action =
+      @parent.__send__(:__add_method, __decoration_name(:after), proc)
+  end
+
+  def __decoration_name(type)
+    if @parent.is_a? Puppet::Interface::Action then
+      :"option #{name} from #{parent.name} #{type} decoration"
+    else
+      :"option #{name} #{type} decoration"
+    end
+  end
+end