puppet-parse 0.0.1 → 0.0.2

data/lib/vendor/puppet/rb_tree_map.rb

@@ -0,0 +1,388 @@
+# Algorithms and Containers project is Copyright (c) 2009 Kanwei Li
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the 'Software'), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+#
+# A RbTreeMap is a map that is stored in sorted order based on the order of its keys. This ordering is
+# determined by applying the function <=> to compare the keys. No duplicate values for keys are allowed,
+# so duplicate values are overwritten.
+#
+# A major advantage of RBTreeMap over a Hash is the fact that keys are stored in order and can thus be
+# iterated over in order. This is useful for many datasets.
+#
+# The implementation is adapted from Robert Sedgewick's Left Leaning Red-Black Tree implementation,
+# which can be found at http://www.cs.princeton.edu/~rs/talks/LLRB/Java/RedBlackBST.java
+#
+# Most methods have O(log n) complexity.
+
+class Puppet::RbTreeMap
+  include Enumerable
+
+  attr_reader :size
+
+  alias_method :length, :size
+
+  # Create and initialize a new empty TreeMap.
+  def initialize
+    @root = nil
+    @size = 0
+  end
+
+  # Insert an item with an associated key into the TreeMap, and returns the item inserted
+  #
+  # Complexity: O(log n)
+  #
+  # map = Containers::TreeMap.new
+  # map.push("MA", "Massachusetts") #=> "Massachusetts"
+  # map.get("MA") #=> "Massachusetts"
+  def push(key, value)
+    @root = insert(@root, key, value)
+    @root.color = :black
+    value
+  end
+  alias_method :[]=, :push
+
+  # Return true if key is found in the TreeMap, false otherwise
+  #
+  # Complexity: O(log n)
+  #
+  #   map = Containers::TreeMap.new
+  #   map.push("MA", "Massachusetts")
+  #   map.push("GA", "Georgia")
+  #   map.has_key?("GA") #=> true
+  #   map.has_key?("DE") #=> false
+  def has_key?(key)
+    !get_recursive(@root, key).nil?
+  end
+
+  # Return the item associated with the key, or nil if none found.
+  #
+  # Complexity: O(log n)
+  #
+  #   map = Containers::TreeMap.new
+  #   map.push("MA", "Massachusetts")
+  #   map.push("GA", "Georgia")
+  #   map.get("GA") #=> "Georgia"
+  def get(key)
+    node = get_recursive(@root, key)
+    node ? node.value : nil
+    node.value if node
+  end
+  alias_method :[], :get
+
+  # Return the smallest key in the map.
+  #
+  # Complexity: O(log n)
+  #
+  #   map = Containers::TreeMap.new
+  #   map.push("MA", "Massachusetts")
+  #   map.push("GA", "Georgia")
+  #   map.min_key #=> "GA"
+  def min_key
+    @root.nil? ? nil : min_recursive(@root).key
+  end
+
+  # Return the largest key in the map.
+  #
+  # Complexity: O(log n)
+  #
+  #   map = Containers::TreeMap.new
+  #   map.push("MA", "Massachusetts")
+  #   map.push("GA", "Georgia")
+  #   map.max_key #=> "MA"
+  def max_key
+    @root.nil? ? nil : max_recursive(@root).key
+  end
+
+  # Deletes the item and key if it's found, and returns the item. Returns nil
+  # if key is not present.
+  #
+  # Complexity: O(log n)
+  #
+  #   map = Containers::TreeMap.new
+  #   map.push("MA", "Massachusetts")
+  #   map.push("GA", "Georgia")
+  #   map.delete("MA") #=> "Massachusetts"
+  def delete(key)
+    result = nil
+    if @root
+      return unless has_key? key
+      @root, result = delete_recursive(@root, key)
+      @root.color = :black if @root
+      @size -= 1
+    end
+    result
+  end
+
+  # Returns true if the tree is empty, false otherwise
+  def empty?
+    @root.nil?
+  end
+
+  # Deletes the item with the smallest key and returns the item. Returns nil
+  # if key is not present.
+  #
+  # Complexity: O(log n)
+  #
+  #   map = Containers::TreeMap.new
+  #   map.push("MA", "Massachusetts")
+  #   map.push("GA", "Georgia")
+  #   map.delete_min #=> "Massachusetts"
+  #   map.size #=> 1
+  def delete_min
+    result = nil
+    if @root
+      @root, result = delete_min_recursive(@root)
+      @root.color = :black if @root
+      @size -= 1
+    end
+    result
+  end
+
+  # Deletes the item with the largest key and returns the item. Returns nil
+  # if key is not present.
+  #
+  # Complexity: O(log n)
+  #
+  #   map = Containers::TreeMap.new
+  #   map.push("MA", "Massachusetts")
+  #   map.push("GA", "Georgia")
+  #   map.delete_max #=> "Georgia"
+  #   map.size #=> 1
+  def delete_max
+    result = nil
+    if @root
+      @root, result = delete_max_recursive(@root)
+      @root.color = :black if @root
+      @size -= 1
+    end
+    result
+  end
+
+  # Yields [key, value] pairs in order by key.
+  def each(&blk)
+    recursive_yield(@root, &blk)
+  end
+
+  def first
+    return nil unless @root
+    node = min_recursive(@root)
+    [node.key, node.value]
+  end
+
+  def last
+    return nil unless @root
+    node = max_recursive(@root)
+    [node.key, node.value]
+  end
+
+  def to_hash
+    @root ? @root.to_hash : {}
+  end
+
+  class Node # :nodoc: all
+    attr_accessor :color, :key, :value, :left, :right
+    def initialize(key, value)
+      @key = key
+      @value = value
+      @color = :red
+      @left = nil
+      @right = nil
+    end
+
+    def to_hash
+      h = {
+        :node => {
+          :key => @key,
+          :value => @value,
+          :color => @color,
+        }
+      }
+      h.merge!(:left => left.to_hash) if @left
+      h.merge!(:right => right.to_hash) if @right
+      h
+    end
+
+    def red?
+      @color == :red
+    end
+
+    def colorflip
+      @color       = @color == :red       ? :black : :red
+      @left.color  = @left.color == :red  ? :black : :red
+      @right.color = @right.color == :red ? :black : :red
+    end
+
+    def rotate_left
+      r = @right
+      r_key, r_value, r_color = r.key, r.value, r.color
+      b = r.left
+      r.left = @left
+      @left = r
+      @right = r.right
+      r.right = b
+      r.color, r.key, r.value = :red, @key, @value
+      @key, @value = r_key, r_value
+      self
+    end
+
+    def rotate_right
+      l = @left
+      l_key, l_value, l_color = l.key, l.value, l.color
+      b = l.right
+      l.right = @right
+      @right = l
+      @left = l.left
+      l.left = b
+      l.color, l.key, l.value = :red, @key, @value
+      @key, @value = l_key, l_value
+      self
+    end
+
+    def move_red_left
+      colorflip
+      if (@right.left && @right.left.red?)
+        @right.rotate_right
+        rotate_left
+        colorflip
+      end
+      self
+    end
+
+    def move_red_right
+      colorflip
+      if (@left.left && @left.left.red?)
+        rotate_right
+        colorflip
+      end
+      self
+    end
+
+    def fixup
+      rotate_left if @right && @right.red?
+      rotate_right if (@left && @left.red?) && (@left.left && @left.left.red?)
+      colorflip if (@left && @left.red?) && (@right && @right.red?)
+
+      self
+    end
+  end
+
+  private
+
+  def recursive_yield(node, &blk)
+    return unless node
+    recursive_yield(node.left, &blk)
+    yield node.key, node.value
+    recursive_yield(node.right, &blk)
+  end
+
+  def delete_recursive(node, key)
+    if (key <=> node.key) == -1
+      node.move_red_left if ( !isred(node.left) && !isred(node.left.left) )
+      node.left, result = delete_recursive(node.left, key)
+    else
+      node.rotate_right if isred(node.left)
+      if ( ( (key <=> node.key) == 0) && node.right.nil? )
+        return nil, node.value
+      end
+      if ( !isred(node.right) && !isred(node.right.left) )
+        node.move_red_right
+      end
+      if (key <=> node.key) == 0
+        result = node.value
+        min_child = min_recursive(node.right)
+        node.value = min_child.value
+        node.key = min_child.key
+        node.right = delete_min_recursive(node.right).first
+      else
+        node.right, result = delete_recursive(node.right, key)
+      end
+    end
+    return node.fixup, result
+  end
+
+  def delete_min_recursive(node)
+    if node.left.nil?
+      return nil, node.value
+    end
+    if ( !isred(node.left) && !isred(node.left.left) )
+      node.move_red_left
+    end
+    node.left, result = delete_min_recursive(node.left)
+
+    return node.fixup, result
+  end
+
+  def delete_max_recursive(node)
+    if (isred(node.left))
+      node = node.rotate_right
+    end
+    return nil, node.value if node.right.nil?
+    if ( !isred(node.right) && !isred(node.right.left) )
+      node.move_red_right
+    end
+    node.right, result = delete_max_recursive(node.right)
+
+    return node.fixup, result
+  end
+
+  def get_recursive(node, key)
+    return nil if node.nil?
+    case key <=> node.key
+    when  0 then return node
+    when -1 then return get_recursive(node.left, key)
+    when  1 then return get_recursive(node.right, key)
+    end
+  end
+
+  def min_recursive(node)
+    return node if node.left.nil?
+
+    min_recursive(node.left)
+  end
+
+  def max_recursive(node)
+    return node if node.right.nil?
+
+    max_recursive(node.right)
+  end
+
+  def insert(node, key, value)
+    unless node
+      @size += 1
+      return Node.new(key, value)
+    end
+
+    case key <=> node.key
+    when  0 then node.value = value
+    when -1 then node.left = insert(node.left, key, value)
+    when  1 then node.right = insert(node.right, key, value)
+    end
+
+    node.rotate_left if (node.right && node.right.red?)
+    node.rotate_right if (node.left && node.left.red? && node.left.left && node.left.left.red?)
+    node.colorflip if (node.left && node.left.red? && node.right && node.right.red?)
+    node
+  end
+
+  def isred(node)
+    return false if node.nil?
+
+    node.color == :red
+  end
+end

