puppet 3.1.1 → 3.2.0.rc1

data/lib/puppet/pops/validation/validator_factory_3_1.rb

@@ -0,0 +1,41 @@
+# Configures validation suitable for 3.1 + iteration
+#
+class Puppet::Pops::Validation::ValidatorFactory_3_1
+  Issues = Puppet::Pops::Issues
+
+  # Produces a validator with the given acceptor as the recipient of produced diagnostics.
+  #
+  def validator acceptor
+    checker(diagnostic_producer(acceptor))
+  end
+
+  # Produces the diagnostics producer to use given an acceptor as the recipient of produced diagnostics
+  #
+  def diagnostic_producer acceptor
+    Puppet::Pops::Validation::DiagnosticProducer.new(acceptor, severity_producer(), label_provider())
+  end
+
+  # Produces the checker to use
+  def checker diagnostic_producer
+    Puppet::Pops::Validation::Checker3_1.new(diagnostic_producer)
+  end
+
+  # Produces the label provider to use
+  def label_provider
+    Puppet::Pops::Model::ModelLabelProvider.new()
+  end
+
+  # Produces the severity producer to use
+  def severity_producer
+    p = Puppet::Pops::Validation::SeverityProducer.new
+
+    # Configure each issue that should **not** be an error
+    #
+    p[Issues::RT_NO_STORECONFIGS_EXPORT]    = :warning
+    p[Issues::RT_NO_STORECONFIGS]           = :warning
+    p[Issues::NAME_WITH_HYPHEN]             = :deprecation
+    p[Issues::DEPRECATED_NAME_AS_TYPE]      = :deprecation
+
+    p
+  end
+end

data/lib/puppet/pops/visitable.rb

@@ -0,0 +1,6 @@
+# Visitable is a mix-in module that makes a class visitable by a Visitor
+module Puppet::Pops::Visitable
+  def accept(visitor, *arguments)
+    visitor.visit(self, *arguments)
+  end
+end

data/lib/puppet/pops/visitor.rb

@@ -0,0 +1,50 @@
+# A Visitor performs delegation to a given receiver based on the configuration of the Visitor.
+# A new visitor is created with a given receiver, a method prefix, min, and max argument counts.
+# e.g.
+#   vistor = Visitor.new(self, "visit_from", 1, 1)
+# will make the visitor call "self.visit_from_CLASS(x)" where CLASS is resolved to the given
+# objects class, or one of is ancestors, the first class for which there is an implementation of
+# a method will be selected.
+#
+# Raises RuntimeError if there are too few or too many arguments, or if the receiver is not
+# configured to handle a given visiting object.
+#
+class Puppet::Pops::Visitor
+  attr_reader :receiver, :message, :min_args, :max_args, :cache
+  def initialize(receiver, message, min_args=0, max_args=nil)
+    raise ArgumentError.new("min_args must be >= 0") if min_args < 0
+    raise ArgumentError.new("max_args must be >= min_args or nil") if max_args && max_args < min_args
+
+    @receiver = receiver
+    @message = message
+    @min_args = min_args
+    @max_args = max_args
+    @cache = Hash.new
+  end
+
+  # Visit the configured receiver
+  def visit(thing, *args)
+    visit_this(@receiver, thing, *args)
+  end
+
+  # Visit an explicit receiver
+  def visit_this(receiver, thing, *args)
+    raise "Visitor Error: Too few arguments passed. min = #{@min_args}" unless args.length >= @min_args
+    if @max_args
+      raise "Visitor Error: Too many arguments passed. max = #{@max_args}" unless args.length <= @max_args
+    end
+    if method_name = @cache[thing.class]
+      return receiver.send(method_name, thing, *args)
+    else
+      thing.class.ancestors().each do |ancestor|
+        method_name = :"#{@message}_#{ancestor.name.split("::").last}"
+        # DEBUG OUTPUT
+        # puts "Visitor checking: #{receiver.class}.#{method_name}, responds to: #{@receiver.respond_to? method_name}"
+        next unless receiver.respond_to? method_name
+        @cache[thing.class] = method_name
+        return receiver.send(method_name, thing, *args)
+      end
+    end
+    raise "Visitor Error: the configured receiver (#{receiver.class}) can't handle instance of: #{thing.class}"
+  end
+end

