puppet 3.2.4 → 3.3.0.rc2

data/lib/puppet/pops/types/type_factory.rb

@@ -0,0 +1,147 @@
+# Helper module that makes creation of type objects simpler.
+# @api public
+#
+module Puppet::Pops::Types::TypeFactory
+  @type_calculator = Puppet::Pops::Types::TypeCalculator.new()
+
+  Types = Puppet::Pops::Types
+
+  # Produces the Integer type
+  # @api public
+  #
+  def self.integer()
+    Types::PIntegerType.new()
+  end
+
+  # Produces the Float type
+  # @api public
+  #
+  def self.float()
+    Types::PFloatType.new()
+  end
+
+  # Produces a string representation of the type
+  # @api public
+  #
+  def self.label(t)
+    @type_calculator.string(t)
+  end
+
+  # Produces the String type
+  # @api public
+  #
+  def self.string()
+    Types::PStringType.new()
+  end
+
+  # Produces the Boolean type
+  # @api public
+  #
+  def self.boolean()
+    Types::PBooleanType.new()
+  end
+
+  # Produces the Pattern type
+  # @api public
+  #
+  def self.pattern()
+    Types::PPatternType.new()
+  end
+
+  # Produces the Literal type
+  # @api public
+  #
+  def self.literal()
+    Types::PLiteralType.new()
+  end
+
+  # Produces the abstract type Collection
+  # @api public
+  #
+  def self.collection()
+    Types::PCollectionType.new()
+  end
+
+  # Produces the Data type
+  # @api public
+  #
+  def self.data()
+    Types::PDataType.new()
+  end
+
+  # Produces a type for Array[o] where o is either a type, or an instance for which a type is inferred.
+  # @api public
+  #
+  def self.array_of(o)
+    type = Types::PArrayType.new()
+    type.element_type = type_of(o)
+    type
+  end
+
+  # Produces a type for Hash[Literal, o] where o is either a type, or an instance for which a type is inferred.
+  # @api public
+  #
+  def self.hash_of(value, key = literal())
+    type = Types::PHashType.new()
+    type.key_type = type_of(key)
+    type.element_type = type_of(value)
+    type
+  end
+
+  # Produces a type for Array[Data]
+  # @api public
+  #
+  def self.array_of_data()
+    type = Types::PArrayType.new()
+    type.element_type = data()
+    type
+  end
+
+  # Produces a type for Hash[Literal, Data]
+  # @api public
+  #
+  def self.hash_of_data()
+    type = Types::PHashType.new()
+    type.key_type = literal()
+    type.element_type = data()
+    type
+  end
+
+  # Produce a type corresponding to the class of given unless given is a String, Class or a PObjectType.
+  # When a String is given this is taken as a classname.
+  #
+  def self.type_of(o)
+    if o.is_a?(Class)
+      @type_calculator.type(o)
+    elsif o.is_a?(Types::PObjectType)
+      o
+    elsif o.is_a?(String)
+      type = Types::PRubyType.new()
+      type.ruby_class = o
+      type
+    else
+      @type_calculator.infer(o)
+    end
+  end
+
+  # Produces a type for a class or infers a type for something that is not a class
+  # @note
+  #   To get the type for the class' class use `TypeCalculator.infer(c)`
+  #
+  # @overload ruby(o)
+  #   @param o [Class] produces the type corresponding to the class (e.g. Integer becomes PIntegerType)
+  # @overload ruby(o)
+  #   @param o [Object] produces the type corresponding to the instance class (e.g. 3 becomes PIntegerType)
+  #
+  # @api public
+  #
+  def self.ruby(o)
+    if o.is_a?(Class)
+      @type_calculator.type(o)
+    else
+      type = Types::PRubyType.new()
+      type.ruby_class = o.class.name
+      type
+    end
+  end
+end

data/lib/puppet/pops/types/type_parser.rb

