puppet 3.1.1 → 3.2.0.rc1

data/lib/puppet/type.rb

@@ -16,7 +16,7 @@ require 'puppet/util/tagging'
 
 module Puppet
 # The base class for all Puppet types.
-#  
+#
 # A type describes:
 #--
 # * **Attributes** - properties, parameters, and meta-parameters are different types of attributes of a type.
@@ -30,7 +30,7 @@ module Puppet
 #   * **Parameters** - additional attributes of the type (that does not directly related to an instance of the managed
 #     resource; if an operation is recursive or not, where to look for things, etc.). A Parameter (in contrast to Property)
 #     has one current value where a Property has two (current-state and wanted-state).
-#   * **Meta-Parameters** - parameters that are available across all types. A meta-parameter typically has 
+#   * **Meta-Parameters** - parameters that are available across all types. A meta-parameter typically has
 #     additional semantics; like the `require` meta-parameter. A new type typically does not add new meta-parameters,
 #     but you need to be aware of their existence so you do not inadvertently shadow an existing meta-parameters.
 # * **Parent** - a type can have a super type (that it inherits from).
@@ -40,7 +40,7 @@ module Puppet
 #     by a provider) into an internal representation and vice versa. A Type supports adding custom logic for these.
 # * **Auto Requirements** - a type can specify automatic relationships to resources to ensure that if they are being
 #     managed, they will be processed before this type.
-# * **Providers** - a provider is an implementation of a type's behavior - the management of a resource in the 
+# * **Providers** - a provider is an implementation of a type's behavior - the management of a resource in the
 #     system being managed. A provider is often platform specific and is selected at runtime based on
 #     criteria/predicates specified in the configured providers. See {Puppet::Provider} for details.
 # * **Device Support** - A type has some support for being applied to a device; i.e. something that is managed
@@ -55,12 +55,12 @@ module Puppet
 #     its interface (what can be said/what is known about a resource of this type),
 # * **Managed Entity** - This is not a term in general use, but is used here when there is a need to make
 #     a distinction between a resource (a description of what/how something should be managed), and what it is
-#     managing (a file in the file system). The term _managed entity_ is a reference to the "file in the file system" 
+#     managing (a file in the file system). The term _managed entity_ is a reference to the "file in the file system"
 # * **Isomorphism** - the quality of being _isomorphic_ means that two resource instances with the same name
 #     refers to the same managed entity. Or put differently; _an isomorphic name is the identity of a resource_.
 #     As an example, `exec` resources (that executes some command) have the command (i.e. the command line string) as
 #     their name, and these resources are said to be non-isomorphic.
-# 
+#
 # @note The Type class deals with multiple concerns; some methods provide an internal DSL for convenient definition
 #   of types, other methods deal with various aspects while running; wiring up a resource (expressed in Puppet DSL
 #   or Ruby DSL) with its _resource type_ (i.e. an instance of Type) to enable validation, transformation of values
@@ -70,7 +70,7 @@ module Puppet
 #   documentation of this class, you will be switching between these concepts, as well as switching between
 #   the conceptual level "a resource is an instance of a resource-type" and the actual implementation classes
 #   (Type, Resource, Provider, and various utility and helper classes).
-# 
+#
 # @api public
 #
 #
@@ -83,7 +83,7 @@ class Type
 
   # Comparing type instances.
   include Comparable
-  
+
   # Compares this type against the given _other_ (type) and returns -1, 0, or +1 depending on the order.
   # @param other [Object] the object to compare against (produces nil, if not kind of Type}
   # @return [-1, 0, +1, nil] produces -1 if this type is before the given _other_ type, 0 if equals, and 1 if after.
@@ -102,7 +102,7 @@ class Type
   class << self
     include Puppet::Util::ClassGen
     include Puppet::Util::Warnings
-    
+
     # @return [Array<Puppet::Property>] The list of declared properties for the resource type.
     # The returned lists contains instances if Puppet::Property or its subclasses.
     attr_reader :properties
@@ -154,7 +154,7 @@ class Type
 
     @attrtypes[attr]
   end
-  
+
   # Provides iteration over meta-parameters.
   # @yieldparam p [Puppet::Parameter] each meta parameter
   # @return [void]
