openvox 8.19.0

data/lib/puppet/util/rdoc/parser/puppet_parser_core.rb

@@ -0,0 +1,262 @@
+# frozen_string_literal: true
+
+# Functionality common to both our RDoc version 1 and 2 parsers.
+module RDoc::PuppetParserCore
+  SITE = "__site__"
+
+  def self.included(base)
+    base.class_eval do
+      attr_accessor :input_file_name, :top_level
+
+      # parser registration into RDoc
+      parse_files_matching(/\.(rb)$/)
+    end
+  end
+
+  # called with the top level file
+  def initialize(top_level, file_name, body, options, stats)
+    @options = options
+    @stats   = stats
+    @input_file_name = file_name
+    @top_level = top_level
+    @top_level.extend(RDoc::PuppetTopLevel)
+    @progress = $stderr unless options.quiet
+  end
+
+  # main entry point
+  def scan
+    environment = Puppet.lookup(:current_environment)
+    scan_top_level(@top_level, environment)
+    @top_level
+  end
+
+  # Due to a bug in RDoc, we need to roll our own find_module_named
+  # The issue is that RDoc tries harder by asking the parent for a class/module
+  # of the name. But by doing so, it can mistakenly use a module of same name
+  # but from which we are not descendant.
+  def find_object_named(container, name)
+    return container if container.name == name
+
+    container.each_classmodule do |m|
+      return m if m.name == name
+    end
+    nil
+  end
+
+  # walk down the namespace and lookup/create container as needed
+  def get_class_or_module(container, name)
+    # class ::A -> A is in the top level
+    if name =~ /^::/
+      container = @top_level
+    end
+
+    names = name.split('::')
+
+    final_name = names.pop
+    names.each do |n|
+      prev_container = container
+      container = find_object_named(container, n)
+      container ||= prev_container.add_class(RDoc::PuppetClass, n, nil)
+    end
+    [container, final_name]
+  end
+
+  # split_module tries to find if +path+ belongs to the module path
+  # if it does, it returns the module name, otherwise if we are sure
+  # it is part of the global manifest path, "__site__" is returned.
+  # And finally if this path couldn't be mapped anywhere, nil is returned.
+  def split_module(path, environment)
+    # find a module
+    fullpath = File.expand_path(path)
+    Puppet.debug "rdoc: testing #{fullpath}"
+    if fullpath =~ %r{(.*)/([^/]+)/(?:manifests|plugins|lib)/.+\.(rb)$}
+      modpath = ::Regexp.last_match(1)
+      name = ::Regexp.last_match(2)
+      Puppet.debug "rdoc: module #{name} into #{modpath} ?"
+      environment.modulepath.each do |mp|
+        if File.identical?(modpath, mp)
+          Puppet.debug "rdoc: found module #{name}"
+          return name
+        end
+      end
+    end
+    if fullpath =~ /\.(rb)$/
+      # there can be paths we don't want to scan under modules
+      # imagine a ruby or manifest that would be distributed as part as a module
+      # but we don't want those to be hosted under <site>
+      environment.modulepath.each do |mp|
+        # check that fullpath is a descendant of mp
+        dirname = fullpath
+        previous = dirname
+        while (dirname = File.dirname(previous)) != previous
+          previous = dirname
+          return nil if File.identical?(dirname, mp)
+        end
+      end
+    end
+    # we are under a global manifests
+    Puppet.debug "rdoc: global manifests"
+    SITE
+  end
+
+  # create documentation for the top level +container+
+  def scan_top_level(container, environment)
+    # use the module README as documentation for the module
+    comment = ""
+    %w[README README.rdoc].each do |rfile|
+      readme = File.join(File.dirname(File.dirname(@input_file_name)), rfile)
+      # module README should be UTF-8, not default system encoding
+      comment = File.open(readme, "r:UTF-8", &:read) if FileTest.readable?(readme)
+    end
+    look_for_directives_in(container, comment) unless comment.empty?
+
+    # infer module name from directory
+    name = split_module(@input_file_name, environment)
+    if name.nil?
+      # skip .pp files that are not in manifests directories as we can't guarantee they're part
+      # of a module or the global configuration.
+      # PUP-3638, keeping this while it should have no effect since no .pp files are now processed
+      container.document_self = false
+      return
+    end
+
+    Puppet.debug "rdoc: scanning for #{name}"
+
+    container.module_name = name
+    container.global = true if name == SITE
+
+    container, name = get_class_or_module(container, name)
+    mod = container.add_module(RDoc::PuppetModule, name)
+    mod.record_location(@top_level)
+    mod.add_comment(comment, @top_level)
+
+    if @input_file_name =~ /\.rb$/
+      parse_plugins(mod)
+    end
+  end
+
+  # create documentation for plugins
+  def parse_plugins(container)
+    Puppet.debug "rdoc: scanning plugin or fact"
+    if @input_file_name =~ %r{/facter/[^/]+\.rb$}
+      parse_fact(container)
+    else
+      parse_puppet_plugin(container)
+    end
+  end
+
+  # this is a poor man custom fact parser :-)
+  def parse_fact(container)
+    comments = ""
+    current_fact = nil
+    parsed_facts = []
+    File.open(@input_file_name) do |of|
+      of.each do |line|
+        # fetch comments
+        case line
+        when /^[ \t]*# ?(.*)$/
+          comments += ::Regexp.last_match(1) + "\n"
+        when /^[ \t]*(Facter.add|Puppet\.runtime\[:facter\].add)\(['"](.*?)['"]\)/
+          current_fact = RDoc::Fact.new(::Regexp.last_match(1), {})
+          look_for_directives_in(container, comments) unless comments.empty?
+          current_fact.comment = comments
+          parsed_facts << current_fact
+          comments = ""
+          Puppet.debug "rdoc: found custom fact #{current_fact.name}"
+        when /^[ \t]*confine[ \t]*:(.*?)[ \t]*=>[ \t]*(.*)$/
+          current_fact.confine = { :type => ::Regexp.last_match(1), :value => ::Regexp.last_match(2) } unless current_fact.nil?
+        else # unknown line type
+          comments = ""
+        end
+      end
+    end
+    parsed_facts.each do |f|
+      container.add_fact(f)
+      f.record_location(@top_level)
+    end
+  end
+
+  # this is a poor man puppet plugin parser :-)
+  # it doesn't extract doc nor desc :-(
+  def parse_puppet_plugin(container)
+    comments = ""
+    current_plugin = nil
+
+    File.open(@input_file_name) do |of|
+      of.each do |line|
+        # fetch comments
+        case line
+        when /^[ \t]*# ?(.*)$/
+          comments += ::Regexp.last_match(1) + "\n"
+        when /^[ \t]*(?:Puppet::Parser::Functions::)?newfunction[ \t]*\([ \t]*:(.*?)[ \t]*,[ \t]*:type[ \t]*=>[ \t]*(:rvalue|:lvalue)/
+          current_plugin = RDoc::Plugin.new(::Regexp.last_match(1), "function")
+          look_for_directives_in(container, comments) unless comments.empty?
+          current_plugin.comment = comments
+          current_plugin.record_location(@top_level)
+          container.add_plugin(current_plugin)
+          comments = ""
+          Puppet.debug "rdoc: found new function plugins #{current_plugin.name}"
+        when /^[ \t]*Puppet::Type.newtype[ \t]*\([ \t]*:(.*?)\)/
+          current_plugin = RDoc::Plugin.new(::Regexp.last_match(1), "type")
+          look_for_directives_in(container, comments) unless comments.empty?
+          current_plugin.comment = comments
+          current_plugin.record_location(@top_level)
+          container.add_plugin(current_plugin)
+          comments = ""
+          Puppet.debug "rdoc: found new type plugins #{current_plugin.name}"
+        when /module Puppet::Parser::Functions/
+          # skip
+        else # unknown line type
+          comments = ""
+        end
+      end
+    end
+  end
+
+  # New instance of the appropriate PreProcess for our RDoc version.
+  def create_rdoc_preprocess
+    raise(NotImplementedError, "This method must be overwritten for whichever version of RDoc this parser is working with")
+  end
+
+  # look_for_directives_in scans the current +comment+ for RDoc directives
+  def look_for_directives_in(context, comment)
+    preprocess = create_rdoc_preprocess
+
+    preprocess.handle(comment) do |directive, param|
+      case directive
+      when "stopdoc"
+        context.stop_doc
+        ""
+      when "startdoc"
+        context.start_doc
+        context.force_documentation = true
+        ""
+      when "enddoc"
+        # context.done_documenting = true
+        # ""
+        throw :enddoc
+      when "main"
+        options = Options.instance
+        options.main_page = param
+        ""
+      when "title"
+        options = Options.instance
+        options.title = param
+        ""
+      when "section"
+        context.set_current_section(param, comment)
+        comment.replace("") # 1.8 doesn't support #clear
+        break
+      else
+        warn "Unrecognized directive '#{directive}'"
+        break
+      end
+    end
+    remove_private_comments(comment)
+  end
+
+  def remove_private_comments(comment)
+    comment.gsub!(/^#--.*?^#\+\+/m, '')
+    comment.sub!(/^#--.*/m, '')
+  end
+end

data/lib/puppet/util/rdoc/parser/puppet_parser_rdoc2.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require_relative '../../../../puppet/util/rdoc/parser/puppet_parser_core'
+
+module RDoc
+  PUPPET_RDOC_VERSION = 2
+
+  # @api private
+  class PuppetParserRDoc2 < Parser
+    include PuppetParserCore
+
+    def create_rdoc_preprocess
+      Markup::PreProcess.new(@input_file_name, @options.rdoc_include)
+    end
+  end
+end

data/lib/puppet/util/rdoc/parser.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+# Puppet "parser" for the rdoc system
+# The parser uses puppet parser and traverse the AST to instruct RDoc about
+# our current structures. It also parses ruby files that could contain
+# either custom facts or puppet plugins (functions, types...)
+
+# rdoc2 includes
+require 'rdoc/code_objects'
+require_relative '../../../puppet/util/rdoc/code_objects'
+require 'rdoc/token_stream'
+require 'rdoc/markup/pre_process'
+require 'rdoc/parser'
+require_relative 'parser/puppet_parser_rdoc2'

data/lib/puppet/util/rdoc.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require_relative '../../puppet/util'
+module Puppet::Util::RDoc
+  module_function
+
+  # launch a rdoc documentation process
+  # with the files/dir passed in +files+
+  def rdoc(outputdir, files, charset = nil)
+    # then rdoc
+    require 'rdoc/rdoc'
+    require 'rdoc/options'
+
+    # load our parser
+    require_relative 'rdoc/parser'
+
+    r = RDoc::RDoc.new
+
+    # specify our own format & where to output
+    options = ["--fmt", "puppet",
+               "--quiet",
+               "--exclude", "/modules/[^/]*/spec/.*$",
+               "--exclude", "/modules/[^/]*/files/.*$",
+               "--exclude", "/modules/[^/]*/tests/.*$",
+               "--exclude", "/modules/[^/]*/templates/.*$",
+               "--op", outputdir]
+
+    options << "--force-update"
+    options += ["--charset", charset] if charset
+    options += files
+
+    # launch the documentation process
+    r.document(options)
+  end
+
+  # launch an output to console manifest doc
+  def manifestdoc(files)
+    raise _("RDOC SUPPORT FOR MANIFEST HAS BEEN REMOVED - See PUP-3638")
+  end
+
+  # Outputs to the console the documentation
+  # of a manifest
+  def output(file, ast)
+    raise _("RDOC SUPPORT FOR MANIFEST HAS BEEN REMOVED - See PUP-3638")
+  end
+
+  def output_astnode_doc(ast)
+    raise _("RDOC SUPPORT FOR MANIFEST HAS BEEN REMOVED - See PUP-3638")
+  end
+
+  def output_resource_doc(code)
+    raise _("RDOC SUPPORT FOR MANIFEST HAS BEEN REMOVED - See PUP-3638")
+  end
+end

data/lib/puppet/util/reference.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+require_relative '../../puppet/util/instance_loader'
+require 'fileutils'
+
+# Manage Reference Documentation.
+class Puppet::Util::Reference
+  include Puppet::Util
+  include Puppet::Util::Docs
+
+  extend Puppet::Util::InstanceLoader
+
+  instance_load(:reference, 'puppet/reference')
+
+  def self.modes
+    %w[text]
+  end
+
+  def self.newreference(name, options = {}, &block)
+    ref = new(name, **options, &block)
+    instance_hash(:reference)[name.intern] = ref
+
+    ref
+  end
+
+  def self.page(*sections)
+    depth = 4
+    # Use the minimum depth
+    sections.each do |name|
+      section = reference(name) or raise _("Could not find section %{name}") % { name: name }
+      depth = section.depth if section.depth < depth
+    end
+  end
+
+  def self.references(environment)
+    instance_loader(:reference).loadall(environment)
+    loaded_instances(:reference).sort_by(&:to_s)
+  end
+
+  attr_accessor :page, :depth, :header, :title, :dynamic
+  attr_writer :doc
+
+  def doc
+    if defined?(@doc)
+      "#{@name} - #{@doc}"
+    else
+      @title
+    end
+  end
+
+  def dynamic?
+    dynamic
+  end
+
+  def initialize(name, title: nil, depth: nil, dynamic: nil, doc: nil, &block)
+    @name = name
+    @title = title
+    @depth = depth
+    @dynamic = dynamic
+    @doc = doc
+
+    meta_def(:generate, &block)
+
+    # Now handle the defaults
+    @title ||= _("%{name} Reference") % { name: @name.to_s.capitalize }
+    @page ||= @title.gsub(/\s+/, '')
+    @depth ||= 2
+    @header ||= ""
+  end
+
+  # Indent every line in the chunk except those which begin with '..'.
+  def indent(text, tab)
+    text.gsub(/(^|\A)/, tab).gsub(/^ +\.\./, "..")
+  end
+
+  def option(name, value)
+    ":#{name.to_s.capitalize}: #{value}\n"
+  end
+
+  def text
+    puts output
+  end
+
+  def to_markdown(withcontents = true)
+    # First the header
+    text = markdown_header(@title, 1)
+
+    text << @header
+
+    text << generate
+
+    text
+  end
+end

data/lib/puppet/util/resource_template.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require_relative '../../puppet/util'
+require_relative '../../puppet/util/logging'
+require 'erb'
+
+# A template wrapper that evaluates a template in the
+# context of a resource, allowing the resource attributes
+# to be looked up from within the template.
+#  This provides functionality essentially equivalent to
+# the language's template() function.  You pass your file
+# path and the resource you want to use into the initialization
+# method, then call result on the instance, and you get back
+# a chunk of text.
+#  The resource's parameters are available as instance variables
+# (as opposed to the language, where we use a method_missing trick).
+#  For example, say you have a resource that generates a file.  You would
+# need to implement the following style of `generate` method:
+#
+#   def generate
+#       template = Puppet::Util::ResourceTemplate.new("/path/to/template", self)
+#
+#       return Puppet::Type.type(:file).new :path => "/my/file",
+#           :content => template.evaluate
+#   end
+#
+# This generated file gets added to the catalog (which is what `generate` does),
+# and its content is the result of the template.  You need to use instance
+# variables in your template, so if your template just needs to have the name
+# of the generating resource, it would just have:
+#
+#   <%= @name %>
+#
+# Since the ResourceTemplate class sets as instance variables all of the resource's
+# parameters.
+#
+# Note that this example uses the generating resource as its source of
+# parameters, which is generally most useful, since it allows you to configure
+# the generated resource via the generating resource.
+class Puppet::Util::ResourceTemplate
+  include Puppet::Util::Logging
+
+  def evaluate
+    set_resource_variables
+    Puppet::Util.create_erb(Puppet::FileSystem.read(@file, :encoding => 'utf-8')).result(binding)
+  end
+
+  def initialize(file, resource)
+    raise ArgumentError, _("Template %{file} does not exist") % { file: file } unless Puppet::FileSystem.exist?(file)
+
+    @file = file
+    @resource = resource
+  end
+
+  private
+
+  def set_resource_variables
+    @resource.to_hash.each do |param, value|
+      var = "@#{param}"
+      instance_variable_set(var, value)
+    end
+  end
+end

data/lib/puppet/util/retry_action.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Puppet::Util::RetryAction
+  class RetryException < Exception; end # rubocop:disable Lint/InheritException
+  class RetryException::NoBlockGiven < RetryException; end
+  class RetryException::NoRetriesGiven < RetryException; end
+  class RetryException::RetriesExceeded < RetryException; end
+
+  # Execute the supplied block retrying with exponential backoff.
+  #
+  # @param [Hash] options the retry options
+  # @option options [Integer] :retries Maximum number of times to retry.
+  # @option options [Array<Exception>] :retry_exceptions ([StandardError]) Optional array of exceptions that are allowed to be retried.
+  # @yield The block to be executed.
+  def self.retry_action(options = {})
+    # Retry actions for a specified amount of time. This method will allow the final
+    # retry to complete even if that extends beyond the timeout period.
+    unless block_given?
+      raise RetryException::NoBlockGiven
+    end
+
+    retries = options[:retries]
+    if retries.nil?
+      raise RetryException::NoRetriesGiven
+    end
+
+    retry_exceptions = options[:retry_exceptions] || [StandardError]
+    failures = 0
+    begin
+      yield
+    rescue *retry_exceptions => e
+      if failures >= retries
+        raise RetryException::RetriesExceeded, _("%{retries} exceeded") % { retries: retries }, e.backtrace
+      end
+
+      Puppet.info(_("Caught exception %{klass}:%{error} retrying") % { klass: e.class, error: e })
+
+      failures += 1
+
+      # Increase the amount of time that we sleep after every
+      # failed retry attempt.
+      sleep(((2**failures) - 1) * 0.1)
+
+      retry
+    end
+  end
+end