puppet 3.1.1 → 3.2.0.rc1

data/lib/puppet/parser/type_loader.rb

@@ -1,6 +1,7 @@
 require 'find'
 require 'forwardable'
 require 'puppet/node/environment'
+require 'puppet/parser/parser_factory'
 
 class Puppet::Parser::TypeLoader
   extend  Forwardable
@@ -137,7 +138,8 @@ class Puppet::Parser::TypeLoader
 
   def parse_file(file)
     Puppet.debug("importing '#{file}' in environment #{environment}")
-    parser = Puppet::Parser::Parser.new(environment)
+#    parser = Puppet::Parser::Parser.new(environment)
+    parser = Puppet::Parser::ParserFactory.parser(environment)
     parser.file = file
     return parser.parse
   end

data/lib/puppet/pops.rb

@@ -0,0 +1,40 @@
+module Puppet
+  module Pops
+    require 'puppet/pops/patterns'
+    require 'puppet/pops/utils'
+
+    require 'puppet/pops/adaptable'
+    require 'puppet/pops/adapters'
+
+    require 'puppet/pops/visitable'
+    require 'puppet/pops/visitor'
+
+    require 'puppet/pops/containment'
+
+    require 'puppet/pops/issues'
+    require 'puppet/pops/label_provider'
+    require 'puppet/pops/validation'
+
+    require 'puppet/pops/model/model'
+
+    module Model
+      require 'puppet/pops/model/tree_dumper'
+      require 'puppet/pops/model/ast_transformer'
+      require 'puppet/pops/model/ast_tree_dumper'
+      require 'puppet/pops/model/factory'
+      require 'puppet/pops/model/model_tree_dumper'
+      require 'puppet/pops/model/model_label_provider'
+    end
+
+    module Parser
+      require 'puppet/pops/parser/eparser'
+      require 'puppet/pops/parser/parser_support'
+      require 'puppet/pops/parser/lexer'
+    end
+
+    module Validation
+      require 'puppet/pops/validation/checker3_1'
+      require 'puppet/pops/validation/validator_factory_3_1'
+    end
+  end
+end

data/lib/puppet/pops/adaptable.rb

