puppet 3.2.4 → 3.3.0.rc2

data/lib/puppet/pops/binder/bindings_label_provider.rb

@@ -0,0 +1,46 @@
+# A provider of labels for bindings model object, producing a human name for the model object.
+# @api private
+#
+class Puppet::Pops::Binder::BindingsLabelProvider < Puppet::Pops::LabelProvider
+  def initialize
+    @@label_visitor ||= Puppet::Pops::Visitor.new(self,"label",0,0)
+  end
+
+  # Produces a label for the given object without article.
+  # @return [String] a human readable label
+  #
+  def label o
+   @@label_visitor.visit(o)
+  end
+
+  def label_PObjectType o                       ; "#{Puppet::Pops::Types::TypeFactory.label(o)}" end
+  def label_ProducerDescriptor o                ; "Producer"                                     end
+  def label_NonCachingProducerDescriptor o      ; "Non Caching Producer"                         end
+  def label_ConstantProducerDescriptor o        ; "Producer['#{o.value}']"                       end
+  def label_EvaluatingProducerDescriptor o      ; "Evaluating Producer"                          end
+  def label_InstanceProducerDescriptor o        ; "Producer[#{o.class_name}]"                    end
+  def label_LookupProducerDescriptor o          ; "Lookup Producer[#{o.name}]"                   end
+  def label_HashLookupProducerDescriptor o      ; "Hash Lookup Producer[#{o.name}][#{o.key}]"    end
+  def label_FirstFoundProducerDescriptor o      ; "First Found Producer"                         end
+  def label_ProducerProducerDescriptor o        ; "Producer[Producer]"                           end
+  def label_MultibindProducerDescriptor o       ; "Multibind Producer"                           end
+  def label_ArrayMultibindProducerDescriptor o  ; "Array Multibind Producer"                     end
+  def label_HashMultibindProducerDescriptor o   ; "Hash Multibind Producer"                      end
+  def label_Bindings o                          ; "Bindings"                                     end
+  def label_NamedBindings o                     ; "Named Bindings"                               end
+  def label_Category o                          ; "Category '#{o.categorization}/#{o.value}'"    end
+  def label_CategorizedBindings o               ; "Categorized Bindings"                         end
+  def label_LayeredBindings o                   ; "Layered Bindings"                             end
+  def label_NamedLayer o                        ; "Layer '#{o.name}'"                            end
+  def label_EffectiveCategories o               ; "Effective Categories"                         end
+  def label_ContributedBindings o               ; "Contributed Bindings"                         end
+  def label_NamedArgument o                     ; "Named Argument"                               end
+
+  def label_Binding(o)
+    'Binding' + (o.multibind_id.nil? ? '' : ' In Multibind')
+  end
+  def label_Multibinding(o)
+    'Multibinding' + (o.multibind_id.nil? ? '' : ' In Multibind')
+  end
+
+end

data/lib/puppet/pops/binder/bindings_loader.rb