data/lib/puppet/property.rb

@@ -18,11 +18,11 @@ require 'puppet/parameter'
 # value _(should)_ is read and written with the methods {#value} and {#value=} which delegate to
 # {#should} and {#should=}, i.e. when a property is used like any other parameter, it is the _should_ value
 # that is operated on.
-# 
+#
 # All resource type properties in the puppet system are derived from this class.
 #
 # The intention is that new parameters are created by using the DSL method {Puppet::Type.newproperty}.
-# 
+#
 # @abstract
 # @note Properties of Types are expressed using subclasses of this class. Such a class describes one
 #   named property of a particular Type (as opposed to describing a type of property in general). This
@@ -35,12 +35,12 @@ require 'puppet/parameter'
 #
 # @todo Describe meta-parameter shadowing. This concept can not be understood by just looking at the descriptions
 #   of the methods involved.
-# 
+#
 # @see Puppet::Type
 # @see Puppet::Parameter
 #
 # @api public
-# 
+#
 class Puppet::Property < Puppet::Parameter
   require 'puppet/property/ensure'
 
@@ -52,9 +52,9 @@ class Puppet::Property < Puppet::Parameter
 
   # The noop mode for this property.
   # By setting a property's noop mode to `true`, any management of this property is inhibited. Calculation
-  # and reporting still takes place, but if a change of the underlying managed entity's state 
+  # and reporting still takes place, but if a change of the underlying managed entity's state
   # should take place it will not be carried out. This noop
-  # setting overrides the overall `Puppet[:noop]` mode as well as the noop mode in the _associated resource_ 
+  # setting overrides the overall `Puppet[:noop]` mode as well as the noop mode in the _associated resource_
   #
   attr_writer :noop
 
@@ -63,21 +63,21 @@ class Puppet::Property < Puppet::Parameter
     #   reads or writes this attribute.
     # ??? Probably Unused
     attr_accessor :unmanaged
-    
+
     # @return [Symbol] The name of the property as given when the property was created.
-    # 
+    #
     attr_reader :name
 
     # @!attribute [rw] array_matching
     # @comment note that $#46; is a period - char code require to not terminate sentence.
     # The `is` vs&#46; `should` array matching mode; `:first`, or `:all`.
-    # 
+    #
     # @comment there are two blank chars after the symbols to cause a break - do not remove these.
-    # * `:first`  
+    # * `:first`
     #   This is primarily used for single value properties. When matched against an array of values
     #   a match is true if the `is` value matches any of the values in the `should` array. When the `is` value
     #   is also an array, the matching is performed against the entire array as the `is` value.
-    # * `:all`  
+    # * `:all`
     #   : This is primarily used for multi-valued properties. When matched against an array of
     #     `should` values, the size of `is` and `should` must be the same, and all values in `is` must match
     #     a value in `should`.
@@ -104,7 +104,7 @@ class Puppet::Property < Puppet::Parameter
   end
 
   # Looks up a value's name among valid values, to enable option lookup with result as a key.
-  # @param name [Object] the parameter value to match against valid values (names). 
+  # @param name [Object] the parameter value to match against valid values (names).
   # @return {Symbol, Regexp} a value matching predicate
   # @api private
   #
@@ -142,6 +142,10 @@ class Puppet::Property < Puppet::Parameter
   #   was possible to specify a value of `:before` or `:after` for the purpose of calling
   #   both the block and the provider. Use of these deprecated options will now raise an exception later
   #   in the process when the _is_ value is set (see #set).
+  # @option options [Symbol] :invalidate_refreshes Indicates a change on this property should invalidate and
+  #   remove any scheduled refreshes (from notify or subscribe) targeted at the same resource. For example, if
+  #   a change in this property takes into account any changes that a scheduled refresh would have performed,
+  #   then the scheduled refresh would be deleted.
   # @option options [Object] any Any other option is treated as a call to a setter having the given
   #   option name (e.g. `:required_features` calls `required_features=` with the option's value as an
   #   argument).