data/lib/vendor/puppet/reference/configuration.rb

@@ -0,0 +1,69 @@
+config = Puppet::Util::Reference.newreference(:configuration, :depth => 1, :doc => "A reference for all configuration parameters") do
+  docs = {}
+  Puppet.settings.each do |name, object|
+    docs[name] = object
+  end
+
+  str = ""
+  docs.sort { |a, b|
+    a[0].to_s <=> b[0].to_s
+  }.each do |name, object|
+    # Make each name an anchor
+    header = name.to_s
+    str << markdown_header(header, 3)
+
+    # Print the doc string itself
+    begin
+      str << object.desc.gsub(/\n/, " ")
+    rescue => detail
+      puts detail.backtrace
+      puts detail
+    end
+    str << "\n\n"
+
+    # Now print the data about the item.
+    str << ""
+    val = object.default
+    if name.to_s == "vardir"
+      val = "/var/lib/puppet"
+    elsif name.to_s == "confdir"
+      val = "/etc/puppet"
+    end
+
+    # Leave out the section information; it was apparently confusing people.
+    #str << "- **Section**: #{object.section}\n"
+    unless val == ""
+      str << "- *Default*: #{val}\n"
+    end
+    str << "\n"
+  end
+
+  return str
+end
+
+config.header = <<EOT
+## Configuration Settings
+
+* Each of these settings can be specified in `puppet.conf` or on the
+  command line.
+* When using boolean settings on the command line, use `--setting` and
+  `--no-setting` instead of `--setting (true|false)`.
+* Settings can be interpolated as `$variables` in other settings; `$environment`
+  is special, in that puppet master will interpolate each agent node's
+  environment instead of its own.
+* Multiple values should be specified as comma-separated lists; multiple
+  directories should be separated with the system path separator (usually
+  a colon).
+* Settings that take a single file or directory can optionally set the owner,
+  group, and mode for their value: `rundir = $vardir/run { owner = puppet,
+  group = puppet, mode = 644 }`
+* The Puppet executables will ignore any setting that isn't relevant to
+  their function.
+
+See the [configuration guide][confguide] for more details.
+
+[confguide]: http://docs.puppetlabs.com/guides/configuring.html
+
+* * *
+
+EOT