@@ -0,0 +1,79 @@
+require 'rgen/metamodel_builder'
+
+# The ClassLoader provides a Class instance given a class name or a meta-type.
+# If the class is not already loaded, it is loaded using the Puppet Autoloader.
+# This means it can load a class from a gem, or from puppet modules.
+#
+class Puppet::Pops::Binder::BindingsLoader
+  @autoloader = Puppet::Util::Autoload.new("BindingsLoader", "puppet/bindings", :wrap => false)
+
+  # Returns a XXXXX given a fully qualified class name.
+  # Lookup of class is never relative to the calling namespace.
+  # @param name [String, Array<String>, Array<Symbol>, Puppet::Pops::Types::PObjectType] A fully qualified
+  #   class name String (e.g. '::Foo::Bar', 'Foo::Bar'), a PObjectType, or a fully qualified name in Array form where each part
+  #   is either a String or a Symbol, e.g. `%w{Puppetx Puppetlabs SomeExtension}`.
+  # @return [Class, nil] the looked up class or nil if no such class is loaded
+  # @raise ArgumentError If the given argument has the wrong type
+  # @api public
+  #
+  def self.provide(scope, name)
+    case name
+    when String
+      provide_from_string(scope, name)
+
+    when Array
+      provide_from_name_path(scope, name.join('::'), name)
+
+    else
+      raise ArgumentError, "Cannot provide a bindings from a '#{name.class.name}'"
+    end
+  end
+
+  # If loadable name exists relative to a a basedir or not. Returns the loadable path as a side effect.
+  # @return [String, nil] a loadable path for the given name, or nil
+  #
+  def self.loadable?(basedir, name)
+    # note, "lib" is added by the autoloader
+    #
+    paths_for_name(name).find {|p| File.exists?(File.join(basedir, "lib/puppet/bindings", p)+'.rb') }
+  end
+
+  private
+
+  def self.provide_from_string(scope, name)
+    name_path = name.split('::')
+    # always from the root, so remove an empty first segment
+    if name_path[0].empty?
+      name_path = name_path[1..-1]
+    end
+    provide_from_name_path(scope, name, name_path)
+  end
+
+  def self.provide_from_name_path(scope, name, name_path)
+    # If bindings is already loaded, try this first
+    result = Puppet::Bindings.resolve(scope, name)
+
+    unless result
+      # Attempt to load it using the auto loader
+      paths_for_name(name).find {|path| @autoloader.load(path) }
+      result = Puppet::Bindings.resolve(scope, name)
+    end
+    result
+  end
+
+  def self.paths_for_name(fq_name)
+    [de_camel(fq_name), downcased_path(fq_name)]
+  end
+
+  def self.downcased_path(fq_name)
+    fq_name.to_s.gsub(/::/, '/').downcase
+  end
+
+  def self.de_camel(fq_name)
+    fq_name.to_s.gsub(/::/, '/').
+    gsub(/([A-Z]+)([A-Z][a-z])/,'\1_\2').
+    gsub(/([a-z\d])([A-Z])/,'\1_\2').
+    tr("-", "_").
+    downcase
+  end
+end

data/lib/puppet/pops/binder/bindings_model.rb