@@ -0,0 +1,190 @@
+# Adaptable is a mix-in module that adds adaptability to a class.
+# This means that an adapter can
+# associate itself with an instance of the class and store additional data/have behavior.
+#
+# This mechanism should be used when there is a desire to keep implementation concerns separate.
+# In Ruby it is always possible to open and modify a class or instance to teach it new tricks, but it
+# is however not possible to do this for two different versions of some service at the same time.
+# The Adaptable pattern is also good when only a few of the objects of some class needs to have extra
+# information (again possible in Ruby by adding instance variables dynamically). In fact, the implementation
+# of Adaptable does just that; it adds an instance variable named after the adapter class and keeps an
+# instance of this class in this slot.
+#
+# @note the implementation details; the fact that an instance variable is used to keep the adapter
+#   instance data should not
+#   be exploited as the implementation of _being adaptable_ may change in the future.
+# @api private
+#
+module Puppet::Pops::Adaptable
+  # Base class for an Adapter.
+  #
+  # A typical adapter just defines some accessors.
+  #
+  # A more advanced adapter may need to setup the adapter based on the object it is adapting.
+  # @example Making Duck adaptable
+  #   class Duck
+  #     include Puppet::Pops::Adaptable
+  #   end
+  # @example Giving a Duck a nick name
+  #   class NickNameAdapter < Puppet::Pops::Adaptable::Adapter
+  #     attr_accessor :nick_name
+  #   end
+  #   d = Duck.new
+  #   NickNameAdapter.adapt(d).nick_name = "Daffy"
+  #   NickNameAdapter.get(d).nick_name # => "Daffy"
+  #
+  # @example Giving a Duck a more elaborate nick name
+  #   class NickNameAdapter < Puppet::Pops::Adaptable::Adapter
+  #     attr_accessor :nick_name, :object
+  #     def initialize o
+  #       @object = o
+  #       @nick_name = "Yo"
+  #     end
+  #     def nick_name
+  #       "#{@nick_name}, the #{o.class.name}"
+  #     end
+  #     def NickNameAdapter.create_adapter(o)
+  #       x = new o
+  #       x
+  #     end
+  #   end
+  #   d = Duck.new
+  #   n = NickNameAdapter.adapt(d)
+  #   n.nick_name # => "Yo, the Duck"
+  #   n.nick_name = "Daffy"
+  #   n.nick_name # => "Daffy, the Duck"
+  # @example Using a block to set values
+  #   NickNameAdapter.adapt(o) { |a| a.nick_name = "Buddy!" }
+  #   NickNameAdapter.adapt(o) { |a, o| a.nick_name = "You're the best #{o.class.name} I met."}
+  #
+  class Adapter
+    # Returns an existing adapter for the given object, or nil, if the object is not
+    # adapted.
+    #
+    # @param o [Adaptable] object to get adapter from
+    # @return [Adapter<self>] an adapter of the same class as the receiver of #get
+    # @return [nil] if the given object o has not been adapted by the receiving adapter
+    # @raise [ArgumentError] if the object is not adaptable
+    #
+    def self.get(o)
+      attr_name = :"@#{instance_var_name(self.name)}"
+      if existing = o.instance_variable_defined?(attr_name)
+        o.instance_variable_get(attr_name)
+      else
+        nil
+      end
+    end
+
+    # Returns an existing adapter for the given object, or creates a new adapter if the
+    # object has not been adapted, or the adapter has been cleared.
+    #
+    # @example Using a block to set values
+    #   NickNameAdapter.adapt(o) { |a| a.nick_name = "Buddy!" }
+    #   NickNameAdapter.adapt(o) { |a, o| a.nick_name = "Your the best #{o.class.name} I met."}
+    # @overload adapt(o)
+    # @overload adapt(o, {|adapter| block})
+    # @overload adapt(o, {|adapter, o| block})
+    # @param o [Adaptable] object to add adapter to
+    # @yieldparam adapter [Adapter<self>] the created adapter
+    # @yieldparam o [Adaptable] optional, the given adaptable
+    # @param block [Proc] optional, evaluated in the context of the adapter (existing or new)
+    # @return [Adapter<self>] an adapter of the same class as the receiver of the call
+    # @raise [ArgumentError] if the given object o is not adaptable
+    #
+    def self.adapt(o, &block)
+      attr_name = :"@#{instance_var_name(self.name)}"
+      adapter = if existing = o.instance_variable_defined?(attr_name) && value = o.instance_variable_get(attr_name)
+        value
+      else
+        associate_adapter(create_adapter(o), o)
+      end
+      if block_given?
+        case block.arity
+          when 1
+            block.call(adapter)
+          else
+            block.call(adapter, o)
+        end
+      end
+      adapter
+    end
+
+    # Creates a new adapter, associates it with the given object and returns the adapter.
+    #
+    # @example Using a block to set values
+    #   NickNameAdapter.adapt_new(o) { |a| a.nick_name = "Buddy!" }
+    #   NickNameAdapter.adapt_new(o) { |a, o| a.nick_name = "Your the best #{o.class.name} I met."}
+    # This is used when a fresh adapter is wanted instead of possible returning an
+    # existing adapter as in the case of {Adapter.adapt}.
+    # @overload adapt_new(o)
+    # @overload adapt_new(o, {|adapter| block})
+    # @overload adapt_new(o, {|adapter, o| block})
+    # @yieldparam adapter [Adapter<self>] the created adapter
+    # @yieldparam o [Adaptable] optional, the given adaptable
+    # @param o [Adaptable] object to add adapter to
+    # @param block [Proc] optional, evaluated in the context of the new adapter
+    # @return [Adapter<self>] an adapter of the same class as the receiver of the call
+    # @raise [ArgumentError] if the given object o is not adaptable
+    #
+    def self.adapt_new(o, &block)
+      adapter = associate_adapter(create_adapter(o), o)
+      if block_given?
+        case block.arity
+        when 1
+          block.call(adapter)
+        else
+          block.call(adapter, o)
+        end
+      end
+      adapter
+    end
+
+    # Clears the adapter set in the given object o. Returns any set adapter or nil.
+    # @param o [Adaptable] the object where the adapter should be cleared
+    # @return [Adapter] if an adapter was set
+    # @return [nil] if the adapter has not been set
+    #
+    def self.clear(o)
+      attr_name = :"@#{instance_var_name(self.name)}"
+      if o.instance_variable_defined?(attr_name)
+        o.send(:remove_instance_variable, attr_name)
+      else
+        nil
+      end
+    end
+
+    # This base version creates an instance of the class (i.e. an instance of the concrete subclass
+    # of Adapter). A Specialization may want to create an adapter instance specialized for the given target
+    # object.
+    # @param o [Adaptable] The object to adapt. This implementation ignores this variable, but a
+    #   specialization may want to initialize itself differently depending on the object it is adapting.
+    # @return [Adapter<self>] instance of the subclass of Adapter receiving the call
+    #
+    def self.create_adapter(o)
+      new
+    end
+
+    # Associates the given adapter with the given target object
+    # @param adapter [Adapter] the adapter to associate with the given object _o_
+    # @param o [Adaptable] the object to adapt
+    # @return [adapter] the given adapter
+    #
+    def self.associate_adapter(adapter, o)
+      attr_name = :"@#{instance_var_name(adapter.class.name)}"
+      o.instance_variable_set(attr_name, adapter)
+      adapter
+    end
+
+    # Returns a suitable instance variable name given a class name.
+    # The returned string is the fully qualified name of a class with '::' replaced by '_' since
+    # '::' is not allowed in an instance variable name.
+    # @param name [String] the fully qualified name of a class
+    # @return [String] the name with all '::' replaced by '_'
+    # @api private
+    # @private
+    #
+    def self.instance_var_name(name)
+      name.split("::").join('_')
+    end
+  end
+end

