puppet-retrospec 0.7.0 → 0.7.2

data/vendor/gems/puppet-3.7.3/lib/puppet/reference/function.rb

@@ -0,0 +1,17 @@
+function = Puppet::Util::Reference.newreference :function, :doc => "All functions available in the parser" do
+  Puppet::Parser::Functions.functiondocs
+end
+function.header = "
+There are two types of functions in Puppet: Statements and rvalues.
+Statements stand on their own and do not return arguments; they are used for
+performing stand-alone work like importing.  Rvalues return values and can
+only be used in a statement requiring a value, such as an assignment or a case
+statement.
+
+Functions execute on the Puppet master.  They do not execute on the Puppet agent.
+Hence they only have access to the commands and data available on the Puppet master
+host.
+
+Here are the functions available in Puppet:
+
+"

data/vendor/gems/puppet-3.7.3/lib/puppet/reference/indirection.rb

@@ -0,0 +1,71 @@
+require 'puppet/indirector/indirection'
+require 'puppet/util/checksums'
+require 'puppet/file_serving/content'
+require 'puppet/file_serving/metadata'
+
+reference = Puppet::Util::Reference.newreference :indirection, :doc => "Indirection types and their terminus classes" do
+  text = ""
+  Puppet::Indirector::Indirection.instances.sort { |a,b| a.to_s <=> b.to_s }.each do |indirection|
+    ind = Puppet::Indirector::Indirection.instance(indirection)
+    name = indirection.to_s.capitalize
+    text << "## " + indirection.to_s + "\n\n"
+
+    text << Puppet::Util::Docs.scrub(ind.doc) + "\n\n"
+
+    Puppet::Indirector::Terminus.terminus_classes(ind.name).sort { |a,b| a.to_s <=> b.to_s }.each do |terminus|
+      terminus_name = terminus.to_s
+      term_class = Puppet::Indirector::Terminus.terminus_class(ind.name, terminus)
+      if term_class
+        terminus_doc = Puppet::Util::Docs.scrub(term_class.doc)
+        text << markdown_header("`#{terminus_name}` terminus", 3) << terminus_doc << "\n\n"
+      else
+        Puppet.warning "Could not build docs for indirector #{name.inspect}, terminus #{terminus_name.inspect}: could not locate terminus."
+      end
+    end
+  end
+
+  text
+end
+
+reference.header = <<HEADER
+
+## About Indirection
+
+Puppet's indirector support pluggable backends (termini) for a variety of key-value stores (indirections).
+Each indirection type corresponds to a particular Ruby class (the "Indirected Class" below) and values are instances of that class.
+Each instance's key is available from its `name` method.
+The termini can be local (e.g., on-disk files) or remote (e.g., using a REST interface to talk to a puppet master).
+
+An indirector has five methods, which are mapped into HTTP verbs for the REST interface:
+
+* `find(key)` - get a single value (mapped to GET or POST with a singular endpoint)
+* `search(key)` - get a list of matching values (mapped to GET with a plural endpoint)
+* `head(key)` - return true if the key exists (mapped to HEAD)
+* `destroy(key)` - remove the key van value (mapped to DELETE)
+* `save(instance)` - write the instance to the store, using the instance's name as the key (mapped to PUT)
+
+These methods are available via the `indirection` class method on the indirected classes.  For example:
+
+    foo_cert = Puppet::SSL::Certificate.indirection.find('foo.example.com')
+
+At startup, each indirection is configured with a terminus.
+In most cases, this is the default terminus defined by the indirected class, but it can be overridden by the application or face, or overridden with the `route_file` configuration.
+The available termini differ for each indirection, and are listed below.
+
+Indirections can also have a cache, represented by a second terminus.
+This is a write-through cache: modifications are written both to the cache and to the primary terminus.
+Values fetched from the terminus are written to the cache.
+
+### Interaction with REST
+
+REST endpoints have the form `/{environment}/{indirection}/{key}`, where the indirection can be singular or plural, following normal English spelling rules.
+On the server side, REST responses are generated from the locally-configured endpoints.
+
+### Indirections and Termini
+
+Below is the list of all indirections, their associated terminus classes, and how you select between them.
+
+In general, the appropriate terminus class is selected by the application for you (e.g., `puppet agent` would always use the `rest`
+terminus for most of its indirected classes), but some classes are tunable via normal settings.  These will have `terminus setting` documentation listed with them.
+
+HEADER