@@ -0,0 +1,215 @@
+require 'rgen/metamodel_builder'
+
+# The Bindings model is a model of Key to Producer mappings (bindings).
+# The central concept is that a Bindings is a nested structure of bindings.
+# A top level Bindings should be a NamedBindings (the name is used primarily
+# in error messages). A Key is a Type/Name combination.
+#
+# TODO: In this version, references to "any object" uses the class Object,
+#       but this is only temporary. The intent is to use specific Puppet Objects
+#       that are typed using the Puppet Type System (to enable serialization).
+#
+# @see Puppet::Pops::Binder::BindingsFactory The BindingsFactory for more details on how to create model instances.
+# @api public
+module Puppet::Pops::Binder::Bindings
+
+  # @abstract
+  # @api public
+  #
+  class AbstractBinding < Puppet::Pops::Model::PopsObject
+    abstract
+  end
+
+  # An abstract producer
+  # @abstract
+  # @api public
+  #
+  class ProducerDescriptor < Puppet::Pops::Model::PopsObject
+    abstract
+    contains_one_uni 'transformer', Puppet::Pops::Model::LambdaExpression
+  end
+
+  # All producers are singleton producers unless wrapped in a non caching producer
+  # where each lookup produces a new instance. It is an error to have a nesting level > 1
+  # and to nest a NonCachingProducerDescriptor.
+  #
+  # @api public
+  #
+  class NonCachingProducerDescriptor < ProducerDescriptor
+    contains_one_uni 'producer', ProducerDescriptor
+  end
+
+  # Produces a constant value (i.e. something of {Puppet::Pops::Types::PDataType PDataType})
+  # @api public
+  #
+  class ConstantProducerDescriptor < ProducerDescriptor
+    # TODO: This should be a typed Puppet Object
+    has_attr 'value', Object
+  end
+
+  # Produces a value by evaluating a Puppet DSL expression
+  # @api public
+  #
+  class EvaluatingProducerDescriptor < ProducerDescriptor
+    contains_one_uni 'expression', Puppet::Pops::Model::Expression
+  end
+
+  # An InstanceProducer creates an instance of the given class
+  # Arguments are passed to the class' `new` operator in the order they are given.
+  # @api public
+  #
+  class InstanceProducerDescriptor < ProducerDescriptor
+    # TODO: This should be a typed Puppet Object ??
+    has_many_attr 'arguments', Object, :upperBound => -1
+    has_attr 'class_name', String
+  end
+
+  # A ProducerProducerDescriptor, describes that the produced instance is itself a Producer
+  # that should be used to produce the value.
+  # @api public
+  #
+  class ProducerProducerDescriptor < ProducerDescriptor
+    contains_one_uni 'producer', ProducerDescriptor, :lowerBound => 1
+  end
+
+  # Produces a value by looking up another key (type/name)
+  # @api public
+  #
+  class LookupProducerDescriptor < ProducerDescriptor
+    contains_one_uni 'type', Puppet::Pops::Types::PObjectType
+    has_attr 'name', String
+  end
+
+  # Produces a value by looking up another multibound key, and then looking up
+  # the detail using a detail_key.
+  # This is used to produce a specific service of a given type (such as a SyntaxChecker for the syntax "json").
+  # @api public
+  #
+  class HashLookupProducerDescriptor < LookupProducerDescriptor
+    has_attr 'key', String
+  end
+
+  # Produces a value by looking up each producer in turn. The first existing producer wins.
+  # @api public
+  #
+  class FirstFoundProducerDescriptor < ProducerDescriptor
+    contains_many_uni 'producers', LookupProducerDescriptor
+  end
+
+  # @api public
+  # @abstract
+  class MultibindProducerDescriptor < ProducerDescriptor
+    abstract
+  end
+
+  # Used in a Multibind of Array type unless it has a producer. May explicitly be used as well.
+  # @api public
+  #
+  class ArrayMultibindProducerDescriptor < MultibindProducerDescriptor
+  end
+
+  # Used in a Multibind of Hash type unless it has a producer. May explicitly be used as well.
+  # @api public
+  #
+  class HashMultibindProducerDescriptor < MultibindProducerDescriptor
+  end
+
+  # Plays the role of "Hash[String, Object] entry" but with keys in defined order.
+  #
+  # @api public
+  #
+  class NamedArgument < Puppet::Pops::Model::PopsObject
+    has_attr 'name', String, :lowerBound => 1
+    has_attr 'value', Object, :lowerBound => 1
+  end
+
+  # Binds a type/name combination to a producer. Optionally marking the bindidng as being abstract, or being an
+  # override of another binding. Optionally, the binding defines producer arguments passed to the producer when
+  # it is created.
+  #
+  # @api public
+  class Binding < AbstractBinding
+    contains_one_uni 'type', Puppet::Pops::Types::PObjectType
+    has_attr 'name', String
+    has_attr 'override', Boolean
+    has_attr 'abstract', Boolean
+    # If set is a contribution in a multibind
+    has_attr 'multibind_id', String, :lowerBound => 0
+    # Invariant: Only multibinds may have lowerBound 0, all regular Binding must have a producer.
+    contains_one_uni 'producer', ProducerDescriptor, :lowerBound => 0
+    contains_many_uni 'producer_args', NamedArgument, :lowerBound => 0
+  end
+
+
+  # A multibinding is a binding other bindings can contribute to.
+  #
+  # @api public
+  class Multibinding < Binding
+    has_attr 'id', String
+  end
+
+  # A container of Binding instances
+  # @api public
+  #
+  class Bindings < AbstractBinding
+    contains_many_uni 'bindings', AbstractBinding
+  end
+
+  # The top level container of bindings can have a name (for error messages, logging, tracing).
+  # May be nested.
+  # @api public
+  #
+  class NamedBindings < Bindings
+    has_attr 'name', String
+  end
+
+  # A category predicate (the request has to be in this category).
+  # @api public
+  #
+  class Category < Puppet::Pops::Model::PopsObject
+    has_attr 'categorization', String, :lowerBound => 1
+    has_attr 'value', String, :lowerBound => 1
+  end
+
+  # A container of Binding instances that are in effect when the
+  # predicates (min one) evaluates to true. Multiple predicates are handles as an 'and'.
+  # Note that 'or' semantics are handled by repeating the same rules.
+  # @api public
+  #
+  class CategorizedBindings < Bindings
+    contains_many_uni 'predicates', Category, :lowerBound => 1
+  end
+
+  # A named layer of bindings having the same priority.
+  # @api public
+  class NamedLayer < Puppet::Pops::Model::PopsObject
+    has_attr 'name', String, :lowerBound => 1
+    contains_many_uni 'bindings', NamedBindings
+  end
+
+  # A list of layers with bindings in descending priority order.
+  # @api public
+  #
+  class LayeredBindings < Puppet::Pops::Model::PopsObject
+    contains_many_uni 'layers', NamedLayer
+  end
+
+  # A list of categories consisting of categroization name and category value (i.e. the *state of the request*)
+  # @api public
+  #
+  class EffectiveCategories < Puppet::Pops::Model::PopsObject
+    # The order is from highest precedence to lowest
+    contains_many_uni 'categories', Category
+  end
+
+  # ContributedBindings is a named container of one or more NamedBindings.
+  # The intent is that a bindings producer returns a ContributedBindings which in addition to the bindings
+  # may optionally contain provider's opinion about the precedence of categories, and their category values.
+  # This enables merging of bindings, and validation of consistency.
+  #
+  # @api public
+  #
+  class ContributedBindings < NamedLayer
+    contains_one_uni 'effective_categories', EffectiveCategories
+  end
+end