data/lib/puppet/pops/adapters.rb

@@ -0,0 +1,65 @@
+# The Adapters module contains adapters for Documentation, Origin, SourcePosition, and Loader.
+#
+module Puppet::Pops::Adapters
+  # A documentation adapter adapts an object with a documentation string.
+  # (The intended use is for a source text parser to extract documentation and store this
+  # in DocumentationAdapter instances).
+  #
+  class DocumentationAdapter < Puppet::Pops::Adaptable::Adapter
+    # @return [String] The documentation associated with an object
+    attr_accessor :documentation
+  end
+
+  # An origin adapter adapts an object with where it came from. This origin
+  # describes the resource (a file, etc.) where source text originates.
+  # Instances of SourcePosAdapter is then used on other objects in a model to
+  # describe their relative position versus the origin.
+  #
+  # @see Puppet::Pops::Utils#find_adapter
+  #
+  class OriginAdapter < Puppet::Pops::Adaptable::Adapter
+    # @return [String] the origin of the adapted (usually a filename)
+    attr_accessor :origin
+  end
+
+  # A SourcePosAdapter describes a position relative to an origin. (Typically an {OriginAdapter} is
+  # associated with the root of a model. This origin has a URI to the resource, and a line number.
+  # The offset in the SourcePosAdapter is then relative to this origin.
+  # (This somewhat complex structure makes it possible to correctly refer to a source position
+  # in source that is embedded in some resource; a parser only sees the embedded snippet of source text
+  # and does not know where it was embedded).
+  #
+  # @see Puppet::Pops::Utils#find_adapter
+  #
+  class SourcePosAdapter < Puppet::Pops::Adaptable::Adapter
+    # @return [Fixnum] The start line in source starting from 1
+    attr_accessor :line
+
+    # @return [Fixnum] The position on the start_line (in characters) starting from 0
+    attr_accessor :pos
+
+    # @return [Fixnum] The (start) offset of source text characters
+    #   (starting from 0) representing the adapted object.
+    #   Value may be nil
+    attr_accessor :offset
+
+    # @return [Fixnum] The length (count) of characters of source text
+    #   representing the adapted object from the origin. Not including any
+    #   trailing whitespace.
+    attr_accessor :length
+  end
+
+  # A LoaderAdapter adapts an object with a {Puppet::Pops::Loader}. This is used to make further loading from the
+  # perspective of the adapted object take place in the perspective of this Loader.
+  #
+  # It is typically enough to adapt the root of a model as a search is made towards the root of the model
+  # until a loader is found, but there is no harm in duplicating this information provided a contained
+  # object is adapted with the correct loader.
+  #
+  # @see Puppet::Pops::Utils#find_adapter
+  #
+  class LoaderAdapter < Puppet::Pops::Adaptable::Adapter
+    # @return [Puppet::Pops::Loader] the loader
+    attr_accessor :loader
+  end
+end

