puppet 3.1.1 → 3.2.0.rc1

data/lib/puppet/pops/parser/makefile

@@ -0,0 +1,13 @@
+
+#parser.rb: grammar.ra
+#	racc -o$@ grammar.ra
+#
+#grammar.output: grammar.ra
+#	racc -v -o$@ grammar.ra
+#
+
+eparser.rb: egrammar.ra
+	racc -o$@ egrammar.ra
+
+egrammar.output: egrammar.ra
+	racc -v -o$@ egrammar.ra

data/lib/puppet/pops/parser/parser_support.rb

@@ -0,0 +1,203 @@
+require 'puppet/parser/functions'
+require 'puppet/parser/files'
+require 'puppet/resource/type_collection'
+require 'puppet/resource/type_collection_helper'
+require 'puppet/resource/type'
+require 'monitor'
+
+# Supporting logic for the parser.
+# This supporting logic has slightly different responsibilities compared to the original Puppet::Parser::Parser.
+# It is only concerned with parsing.
+#
+class Puppet::Pops::Parser::Parser
+  # Note that the name of the contained class and the file name (currently parser_support.rb)
+  # needs to be different as the class is generated by Racc, and this file (parser_support.rb) is included as a mix in
+  #
+
+  # Simplify access to the Model factory
+  # Note that the parser/parser support does not have direct knowledge about the Model.
+  # All model construction/manipulation is made by the Factory.
+  #
+  Factory = Puppet::Pops::Model::Factory
+  Model = Puppet::Pops::Model
+
+  include Puppet::Resource::TypeCollectionHelper
+
+  attr_accessor :lexer
+
+  # Returns the token text of the given lexer token, or nil, if token is nil
+  def token_text t
+    return t if t.nil?
+    t = t.current if t.respond_to?(:current)
+    return t.value if t.is_a? Model::QualifiedName
+
+    # else it is a lexer token
+    t[:value]
+  end
+
+  # Produces the fully qualified name, with the full (current) namespace for a given name.
+  #
+  # This is needed because class bodies are lazily evaluated and an inner class' container(s) may not
+  # have been evaluated before some external reference is made to the inner class; its must therefore know its complete name
+  # before evaluation-time.
+  #
+  def classname(name)
+    [@lexer.namespace, name].join("::").sub(/^::/, '')
+  end
+
+  # Reinitializes variables (i.e. creates a new lexer instance
+  #
+  def clear
+    initvars
+  end
+
+  # Raises a Parse error.
+  def error(message, options = {})
+    except = Puppet::ParseError.new(message)
+    except.line = options[:line] || @lexer.line
+    except.file = options[:file] || @lexer.file
+    except.pos = options[:pos]   || @lexer.pos
+
+    raise except
+  end
+
+  # Parses a file expected to contain pp DSL logic.
+  def parse_file(file)
+    unless FileTest.exist?(file)
+      unless file =~ /\.pp$/
+        file = file + ".pp"
+      end
+    end
+    @lexer.file = file
+    _parse()
+  end
+
+  def initialize()
+    # Since the parser is not responsible for importing (removed), and does not perform linking,
+    # and there is no syntax that requires knowing if something referenced exists, it is safe
+    # to assume that no environment is needed when parsing. (All that comes later).
+    #
+    initvars
+  end
+
+  # Initializes the parser support by creating a new instance of {Puppet::Pops::Parser::Lexer}
+  # @return [void]
+  #
+  def initvars
+    @lexer = Puppet::Pops::Parser::Lexer.new
+  end
+
+  # This is a callback from the generated grammar (when an error occurs while parsing)
+  # TODO Picks up origin information from the lexer, probably needs this from the caller instead
+  #   (for code strings, and when start line is not line 1 in a code string (or file), etc.)
+  #
+  def on_error(token,value,stack)
+    if token == 0 # denotes end of file
+      value = 'end of file'
+    else
+      value = "'#{value[:value]}'"
+    end
+    error = "Syntax error at #{value}"
+
+    # The 'expected' is only of value at end of input, otherwise any parse error involving a
+    # start of a pair will be reported as expecting the close of the pair - e.g. "$x.each |$x {", would
+    # report that "seeing the '{', the '}' is expected. That would be wrong.
+    # Real "expected" tokens are very difficult to compute (would require parsing of racc output data). Output of the stack
+    # could help, but can require extensive backtracking and produce many options.
+    #
+    if token == 0 && brace = @lexer.expected
+      error += "; expected '#{brace}'"
+    end
+
+    except = Puppet::ParseError.new(error)
+    except.line = @lexer.line
+    except.file = @lexer.file if @lexer.file
+    except.pos  = @lexer.pos
+
+    raise except
+  end
+
+  # Parses a String of pp DSL code.
+  # @todo make it possible to pass a given origin
+  #
+  def parse_string(code)
+    @lexer.string = code
+    _parse()
+  end
+
+  # Mark the factory wrapped model object with location information
+  # @todo the lexer produces :line for token, but no offset or length
+  # @return [Puppet::Pops::Model::Factory] the given factory
+  # @api private
+  #
+  def loc(factory, start_token, end_token = nil)
+    factory.record_position(sourcepos(start_token), sourcepos(end_token))
+  end
+
+  # Associate documentation with the factory wrapped model object.
+  # @return [Puppet::Pops::Model::Factory] the given factory
+  # @api private
+  def doc factory, doc_string
+    factory.doc = doc_string
+  end
+
+  def sourcepos(o)
+    if !o
+      Puppet::Pops::Adapters::SourcePosAdapter.new
+    elsif o.is_a? Puppet::Pops::Model::Factory
+      # It is a built model element with loc set returns start at pos 0
+      o.loc
+    else
+      loc = Puppet::Pops::Adapters::SourcePosAdapter.new
+      # It must be a token
+      loc.line = o[:line]
+      loc.pos = o[:pos]
+      loc.offset = o[:offset]
+      loc.length = o[:length]
+      loc
+    end
+  end
+
+  def aryfy(o)
+    o = [o] unless o.is_a?(Array)
+    o
+  end
+
+  # Transforms an array of expressions containing literal name expressions to calls if followed by an
+  # expression, or expression list
+  #
+  def transform_calls(expressions)
+    Factory.transform_calls(expressions)
+  end
+
+  # Performs the parsing and returns the resulting model.
+  # The lexer holds state, and this is setup with {#parse_string}, or {#parse_file}.
+  #
+  # TODO: Drop support for parsing a ruby file this way (should be done where it is decided
+  #   which file to load/run (i.e. loaders), and initial file to run
+  # TODO: deal with options containing origin (i.e. parsing a string from externally known location).
+  # TODO: should return the model, not a Hostclass
+  #
+  # @api private
+  #
+  def _parse()
+    begin
+      @yydebug = false
+      main = yyparse(@lexer,:scan)
+      # #Commented out now because this hides problems in the racc grammar while developing
+      # # TODO include this when test coverage is good enough.
+      #      rescue Puppet::ParseError => except
+      #        except.line ||= @lexer.line
+      #        except.file ||= @lexer.file
+      #        except.pos  ||= @lexer.pos
+      #        raise except
+      #      rescue => except
+      #        raise Puppet::ParseError.new(except.message, @lexer.file, @lexer.line, @lexer.pos, except)
+    end
+    main.record_origin(@lexer.file) if main
+    return main
+  ensure
+    @lexer.clear
+  end
+
+end