data/lib/puppet/pops/binder/bindings_model_dumper.rb

@@ -0,0 +1,205 @@
+
+# Dumps a Pops::Binder::Bindings model in reverse polish notation; i.e. LISP style
+# The intention is to use this for debugging output
+# TODO: BAD NAME - A DUMP is a Ruby Serialization
+# NOTE: use :break, :indent, :dedent in lists to do just that
+#
+class Puppet::Pops::Binder::BindingsModelDumper < Puppet::Pops::Model::TreeDumper
+  Bindings = Puppet::Pops::Binder::Bindings
+
+  attr_reader :type_calculator
+  attr_reader :expression_dumper
+
+  def initialize
+    super
+    @type_calculator = Puppet::Pops::Types::TypeCalculator.new()
+    @expression_dumper = Puppet::Pops::Model::ModelTreeDumper.new()
+  end
+
+  def dump_BindingsFactory o
+    do_dump(o.model)
+  end
+
+  def dump_BindingsBuilder o
+    do_dump(o.model)
+  end
+
+  def dump_BindingsContainerBuilder o
+    do_dump(o.model)
+  end
+
+  def dump_NamedLayer o
+    result = ['named-layer', (o.name.nil? ? '<no-name>': o.name), :indent]
+    if o.bindings
+      o.bindings.each do |b|
+        result << :break
+        result << do_dump(b)
+      end
+    end
+    result << :dedent
+    result
+  end
+
+
+  def dump_Array o
+    o.collect {|e| do_dump(e) }
+  end
+
+  def dump_ASTArray o
+    ["[]"] + o.children.collect {|x| do_dump(x)}
+  end
+
+  def dump_ASTHash o
+    ["{}"] + o.value.sort_by{|k,v| k.to_s}.collect {|x| [do_dump(x[0]), do_dump(x[1])]}
+  end
+
+  def dump_Integer o
+    o.to_s
+  end
+
+  # Dump a Ruby String in single quotes unless it is a number.
+  def dump_String o
+    "'#{o}'"
+  end
+
+  def dump_NilClass o
+    "()"
+  end
+
+  def dump_Object o
+    ['dev-error-no-polymorph-dump-for:', o.class.to_s, o.to_s]
+  end
+
+  def is_nop? o
+    o.nil? || o.is_a?(Model::Nop) || o.is_a?(AST::Nop)
+  end
+
+  def dump_ProducerDescriptor o
+     result = [o.class.name]
+     result << expression_dumper.dump(o.transformer) if o.transformer
+     result
+  end
+
+  def dump_NonCachingProducerDescriptor o
+    dump_ProducerDescriptor(o) + do_dump(o.producer)
+  end
+
+  def dump_ConstantProducerDescriptor o
+    ['constant', do_dump(o.value)]
+  end
+
+  def dump_EvaluatingProducerDescriptor o
+    result = dump_ProducerDescriptor(o)
+    result << expression_dumper.dump(o.expression)
+  end
+
+  def dump_InstanceProducerDescriptor
+    # TODO: o.arguments, o. transformer
+    ['instance', o.class_name]
+  end
+
+  def dump_ProducerProducerDescriptor o
+    # skip the transformer lambda...
+    result = ['producer-producer', do_dump(o.producer)]
+    result << expression_dumper.dump(o.transformer) if o.transformer
+    result
+  end
+
+  def dump_LookupProducerDescriptor o
+    ['lookup', do_dump(o.type), o.name]
+  end
+
+  def dump_PObjectType o
+    type_calculator.string(o)
+  end
+
+  def dump_HashLookupProducerDescriptor o
+    # TODO: transformer lambda
+    result = ['hash-lookup', do_dump(o.type), o.name, "[#{do_dump(o.key)}]"]
+    result << expression_dumper.dump(o.transformer) if o.transformer
+    result
+  end
+
+  def dump_FirstFoundProducerDescriptor o
+    # TODO: transformer lambda
+    ['first-found', do_dump(o.producers)]
+  end
+
+  def dump_ArrayMultibindProducerDescriptor o
+    ['multibind-array']
+  end
+
+  def dump_HashMultibindProducerDescriptor o
+    ['multibind-hash']
+  end
+
+  def dump_NamedArgument o
+    "#{o.name} => #{do_dump(o.value)}"
+  end
+
+  def dump_Binding o
+    result = ['bind']
+    result << 'override' if o.override
+    result << 'abstract' if o.abstract
+    result.concat([do_dump(o.type), o.name])
+    result << "(in #{o.multibind_id})" if o.multibind_id
+    result << ['to', do_dump(o.producer)] + do_dump(o.producer_args)
+    result
+  end
+
+  def dump_Multibinding o
+    result = ['multibind', o.id]
+    result << 'override' if o.override
+    result << 'abstract' if o.abstract
+    result.concat([do_dump(o.type), o.name])
+    result << "(in #{o.multibind_id})" if o.multibind_id
+    result << ['to', do_dump(o.producer)] + do_dump(o.producer_args)
+    result
+  end
+
+  def dump_Bindings o
+    do_dump(o.bindings)
+  end
+
+  def dump_NamedBindings o
+    result = ['named-bindings', o.name, :indent]
+    o.bindings.each do |b|
+      result << :break
+      result << do_dump(b)
+    end
+    result << :dedent
+    result
+  end
+
+  def dump_Category o
+    ['category', o.categorization, do_dump(o.value)]
+  end
+
+  def dump_CategorizedBindings o
+    result = ['when', do_dump(o.predicates), :indent]
+    o.bindings.each do |b|
+      result << :break
+      result << do_dump(b)
+    end
+    result << :dedent
+    result
+  end
+
+  def dump_LayeredBindings o
+    result = ['layers', :indent]
+      o.layers.each do |layer|
+        result << :break
+        result << do_dump(layer)
+      end
+    result << :dedent
+    result
+  end
+
+  def dump_EffectiveCategories o
+    ['categories', do_dump(o.categories)]
+  end
+
+  def dump_ContributedBindings o
+    ['contributed', o.name, do_dump(o.effective_categories), do_dump(o.bindings)]
+  end
+end