@@ -0,0 +1,117 @@
+# This class provides parsing of Type Specification from a string into the Type
+# Model that is produced by the Puppet::Pops::Types::TypeFactory.
+#
+# The Type Specifications that are parsed are the same as the stringified forms
+# of types produced by the {Puppet::Pops::Types::TypeCalculator TypeCalculator}.
+#
+# @api public
+class Puppet::Pops::Types::TypeParser
+  # @api private
+  TYPES = Puppet::Pops::Types::TypeFactory
+
+  # @api public
+  def initialize
+    @parser = Puppet::Pops::Parser::Parser.new()
+    @type_transformer = Puppet::Pops::Visitor.new(nil, "interpret", 0, 0)
+  end
+
+  # Produces a *puppet type* based on the given string.
+  #
+  # @example
+  #     parser.parse('Integer')
+  #     parser.parse('Array[String]')
+  #     parser.parse('Hash[Integer, Array[String]]')
+  #
+  # @param string [String] a string with the type expressed in stringified form as produced by the 
+  #   {Puppet::Pops::Types::TypeCalculator#string TypeCalculator#string} method.
+  # @return [Puppet::Pops::Types::PObjectType] a specialization of the PObjectType representing the type.
+  #
+  # @api public
+  #
+  def parse(string)
+    @string = string
+    model = @parser.parse_string(@string)
+    if model
+      interpret(model.current)
+    else
+      raise_invalid_type_specification_error
+    end
+  end
+
+  # @api private
+  def interpret(ast)
+    @type_transformer.visit_this(self, ast)
+  end
+
+  # @api private
+  def interpret_Object(anything)
+    raise_invalid_type_specification_error
+  end
+
+  # @api private
+  def interpret_QualifiedReference(name_ast)
+    case name_ast.value
+    when "integer"
+      TYPES.integer
+    when "float"
+      TYPES.float
+    when "string"
+      TYPES.string
+    when "boolean"
+      TYPES.boolean
+    when "pattern"
+      TYPES.pattern
+    when "data"
+      TYPES.data
+    when "array"
+      TYPES.array_of_data
+    when "hash"
+      TYPES.hash_of_data
+    else
+      raise_unknown_type_error(name_ast)
+    end
+  end
+
+  # @api private
+  def interpret_AccessExpression(parameterized_ast)
+    parameters = parameterized_ast.keys.collect { |param| interpret(param) }
+    case parameterized_ast.left_expr.value
+    when "array"
+      if parameters.size != 1
+        raise_invalid_parameters_error("Array", 1, parameters.size)
+      end
+      TYPES.array_of(parameters[0])
+    when "hash"
+      if parameters.size == 1
+        TYPES.hash_of(parameters[0])
+      elsif parameters.size != 2
+        raise_invalid_parameters_error("Hash", "1 or 2", parameters.size)
+      else
+        TYPES.hash_of(parameters[1], parameters[0])
+      end
+    else
+      raise_unknown_type_error(parameterized_ast.left_expr)
+    end
+  end
+
+  private
+
+  def raise_invalid_type_specification_error
+    raise Puppet::ParseError,
+      "The expression <#{@string}> is not a valid type specification."
+  end
+
+  def raise_invalid_parameters_error(type, required, given)
+    raise Puppet::ParseError,
+      "Invalid number of type parameters specified: #{type} requires #{required}, #{given} provided"
+  end
+
+  def raise_unknown_type_error(ast)
+    raise Puppet::ParseError, "Unknown type <#{original_text_of(ast)}>"
+  end
+
+  def original_text_of(ast)
+    position = Puppet::Pops::Adapters::SourcePosAdapter.adapt(ast)
+    position.extract_text_from_string(@string)
+  end
+end

data/lib/puppet/pops/types/types.rb