data/lib/puppet/pops/patterns.rb

@@ -0,0 +1,35 @@
+# The Patterns module contains common regular expression patters for the Puppet DSL language
+module Puppet::Pops::Patterns
+
+  # NUMERIC matches hex, octal, decimal, and floating point and captures three parts
+  # 0 = entire matched number, leading and trailing whitespace included
+  # 1 = hexadecimal number
+  # 2 = non hex integer portion, possibly with leading 0 (octal)
+  # 3 = floating point part, starts with ".", decimals and optional exponent
+  #
+  # Thus, a hex number has group 1 value, an octal value has group 2 (if it starts with 0), and no group 3
+  # and a floating point value has group 2 and group 3.
+  #
+  NUMERIC = %r{^\s*(?:(0[xX][0-9A-Fa-f]+)|(0?\d+)((?:\.\d+)?(?:[eE]-?\d+)?))\s*$}
+
+  # ILLEGAL_P3_1_HOSTNAME matches if a hostname contains illegal characters.
+  # This check does not prevent pathological names like 'a....b', '.....', "---". etc.
+  ILLEGAL_HOSTNAME_CHARS = %r{[^-\w.]}
+
+  # NAME matches a name the same way as the lexer.
+  # This name includes hyphen, which may be illegal in variables, and names in general.
+  NAME = %r{((::)?[a-z0-9][-\w]*)(::[a-z0-9][-\w]*)*}
+
+  # CLASSREF_EXT matches a class reference the same way as the lexer - i.e. the external source form
+  # where each part must start with a capital letter A-Z.
+  # This name includes hyphen, which may be illegal in some cases.
+  #
+  CLASSREF_EXT = %r{((::){0,1}[A-Z][-\w]*)+}
+
+  # CLASSREF matches a class reference the way it is represented internall in the
+  # model (i.e. in lower case).
+  # This name includes hyphen, which may be illegal in some cases.
+  #
+  CLASSREF = %r{((::){0,1}[a-z][-\w]*)+}
+
+end