data/lib/vendor/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/lib/vendor/puppet/reference/indirection.rb

@@ -0,0 +1,32 @@
+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 << 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)
+      terminus_doc = Puppet::Util::Docs.scrub(term_class.doc)
+      text << markdown_definitionlist(terminus_name, terminus_doc)
+    end
+  end
+
+  text
+end
+
+reference.header = "This 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.
+
+
+"

data/lib/vendor/puppet/reference/metaparameter.rb

@@ -0,0 +1,43 @@
+metaparameter = 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
+    
+Metaparameters are parameters that work with any resource type; they are part of the 
+Puppet framework itself rather than being part of the implementation of any
+given instance.  Thus, any defined metaparameter can be used with any instance
+in your manifest, including defined components.
+
+## 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
+    puts detail.backtrace
+    puts "incorrect metaparams: #{detail}"
+    exit(1)
+  end
+
+  str
+end

data/lib/vendor/puppet/reference/network.rb

@@ -0,0 +1,39 @@
+require 'puppet/network/handler'
+
+network = Puppet::Util::Reference.newreference :network, :depth => 2, :doc => "Available network handlers and clients" do
+  ret = ""
+  Puppet::Network::Handler.subclasses.sort { |a,b| a.to_s <=> b.to_s }.each do |name|
+    handler = Puppet::Network::Handler.handler(name)
+
+    next if ! handler.doc or handler.doc == ""
+
+    interface = handler.interface
+
+    ret << markdown_header(name, 2)
+
+    ret << scrub(handler.doc)
+    ret << "\n\n"
+    ret << option(:prefix, interface.prefix)
+    ret << option(:side, handler.side.to_s.capitalize)
+    ret << option(:methods, interface.methods.collect { |ary| ary[0] }.join(", ") )
+    ret << "\n\n"
+  end
+
+  ret
+end
+
+network.header = "
+This is a list of all Puppet network interfaces.  Each interface is
+implemented in the form of a client and a handler; the handler is loaded
+on the server, and the client knows how to call the handler's methods
+appropriately.
+
+Most handlers are meant to be started on the server, usually within
+`puppet master`, and the clients are mostly started on the client,
+usually within `puppet agent`.
+
+You can find the server-side handler for each interface at
+`puppet/network/handler/<name>.rb` and the client class at
+`puppet/network/client/<name>.rb`.
+
+"

data/lib/vendor/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.
+
+"