@@ -0,0 +1,132 @@
+require 'rgen/metamodel_builder'
+
+# The Types model is a model of Puppet Language types.
+#
+# The exact relationship between types is not visible in this model wrt. the PDataType which is an abstraction
+# of Literal, Array[Data], and Hash[Literal, Data] nested to any depth. This means it is not possible to
+# infer the type by simply looking at the inheritance hierarchy. The {Puppet::Pops::Types::TypeCalculator} should
+# be used to answer questions about types. The {Puppet::Pops::Types::TypeFactory} should be used to create an instance
+# of a type whenever one is needed.
+#
+# @api public
+#
+module Puppet::Pops::Types
+
+  # The type of types.
+  # @api public
+  class PType < Puppet::Pops::Model::PopsObject
+  end
+
+  # Base type for all types except {Puppet::Pops::Types::PType PType}, the type of types.
+  # @api public
+  class PObjectType < Puppet::Pops::Model::PopsObject
+
+    module ClassModule
+      def hash
+        self.class.hash
+      end
+
+      def ==(o)
+        self.class == o.class
+      end
+
+      alias eql? ==
+    end
+
+  end
+
+  # @api public
+  class PNilType < PObjectType
+  end
+
+  # A flexible data type, being assignable to its subtypes as well as PArrayType and PHashType with element type assignable to PDataType.
+  #
+  # @api public
+  class PDataType < PObjectType
+  end
+
+  # Type that is PDataType compatible, but is not a PCollectionType.
+  # @api public
+  class PLiteralType < PDataType
+  end
+
+  # @api public
+  class PStringType < PLiteralType
+  end
+
+  # @api public
+  class PNumericType < PLiteralType
+  end
+
+  # @api public
+  class PIntegerType < PNumericType
+  end
+
+  # @api public
+  class PFloatType < PNumericType
+  end
+
+  # @api public
+  class PPatternType < PLiteralType
+  end
+
+  # @api public
+  class PBooleanType < PLiteralType
+  end
+
+  # @api public
+  class PCollectionType < PObjectType
+    contains_one_uni 'element_type', PObjectType
+    module ClassModule
+      def hash
+        [self.class, element_type].hash
+      end
+
+      def ==(o)
+        self.class == o.class && element_type == o.element_type
+      end
+    end
+  end
+
+  # @api public
+  class PArrayType < PCollectionType
+    module ClassModule
+      def hash
+        [self.class, element_type].hash
+      end
+
+      def ==(o)
+        self.class == o.class && element_type == o.element_type
+      end
+    end
+  end
+
+  # @api public
+  class PHashType < PCollectionType
+    contains_one_uni 'key_type', PObjectType
+    module ClassModule
+      def hash
+        [self.class, key_type, element_type].hash
+      end
+
+      def ==(o)
+        self.class == o.class && key_type == o.key_type && element_type == o.element_type
+      end
+    end
+  end
+
+  # @api public
+  class PRubyType < PObjectType
+    has_attr 'ruby_class', String
+    module ClassModule
+      def hash
+        [self.class, ruby_class].hash
+      end
+
+      def ==(o)
+        self.class == o.class && ruby_class == o.ruby_class
+      end
+    end
+
+  end
+end

data/lib/puppet/pops/validation.rb

@@ -1,18 +1,98 @@
 # A module with base functionality for validation of a model.
 #
-# * SeverityProducer - produces a severity (:error, :warning, :ignore) for a given Issue
-# * DiagnosticProducer - produces a Diagnostic which binds an Issue to an occurrence of that issue
-# * Acceptor - the receiver/sink/collector of computed diagnostics
-# * DiagnosticFormatter - produces human readable output for a Diagnostic
+# * **Factory** - an abstract factory implementation that makes it easier to create a new validation factory.
+# * **SeverityProducer** - produces a severity (:error, :warning, :ignore) for a given Issue
+# * **DiagnosticProducer** - produces a Diagnostic which binds an Issue to an occurrence of that issue
+# * **Acceptor** - the receiver/sink/collector of computed diagnostics
+# * **DiagnosticFormatter** - produces human readable output for a Diagnostic
 #
 module Puppet::Pops::Validation