@@ -160,7 +164,7 @@ class Puppet::Property < Puppet::Parameter
     value
   end
 
-  # Calls the provider setter method for this property with the given value as argument.  
+  # Calls the provider setter method for this property with the given value as argument.
   # @return [Object] what the provider returns when calling a setter for this property's name
   # @raise [Puppet::Error] when the provider can not handle this property.
   # @see #set
@@ -254,18 +258,23 @@ class Puppet::Property < Puppet::Parameter
 
   # Produces an event describing a change of this property.
   # In addition to the event attributes set by the resource type, this method adds:
-  # 
+  #
   # * `:name` - the event_name
   # * `:desired_value` - a.k.a _should_ or _wanted value_
   # * `:property` - reference to this property
   # * `:source_description` - the _path_ (?? See todo)
+  # * `:invalidate_refreshes` - if scheduled refreshes should be invalidated
   #
   # @todo What is the intent of this method? What is the meaning of the :source_description passed in the
   #   options to the created event?
-  # @return [Puppet::Transaction::Event] the created event 
+  # @return [Puppet::Transaction::Event] the created event
   # @see Puppet::Type#event
   def event
-    resource.event :name => event_name, :desired_value => should, :property => self, :source_description => path
+    attrs = { :name => event_name, :desired_value => should, :property => self, :source_description => path }
+    if should and value = self.class.value_collection.match?(should)
+      attrs[:invalidate_refreshes] = true if value.invalidate_refreshes
+    end
+    resource.event attrs
   end
 
   # @todo What is this?
@@ -274,9 +283,9 @@ class Puppet::Property < Puppet::Parameter
 
   # Initializes a Property the same way as a Parameter and handles the special case when a property is shadowing a meta-parameter.
   # @todo There is some special initialization when a property is not a metaparameter but
-  #   Puppet::Type.metaparamclass(for this class's name) is not nil - if that is the case a 
+  #   Puppet::Type.metaparamclass(for this class's name) is not nil - if that is the case a
   #   setup_shadow is performed for that class.
-  # 
+  #
   # @param hash [Hash] options passed to the super initializer {Puppet::Parameter#initialize}
   # @note New properties of a type should be created via the DSL method {Puppet::Type.newproperty}.
   # @see Puppet::Parameter#initialize description of Parameter initialize options.
@@ -372,11 +381,11 @@ class Puppet::Property < Puppet::Parameter
 
   # Checks if the given current and desired values are equal.
   # This default implementation performs this check in a backwards compatible way where
-  # the equality of the two values is checked, and then the equality of current with desired 
+  # the equality of the two values is checked, and then the equality of current with desired
   # converted to a string.
-  # 
+  #
   # A derived implementation may override this method to perform a property specific equality check.
-  # 
+  #
   # The intent of this method is to provide an equality check suitable for checking if the property
   # value is in sync or not. It is typically called from {#insync?}.
   #
@@ -438,7 +447,7 @@ class Puppet::Property < Puppet::Parameter
   # the _associated resource_ and finally in Puppet[:noop].
   # @todo This logic is different than Parameter#noop in that the resource noop mode overrides
   #   the property's mode - in parameter it is the other way around. Bug or feature?
-  # 
+  #
   def noop
     # This is only here to make testing easier.
     if @resource.respond_to?(:noop?)
@@ -457,7 +466,7 @@ class Puppet::Property < Puppet::Parameter
   # same name as this property (i.e. if the property name is 'gid', a call to the
   # 'provider.gid' is expected to return the current value.
   # @return [Object] what the provider returns as the current value of the property
-  # 
+  #
   def retrieve
     provider.send(self.class.name)
   end