@@ -179,10 +179,10 @@ class Type
   # @overload ensurable({|| ... })
   # @yield [ ] A block evaluated in scope of the new Parameter
   # @yieldreturn [void]
-  # @return [void] 
+  # @return [void]
   # @dsl type
   # @api public
-  # 
+  #
   def self.ensurable(&block)
     if block_given?
       self.newproperty(:ensure, :parent => Puppet::Property::Ensure, &block)
@@ -193,7 +193,7 @@ class Type
     end
   end
 
-  # Returns true if the type implements the default behavior expected by being _ensurable_ "by default". 
+  # Returns true if the type implements the default behavior expected by being _ensurable_ "by default".
   # A type is _ensurable_ by default if it responds to `:exists`, `:create`, and `:destroy`.
   # If a type implements these methods and have not already specified that it is _ensurable_, it will be
   # made so with the defaults specified in {ensurable}.
@@ -248,7 +248,7 @@ class Type
 
   # Returns true if this type is applicable to the given target.
   # @param target [Symbol] should be :device, :host or :target, if anything else, :host is enforced
-  # @return [Boolean] true  
+  # @return [Boolean] true
   # @api private
   #
   def self.can_apply_to(target)
@@ -313,7 +313,7 @@ class Type
   # This creates a new meta-parameter that is added to all types.
   # @param name [Symbol] the name of the parameter
   # @param options [Hash] a hash with options.
-  # @option options [Class<inherits Puppet::Parameter>] :parent (Puppet::Parameter) the super class of this parameter 
+  # @option options [Class<inherits Puppet::Parameter>] :parent (Puppet::Parameter) the super class of this parameter
   # @option options [Hash{String => Object}] :attributes a hash that is applied to the generated class
   #   by calling setter methods corresponding to this hash's keys/value pairs. This is done before the given
   #   block is evaluated.
@@ -352,7 +352,7 @@ class Type
   end
 
   # Returns parameters that act as a key.
-  # All parameters that return true from #isnamevar? or is named `:name` are included in the returned result. 
+  # All parameters that return true from #isnamevar? or is named `:name` are included in the returned result.
   # @todo would like a better explanation
   # @return Array<??? Puppet::Parameter>
   #
@@ -383,10 +383,10 @@ class Type
   #   These advanced options are rarely used (only one of the built in puppet types use this, and then only
   #   a small part of the available functionality), and the support for these advanced mappings is not
   #   implemented in a straight forward way. For these reasons, this method has been marked as private).
-  #  
+  #
   # @raise [Puppet::DevError] if there is no title pattern and there are two or more key attributes
   # @return [Array<Array<Regexp, Array<Array <Symbol, Proc>>>>, nil] a structure with a regexp and the first key_attribute ???
-  # @comment This wonderful piece of logic creates a structure used by Resource.parse_title which 
+  # @comment This wonderful piece of logic creates a structure used by Resource.parse_title which
   #   has the capability to assign parts of the title to one or more attributes; It looks like an implementation
   #   of a composite identity key (all parts of the key_attributes array are in the key). This can also
   #   be seen in the method uniqueness_key.
@@ -396,7 +396,7 @@ class Type
   #   as it raises an exception if there is more than 1. Note that in puppet, it is only File that uses this
   #   to create a different pattern for assigning to the :path attribute
   #   This requires further digging.
-  #   The entire construct is somewhat strange, since resource checks if the method "title_patterns" is 
+  #   The entire construct is somewhat strange, since resource checks if the method "title_patterns" is
   #   implemented (it seems it always is) - why take this more expensive regexp mathching route for all
   #   other types?
   # @api private
@@ -422,7 +422,7 @@ class Type
   # Creates a new parameter.
   # @param name [Symbol] the name of the parameter
   # @param options [Hash] a hash with options.
-  # @option options [Class<inherits Puppet::Parameter>] :parent (Puppet::Parameter) the super class of this parameter 
+  # @option options [Class<inherits Puppet::Parameter>] :parent (Puppet::Parameter) the super class of this parameter
   # @option options [Hash{String => Object}] :attributes a hash that is applied to the generated class
   #   by calling setter methods corresponding to this hash's keys/value pairs. This is done before the given
   #   block is evaluated.