data/lib/puppet/pops/utils.rb

@@ -0,0 +1,104 @@
+# Provides utility methods
+module Puppet::Pops::Utils
+  # Can the given o be converted to numeric? (or is numeric already)
+  # Accepts a leading '::'
+  # Returns a boolean if the value is numeric
+  # If testing if value can be converted it is more efficient to call {#to_n} or {#to_n_with_radix} directly
+  # and check if value is nil.
+  def self.is_numeric?(o)
+    case o
+    when Numeric, Integer, Fixnum, Float
+      !!o
+    else
+      !!Puppet::Pops::Patterns::NUMERIC.match(relativize_name(o.to_s))
+    end
+  end
+
+  # To LiteralNumber with radix, or nil if not a number.
+  # If the value is already a number it is returned verbatim with a radix of 10.
+  # @param o [String, Number] a string containing a number in octal, hex, integer (decimal) or floating point form
+  # @return [Array<Number, Integer>, nil] array with converted number and radix, or nil if not possible to convert
+  # @api public
+  #
+  def self.to_n_with_radix o
+    begin
+      case o
+      when String
+        match = Puppet::Pops::Patterns::NUMERIC.match(relativize_name(o))
+        if !match
+          nil
+        elsif match[3].to_s.length > 0
+          # Use default radix (default is decimal == 10) for floats
+          [Float(match[0]), 10]
+        else
+          # Set radix (default is decimal == 10)
+          radix = 10
+          if match[1].to_s.length > 0
+            radix = 16
+          elsif match[2].to_s.length > 0 && match[2][0] == '0'
+            radix = 8
+          end
+          [Integer(match[0], radix), radix]
+        end
+      when Numeric, Fixnum, Integer, Float
+        # Impossible to calculate radix, assume decimal
+        [o, 10]
+      else
+        nil
+      end
+    rescue ArgumentError
+      nil
+    end
+  end
+
+  # To Numeric (or already numeric)
+  # Returns nil if value is not numeric, else an Integer or Float
+  # A leading '::' is accepted (and ignored)
+  #
+  def self.to_n o
+    begin
+      case o
+      when String
+        match = Puppet::Pops::Patterns::NUMERIC.match(relativize_name(o))
+        if !match
+          nil
+        elsif match[3].to_s.length > 0
+          Float(match[0])
+        else
+          Integer(match[0])
+        end
+      when Numeric, Fixnum, Integer, Float
+        o
+      else
+        nil
+      end
+    rescue ArgumentError
+      nil
+    end
+  end
+
+  # is the name absolute (i.e. starts with ::)
+  def self.is_absolute? name
+    name.start_with? "::"
+  end
+
+  def self.name_to_segments name
+    name.split("::")
+  end
+
+  def self.relativize_name name
+    is_absolute?(name) ? name[2..-1] : name
+  end
+
+  # Finds an adapter for o or for one of its containers, or nil, if none of the containers
+  # was adapted with the given adapter.
+  # This method can only be used with objects that respond to `:eContainer`.
+  # with true, and Adaptable#adapters.
+  #
+  def self.find_adapter(o, adapter)
+    return nil unless o
+    a = adapter.get(o)
+    return a if a
+    return find_adapter(o.eContainer, adapter)
+  end
+end

data/lib/puppet/pops/validation.rb

