bolt 0.20.0 → 0.20.2

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

@@ -0,0 +1,12 @@
+# 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 "puppet/util/rdoc/code_objects"
+require "rdoc/token_stream"
+require "rdoc/markup/pre_process"
+require "rdoc/parser"
+require "puppet/util/rdoc/parser/puppet_parser_rdoc2.rb"

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

@@ -0,0 +1,259 @@
+# 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 =~ /(.*)\/([^\/]+)\/(?:manifests|plugins|lib)\/.+\.(rb)$/
+      modpath = $1
+      name = $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") { |f| f.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, @input_file_name)
+
+    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 =~ /\/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
+        if line =~ /^[ \t]*# ?(.*)$/
+          comments += $1 + "\n"
+        elsif line =~ /^[ \t]*Facter.add\(['"](.*?)['"]\)/
+          current_fact = RDoc::Fact.new($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}"
+        elsif line =~ /^[ \t]*confine[ \t]*:(.*?)[ \t]*=>[ \t]*(.*)$/
+          current_fact.confine = { :type => $1, :value => $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
+        if line =~ /^[ \t]*# ?(.*)$/
+          comments += $1 + "\n"
+        elsif line =~ /^[ \t]*(?:Puppet::Parser::Functions::)?newfunction[ \t]*\([ \t]*:(.*?)[ \t]*,[ \t]*:type[ \t]*=>[ \t]*(:rvalue|:lvalue)/
+          current_plugin = RDoc::Plugin.new($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}"
+        elsif line =~ /^[ \t]*Puppet::Type.newtype[ \t]*\([ \t]*:(.*?)\)/
+          current_plugin = RDoc::Plugin.new($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}"
+        elsif line =~ /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/vendored/puppet/lib/puppet/util/rdoc/parser/puppet_parser_rdoc2.rb

@@ -0,0 +1,14 @@
+require 'puppet/util/rdoc/parser/puppet_parser_core.rb'
+
+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/vendored/puppet/lib/puppet/util/reference.rb

@@ -0,0 +1,118 @@
+require 'puppet/util/instance_loader'
+require 'puppet/util/methodhelper'
+require 'fileutils'
+
+# Manage Reference Documentation.
+class Puppet::Util::Reference
+  include Puppet::Util
+  include Puppet::Util::MethodHelper
+  include Puppet::Util::Docs
+
+  extend Puppet::Util::InstanceLoader
+
+  instance_load(:reference, 'puppet/reference')
+
+  def self.modes
+    %w{pdf text}
+  end
+
+  def self.newreference(name, options = {}, &block)
+    ref = self.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.pdf(text)
+    puts _("creating pdf")
+    rst2latex = which('rst2latex') || which('rst2latex.py') ||
+      raise(_("Could not find rst2latex"))
+
+    cmd = %{#{rst2latex} /tmp/puppetdoc.txt > /tmp/puppetdoc.tex}
+    Puppet::Util.replace_file("/tmp/puppetdoc.txt") {|f| f.puts text }
+    # There used to be an attempt to use secure_open / replace_file to secure
+    # the target, too, but that did nothing: the race was still here.  We can
+    # get exactly the same benefit from running this effort:
+    Puppet::FileSystem.unlink('/tmp/puppetdoc.tex') rescue nil
+    output = %x{#{cmd}}
+    unless $CHILD_STATUS == 0
+      $stderr.puts _("rst2latex failed")
+      $stderr.puts output
+      exit(1)
+    end
+    $stderr.puts output
+
+    # Now convert to pdf
+    Dir.chdir("/tmp") do
+      %x{texi2pdf puppetdoc.tex >/dev/null 2>/dev/null}
+    end
+
+  end
+
+  def self.references
+    instance_loader(:reference).loadall
+    loaded_instances(:reference).sort { |a,b| a.to_s <=> b.to_s }
+  end
+
+  attr_accessor :page, :depth, :header, :title, :dynamic
+  attr_writer :doc
+
+  def doc
+    if defined?(@doc)
+      return "#{@name} - #{@doc}"
+    else
+      return @title
+    end
+  end
+
+  def dynamic?
+    self.dynamic
+  end
+
+  def initialize(name, options = {}, &block)
+    @name = name
+    set_options(options)
+
+    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 << _("\n\n**This page is autogenerated; any changes will get overwritten**\n\n")
+
+    text << @header
+
+    text << generate
+
+    text
+  end
+end

data/vendored/puppet/lib/puppet/util/resource_template.rb

@@ -0,0 +1,61 @@
+require 'puppet/util'
+require '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
+    ERB.new(Puppet::FileSystem.read(@file, :encoding => 'utf-8'), 0, "-").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.to_s}"
+      instance_variable_set(var, value)
+    end
+  end
+end
+