+
+  # This class is an abstract base implementation of a _model validation factory_ that creates a validator instance
+  # and associates it with a fully configured DiagnosticProducer.
+  #
+  # A _validator_ is responsible for validating a model. There may be different versions of validation available
+  # for one and the same model; e.g. different semantics for different puppet versions, or different types of
+  # validation configuration depending on the context/type of validation that should be performed (static, vs. runtime, etc.).
+  #
+  # This class is abstract and must be subclassed. The subclass must implement the methods
+  # {#label_provider} and {#checker}. It is also expected that the sublcass will override
+  # the severity_producer and configure the issues that should be reported as errors (i.e. if they should be ignored, produce
+  # a warning, or a deprecation warning).
+  #
+  # @abstract Subclass must implement {#checker}, and {#label_provider}
+  # @api public
+  #
+  class Factory
+
+    # Produces a validator with the given acceptor as the recipient of produced diagnostics.
+    # The acceptor is where detected issues are received (and typically collected).
+    #
+    # @param acceptor [Acceptor] the acceptor is the receiver of all detected issues
+    # @return [#validate] a validator responding to `validate(model)`
+    #
+    # @api public
+    #
+    def validator(acceptor)
+      checker(diagnostic_producer(acceptor))
+    end
+
+    # Produces the diagnostics producer to use given an acceptor of issues.
+    #
+    # @param acceptor [Acceptor] the acceptor is the receiver of all detected issues
+    # @return [DiagnosticProducer] a detector of issues
+    #
+    # @api public
+    #
+    def diagnostic_producer(acceptor)
+      Puppet::Pops::Validation::DiagnosticProducer.new(acceptor, severity_producer(), label_provider())
+    end
+
+    # Produces the SeverityProducer to use
+    # Subclasses should implement and add specific overrides
+    #
+    # @return [SeverityProducer] a severity producer producing error, warning or ignore per issue
+    #
+    # @api public
+    #
+    def severity_producer
+      Puppet::Pops::Validation::SeverityProducer.new
+    end
+
+    # Produces the checker to use.
+    #
+    # @abstract
+    #
+    # @api public
+    #
+    def checker(diagnostic_producer)
+      raise NoMethodError, "checker"
+    end
+
+    # Produces the label provider to use.
+    #
+    # @abstract
+    #
+    # @api public
+    #
+    def label_provider
+      raise NoMethodError, "label_provider"
+    end
+  end
+
   # Decides on the severity of a given issue.
   # The produced severity is one of `:error`, `:warning`, or `:ignore`.
   # By default, a severity of `:error` is produced for all issues. To configure the severity
   # of an issue call `#severity=(issue, level)`.
   #
+  # @return [Symbol] a symbol representing the severity `:error`, `:warning`, or `:ignore`
+  #
+  # @api public
+  #
   class SeverityProducer
+
     # Creates a new instance where all issues are diagnosed as :error unless overridden.
+    # @api public
     #
     def initialize
       # If diagnose is not set, the default is returned by the block
@@ -20,13 +100,17 @@ module Puppet::Pops::Validation
     end
 
     # Returns the severity of the given issue.
-    # @returns [Symbol] severity level :error, :warning, or :ignore
+    # @return [Symbol] severity level :error, :warning, or :ignore
+    # @api public
     #
-    def severity issue
+    def severity(issue)
       assert_issue(issue)
       @severities[issue]
     end
 
+    # @see {#severity}
+    # @api public
+    #
     def [] issue
       severity issue
     end
@@ -35,26 +119,35 @@ module Puppet::Pops::Validation
     #
     # @param issue [Puppet::Pops::Issues::Issue] the issue for which to set severity
     # @param level [Symbol] the severity level (:error, :warning, or :ignore).
+    # @api public
     #
-    def []= issue, level
+    def []=(issue, level)
       assert_issue(issue)
       assert_severity(level)
       raise Puppet::DevError.new("Attempt to demote the hard issue '#{issue.issue_code}' to #{level}") unless issue.demotable? || level == :error
       @severities[issue] = level
     end
 