data/lib/puppet/pops/containment.rb

@@ -0,0 +1,37 @@
+# FIXME: This module should be updated when a newer version of RGen (>0.6.2) adds required meta model "e-method" supports.
+#
+module Puppet::Pops::Containment
+  # Returns Enumerable, thus allowing
+  # some_element.eAllContents each {|contained| }
+  # This is a depth first enumeration where parent appears before children.
+  # @note the top-most object itself is not included in the enumeration, only what it contains.
+  def eAllContents
+    EAllContentsEnumerator.new(self)
+  end
+
+  class EAllContentsEnumerator
+    include Enumerable
+    def initialize o
+      @element = o
+    end
+
+    def each &block
+      if block_given?
+        eAllContents(@element, &block)
+        @element
+      else
+        self
+      end
+    end
+
+    def eAllContents(element, &block)
+      element.class.ecore.eAllReferences.select{|r| r.containment}.each do |r|
+        children = element.getGenericAsArray(r.name)
+        children.each do |c|
+          block.call(c)
+          eAllContents(c, &block)
+        end
+      end
+    end
+  end
+end

data/lib/puppet/pops/issues.rb

@@ -0,0 +1,258 @@
+# Defines classes to deal with issues, and message formatting and defines constants with Issues.
+# @api public
+#
+module Puppet::Pops::Issues
+  # Describes an issue, and can produce a message for an occurrence of the issue.
+  #
+  class Issue
+    # The issue code
+    # @return [Symbol]
+    attr_reader :issue_code
+
+    # A block producing the message
+    # @return [Proc]
+    attr_reader :message_block
+
+    # Names that must be bound in an occurrence of the issue to be able to produce a message.
+    # These are the names in addition to requirements stipulated by the Issue formatter contract; i.e. :label`,
+    # and `:semantic`.
+    #
+    attr_reader :arg_names
+
+    # If this issue can have its severity lowered to :warning, :deprecation, or :ignored
+    attr_writer :demotable
+    # Configures the Issue with required arguments (bound by occurrence), and a block producing a message.
+    def initialize issue_code, *args, &block
+      @issue_code = issue_code
+      @message_block = block
+      @arg_names = args
+      @demotable = true
+    end
+
+    # Returns true if it is allowed to demote this issue
+    def demotable?
+      @demotable
+    end
+
+    # Formats a message for an occurrence of the issue with argument bindings passed in a hash.
+    # The hash must contain a LabelProvider bound to the key `label` and the semantic model element
+    # bound to the key `semantic`. All required arguments as specified by `arg_names` must be bound
+    # in the given `hash`.
+    # @api public
+    #
+    def format(hash ={})
+      # Create a Message Data where all hash keys become methods for convenient interpolation
+      # in issue text.
+      msgdata = MessageData.new(*arg_names)
+      # Evaluate the message block in the msg data's binding
+      msgdata.format(hash, &message_block)
+    end
+  end
+
+  # Provides a binding of arguments passed to Issue.format to method names available
+  # in the issue's message producing block.
+  # @api private
+  #
+  class MessageData
+    def initialize *argnames
+      singleton = class << self; self end
+      argnames.each do |name|
+        singleton.send(:define_method, name) do
+          @data[name]
+        end
+      end
+    end
+
+    def format(hash, &block)
+      @data = hash
+      instance_eval &block
+    end
+
+    # Returns the label provider given as a key in the hash passed to #format.
+    #
+    def label
+      raise "Label provider key :label must be set to produce the text of the message!" unless @data[:label]
+      @data[:label]
+    end
+
+    # Returns the label provider given as a key in the hash passed to #format.
+    #
+    def semantic
+      raise "Label provider key :semantic must be set to produce the text of the message!" unless @data[:semantic]
+      @data[:semantic]
+    end
+  end
+
+  # Defines an issue with the given `issue_code`, additional required parameters, and a block producing a message.
+  # The block is evaluated in the context of a MessageData which provides convenient access to all required arguments
+  # via accessor methods. In addition to accessors for specified arguments, these are also available:
+  # * `label` - a `LabelProvider` that provides human understandable names for model elements and production of article (a/an/the).
+  # * `semantic` - the model element for which the issue is reported
+  #
+  # @param issue_code [Symbol] the issue code for the issue used as an identifier, should be the same as the constant
+  #   the issue is bound to.
+  # @param *args [Symbol] required arguments that must be passed when formatting the message, may be empty
+  # @param &block [Proc] a block producing the message string, evaluated in a MessageData scope. The produced string
+  #   should not end with a period as additional information may be appended.
+  #
+  # @see MessageData
+  # @api public
+  #
+  def self.issue (issue_code, *args, &block)
+    Issue.new(issue_code, *args, &block)
+  end
+
+  # Creates a non demotable issue.
+  # @see Issue.issue
+  #
+  def self.hard_issue(issue_code, *args, &block)
+    result = Issue.new(issue_code, *args, &block)
+    result.demotable = false
+    result
+  end
+
+  # @comment Here follows definitions of issues. The intent is to provide a list from which yardoc can be generated
+  #   containing more detailed information / explanation of the issue.
+  #   These issues are set as constants, but it is unfortunately not possible for the created object to easily know which
+  #   name it is bound to. Instead the constant has to be repeated. (Alternatively, it could be done by instead calling
+  #   #const_set on the module, but the extra work required to get yardoc output vs. the extra effort to repeat the name
+  #   twice makes it not worth it (if doable at all, since there is no tag to artificially construct a constant, and
+  #   the parse tag does not produce any result for a constant assignment).
+
+  # This is allowed (3.1) and has not yet been deprecated.
+  # @todo configuration
+  #
+  NAME_WITH_HYPHEN = issue :NAME_WITH_HYPHEN, :name do
+    "#{label.a_an_uc(semantic)} may not have a name contain a hyphen. The name '#{name}' is not legal"
+  end
+
+  # When a variable name contains a hyphen and these are illegal.
+  # It is possible to control if a hyphen is legal in a name or not using the setting TODO
+  # @todo describe the setting
+  # @api public
+  # @todo configuration if this is error or warning
+  #
+  VAR_WITH_HYPHEN = issue :VAR_WITH_HYPHEN, :name do
+    "A variable name may not contain a hyphen. The name '#{name}' is not legal"
+  end
+
+  # A class, definition, or node may only appear at top level or inside other classes
+  # @todo Is this really true for nodes? Can they be inside classes? Isn't that too late?
+  # @api public
+  #
+  NOT_TOP_LEVEL = hard_issue :NOT_TOP_LEVEL do
+    "Classes, definitions, and nodes may only appear at toplevel or inside other classes"
+  end
+
+  CROSS_SCOPE_ASSIGNMENT = hard_issue :CROSS_SCOPE_ASSIGNMENT, :name do
+    "Illegal attempt to assign to '#{name}'. Cannot assign to variables in other namespaces"
+  end
+
+  # Assignment can only be made to certain types of left hand expressions such as variables.
+  ILLEGAL_ASSIGNMENT = hard_issue :ILLEGAL_ASSIGNMENT do
+    "Illegal attempt to assign to '#{label.a_an(semantic)}'. Not an assignable reference"
+  end
+
+  # Assignment cannot be made to numeric match result variables
+  ILLEGAL_NUMERIC_ASSIGNMENT = issue :ILLEGAL_NUMERIC_ASSIGNMENT, :varname do
+    "Illegal attempt to assign to the numeric match result variable '$#{varname}'. Numeric variables are not assignable"
+  end
+
+  # parameters cannot have numeric names, clashes with match result variables
+  ILLEGAL_NUMERIC_PARAMETER = issue :ILLEGAL_NUMERIC_PARAMETER, :name do
+    "The numeric parameter name '$#{varname}' cannot be used (clashes with numeric match result variables)"
+  end
+
+  # In certain versions of Puppet it may be allowed to assign to a not already assigned key
+  # in an array or a hash. This is an optional validation that may be turned on to prevent accidental
+  # mutation.
+  #
+  ILLEGAL_INDEXED_ASSIGNMENT = issue :ILLEGAL_INDEXED_ASSIGNMENT do
+    "Illegal attempt to assign via [index/key]. Not an assignable reference"
+  end
+
+  # When indexed assignment ($x[]=) is allowed, the leftmost expression must be
+  # a variable expression.
+  #
+  ILLEGAL_ASSIGNMENT_VIA_INDEX = hard_issue :ILLEGAL_ASSIGNMENT_VIA_INDEX do
+    "Illegal attempt to assign to #{label.a_an(semantic)} via [index/key]. Not an assignable reference"
+  end
+
+  # Some expressions/statements may not produce a value (known as right-value, or rvalue).
+  # This may vary between puppet versions.
+  #
+  NOT_RVALUE = issue :NOT_RVALUE do
+    "Invalid use of expression. #{label.a_an_uc(semantic)} does not produce a value"
+  end
+
+  # Appending to attributes is only allowed in certain types of resource expressions.
+  #
+  ILLEGAL_ATTRIBUTE_APPEND = hard_issue :ILLEGAL_ATTRIBUTE_APPEND, :name, :parent do
+    "Illegal +> operation on attribute #{name}. This operator can not be used in #{label.a_an(parent)}"
+  end
+
+  # In case a model is constructed programmatically, it must create valid type references.
+  #
+  ILLEGAL_CLASSREF = hard_issue :ILLEGAL_CLASSREF, :name do
+    "Illegal type reference. The given name '#{name}' does not conform to the naming rule"
+  end
+
+  # This is a runtime issue - storeconfigs must be on in order to collect exported. This issue should be
+  # set to :ignore when just checking syntax.
+  # @todo should be a :warning by default
+  #
+  RT_NO_STORECONFIGS = issue :RT_NO_STORECONFIGS do
+    "You cannot collect exported resources without storeconfigs being set; the collection will be ignored"
+  end
+
+  # This is a runtime issue - storeconfigs must be on in order to export a resource. This issue should be
+  # set to :ignore when just checking syntax.
+  # @todo should be a :warning by default
+  #
+  RT_NO_STORECONFIGS_EXPORT = issue :RT_NO_STORECONFIGS_EXPORT do
+    "You cannot collect exported resources without storeconfigs being set; the export is ignored"
+  end
+
+  # A hostname may only contain letters, digits, '_', '-', and '.'.
+  #
+  ILLEGAL_HOSTNAME_CHARS = hard_issue :ILLEGAL_HOSTNAME_CHARS, :hostname do
+    "The hostname '#{hostname}' contains illegal characters (only letters, digits, '_', '-', and '.' are allowed)"
+  end
+
+  # A hostname may only contain letters, digits, '_', '-', and '.'.
+  #
+  ILLEGAL_HOSTNAME_INTERPOLATION = hard_issue :ILLEGAL_HOSTNAME_INTERPOLATION do
+    "An interpolated expression is not allowed in a hostname of a node"
+  end
+
+  # Issues when an expression is used where it is not legal.
+  # E.g. an arithmetic expression where a hostname is expected.
+  #
+  ILLEGAL_EXPRESSION = hard_issue :ILLEGAL_EXPRESSION, :feature, :container do
+    "Illegal expression. #{label.a_an_uc(semantic)} is unacceptable as #{feature} in #{label.a_an(container)}"
+  end
+
+  # Issues when an expression is used illegaly in a query.
+  # query only supports == and !=, and not <, > etc.
+  #
+  ILLEGAL_QUERY_EXPRESSION = hard_issue :ILLEGAL_QUERY_EXPRESSION do
+    "Illegal query expression. #{label.a_an_uc(semantic)} cannot be used in a query"
+  end
+
+  # If an attempt is made to make a resource default virtual or exported.
+  #
+  NOT_VIRTUALIZEABLE = hard_issue :NOT_VIRTUALIZEABLE do
+    "Resource Defaults are not virtualizable"
+  end
+
+  # When an attempt is made to use multiple keys (to produce a range in Ruby - e.g. $arr[2,-1]).
+  # This is currently not supported, but may be in future versions
+  #
+  UNSUPPORTED_RANGE = issue :UNSUPPORTED_RANGE, :count do
+    "Attempt to use unsupported range in #{label.a_an(semantic)}, #{count} values given for max 1"
+  end
+
+  DEPRECATED_NAME_AS_TYPE = issue :DEPRECATED_NAME_AS_TYPE, :name do
+    "Resource references should now be capitalized. The given '#{name}' does not have the correct form"
+  end
+end