@@ -517,10 +526,10 @@ class Puppet::Property < Puppet::Parameter
   # If the _array matching mode_ {#match_all?} is true, an array of the wanted values in unmunged format
   # is returned, else the first value in the array of wanted values in unmunged format is returned.
   # @return [Array<Object>, Object, nil] Array of values if {#match_all?} else a single value, or nil if there are no
-  #   wanted values. 
+  #   wanted values.
   # @raise [Puppet::DevError] if the wanted value is non nil and not an array
   #
-  # @note This method will potentially return different values than the original values as they are 
+  # @note This method will potentially return different values than the original values as they are
   #   converted via munging/unmunging. If the original values are wanted, call {#shouldorig}.
   #
   # @see #shouldorig
@@ -565,8 +574,8 @@ class Puppet::Property < Puppet::Parameter
 
   # Synchronizes the current value _(is)_ and the wanted value _(should)_ by calling {#set}.
   # @raise [Puppet::DevError] if {#should} is nil
-  # @todo The implementation of this method is somewhat inefficient as it computes the should 
-  #  array twice. 
+  # @todo The implementation of this method is somewhat inefficient as it computes the should
+  #  array twice.
   def sync
     devfail "Got a nil value for should" unless should
     set(should)
@@ -587,7 +596,7 @@ class Puppet::Property < Puppet::Parameter
   # @raise [ArgumentError] if a required feature is not present
   # @return [void]
   # @api private
-  # 
+  #
   def validate_features_per_value(value)
     if features = self.class.value_option(self.class.value_name(value), :required_features)
       features = Array(features)

data/lib/puppet/property/ensure.rb

@@ -67,10 +67,10 @@ class Puppet::Property::Ensure < Puppet::Property
   # The existence of the resource is checked by first consulting the provider (if it responds to
   # `:exists`), and secondly the resource. A a value of `:present` or `:absent` is returned
   # depending on if the managed entity exists or not.
-  # 
+  #
   # @return [Symbol] a value of `:present` or `:absent` depending on if it exists or not
   # @raise [Puppet::DevError] if neither the provider nor the resource responds to `:exists`
-  # 
+  #
   def retrieve
     # XXX This is a problem -- whether the object exists or not often
     # depends on the results of other properties, yet we're the first property

data/lib/puppet/property/ordered_list.rb

@@ -6,7 +6,7 @@ module Puppet
     # The maintained order is the order defined by the 'current' set of values (i.e. the
     # original order is not disrupted). Any additions are added after the current values
     # in their given order).
-    # 
+    #
     # For an unordered list see {Puppet::Property::List}.
     #
     class OrderedList < List

data/lib/puppet/provider.rb

@@ -14,7 +14,7 @@
 #   lifecycle (creates, destroys), or alters some value reflected backed by a property).
 # * **Flush** - is a hook that is called once per resource when everything has been applied. The intent is
 #   that an implementation may defer modification of the current state typically done in property setters
-#   and instead record information that allows flush to perform the changes more efficiently.  
+#   and instead record information that allows flush to perform the changes more efficiently.
 # * **Execution Methods** -  The execution methods provides access to execution of arbitrary commands.
 #   As a convenience execution methods are available on both the instance and the class of a provider since a
 #   lot of provider logic switch between these contexts fairly freely.
@@ -30,8 +30,7 @@
 #
 # @note Class level methods are only called once to configure the provider (when the type is created), and not
 #   for each resource the provider is operating on.
-#   The instance methods are however called for each resource. 
-# 
+#   The instance methods are however called for each resource.
 #
 # @api public
 #
@@ -52,11 +51,11 @@ class Puppet::Provider
     # Include the util module so we have access to things like 'which'
     include Puppet::Util, Puppet::Util::Docs
     include Puppet::Util::Logging
-    
+
     # @return [String] The name of the provider
     attr_accessor :name
 
-    # 
+    #
     # @todo Original = _"The source parameter exists so that providers using the same
     #   source can specify this, so reading doesn't attempt to read the
     #   same package multiple times."_ This seems to be a package type specific attribute. Is this really