@@ -0,0 +1,297 @@
+# 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
+#
+module Puppet::Pops::Validation
+  # 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)`.
+  #
+  class SeverityProducer
+    # Creates a new instance where all issues are diagnosed as :error unless overridden.
+    #
+    def initialize
+      # If diagnose is not set, the default is returned by the block
+      @severities = Hash.new :error
+    end
+
+    # Returns the severity of the given issue.
+    # @returns [Symbol] severity level :error, :warning, or :ignore
+    #
+    def severity issue
+      assert_issue(issue)
+      @severities[issue]
+    end
+
+    def [] issue
+      severity issue
+    end
+
+    # Override a default severity with the given severity level.
+    #
+    # @param issue [Puppet::Pops::Issues::Issue] the issue for which to set severity
+    # @param level [Symbol] the severity level (:error, :warning, or :ignore).
+    #
+    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
+    #
+    def should_report? issue
+      diagnose = self[issue]
+      diagnose == :error || diagnose == :warning || diagnose == :deprecation
+    end
+
+    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
+
+    def assert_severity level
+      raise Puppet::DevError.new("Illegal severity level: #{option}") unless [:ignore, :warning, :error, :deprecation].include? level
+    end
+  end
+
+  # A producer of diagnostics.
+  # An producer of diagnostics is given each issue occurrence as they are found by a diagnostician/validator. It then produces
+  # a Diagnostic, which it passes on to a configured Acceptor.
+  #
+  # This class exists to aid a diagnostician/validator which will typically first check if a particular issue
+  # will be accepted at all (before checking for an occurrence of the issue; i.e. to perform check avoidance for expensive checks).
+  # A validator passes an instance of Issue, the semantic object (the "culprit"), a hash with arguments, and an optional
+  # exception. The semantic object is used to determine the location of the occurrence of the issue (file/line), and it
+  # sets keys in the given argument hash that may be used in the formatting of the issue message.
+  #
+  class DiagnosticProducer
+
+    # A producer of severity for a given issue
+    # @return [SeverityProducer]
+    #
+    attr_reader :severity_producer
+
+    # A producer of labels for objects involved in the issue
+    # @return [LabelProvider]
+    #
+    attr_reader :label_provider
+    # Initializes this producer.
+    #
+    # @param acceptor [Acceptor] a sink/collector of diagnostic results
+    # @param severity_producer [SeverityProducer] the severity producer to use to determine severity of a given issue
+    # @param label_provider [LabelProvider] a provider of model element type to human readable label
+    #
+    def initialize(acceptor, severity_producer, label_provider)
+      @acceptor           = acceptor
+      @severity_producer  = severity_producer
+      @label_provider     = label_provider
+    end
+
+    def accept(issue, semantic, arguments={}, except=nil)
+      return unless will_accept? issue
+
+      # Set label provider unless caller provided a special label provider
+      arguments[:label]    ||= @label_provider
+      arguments[:semantic] ||= semantic
+
+      # A detail message is always provided, but is blank by default.
+      arguments[:detail] ||= ''
+
+      origin_adapter = Puppet::Pops::Utils.find_adapter(semantic, Puppet::Pops::Adapters::OriginAdapter)
+      file = origin_adapter ? origin_adapter.origin : nil
+      source_pos = Puppet::Pops::Utils.find_adapter(semantic, Puppet::Pops::Adapters::SourcePosAdapter)
+      severity = @severity_producer.severity(issue)
+      @acceptor.accept(Diagnostic.new(severity, issue, file, source_pos, arguments))
+    end
+
+    def will_accept? issue
+      @severity_producer.should_report? issue
+    end
+  end
+
+  class Diagnostic
+    attr_reader :severity
+    attr_reader :issue
+    attr_reader :arguments
+    attr_reader :exception
+    attr_reader :file
+    attr_reader :source_pos
+    def initialize severity, issue, file, source_pos, arguments={}, exception=nil
+      @severity = severity
+      @issue = issue
+      @file = file
+      @source_pos = source_pos
+      @arguments = arguments
+      @exception = exception
+    end
+  end
+
+  # Formats a diagnostic for output.
+  # Produces a diagnostic output typical for a compiler (suitable for interpretation by tools)
+  # The format is:
+  # `file:line:pos: Message`, where pos, line and file are included if available.
+  #
+  class DiagnosticFormatter
+    def format diagnostic
+      "#{loc(diagnostic)} #{format_severity(diagnostic)}#{format_message(diagnostic)}"
+    end
+
+    def format_message diagnostic
+      diagnostic.issue.format(diagnostic.arguments)
+    end
+
+    # This produces "Deprecation notice: " prefix if the diagnostic has :deprecation severity, otherwise "".
+    # The idea is that all other diagnostics are emitted with the methods Puppet.err (or an exception), and
+    # Puppet.warning.
+    # @note Note that it is not a good idea to use Puppet.deprecation_warning as it is for internal deprecation.
+    #
+    def format_severity diagnostic
+      diagnostic.severity == :deprecation ? "Deprecation notice: " : ""
+    end
+
+    def format_location diagnostic
+      file = diagnostic.file
+      line = diagnostic.source_pos.line
+      pos = diagnostic.source_pos.pos
+      if file && line && pos
+        "#{file}:#{line}:#{pos}:"
+      elsif file && line
+        "#{file}:#{line}:"
+      elsif file
+        "#{file}:"
+      else
+        ""
+      end
+    end
+  end
+
+  # Produces a diagnostic output in the "puppet style", where the location is appended with an "at ..." if the
+  # location is known.
+  #
+  class DiagnosticFormatterPuppetStyle < DiagnosticFormatter
+    def format diagnostic
+      if (location = format_location diagnostic) != ""
+        "#{format_severity(diagnostic)}#{format_message(diagnostic)}#{location}"
+      else
+        format_message(diagnostic)
+      end
+    end
+
+    # The somewhat (machine) unusable format in current use by puppet.
+    # 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
+      if file && line && pos
+        " at #{file}:#{line}:#{pos}"
+      elsif file and line
+        " at #{file}:#{line}"
+      elsif line && pos
+        " at line #{line}:#{pos}"
+      elsif line
+        " at line #{line}"
+      elsif file
+        " in #{file}"
+      else
+        ""
+      end
+    end
+  end
+
+  # An acceptor of diagnostics.
+  # An acceptor of diagnostics is given each issue as they are found by a diagnostician/validator. An
+  # acceptor can collect all found issues, or decide to collect a few and then report, or give up as the first issue
+  # if found.
+  # This default implementation collects all diagnostics in the order they are produced, and can then
+  # answer questions about what was diagnosed.
+  #
+  class Acceptor
+
+    # All diagnstic in the order they were issued
+    attr_reader :diagnostics
+
+    # The number of :warning severity issues + number of :deprecation severity issues
+    attr_reader :warning_count
+
+    # The number of :error severity issues
+    attr_reader :error_count
+    # Initializes this diagnostics acceptor.
+    # By default, the acceptor is configured with a default severity producer.
+    # @param severity_producer [SeverityProducer] the severity producer to use to determine severity of an issue
+    #
+    # TODO add semantic_label_provider
+    #
+    def initialize()
+      @diagnostics = []
+      @error_count = 0
+      @warning_count = 0
+    end
+
+    # Returns true when errors have been diagnosed.
+    def errors?
+      @error_count > 0
+    end
+
+    # Returns true when warnings have been diagnosed.
+    def warnings?
+      @warning_count > 0
+    end
+
+    # Returns true when errors and/or warnings have been diagnosed.
+    def errors_or_warnings?
+      errors? || warnings?
+    end
+
+    # Returns the diagnosed errors in the order thwy were reported.
+    def errors
+      @diagnostics.select {|d| d.severity == :error }
+    end
+
+    # Returns the diagnosed warnings in the order thwy were reported.
+    # (This includes :warning and :deprecation severity)
+    def warnings
+      @diagnostics.select {|d| d.severity == :warning || d.severity == :deprecation }
+    end
+
+    def errors_and_warnings
+      @diagnostics.select {|d| d.severity != :ignored}
+    end
+
+    # Returns the ignored diagnostics in the order thwy were reported (if reported at all)
+    def ignored
+      @diagnostics.select {|d| d.severity == :ignore }
+    end
+
+    # Add a diagnostic to the set of diagnostics
+    def accept(diagnostic)
+      self.send(diagnostic.severity, diagnostic)
+    end
+
+    private
+
+    def ignore diagnostic
+      @diagnostics << diagnostic
+    end
+
+    def error diagnostic
+      @diagnostics << diagnostic
+      @error_count += 1
+    end
+
+    def warning diagnostic
+      @diagnostics << diagnostic
+      @warning_count += 1
+    end
+
+    def deprecation diagnostic
+      warning diagnostic
+    end
+  end
+end