data/vendor/gems/puppet-3.7.3/lib/puppet/reference/metaparameter.rb

@@ -0,0 +1,44 @@
+Puppet::Util::Reference.newreference :metaparameter, :doc => "All Puppet metaparameters and all their details" do
+  types = {}
+  Puppet::Type.loadall
+
+  Puppet::Type.eachtype { |type|
+    next if type.name == :puppet
+    next if type.name == :component
+    types[type.name] = type
+  }
+
+  str = %{
+
+Metaparameters are attributes that work with any resource type, including custom
+types and defined types.
+
+In general, they affect _Puppet's_ behavior rather than the desired state of the
+resource. Metaparameters do things like add metadata to a resource (`alias`,
+`tag`), set limits on when the resource should be synced (`require`, `schedule`,
+etc.), prevent Puppet from making changes (`noop`), and change logging verbosity
+(`loglevel`).
+
+## Available Metaparameters
+
+}
+  begin
+    params = []
+    Puppet::Type.eachmetaparam { |param|
+      params << param
+    }
+
+    params.sort { |a,b|
+      a.to_s <=> b.to_s
+    }.each { |param|
+      str << markdown_header(param.to_s, 3)
+      str << scrub(Puppet::Type.metaparamdoc(param))
+      str << "\n\n"
+    }
+  rescue => detail
+    Puppet.log_exception(detail, "incorrect metaparams: #{detail}")
+    exit(1)
+  end
+
+  str
+end

data/vendor/gems/puppet-3.7.3/lib/puppet/reference/providers.rb

@@ -0,0 +1,119 @@
+# This doesn't get stored in trac, since it changes every time.
+providers = Puppet::Util::Reference.newreference :providers, :title => "Provider Suitability Report", :depth => 1, :dynamic => true, :doc => "Which providers are valid for this machine" do
+  types = []
+  Puppet::Type.loadall
+  Puppet::Type.eachtype do |klass|
+    next unless klass.providers.length > 0
+    types << klass
+  end
+  types.sort! { |a,b| a.name.to_s <=> b.name.to_s }
+
+  command_line = Puppet::Util::CommandLine.new
+  types.reject! { |type| ! command_line.args.include?(type.name.to_s) } unless command_line.args.empty?
+
+  ret = "Details about this host:\n\n"
+
+  # Throw some facts in there, so we know where the report is from.
+  ["Ruby Version", "Puppet Version", "Operating System", "Operating System Release"].each do |label|
+    name = label.gsub(/\s+/, '')
+    value = Facter.value(name)
+    ret << option(label, value)
+  end
+  ret << "\n"
+
+  count = 1
+
+  # Produce output for each type.
+  types.each do |type|
+    features = type.features
+    ret << "\n" # add a trailing newline
+
+    # Now build up a table of provider suitability.
+    headers = %w{Provider Suitable?} + features.collect { |f| f.to_s }.sort
+
+    table_data = {}
+
+    functional = false
+    notes = []
+    default = type.defaultprovider ? type.defaultprovider.name : 'none'
+    type.providers.sort { |a,b| a.to_s <=> b.to_s }.each do |pname|
+      data = []
+      table_data[pname] = data
+      provider = type.provider(pname)
+
+      # Add the suitability note
+      if missing = provider.suitable?(false) and missing.empty?
+        data << "*X*"
+        suit = true
+        functional = true
+      else
+        data << "[#{count}]_" # A pointer to the appropriate footnote
+        suit = false
+      end
+
+      # Add a footnote with the details about why this provider is unsuitable, if that's the case
+      unless suit
+        details = ".. [#{count}]\n"
+        missing.each do |test, values|
+          case test
+          when :exists
+            details << "  - Missing files #{values.join(", ")}\n"
+          when :variable
+            values.each do |name, facts|
+              if Puppet.settings.valid?(name)
+                details << "  - Setting #{name} (currently #{Puppet.settings.value(name).inspect}) not in list #{facts.join(", ")}\n"
+              else
+                details << "  - Fact #{name} (currently #{Facter.value(name).inspect}) not in list #{facts.join(", ")}\n"
+              end
+            end
+          when :true
+            details << "  - Got #{values} true tests that should have been false\n"
+          when :false
+            details << "  - Got #{values} false tests that should have been true\n"
+          when :feature
+            details << "  - Missing features #{values.collect { |f| f.to_s }.join(",")}\n"
+          end
+        end
+        notes << details
+
+        count += 1
+      end
+
+      # Add a note for every feature
+      features.each do |feature|
+        if provider.features.include?(feature)
+          data << "*X*"
+        else
+          data << ""
+        end
+      end
+    end
+
+    ret << markdown_header(type.name.to_s + "_", 2)
+
+    ret << "[#{type.name}](#{"http://docs.puppetlabs.com/references/stable/type.html##{type.name}"})\n\n"
+    ret << option("Default provider", default)
+    ret << doctable(headers, table_data)
+
+    notes.each do |note|
+      ret << note + "\n"
+    end
+
+    ret << "\n"
+  end
+
+  ret << "\n"
+
+  ret
+end
+providers.header = "
+Puppet resource types are usually backed by multiple implementations called `providers`,
+which handle variance between platforms and tools.
+
+Different providers are suitable or unsuitable on different platforms based on things
+like the presence of a given tool.
+
+Here are all of the provider-backed types and their different providers.  Any unmentioned
+types do not use providers yet.
+
+"