@@ -72,19 +71,19 @@ class Puppet::Provider
     # @api private
     # @deprecated This attribute is available for backwards compatibility reasons.
     attr_reader :model
-    
+
     # @todo What is this type? A reference to a Puppet::Type ?
     # @return [Puppet::Type] the resource type (that this provider is ... WHAT?)
     #
     attr_accessor :resource_type
-    
+
     # @!attribute [r] doc
     #   The (full) documentation for this provider class. The documentation for the provider class itself
     #   should be set with the DSL method {desc=}. Setting the documentation with with {doc=} has the same effect
     #   as setting it with {desc=} (only the class documentation part is set). In essence this means that
     #   there is no getter for the class documentation part (since the getter returns the full
     #   documentation when there are additional contributors).
-    #   
+    #
     #   @return [String] Returns the full documentation for the provider.
     # @see Puppet::Utils::Docs
     # @comment This is puzzling ... a write only doc attribute??? The generated setter never seems to be
@@ -96,17 +95,15 @@ class Puppet::Provider
     #   {doc} attribute).
     #
     #   @dsl type
-    # 
     #
     attr_writer :doc
-    
   end
 
   # @todo original = _"LAK 2007-05-09: Keep the model stuff around for backward compatibility"_, why is it
   #   both here (instance) and at class level? Is this a different model?
   # @return [???] model is WHAT?
   attr_reader :model
-  
+
   # @return [???] This resource is what? Is an instance of a provider attached to one particular Puppet::Resource?
   #
   attr_accessor :resource
@@ -168,11 +165,11 @@ class Puppet::Provider
   # Confines this provider to be suitable only on hosts where the given commands are present.
   # Also see {Puppet::Provider::Confiner#confine} for other types of confinement of a provider by use of other types of
   # predicates.
-  # 
+  #
   # @note It is preferred if the commands are not entered with absolute paths as this allows puppet
   #   to search for them using the PATH variable.
   #
-  # @param command_specs [Hash{String => String}] Map of name to command that the provider will 
+  # @param command_specs [Hash{String => String}] Map of name to command that the provider will
   #   be executing on the system. Each command is specified with a name and the path of the executable.
   # @return [void]
   # @see optional_commands
@@ -188,7 +185,7 @@ class Puppet::Provider
   # is lazy (when a resource is evaluated) and the absence of commands
   # that will be present after other resources have been applied no longer needs to be specified as
   # optional.
-  # @param [Hash{String => String}] command_specs Named commands that the provider will 
+  # @param [Hash{String => String}] command_specs Named commands that the provider will
   #   be executing on the system. Each command is specified with a name and the path of the executable.
   # (@see #has_command)
   # @see commands
@@ -202,8 +199,8 @@ class Puppet::Provider
 
   # Creates a convenience method for invocation of a command.
   #
-  # This generates a Provider method that allows easy execution of the command. The generated 
-  # method may take arguments that will be passed through to the executable as the command line arguments 
+  # This generates a Provider method that allows easy execution of the command. The generated
+  # method may take arguments that will be passed through to the executable as the command line arguments
   # when it is invoked.
   #
   # @example Use it like this:
@@ -223,7 +220,7 @@ class Puppet::Provider
   # @yield [ ] A block that configures the command (see {Puppet::Provider::Command})
   # @comment a yield [ ] produces {|| ...} in the signature, do not remove the space.
   # @note the name ´has_command´ looks odd in an API context, but makes more sense when seen in the internal
-  #   DSL context where a Provider is declaratively defined. 
+  #   DSL context where a Provider is declaratively defined.
   #
   def self.has_command(name, path, &block)
     name = name.intern
@@ -325,9 +322,9 @@ class Puppet::Provider
   #
   # The _ancestors_ is the Ruby Module::ancestors method and the number of classes returned is used
   # to boost the score. The intent is that if two providers are equal, but one is more "derived" than the other
-  # (i.e. includes more classes), it should win because it is more specific). 
+  # (i.e. includes more classes), it should win because it is more specific).
   # @note Because of how this value is