@@ -462,7 +462,7 @@ class Type
   # @param options [Hash] a hash with options.
   # @option options [Symbol] :array_matching (:first) specifies how the current state is matched against
   #   the wanted state. Use `:first` if the property is single valued, and (`:all`) otherwise.
-  # @option options [Class<inherits Puppet::Property>] :parent (Puppet::Property) the super class of this property 
+  # @option options [Class<inherits Puppet::Property>] :parent (Puppet::Property) the super class of this property
   # @option options [Hash{String => Object}] :attributes a hash that is applied to the generated class
   #   by calling setter methods corresponding to this hash's keys/value pairs. This is done before the given
   #   block is evaluated.
@@ -474,7 +474,7 @@ class Type
   # @yield [ ] a required block that is evaluated in the scope of the new property
   # @api public
   # @dsl type
-  #  
+  #
   def self.newproperty(name, options = {}, &block)
     name = name.intern
 
@@ -604,7 +604,7 @@ class Type
   #   The logic caches the name of the namevar if it is a single name, but otherwise always
   #   calls key_attributes, and then caches the first if there was only one, otherwise it returns
   #   false and caches this (which is then subsequently returned as a cache hit).
-  # 
+  #
   def name_var
     return @name_var_cache unless @name_var_cache.nil?
     key_attributes = self.class.key_attributes
@@ -634,8 +634,10 @@ class Type
   end
 
   # Sets the 'should' (wanted state) value of a property, or the value of a parameter.
-  # @return 
+  # @return
   # @raise [Puppet::Error] if the setting of the value fails, or if the given name is nil.
+  # @raise [Puppet::ResourceError] when the parameter validation raises Puppet::Error or
+  #   ArgumentError
   def []=(name,value)
     name = name.intern
 
@@ -652,9 +654,9 @@ class Type
       begin
         # make sure the parameter doesn't have any errors
         property.value = value
-      rescue => detail
-        error = Puppet::Error.new("Parameter #{name} failed on #{ref}: #{detail}")
-        error.set_backtrace(detail.backtrace)
+      rescue Puppet::Error, ArgumentError => detail
+        error = Puppet::ResourceError.new("Parameter #{name} failed on #{ref}: #{detail}")
+        adderrorcontext(error, detail)
         raise error
       end
     end
@@ -667,8 +669,8 @@ class Type
   # @todo Incomprehensible - the comment says "Remove a property", the code refers to @parameters, and
   #   the method parameter is called "attr" - What is it, property, parameter, both (i.e an attribute) or what?
   # @todo Don't know what the attr is (name or Property/Parameter?). Guessing it is a String name...
-  # @todo Is it possible to delete a meta-parameter? 
-  # @todo What does delete mean? Is it deleted from the type or is its value state 'is'/'should' deleted? 
+  # @todo Is it possible to delete a meta-parameter?
+  # @todo What does delete mean? Is it deleted from the type or is its value state 'is'/'should' deleted?
   # @param attr [String] the attribute to delete from this object. WHAT IS THE TYPE?
   # @raise [Puppet::DecError] when an attempt is made to delete an attribute that does not exists.
   #
@@ -700,13 +702,13 @@ class Type
   # @todo Needs a better explanation "Why should I care who is calling this method?", What do I need to know
   #   about events and how they work? Where can I read about them?
   # @param options [Hash] options merged with a fixed set of options defined by this method, passed on to {Puppet::Transaction::Event}.
-  # @return [Puppet::Transaction::Event] the created event 
+  # @return [Puppet::Transaction::Event] the created event
   def event(options = {})
     Puppet::Transaction::Event.new({:resource => self, :file => file, :line => line, :tags => tags}.merge(options))
   end
 
   # @return [Object, nil] Returns the 'should' (wanted state) value for a specified property, or nil if the
-  #   given attribute name is not a property (i.e. if it is a parameter, meta-parameter, or does not exist). 
+  #   given attribute name is not a property (i.e. if it is a parameter, meta-parameter, or does not exist).
   def should(name)
     name = name.intern
     (prop = @parameters[name] and prop.is_a?(Puppet::Property)) ? prop.should : nil
@@ -785,7 +787,7 @@ class Type
   #   to self.class.attrclass to produce a class on which a check is made if it has a method class :default (does
   #   not seem to support an array...
   # @return [void]