data/vendor/gems/puppet-3.7.3/lib/puppet/reference/report.rb

@@ -0,0 +1,23 @@
+require 'puppet/reports'
+
+report = Puppet::Util::Reference.newreference :report, :doc => "All available transaction reports" do
+  Puppet::Reports.reportdocs
+end
+
+report.header = "
+Puppet clients can report back to the server after each transaction.  This
+transaction report is sent as a YAML dump of the
+`Puppet::Transaction::Report` class and includes every log message that was
+generated during the transaction along with as many metrics as Puppet knows how
+to collect.  See [Reports and Reporting](http://docs.puppetlabs.com/guides/reporting.html) for more information on how to use reports.
+
+Currently, clients default to not sending in reports; you can enable reporting
+by setting the `report` parameter to true.
+
+To use a report, set the `reports` parameter on the server; multiple
+reports must be comma-separated.  You can also specify `none` to disable
+reports entirely.
+
+Puppet provides multiple report handlers that will process client reports:
+
+"

data/vendor/gems/puppet-3.7.3/lib/puppet/reference/type.rb

@@ -0,0 +1,116 @@
+Puppet::Util::Reference.newreference :type, :doc => "All Puppet resource types and all their details" do
+  types = {}
+  Puppet::Type.loadall
+
+  Puppet::Type.eachtype { |type|
+    next if type.name == :puppet
+    next if type.name == :component
+    next if type.name == :whit
+    types[type.name] = type
+  }
+
+  str = %{
+
+## Resource Types
+
+- The *namevar* is the parameter used to uniquely identify a type instance.
+  This is the parameter that gets assigned when a string is provided before
+  the colon in a type declaration.  In general, only developers will need to
+  worry about which parameter is the `namevar`.
+
+  In the following code:
+
+      file { "/etc/passwd":
+        owner => root,
+        group => root,
+        mode  => 644
+      }
+
+  `/etc/passwd` is considered the title of the file object (used for things like
+  dependency handling), and because `path` is the namevar for `file`, that
+  string is assigned to the `path` parameter.
+
+- *Parameters* determine the specific configuration of the instance.  They either
+  directly modify the system (internally, these are called properties) or they affect
+  how the instance behaves (e.g., adding a search path for `exec` instances or determining recursion on `file` instances).
+
+- *Providers* provide low-level functionality for a given resource type.  This is
+  usually in the form of calling out to external commands.
+
+  When required binaries are specified for providers, fully qualifed paths
+  indicate that the binary must exist at that specific path and unqualified
+  binaries indicate that Puppet will search for the binary using the shell
+  path.
+
+- *Features* are abilities that some providers might not support.  You can use the list
+  of supported features to determine how a given provider can be used.
+
+  Resource types define features they can use, and providers can be tested to see
+  which features they provide.
+
+    }
+
+    types.sort { |a,b|
+      a.to_s <=> b.to_s
+    }.each { |name,type|
+
+      str << "
+
+----------------
+
+"
+
+  str << markdown_header(name, 3)
+  str << scrub(type.doc) + "\n\n"
+
+  # Handle the feature docs.
+  if featuredocs = type.featuredocs
+    str << markdown_header("Features", 4)
+    str << featuredocs
+    end
+
+    docs = {}
+    type.validproperties.sort { |a,b|
+      a.to_s <=> b.to_s
+    }.reject { |sname|
+      property = type.propertybyname(sname)
+      property.nodoc
+    }.each { |sname|
+      property = type.propertybyname(sname)
+
+      raise "Could not retrieve property #{sname} on type #{type.name}" unless property
+
+      doc = nil
+      unless doc = property.doc
+        $stderr.puts "No docs for #{type}[#{sname}]"
+        next
+      end
+      doc = doc.dup
+      tmp = doc
+      tmp = scrub(tmp)
+
+      docs[sname]  = tmp
+    }
+
+    str << markdown_header("Parameters", 4) + "\n"
+    type.parameters.sort { |a,b|
+      a.to_s <=> b.to_s
+    }.each { |name,param|
+      #docs[name] = indent(scrub(type.paramdoc(name)), $tab)
+      docs[name] = scrub(type.paramdoc(name))
+    }
+
+    additional_key_attributes = type.key_attributes - [:name]
+    docs.sort { |a, b|
+      a[0].to_s <=> b[0].to_s
+    }.each { |name, doc|
+      if additional_key_attributes.include?(name)
+        doc = "(**Namevar:** If omitted, this parameter's value defaults to the resource's title.)\n\n" + doc
+      end
+      str << markdown_definitionlist(name, doc)
+    }
+    str << "\n"
+  }
+
+  str
+end

data/vendor/gems/puppet-3.7.3/lib/puppet/relationship.rb

@@ -0,0 +1,103 @@
+# subscriptions are permanent associations determining how different
+# objects react to an event
+
+require 'puppet/util/pson'
+
+# This is Puppet's class for modeling edges in its configuration graph.
+# It used to be a subclass of GRATR::Edge, but that class has weird hash
+# overrides that dramatically slow down the graphing.
+class Puppet::Relationship
+  extend Puppet::Util::Pson
+  attr_accessor :source, :target, :callback
+
+  attr_reader :event
+
+  def self.from_data_hash(data)
+    source = data["source"]
+    target = data["target"]
+
+    args = {}
+    if event = data["event"]
+      args[:event] = event
+    end
+    if callback = data["callback"]
+      args[:callback] = callback
+    end
+
+    new(source, target, args)
+  end
+
+  def self.from_pson(pson)
+    Puppet.deprecation_warning("from_pson is being removed in favour of from_data_hash.")
+    self.from_data_hash(pson)
+  end
+
+  def event=(event)
+    raise ArgumentError, "You must pass a callback for non-NONE events" if event != :NONE and ! callback
+    @event = event
+  end
+
+  def initialize(source, target, options = {})
+    @source, @target = source, target
+
+    options = (options || {}).inject({}) { |h,a| h[a[0].to_sym] = a[1]; h }
+    [:callback, :event].each do |option|
+      if value = options[option]
+        send(option.to_s + "=", value)
+      end
+    end
+  end
+
+  # Does the passed event match our event?  This is where the meaning
+  # of :NONE comes from.
+  def match?(event)
+    if self.event.nil? or event == :NONE or self.event == :NONE
+      return false
+    elsif self.event == :ALL_EVENTS or event == self.event
+      return true
+    else
+      return false
+    end
+  end
+
+  def label
+    result = {}
+    result[:callback] = callback if callback
+    result[:event] = event if event
+    result
+  end
+
+  def ref
+    "#{source} => #{target}"
+  end
+
+  def inspect
+    "{ #{source} => #{target} }"
+  end
+
+  def to_data_hash
+    data = {
+      'source' => source.to_s,
+      'target' => target.to_s
+    }
+
+    ["event", "callback"].each do |attr|
+      next unless value = send(attr)
+      data[attr] = value
+    end
+    data
+  end
+
+  # This doesn't include document type as it is part of a catalog
+  def to_pson_data_hash
+    to_data_hash
+  end
+
+  def to_pson(*args)
+    to_data_hash.to_pson(*args)
+  end
+
+  def to_s
+    ref
+  end
+end