-  #   calculated there could be surprising side effects if a provider included an excessive amount of classes. 
+  #   calculated there could be surprising side effects if a provider included an excessive amount of classes.
   #
   def self.specificity
     # This strange piece of logic attempts to figure out how many parent providers there
@@ -356,9 +353,9 @@ class Puppet::Provider
   #
   # An implementation of this method should only cache the values of properties
   # if they are discovered as part of the process for finding existing resources.
-  # Resource properties that require additional commands (than those used to determine existence/identity) 
+  # Resource properties that require additional commands (than those used to determine existence/identity)
   # should be implemented in their respective getter method. (This is important from a performance perspective;
-  # it may be expensive to compute, as well as wasteful as all discovered resources may perhaps not be managed). 
+  # it may be expensive to compute, as well as wasteful as all discovered resources may perhaps not be managed).
   #
   # An implementation may return an empty list (naturally with the effect that it is not possible to query
   # for manageable entities).
@@ -370,7 +367,7 @@ class Puppet::Provider
   # @return [Array<Puppet::Provider>] a list of providers referencing the system entities
   # @abstract this method must be implemented by a subclass and this super method should never be called as it raises an exception.
   # @raise [Puppet::DevError] Error indicating that the method should have been implemented by subclass.
-  # @see prefetch 
+  # @see prefetch
   def self.instances
     raise Puppet::DevError, "Provider #{self.name} has not defined the 'instances' class method"
   end
@@ -406,7 +403,7 @@ class Puppet::Provider
   # The generated methods may be overridden by more advanced implementations if something
   # else than a straight forward getter/setter pair of methods is required.
   # (i.e. define such overriding methods after this method has been called)
-  # 
+  #
   # An implementor of a provider that makes use of `prefetch` and `flush` can use this method since it uses
   # the internal `@property_hash` variable to store values. An implementation would then update the system
   # state on a call to `flush` based on the current values in the `@property_hash`.
@@ -447,7 +444,7 @@ class Puppet::Provider
   private_class_method :create_class_and_instance_method
 
   # @return [String] Returns the data source, which is the provider name if no other source has been set.
-  # @todo Unclear what "the source" is used for? 
+  # @todo Unclear what "the source" is used for?
   def self.source
     @source ||= self.name
   end
@@ -508,7 +505,7 @@ class Puppet::Provider
     end
   end
 
-  # Clears this provider instance to allow GC to clean up. 
+  # Clears this provider instance to allow GC to clean up.
   def clear
     @resource = nil
     @model = nil
@@ -532,8 +529,8 @@ class Puppet::Provider
   # it is remembered for further operations. If a hash is used it becomes the internal `@property_hash`
   # structure of the provider - this hash holds the current state property values of system entities
   # as they are being discovered by querying or other operations (typically getters).
-  # 
-  # @todo The use of a hash as a parameter needs a better exaplanation; why is this done? What is the intent? 
+  #
+  # @todo The use of a hash as a parameter needs a better exaplanation; why is this done? What is the intent?
   # @param resource [Puppet::Resource, Hash] optional resource or hash
   #
   def initialize(resource = nil)
@@ -596,7 +593,7 @@ class Puppet::Provider
     # Otherwise, order by the providers class name.
     return self.class.name <=> other.class.name
   end
-  
+
   # @comment Document prefetch here as it does not exist anywhere else (called from transaction if implemented)
   # @!method self.prefetch(resource_hash)
   # @abstract A subclass may implement this - it is not implemented in the Provider class
@@ -605,13 +602,12 @@ class Puppet::Provider
   # fetched state (i.e. what is returned from the {instances} method).
   # @param resources_hash [Hash<{String => Puppet::Resource}>] map from name to resource of resources to prefetch
   # @return [void]
-  
+
   # @comment Document flush here as it does not exist anywhere (called from transaction if implemented)
   # @!method flush()
   # @abstract A subclass may implement this - it is not implemented in the Provider class
   # This method may be implemented by a provider in order to flush properties that has not been individually
   # applied to the managed entity's current state.
   # @return [void]
-
 end