-  # 
+  #
   def set_default(attr)
     return unless klass = self.class.attrclass(attr)
     return unless klass.method_defined?(:default)
@@ -802,7 +804,7 @@ class Type
 
   # @todo the comment says: "Convert our object to a hash.  This just includes properties."
   # @todo this is confused, again it is the @parameters instance variable that is consulted, and
-  #   each value is copied - does it contain "properties" and "parameters" or both? Does it contain 
+  #   each value is copied - does it contain "properties" and "parameters" or both? Does it contain
   #   meta-parameters?
   #
   # @return [Hash{ ??? => ??? }] a hash of WHAT?. The hash is a shallow copy, any changes to the
@@ -901,7 +903,6 @@ class Type
   ###############################
   # Code related to the container behaviour.
 
-  
   # Returns true if the search should be done in depth-first order.
   # This implementation always returns false.
   # @todo What is this used for?
@@ -940,7 +941,6 @@ class Type
   ###############################
   # Code related to evaluating the resources.
 
-  
   # Returns the ancestors - WHAT?
   # This implementation always returns an empty list.
   # @todo WHAT IS THIS ?
@@ -1068,7 +1068,7 @@ class Type
     end
   end
 
-  # Returns the `noop` run mode status of this. 
+  # Returns the `noop` run mode status of this.
   # @return [Boolean] true if running in noop mode.
   def noop?
     # If we're not a host_config, we're almost certainly part of
@@ -1088,7 +1088,7 @@ class Type
   end
 
   # Retrieves all known instances.
-  # @todo Retrieves them from where? Known to whom? 
+  # @todo Retrieves them from where? Known to whom?
   # Either requires providers or must be overridden.
   # @raise [Puppet::DevError] when there are no providers and the implementation has not overridded this method.
   def self.instances
@@ -1375,7 +1375,7 @@ class Type
 
   # RelationshipMetaparam is an implementation supporting the meta-parameters `:require`, `:subscribe`,
   # `:notify`, and `:before`.
-  # 
+  #
   #
   class RelationshipMetaparam < Puppet::Parameter
     class << self
@@ -1417,13 +1417,13 @@ class Type
     # The `:in` relationships are specified by the event-receivers, and `:out`
     # relationships are specified by the event generator.
     # @todo references to "event-receivers" and "event generator" means in this context - are those just
-    #   the resources at the two ends of the relationship? 
+    #   the resources at the two ends of the relationship?
     # This way 'source' and 'target' are consistent terms in both edges
     # and events, i.e. an event targets edges whose source matches
     # the event's source. The direction of the relationship determines
     # which resource is applied first and which resource is considered
     # to be the event generator.
-    # @return [Array<Puppet::Relationship>] 
+    # @return [Array<Puppet::Relationship>]
     # @raise [???fail] when a reference can not be resolved
     #
     def to_edges
@@ -1465,7 +1465,7 @@ class Type
   end
 
   # @todo document this, have no clue what this does... it retuns "RelationshipMetaparam.subclasses"
-  # 
+  #
   def self.relationship_params
     RelationshipMetaparam.subclasses
   end
@@ -1630,7 +1630,7 @@ class Type
     # @api private
     #
     attr_accessor :providerloader
-    
+
     # @todo Don't know if this is a name, or a reference to a Provider instance (now marked up as an instance
     #   of Provider.
     # @return [Puppet::Provider, nil] The default provider for this type, or nil if non is defines
@@ -1705,7 +1705,7 @@ class Type
   # this type.
   # @todo How does the provider know if it is suitable for the type? Is it just suitable for the platform/
   #   environment where this method is executing?
-  # @param name [String] the name of the provider for which validity is checked 
+  # @param name [String] the name of the provider for which validity is checked
   # @return [Boolean] true if the given name references a provider that is suitable
   #
   def self.validprovider?(name)
@@ -1720,12 +1720,12 @@ class Type
   #   Is this a new provider of a Type (metatype), or a provider of an instance of Type (a resource), or
   #   a Provider (the implementation of a Type's behavior). CONFUSED. It calls magically named methods like
   #   "providify" ...