-    # Returns true if the issue should be reported or not.
-    # @returns [Boolean] this implementation returns true for errors and warnings
+    # Returns `true` if the issue should be reported or not.
+    # @return [Boolean] this implementation returns true for errors and warnings
+    #
+    # @api public
     #
     def should_report? issue
       diagnose = self[issue]
       diagnose == :error || diagnose == :warning || diagnose == :deprecation
     end
 
+    # Checks if the given issue is valid.
+    # @api private
+    #
     def assert_issue issue
       raise Puppet::DevError.new("Attempt to get validation severity for something that is not an Issue. (Got #{issue.class})") unless issue.is_a? Puppet::Pops::Issues::Issue
     end
 
+    # Checks if the given severity level is valid.
+    # @api private
+    #
     def assert_severity level
       raise Puppet::DevError.new("Illegal severity level: #{option}") unless [:ignore, :warning, :error, :deprecation].include? level
     end
@@ -157,8 +250,11 @@ module Puppet::Pops::Validation
 
     def format_location diagnostic
       file = diagnostic.file
-      line = diagnostic.source_pos.line
-      pos = diagnostic.source_pos.pos
+      line = pos = nil
+      if diagnostic.source_pos
+        line = diagnostic.source_pos.line
+        pos = diagnostic.source_pos.pos
+      end
       if file && line && pos
         "#{file}:#{line}:#{pos}:"
       elsif file && line
@@ -187,8 +283,12 @@ module Puppet::Pops::Validation
     # have to be used here for backwards compatibility.
     def format_location diagnostic
       file = diagnostic.file
-      line = diagnostic.source_pos.line
-      pos = diagnostic.source_pos.pos
+      line = pos = nil
+      if diagnostic.source_pos
+        line = diagnostic.source_pos.line
+        pos = diagnostic.source_pos.pos
+      end
+
       if file && line && pos
         " at #{file}:#{line}:#{pos}"
       elsif file and line
@@ -214,7 +314,7 @@ module Puppet::Pops::Validation
   #
   class Acceptor
 
-    # All diagnstic in the order they were issued
+    # All diagnostic in the order they were issued
     attr_reader :diagnostics
 
     # The number of :warning severity issues + number of :deprecation severity issues
@@ -261,7 +361,7 @@ module Puppet::Pops::Validation
     end
 
     def errors_and_warnings
-      @diagnostics.select {|d| d.severity != :ignored}
+      @diagnostics.select {|d| d.severity != :ignore }
     end
 
     # Returns the ignored diagnostics in the order thwy were reported (if reported at all)
@@ -269,9 +369,38 @@ module Puppet::Pops::Validation
       @diagnostics.select {|d| d.severity == :ignore }
     end
 
-    # Add a diagnostic to the set of diagnostics
+    # Add a diagnostic, or all diagnostics from another acceptor to the set of diagnostics
+    # @param diagnostic [Puppet::Pops::Validation::Diagnostic, Puppet::Pops::Validation::Acceptor] diagnostic(s) that should be accepted
     def accept(diagnostic)
-      self.send(diagnostic.severity, diagnostic)
+      if diagnostic.is_a?(Acceptor)
+        diagnostic.diagnostics.each {|d| self.send(d.severity, d)}
+      else
+        self.send(diagnostic.severity, diagnostic)
+      end
+    end
+
+    # Prunes the contain diagnostics by removing those for which the given block returns true.
+    # The internal statistics is updated as a consequence of removing.
+    # @return [Array<Puppet::Pops::Validation::Diagnostic, nil] the removed set of diagnostics or nil if nothing was removed
+    #
+    def prune(&block)
+      removed = []
+      @diagnostics.delete_if do |d|
+        if should_remove = yield(d)
+          removed << d
+        end
+        should_remove
+      end
+      removed.each do |d|
+        case d.severity
+        when :error
+          @error_count -= 1
+        when :warning
+          @warning_count -= 1
+        # there is not ignore_count
+        end
+      end
+      removed.empty? ? nil : removed
     end
 
     private