-  # @param name [String, Symbol] the name of the WHAT? provider? type? 
+  # @param name [String, Symbol] the name of the WHAT? provider? type?
   # @param options [Hash{Symbol => Object}] a hash of options, used by this method, and passed on to {#genclass}, (see
   #   it for additional options to pass).
   # @option options [Puppet::Provider] :parent the parent provider (what is this?)
   # @option options [Puppet::Type] :resource_type the resource type, defaults to this type if unspecified
-  # @return [Puppet::Provider] a provider ??? 
+  # @return [Puppet::Provider] a provider ???
   # @raise [Puppet::DevError] when the parent provider could not be found.
   #
   def self.provide(name, options = {}, &block)
@@ -1849,7 +1849,7 @@ class Type
     rmclass(name, :hash => provider_hash, :prefix => "Provider")
   end
 
-  # Returns a list of suitable providers for the given type. 
+  # Returns a list of suitable providers for the given type.
   # A call to this method will load all providers if not already loaded and ask each if it is
   # suitable - those that are are included in the result.
   # @note This method also does some special processing which rejects a provider named `:fake` (for testing purposes).
@@ -1866,7 +1866,7 @@ class Type
 
   # @return [Boolean] Returns true if this is something else than a `:provider`, or if it
   #   is a provider and it is suitable, or if there is a default provider. Otherwise, false is returned.
-  # 
+  #
   def suitable?
     # If we don't use providers, then we consider it suitable.
     return true unless self.class.paramclass(:provider)
@@ -1909,11 +1909,10 @@ class Type
   ###############################
   # All of the relationship code.
 
-  
   # Adds a block producing a single name (or list of names) of the given resource type name to autorequire.
   # @example Autorequire the files File['foo', 'bar']
   #   autorequire( 'file', {|| ['foo', 'bar'] })
-  # 
+  #
   # @todo original = _"Specify a block for generating a list of objects to autorequire.
   #   This makes it so that you don't have to manually specify things that you clearly require."_
   # @param name [String] the name of a type of which one or several resources should be autorequired e.g. "file"
@@ -1944,9 +1943,9 @@ class Type
   # See {autorequire} for how to add an auto-requirement.
   # @todo needs details - see the param rel_catalog, and type of this param
   # @param rel_catalog [Puppet::Catalog, nil] the catalog to add dependencies to. Defaults to the
-  #   catalog (TODO: what is the type of the catalog). 
+  #   catalog (TODO: what is the type of the catalog).
   # @raise [Puppet::DevError] if there is no catalog
-  # 
+  #
   def autorequire(rel_catalog = nil)
     rel_catalog ||= catalog
     raise(Puppet::DevError, "You cannot add relationships without a catalog") unless rel_catalog
@@ -2005,7 +2004,7 @@ class Type
   #  are orphaned ... I think they can just be removed as what they say should be covered
   #  by the now added yardoc. <irony>(Yo! to quote some of the other actual awsome specific comments applicable
   #  to objects called from elsewhere, or not. ;-)</irony>
-  # 
+  #
   # @comment Types (which map to resources in the languages) are entirely composed of
   #   attribute value pairs.  Generally, Puppet calls any of these things an
   #   'attribute', but these attributes always take one of three specific
@@ -2014,13 +2013,12 @@ class Type
   # @comment In naming methods, I have tried to consistently name the method so
   #   that it is clear whether it operates on all attributes (thus has 'attr' in
   #   the method name, or whether it operates on a specific type of attributes.
-  
-  
+
   # The title attribute of WHAT ???
   # @todo Figure out what this is the title attribute of (it appears on line 1926 currently).
   # @return [String] the title
   attr_writer :title
-  
+
   # The noop attribute of WHAT ??? does WHAT???
   # @todo Figure out what this is the noop attribute of (it appears on line 1931 currently).
   # @return [???] the noop WHAT ??? (mode? if so of what, or noop for an instance of the type, or for all
@@ -2039,7 +2037,7 @@ class Type
     # @return [String] the name of the resource type; e.g., "File"
     #
     attr_reader :name
-    
+
     # @return [Boolean] true if the type should send itself a refresh event on change.
     #
     attr_accessor :self_refresh
@@ -2051,7 +2049,7 @@ class Type
   end
 
   # Initializes all of the variables that must be initialized for each subclass.
-  # @todo Does the explanation make sense? 
+  # @todo Does the explanation make sense?
   # @return [void]
   def self.initvars
     # all of the instances of this class
@@ -2084,7 +2082,7 @@ class Type
   # The returned name is on the form "Puppet::Type::<name>", where the first letter of name is
   # capitalized.
   # @return [String] the fully qualified name Puppet::Type::<name> where the first letter of name is captialized
-  # 
+  #
   def self.to_s
     if defined?(@name)
       "Puppet::Type::#{@name.to_s.capitalize}"
@@ -2111,7 +2109,7 @@ class Type
 
   # @return [String] The file from which this type originates from
   attr_accessor :file
-  
+
   # @return [Integer] The line in {#file} from which this type originates from
   attr_accessor :line
 
@@ -2160,9 +2158,13 @@ class Type
   #   causes the title to be resource.ref ("for components") - what is a component?
   #
   # @overaload initialize(hsh)
-  #   @param hsh [Hash] 
+  #   @param hsh [Hash]
+  #   @raise [Puppet::ResourceError] when the type validation raises
+  #     Puppet::Error or ArgumentError
   # @overload initialize(resource)
   #   @param resource [Puppet:Resource]
+  #   @raise [Puppet::ResourceError] when the type validation raises
+  #     Puppet::Error or ArgumentError
   #
   def initialize(resource)
     resource = self.class.hash2resource(resource) unless resource.is_a?(Puppet::Resource)
@@ -2195,7 +2197,13 @@ class Type
 
     set_parameters(@original_parameters)
 
-    self.validate if self.respond_to?(:validate)
+    begin
+      self.validate if self.respond_to?(:validate)
+    rescue Puppet::Error, ArgumentError => detail
+      error = Puppet::ResourceError.new("Validation of #{ref} failed: #{detail}")
+      adderrorcontext(error, detail)
+      raise error
+    end
   end
 
   private
@@ -2205,9 +2213,9 @@ class Type
   # given by the corresponding entry in the given hash - e.g. if name_var appoints the name `:path` the value
   # of `:path` is set to the value at the key `:path` in the given hash. As a side effect this key/value is then
   # removed from the given hash.
-  # 
+  #
   # @note This method mutates the given hash by removing the entry with a key equal to the value
-  #   returned from name_var! 
+  #   returned from name_var!
   # @param hash [Hash] a hash of what
   # @return [void]
   def set_name(hash)
@@ -2215,7 +2223,7 @@ class Type
   end
 
   # Sets parameters from the given hash.
-  # Values are set in _attribute order_ i.e. higher priority attributes before others, otherwise in 
+  # Values are set in _attribute order_ i.e. higher priority attributes before others, otherwise in
   # the order they were specified (as opposed to just setting them in the order they happen to appear in
   # when iterating over the given hash).
   #
@@ -2257,12 +2265,12 @@ class Type
   public
 
   # Finishes any outstanding processing.
-  # This method should be called as a final step in setup, 
+  # This method should be called as a final step in setup,
   # to allow the parameters that have associated auto-require needs to be processed.
-  # 
+  #
   # @todo what is the expected sequence here - who is responsible for calling this? When?
   #   Is the returned type correct?
-  # @return [Array<Puppet::Parameter>] the validated list/set of attributes 
+  # @return [Array<Puppet::Parameter>] the validated list/set of attributes
   #
   def finish
     # Make sure all of our relationships are valid.  Again, must be done
@@ -2349,9 +2357,9 @@ class Type
   # @todo it is somewhat confusing that if the name_var is a valid parameter, it is assumed to
   #  be the name_var called :name, but if it is a property, it uses the name_var.
   #  It is further confusing as Type in some respects supports multiple namevars.
-  #  
+  #
   # @return [String] Returns the title of this object, or it's name if title was not explicetly set.
-  # @raise [??? devfail] if title is not set, and name_var can not be found. 
+  # @raise [??? devfail] if title is not set, and name_var can not be found.
   def title
     unless @title
       if self.class.validparameter?(name_var)
@@ -2375,7 +2383,7 @@ class Type
 
   # @todo What to resource? Which one of the resource forms is prroduced? returned here?
   # @return [??? Resource] a resource that WHAT???
-  # 
+  #
   def to_resource
     resource = self.retrieve_resource
     resource.tag(*self.tags)