class Puppet::Type

@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

@return [String] the name of the resource type; e.g., “File”

The reference to a parent type for the parameter `:provider` used to get a list of providers for documentation purposes.

@return [Array<Puppet::Property>] The list of declared properties for the resource type. The returned lists contains instances if Puppet::Property or its subclasses.

The loader of providers to use when loading providers from disk. Although it looks like this attribute provides a way to operate with different loaders of providers that is not the case; the attribute is written when a new type is created, and should not be changed thereafter. @api private

@return [Boolean] true if the type should send itself a refresh event on change.

@todo what does this mean “this resource” (sounds like this if for an instance of the type, not the meta Type),

but not sure if this is about the catalog where the meta Type is included)

@return [??? TODO] The catalog that this resource is stored in.

@return [Boolean] Flag indicating if this type is exported

@return [String] The file from which this type originates from

@return [Integer] The line in {file} from which this type originates from

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

instances of a type, or for what???

@return [Hash] hash of parameters originally defined @api private

The provider that has been selected for the instance of the resource type. @return [Puppet::Provider,nil] the selected provider or nil, if none has been selected

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

@return [Boolean] Flag indicating if the type is virtual (it should not be).

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.

Returns nil, if the given _other_ is not a kind of Type.

@see Comparable

# File lib/puppet/type.rb, line 91
def <=>(other)
  # We only order against other types, not arbitrary objects.
  return nil unless other.is_a? Puppet::Type
  # Our natural order is based on the reference name we use when comparing
  # against other type instances.
  self.ref <=> other.ref
end

Gets the ‘should’ (wanted state) value of a parameter or property by name. To explicitly get the ‘is’ (current state) value use `o.is(:name)`, and to explicitly get the ‘should’ value use `o.should(:name)` @param name [String] the name of the attribute to obtain the ‘should’ value for. @return [Object] ‘should’/wanted value of the given attribute

# File lib/puppet/type.rb, line 617
def [](name)
  name = name.intern
  fail("Invalid parameter #{name}(#{name.inspect})") unless self.class.validattr?(name)

  if name == :name && nv = name_var
    name = nv
  end

  if obj = @parameters[name]
    # Note that if this is a property, then the value is the "should" value,
    # not the current value.
    obj.value
  else
    return nil
  end
end

Sets the ‘should’ (wanted state) value of a property, or the value of a parameter. @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

# File lib/puppet/type.rb, line 639
def []=(name,value)
  name = name.intern

  fail("Invalid parameter #{name}") unless self.class.validattr?(name)

  if name == :name && nv = name_var
    name = nv
  end
  raise Puppet::Error.new("Got nil value for #{name}") if value.nil?

  property = self.newattr(name)

  if property
    begin
      # make sure the parameter doesn't have any errors
      property.value = value
    rescue Puppet::Error, ArgumentError => detail
      error = Puppet::ResourceError.new("Parameter #{name} failed on #{ref}: #{detail}")
      adderrorcontext(error, detail)
      raise error
    end
  end

  nil
end

Creates a new property value holder for the resource if it is valid and does not already exist @return [Boolean] true if a new parameter was added, false otherwise

# File lib/puppet/type.rb, line 591
def add_property_parameter(prop_name)
  if self.class.validproperty?(prop_name) && !@parameters[prop_name]
    self.newattr(prop_name)
    return true
  end
  false
end

Returns the ancestors - WHAT? This implementation always returns an empty list. @todo WHAT IS THIS ? @return [Array<???>] returns a list of ancestors.

# File lib/puppet/type.rb, line 963
def ancestors
  []
end

@return [Boolean] Returns whether the resource is applicable to `:device` Returns true if a resource of this type can be evaluated on a ‘network device’ kind of hosts. @api private

# File lib/puppet/type.rb, line 2439
def appliable_to_device?
  self.class.can_apply_to(:device)
end

@return [Boolean] Returns whether the resource is applicable to `:host` Returns true if a resource of this type can be evaluated on a regular generalized computer (ie not an appliance like a network device) @api private

# File lib/puppet/type.rb, line 2446
def appliable_to_host?
  self.class.can_apply_to(:host)
end

Adds dependencies to the catalog from added autorequirements. 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::Resource::Catalog, nil] the catalog to

add dependencies to. Defaults to the current catalog (set when the
type instance was added to a catalog)

@raise [Puppet::DevError] if there is no catalog

# File lib/puppet/type.rb, line 1977
def autorequire(rel_catalog = nil)
  rel_catalog ||= catalog
  raise(Puppet::DevError, "You cannot add relationships without a catalog") unless rel_catalog

  reqs = []
  self.class.eachautorequire { |type, block|
    # Ignore any types we can't find, although that would be a bit odd.
    next unless Puppet::Type.type(type)

    # Retrieve the list of names from the block.
    next unless list = self.instance_eval(&block)
    list = [list] unless list.is_a?(Array)

    # Collect the current prereqs
    list.each { |dep|
      # Support them passing objects directly, to save some effort.
      unless dep.is_a? Puppet::Type
        # Skip autorequires that we aren't managing
        unless dep = rel_catalog.resource(type, dep)
          next
        end
      end

      reqs << Puppet::Relationship.new(dep, self)
    }
  }

  reqs
end

Builds the dependencies associated with this resource.

@return [Array<Puppet::Relationship>] list of relationships to other resources

# File lib/puppet/type.rb, line 2010
def builddepends
  # Handle the requires
  self.class.relationship_params.collect do |klass|
    if param = @parameters[klass.name]
      param.to_edges
    end
  end.flatten.reject { |r| r.nil? }
end

Returns a hash of the current properties and their values. If a resource is absent, its value is the symbol `:absent` @return [Hash{Puppet::Property => Object}] mapping of property instance to its value

# File lib/puppet/type.rb, line 1092
def currentpropvalues
  # It's important to use the 'properties' method here, as it follows the order
  # in which they're defined in the class.  It also guarantees that 'ensure'
  # is the first property, which is important for skipping 'retrieve' on
  # all the properties if the resource is absent.
  ensure_state = false
  return properties.inject({}) do | prophash, property|
    if property.name == :ensure
      ensure_state = property.retrieve
      prophash[property] = ensure_state
    else
      if ensure_state == :absent
        prophash[property] = :absent
      else
        prophash[property] = property.retrieve
      end
    end
    prophash
  end
end

Removes an attribute from the object; useful in testing or in cleanup when an error has been encountered @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? @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.

# File lib/puppet/type.rb, line 673
def delete(attr)
  attr = attr.intern
  if @parameters.has_key?(attr)
    @parameters.delete(attr)
  else
    raise Puppet::DevError.new("Undefined attribute '#{attr}' in #{self}")
  end
end

@return [Boolean] Returns true if the wanted state of the resoure is that it should be absent (i.e. to be deleted).

# File lib/puppet/type.rb, line 585
def deleting?
  obj = @parameters[:ensure] and obj.should == :absent
end

Returns true if the search should be done in depth-first order. This implementation always returns false. @todo What is this used for?

@return [Boolean] true if the search should be done in depth first order.

# File lib/puppet/type.rb, line 927
def depthfirst?
  false
end

Iterates over all parameters with value currently set. @yieldparam parameter [Puppet::Parameter] or a subclass thereof @return [void]

# File lib/puppet/type.rb, line 702
def eachparameter
  parameters_with_value.each { |parameter| yield parameter }
end

Iterates over the properties that were set on this resource. @yieldparam property [Puppet::Property] each property @return [void]

# File lib/puppet/type.rb, line 685
def eachproperty
  # properties is a private method
  properties.each { |property|
    yield property
  }
end

Creates a transaction event. Called by Transaction or by a property. Merges the given options with the options `:resource`, `:file`, `:line`, and `:tags`, initialized from values in this object. For possible options to pass (if any ????) see {Puppet::Transaction::Event}. @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

# File lib/puppet/type.rb, line 714
def event(options = {})
  Puppet::Transaction::Event.new({:resource => self, :file => file, :line => line, :tags => tags}.merge(options))
end

@return [Boolean] Returns whether the resource is exported or not

# File lib/puppet/type.rb, line 2433
def exported?; !!@exported; end

Finishes any outstanding processing. 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

# File lib/puppet/type.rb, line 2299
def finish
  # Call post_compile hook on every parameter that implements it. This includes all subclasses
  # of parameter including, but not limited to, regular parameters, metaparameters, relationship
  # parameters, and properties.
  eachparameter do |parameter|
    parameter.post_compile if parameter.respond_to? :post_compile
  end

  # Make sure all of our relationships are valid.  Again, must be done
  # when the entire catalog is instantiated.
  self.class.relationship_params.collect do |klass|
    if param = @parameters[klass.name]
      param.validate_relationship
    end
  end.flatten.reject { |r| r.nil? }
end

Flushes the provider if supported by the provider, else no action. This is called by the transaction. @todo What does Flushing the provider mean? Why is it interesting to know that this is

called by the transaction? (It is not explained anywhere what a transaction is).

@return [???, nil] WHAT DOES IT RETURN? GUESS IS VOID

# File lib/puppet/type.rb, line 989
def flush
  self.provider.flush if self.provider and self.provider.respond_to?(:flush)
end

Returns true if all contained objects are in sync. @todo “contained in what?” in the given “in” parameter?

@todo deal with the comment _“FIXME I don’t think this is used on the type instances any more,

it's really only used for testing"_

@return [Boolean] true if in sync, false otherwise.

# File lib/puppet/type.rb, line 1000
def insync?(is)
  insync = true

  if property = @parameters[:ensure]
    unless is.include? property
      raise Puppet::DevError,
        "The is value is not in the is array for '#{property.name}'"
    end
    ensureis = is[property]
    if property.safe_insync?(ensureis) and property.should == :absent
      return true
    end
  end

  properties.each { |property|
    unless is.include? property
      raise Puppet::DevError,
        "The is value is not in the is array for '#{property.name}'"
    end

    propis = is[property]
    unless property.safe_insync?(propis)
      property.debug("Not in sync: #{propis.inspect} vs #{property.should.inspect}")
      insync = false
    #else
    #    property.debug("In sync")
    end
  }

  #self.debug("#{self} sync status is #{insync}")
  insync
end

@todo check that this gets documentation (it is at the class level as well as instance). (see isomorphic?)

# File lib/puppet/type.rb, line 889
def isomorphic?
  self.class.isomorphic?
end

Creates a log entry with the given message at the log level specified by the parameter `loglevel` @return [void]

# File lib/puppet/type.rb, line 2154
def log(msg)

  Puppet::Util::Log.create(

    :level => @parameters[:loglevel].value,
    :message => msg,

    :source => self
  )
end

Returns true if the instance is a managed instance. A ‘yes’ here means that the instance was created from the language, vs. being created in order resolve other questions, such as finding a package in a list. @note An object that is managed always stays managed, but an object that is not managed

may become managed later in its lifecycle.

@return [Boolean] true if the object is managed

# File lib/puppet/type.rb, line 899
def managed?
  # Once an object is managed, it always stays managed; but an object
  # that is listed as unmanaged might become managed later in the process,
  # so we have to check that every time
  if @managed
    return @managed
  else
    @managed = false
    properties.each { |property|
      s = property.should
      if s and ! property.class.unmanaged
        @managed = true
        break
      end
    }
    return @managed
  end
end

@comment For now, leave the ‘name’ method functioning like it used to. Once ‘title’

works everywhere, I'll switch it.

Returns the resource’s name @todo There is a comment in source that this is not quite the same as ‘:title’ and that a switch should

be made...

@return [String] the name of a resource

# File lib/puppet/type.rb, line 2322
def name
  self[:name]
end

@return [Symbol, Boolean] Returns the name of the namevar if there is only one or false otherwise. @comment This is really convoluted and part of the support for multiple namevars (?).

If there is only one namevar, the produced value is naturally this namevar, but if there are several?
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).

# File lib/puppet/type.rb, line 606
def name_var
  return @name_var_cache unless @name_var_cache.nil?
  key_attributes = self.class.key_attributes
  @name_var_cache = (key_attributes.length == 1) && key_attributes.first
end

Registers an attribute to this resource type insance. Requires either the attribute name or class as its argument. This is a noop if the named property/parameter is not supported by this resource. Otherwise, an attribute instance is created and kept in this resource’s parameters hash. @overload newattr(name)

@param name [Symbol] symbolic name of the attribute

@overload newattr(klass)

@param klass [Class] a class supported as an attribute class, i.e. a subclass of
  Parameter or Property

@return [Object] An instance of the named Parameter or Property class associated

to this resource type instance, or nil if the attribute is not supported

# File lib/puppet/type.rb, line 738
def newattr(name)
  if name.is_a?(Class)
    klass = name
    name = klass.name
  end

  unless klass = self.class.attrclass(name)
    raise Puppet::Error, "Resource type #{self.class.name} does not support parameter #{name}"
  end

  if provider and ! provider.class.supports_parameter?(klass)
    missing = klass.required_features.find_all { |f| ! provider.class.feature?(f) }
    debug "Provider %s does not support features %s; not managing attribute %s" % [provider.class.name, missing.join(", "), name]
    return nil
  end

  return @parameters[name] if @parameters.include?(name)

  @parameters[name] = klass.new(:resource => self)
end

(see noop?)

# File lib/puppet/type.rb, line 1128
def noop
  noop?
end

Returns the `noop` run mode status of this. @return [Boolean] true if running in noop mode.

# File lib/puppet/type.rb, line 1115
def noop?
  # If we're not a host_config, we're almost certainly part of
  # Settings, and we want to ignore 'noop'
  return false if catalog and ! catalog.host_config?

  if defined?(@noop)
    @noop
  else
    Puppet[:noop]
  end
end

Returns the value of this object’s parameter given by name @param name [String] the name of the parameter @return [Object] the value

# File lib/puppet/type.rb, line 769
def parameter(name)
  @parameters[name.to_sym]
end

Returns a shallow copy of this object’s hash of attributes by name. Note that his not only comprises parameters, but also properties and metaparameters. Changes to the contained parameters will have an effect on the parameters of this type, but changes to the returned hash does not. @return [Hash{String => Object}] a new hash being a shallow copy of the parameters map name to parameter

# File lib/puppet/type.rb, line 778
def parameters
  @parameters.dup
end

Return the parameters, metaparams, and properties that have a value or were set by a default. Properties are included since they are a subclass of parameter. @return [Array<Puppet::Parameter>] Array of parameter objects ( or subclass thereof )

# File lib/puppet/type.rb, line 695
def parameters_with_value
  self.class.allattrs.collect { |attr| parameter(attr) }.compact
end

Returns the parent of this in the catalog. In case of an erroneous catalog where multiple parents have been produced, the first found (non deterministic) parent is returned. @return [Puppet::Type, nil] the

containing resource or nil if there is no catalog or no containing
resource.

# File lib/puppet/type.rb, line 2332
def parent
  return nil unless catalog

  @parent ||=
    if parents = catalog.adjacent(self, :direction => :in)
      parents.shift
    else
      nil
    end
end

Returns a string representation of the resource’s containment path in the catalog. @return [String]

# File lib/puppet/type.rb, line 762
def path
  @path ||= '/' + pathbuilder.join('/')
end

Returns an array of strings representing the containment heirarchy (types/classes) that make up the path to the resource from the root of the catalog. This is mostly used for logging purposes.

@api private

# File lib/puppet/type.rb, line 1211
def pathbuilder
  if p = parent
    [p.pathbuilder, self.ref].flatten
  else
    [self.ref]
  end
end

Lifecycle method for a resource. This is called during graph creation. It should perform any consistency checking of the catalog and raise a Puppet::Error if the transaction should be aborted.

It differs from the validate method, since it is called later during initialization and can rely on self.catalog to have references to all resources that comprise the catalog.

@see Puppet::Transaction#add_vertex @raise [Puppet::Error] If the pre-run check failed. @return [void] @abstract a resource type may implement this method to perform

validation checks that can query the complete catalog

# File lib/puppet/type.rb, line 980
def pre_run_check
end

Given the hash of current properties, should this resource be treated as if it currently exists on the system. May need to be overridden by types that offer up more than just :absent and :present.

# File lib/puppet/type.rb, line 1084
def present?(current_values)
  current_values[:ensure] != :absent
end

@return [Array<Puppet::Property>] Returns all of the property objects, in the order specified in the

class.

@todo “what does the ‘order specified in the class’ mean? The order the properties where added in the

ruby file adding a new type with new properties?

# File lib/puppet/type.rb, line 870
def properties
  self.class.properties.collect { |prop| @parameters[prop.name] }.compact
end

Returns a {Puppet::Property} instance by name. To return the value, use ‘resource’ @todo LAK:NOTE(20081028) Since the ‘parameter’ method is now a superset of this method,

this one should probably go away at some point. - Does this mean it should be deprecated ?

@return [Puppet::Property] the property with the given name, or nil if not a property or does not exist.

# File lib/puppet/type.rb, line 794
def property(name)
  (obj = @parameters[name.intern] and obj.is_a?(Puppet::Property)) ? obj : nil
end

@return [Boolean] Returns whether the attribute given by name has been added

to this resource or not.

# File lib/puppet/type.rb, line 784
def propertydefined?(name)
  name = name.intern unless name.is_a? Symbol
  @parameters.include?(name)
end

Sets the provider to the given provider/name. @overload provider=(name)

Sets the provider to the result of resolving the name to an instance of Provider.
@param name [String] the name of the provider

@overload provider=(provider)

Sets the provider to the given instances of Provider.
@param provider [Puppet::Provider] the provider to set

@return [Puppet::Provider] the provider set @raise [ArgumentError] if the provider could not be found/resolved.

# File lib/puppet/type.rb, line 1924
def provider=(name)
  if name.is_a?(Puppet::Provider)
    @provider = name
    @provider.resource = self
  elsif klass = self.class.provider(name)
    @provider = klass.new(self)
  else
    raise ArgumentError, "Could not find #{name} provider of #{self.class.name}"
  end
end

Marks the object as “being purged”. This method is used by transactions to forbid deletion when there are dependencies. @todo what does this mean; “mark that we are purging” (purging what from where). How to use/when?

Is this internal API in transactions?

@see purging?

# File lib/puppet/type.rb, line 2365
def purging
  @purging = true
end

Returns whether this resource is being purged or not. This method is used by transactions to forbid deletion when there are dependencies. @return [Boolean] the current “purging” state

# File lib/puppet/type.rb, line 2373
def purging?
  if defined?(@purging)
    @purging
  else
    false
  end
end

Returns a reference to this as a string in “Type” format. @return [String] a reference to this object on the form ‘Type’

# File lib/puppet/type.rb, line 2346
def ref
  # memoizing this is worthwhile ~ 3 percent of calls are the "first time
  # around" in an average run of Puppet. --daniel 2012-07-17
  @ref ||= "#{self.class.name.to_s.capitalize}[#{self.title}]"
end

Removes this object (FROM WHERE?) @todo removes if from where? @overload remove(rmdeps)

@deprecated Use remove()
@param rmdeps [Boolean] intended to indicate that all subscriptions should also be removed, ignored.

@overload remove() @return [void]

# File lib/puppet/type.rb, line 939
def remove(rmdeps = true)
  # This is hackish (mmm, cut and paste), but it works for now, and it's
  # better than warnings.
  @parameters.each do |name, obj|
    obj.remove
  end
  @parameters.clear

  @parent = nil

  # Remove the reference to the provider.
  if self.provider
    @provider.clear
    @provider = nil
  end
end

Retrieves the current value of all contained properties. Parameters and meta-parameters are not included in the result. @todo As oposed to all non contained properties? How is this different than any of the other

methods that also "gets" properties/parameters/etc. ?

@return [Puppet::Resource] array of all property values (mix of types) @raise [fail???] if there is a provider and it is not suitable for the host this is evaluated for.

# File lib/puppet/type.rb, line 1039
def retrieve
  fail "Provider #{provider.class.name} is not functional on this host" if self.provider.is_a?(Puppet::Provider) and ! provider.class.suitable?

  result = Puppet::Resource.new(self.class, title)

  # Provide the name, so we know we'll always refer to a real thing
  result[:name] = self[:name] unless self[:name] == title

  if ensure_prop = property(:ensure) or (self.class.validattr?(:ensure) and ensure_prop = newattr(:ensure))
    result[:ensure] = ensure_state = ensure_prop.retrieve
  else
    ensure_state = nil
  end

  properties.each do |property|
    next if property.name == :ensure
    if ensure_state == :absent
      result[property] = :absent
    else
      result[property] = property.retrieve
    end
  end

  result
end

Retrieve the current state of the system as a Puppet::Resource. For the base Puppet::Type this does the same thing as retrieve, but specific types are free to implement retrieve as returning a hash, and this will call retrieve and convert the hash to a resource. This is used when determining when syncing a resource.

@return [Puppet::Resource] A resource representing the current state

of the system.

@api private

# File lib/puppet/type.rb, line 1075
def retrieve_resource
  resource = retrieve
  resource = Resource.new(self.class, title, :parameters => resource) if resource.is_a? Hash
  resource
end

(see ::self_refresh) @todo check that meaningful yardoc is produced - this method delegates to “self.class.self_refresh” @return [Boolean] - ??? returns true when … what?

# File lib/puppet/type.rb, line 2356
def self_refresh?
  self.class.self_refresh
end

@todo comment says “For any parameters or properties that have defaults and have not yet been

set, set them now.  This method can be handed a list of attributes,
and if so it will only set defaults for those attributes."

@todo Needs a better explanation, and investigation about the claim an array can be passed (it is passed

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]

# File lib/puppet/type.rb, line 806
def set_default(attr)
  return unless klass = self.class.attrclass(attr)
  return unless klass.method_defined?(:default)
  return if @parameters.include?(klass.name)

  return unless parameter = newattr(klass.name)

  if value = parameter.default and ! value.nil?
    parameter.value = value
  else
    @parameters.delete(parameter.name)
  end
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).

# File lib/puppet/type.rb, line 720
def should(name)
  name = name.intern
  (prop = @parameters[name] and prop.is_a?(Puppet::Property)) ? prop.should : nil
end

@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.

# File lib/puppet/type.rb, line 1896
def suitable?
  # If we don't use providers, then we consider it suitable.
  return true unless self.class.paramclass(:provider)

  # We have a provider and it is suitable.
  return true if provider && provider.class.suitable?

  # We're using the default provider and there is one.
  if !provider and self.class.defaultprovider
    self.provider = self.class.defaultprovider.name
    return true
  end

  # We specified an unsuitable provider, or there isn't any suitable
  # provider.
  false
end

Sets the initial list of tags to associate to this resource.

@return [void] ???

# File lib/puppet/type.rb, line 2022
def tags=(list)
  tag(self.class.name)
  tag(*list)
end

Returns the title of this object, or its name if title was not explicetly set. If the title is not already set, it will be computed by looking up the {name_var} and using that value as the title. @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 its name if title was not explicetly set. @raise [??? devfail] if title is not set, and #name_var can not be found.

# File lib/puppet/type.rb, line 2390
def title
  unless @title
    if self.class.validparameter?(name_var)
      @title = self[:name]
    elsif self.class.validproperty?(name_var)
      @title = self.should(name_var)
    else
      self.devfail "Could not find namevar #{name_var} for #{self.class.name}"
    end
  end

  @title
end

@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
meta-parameters?

@return [Hash{ ??? => ??? }] a hash of WHAT?. The hash is a shallow copy, any changes to the

objects returned in this hash will be reflected in the original resource having these attributes.

# File lib/puppet/type.rb, line 828
def to_hash
  rethash = {}

  @parameters.each do |name, obj|
    rethash[name] = obj.value
  end

  rethash
end

Convert this resource type instance to a Puppet::Resource. @return [Puppet::Resource] Returns a serializable representation of this resource

# File lib/puppet/type.rb, line 2414
def to_resource
  resource = self.retrieve_resource
  resource.tag(*self.tags)

  @parameters.each do |name, param|
    # Avoid adding each instance name twice
    next if param.class.isnamevar? and param.value == self.title

    # We've already got property values
    next if param.is_a?(Puppet::Property)
    resource[name] = param.value
  end

  resource
end

Produces a reference to this in reference format. @see ref

# File lib/puppet/type.rb, line 2407
def to_s
  self.ref
end

@return [String] the name of this object’s class @todo Would that be “file” for the “File” resource type? of “File” or something else?

# File lib/puppet/type.rb, line 841
def type
  self.class.name
end

Produces a resource’s #uniqueness_key (or composite key). This key is an array of all key attributes’ values. Each distinct tuple must be unique for each resource type. @see ::key_attributes @return [Object] an object that is a #uniqueness_key for this object

# File lib/puppet/type.rb, line 416
def uniqueness_key
  self.class.key_attributes.sort_by { |attribute_name| attribute_name.to_s }.map{ |attribute_name| self[attribute_name] }
end

@todo Comment says “Return a specific value for an attribute.”, as opposed to what “An upspecific value”??? @todo is this the ‘is’ or the ‘should’ value? @todo why is the return restricted to things that respond to :value? (Only non structural basic data types

supported?

@return [Object, nil] the value of the attribute having the given name, or nil if the given name is not

an attribute, or the referenced attribute does not respond to `:value`.

# File lib/puppet/type.rb, line 852
def value(name)
  name = name.intern

  (obj = @parameters[name] and obj.respond_to?(:value)) ? obj.value : nil
end

@todo What is this used for? Needs a better explanation. @return [???] the version of the catalog or 0 if there is no catalog.

# File lib/puppet/type.rb, line 860
def version
  return 0 unless catalog
  catalog.version
end

@return [Boolean] Returns whether the resource is virtual or not

# File lib/puppet/type.rb, line 2431
def virtual?;  !!@virtual;  end

Returns all the attribute names of the type in the appropriate order. The {::key_attributes} come first, then the {provider}, then the {properties}, and finally the {parameters} and {metaparams}, all in the order they were specified in the respective files. @return [Array<String>] all type attribute names in a defined order.

# File lib/puppet/type.rb, line 115
def self.allattrs
  key_attributes | (parameters & [:provider]) | properties.collect { |property| property.name } | parameters | metaparams
end

Makes this type apply to `:host` if not already applied to something else. @return [Symbol] a `:device`, `:host`, or `:both` enumeration @api private

# File lib/puppet/type.rb, line 243
def self.apply_to
  @apply_to ||= :host
end

Makes this type applicable to `:both` (i.e. `:host` and `:device`). @return [Symbol] Returns `:both` @api private

# File lib/puppet/type.rb, line 236
def self.apply_to_all
  @apply_to = :both
end

@comment These `::apply_to` methods are horrible. They should really be implemented

as part of the usual system of constraints that apply to a type and
provider pair, but were implemented as a separate shadow system.

@comment We should rip them out in favour of a real constraint pattern around the

target device - whatever that looks like - and not have this additional
magic here. --daniel 2012-03-08

Makes this type applicable to `:device`. @return [Symbol] Returns `:device` @api private

# File lib/puppet/type.rb, line 220
def self.apply_to_device
  @apply_to = :device
end

Makes this type applicable to `:host`. @return [Symbol] Returns `:host` @api private

# File lib/puppet/type.rb, line 228
def self.apply_to_host
  @apply_to = :host
end

Returns the class associated with the given attribute name. @param name [String] the name of the attribute to obtain the class for @return [Class, nil] the class for the given attribute, or nil if the name does not refer to an existing attribute

# File lib/puppet/type.rb, line 123
def self.attrclass(name)
  @attrclasses ||= {}

  # We cache the value, since this method gets called such a huge number
  # of times (as in, hundreds of thousands in a given run).
  unless @attrclasses.include?(name)
    @attrclasses[name] = case self.attrtype(name)
    when :property; @validproperties[name]
    when :meta; @@metaparamhash[name]
    when :param; @paramhash[name]
    end
  end
  @attrclasses[name]
end

Returns the attribute type (`:property`, `;param`, `:meta`). @comment What type of parameter are we dealing with? Cache the results, because

this method gets called so many times.

@return [Symbol] a symbol describing the type of attribute (`:property`, `;param`, `:meta`)

# File lib/puppet/type.rb, line 143
def self.attrtype(attr)
  @attrtypes ||= {}
  unless @attrtypes.include?(attr)
    @attrtypes[attr] = case
      when @validproperties.include?(attr); :property
      when @paramhash.include?(attr); :param
      when @@metaparamhash.include?(attr); :meta
      end
  end

  @attrtypes[attr]
end

Adds a block producing a single name (or list of names) of the given resource type name to autorequire. Resources in the catalog that have the named type and a title that is included in the result will be linked to the calling resource as a requirement.

@example Autorequire the files File[‘foo’, ‘bar’]

autorequire( 'file', {|| ['foo', 'bar'] })

@param name [String] the name of a type of which one or several resources should be autorequired e.g. “file” @yield [ ] a block returning list of names of given type to auto require @yieldreturn [String, Array<String>] one or several resource names for the named type @return [void] @dsl type @api public

# File lib/puppet/type.rb, line 1952
def self.autorequire(name, &block)
  @autorequires ||= {}
  @autorequires[name] = block
end

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 @api private

# File lib/puppet/type.rb, line 252
def self.can_apply_to(target)
  [ target == :device ? :device : :host, :both ].include?(apply_to)
end

The default provider, or the most suitable provider if no default provider was set. @note a warning will be issued if no default provider has been configured and a search for the most

suitable provider returns more than one equally suitable provider.

@return [Puppet::Provider, nil] the default or most suitable provider, or nil if no provider was found

# File lib/puppet/type.rb, line 1672
def self.defaultprovider
  return @defaultprovider if @defaultprovider

  suitable = suitableprovider

  # Find which providers are a default for this system.
  defaults = suitable.find_all { |provider| provider.default? }

  # If we don't have any default we use suitable providers
  defaults = suitable if defaults.empty?
  max = defaults.collect { |provider| provider.specificity }.max
  defaults = defaults.find_all { |provider| provider.specificity == max }

  if defaults.length > 1
    Puppet.warning(
      "Found multiple default providers for #{self.name}: #{defaults.collect { |i| i.name.to_s }.join(", ")}; using #{defaults[0].name}"
    )
  end

  @defaultprovider = defaults.shift unless defaults.empty?
end

Provides the ability to add documentation to a provider.

# File lib/puppet/type.rb, line 1826
def self.doc
  # Since we're mixing @doc with text from other sources, we must normalize
  # its indentation with scrub. But we don't need to manually scrub the
  # provider's doc string, since markdown_definitionlist sanitizes its inputs.
  scrub(@doc) + "Available providers are:\n\n" + parenttype.providers.sort { |a,b|
    a.to_s <=> b.to_s
  }.collect { |i|
    markdown_definitionlist( i, scrub(parenttype().provider(i).doc) )
  }.join
end

Provides iteration over added auto-requirements (see {autorequire}). @yieldparam type [String] the name of the type to autoriquire an instance of @yieldparam block [Proc] a block producing one or several dependencies to auto require (see {autorequire}). @yieldreturn [void] @return [void]

# File lib/puppet/type.rb, line 1962
def self.eachautorequire
  @autorequires ||= {}
  @autorequires.each { |type, block|
    yield(type, block)
  }
end

Provides iteration over meta-parameters. @yieldparam p [Puppet::Parameter] each meta parameter @return [void]

# File lib/puppet/type.rb, line 160
def self.eachmetaparam
  @@metaparams.each { |p| yield p.name }
end

Creates a new `ensure` property with configured default values or with configuration by an optional block. This method is a convenience method for creating a property `ensure` with default accepted values. If no block is specified, the new `ensure` property will accept the default symbolic values `:present`, and `:absent` - see {Puppet::Property::Ensure}. If something else is wanted, pass a block and make calls to {Puppet::Property.newvalue} from this block to define each possible value. If a block is passed, the defaults are not automatically added to the set of valid values.

@note This method will be automatically called without a block if the type implements the methods

specified by {ensurable?}. It is recommended to always call this method and not rely on this automatic
specification to clearly state that the type is ensurable.

@overload ensurable() @overload ensurable({|| … }) @yield [ ] A block evaluated in scope of the new Parameter @yieldreturn [void] @return [void] @dsl type @api public

# File lib/puppet/type.rb, line 184
def self.ensurable(&block)
  if block_given?
    self.newproperty(:ensure, :parent => Puppet::Property::Ensure, &block)
  else
    self.newproperty(:ensure, :parent => Puppet::Property::Ensure) do
      self.defaultvalues
    end
  end
end

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}. @return [Boolean] whether the type is ensurable or not.

# File lib/puppet/type.rb, line 200
def self.ensurable?
  # If the class has all three of these methods defined, then it's
  # ensurable.
  [:exists?, :create, :destroy].all? { |method|
    self.public_method_defined?(method)
  }
end

Processes the options for a named parameter. @param name [String] the name of a parameter @param options [Hash] a hash of options @option options [Boolean] :boolean if option set to true, an access method on the form name? is added for the param @return [void]

# File lib/puppet/type.rb, line 262
def self.handle_param_options(name, options)
  # If it's a boolean parameter, create a method to test the value easily
  if options[:boolean]
    define_method(name.to_s + "?") do
      val = self[name]
      if val == :true or val == true
        return true
      end
    end
  end
end

Converts a simple hash into a Resource instance. @todo as opposed to a complex hash? Other raised exceptions? @param [Hash{Symbol, String => Object}] hash resource attribute to value map to initialize the created resource from @return [Puppet::Resource] the resource created from the hash @raise [Puppet::Error] if a title is missing in the given hash

# File lib/puppet/type.rb, line 1186
def self.hash2resource(hash)
  hash = hash.inject({}) { |result, ary| result[ary[0].to_sym] = ary[1]; result }

  title = hash.delete(:title)
  title ||= hash[:name]
  title ||= hash[key_attributes.first] if key_attributes.length == 1

  raise Puppet::Error, "Title or name must be provided" unless title

  # Now create our resource.
  resource = Puppet::Resource.new(self, title)
  resource.catalog = hash.delete(:catalog)

  hash.each do |param, value|
    resource[param] = value
  end
  resource
end

Initializes all of the variables that must be initialized for each subclass. @todo Does the explanation make sense? @return [void]

# File lib/puppet/type.rb, line 2079
def self.initvars
  # all of the instances of this class
  @objects = Hash.new
  @aliases = Hash.new

  @defaults = {}

  @parameters ||= []

  @validproperties = {}
  @properties = []
  @parameters = []
  @paramhash = {}

  @paramdoc = Hash.new { |hash,key|
    key = key.intern if key.is_a?(String)
    if hash.include?(key)
      hash[key]
    else
      "Param Documentation for #{key} not found"
    end
  }

  @doc ||= ""

end

Retrieves all known instances. @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.

# File lib/puppet/type.rb, line 1136
def self.instances
  raise Puppet::DevError, "#{self.name} has no providers and has not overridden 'instances'" if provider_hash.empty?

  # Put the default provider first, then the rest of the suitable providers.
  provider_instances = {}
  providers_by_source.collect do |provider|
    self.properties.find_all do |property|
      provider.supports_parameter?(property)
    end.collect do |property|
      property.name
    end

    provider.instances.collect do |instance|
      # We always want to use the "first" provider instance we find, unless the resource
      # is already managed and has a different provider set
      if other = provider_instances[instance.name]
        Puppet.debug "%s %s found in both %s and %s; skipping the %s version" %
          [self.name.to_s.capitalize, instance.name, other.class.name, instance.class.name, instance.class.name]
        next
      end
      provider_instances[instance.name] = instance

      result = new(:name => instance.name, :provider => instance)
      properties.each { |name| result.newattr(name) }
      result
    end
  end.flatten.compact
end

Returns true if the type’s notion of name is the identity of a resource. See the overview of this class for a longer explanation of the concept isomorphism. Defaults to true.

@return [Boolan] true, if this type’s name is isomorphic with the object

# File lib/puppet/type.rb, line 879
def self.isomorphic?
  if defined?(@isomorphic)
    return @isomorphic
  else
    return true
  end
end

Returns the list of parameters that comprise the composite key / “uniqueness key”. All parameters that return true from isnamevar? or is named `:name` are included in the returned result. @see #uniqueness_key @return [Array<Puppet::Parameter>] WARNING: this return type is uncertain

# File lib/puppet/type.rb, line 355
def self.key_attribute_parameters
  @key_attribute_parameters ||= (
    @parameters.find_all { |param|
      param.isnamevar? or param.name == :name
    }
  )
end

Returns cached {::key_attribute_parameters} names. Key attributes are properties and parameters that comprise a composite key or “uniqueness key”. @return [Array<String>] cached key_attribute names

# File lib/puppet/type.rb, line 368
def self.key_attributes
  # This is a cache miss around 0.05 percent of the time. --daniel 2012-07-17
  @key_attributes_cache ||= key_attribute_parameters.collect { |p| p.name }
end

Is the given parameter a meta-parameter? @return [Boolean] true if the given parameter is a meta-parameter.

# File lib/puppet/type.rb, line 277
def self.metaparam?(param)
  @@metaparamhash.include?(param.intern)
end

Returns the meta-parameter class associated with the given meta-parameter name. Accepts a `nil` name, and return nil. @param name [String, nil] the name of a meta-parameter @return [Class,nil] the class for the given meta-parameter, or `nil` if no such meta-parameter exists, (or if

the given meta-parameter name is `nil`.

# File lib/puppet/type.rb, line 287
def self.metaparamclass(name)
  return nil if name.nil?
  @@metaparamhash[name.intern]
end

Returns the documentation for a given meta-parameter of this type. @param metaparam [Puppet::Parameter] the meta-parameter to get documentation for. @return [String] the documentation associated with the given meta-parameter, or nil of no such documentation

exists.

@raise if the given metaparam is not a meta-parameter in this type

# File lib/puppet/type.rb, line 305
def self.metaparamdoc(metaparam)
  @@metaparamhash[metaparam].doc
end

Returns all meta-parameter names. @return [Array<String>] all meta-parameter names

# File lib/puppet/type.rb, line 295
def self.metaparams
  @@metaparams.collect { |param| param.name }
end

Creates an instance of Type from a hash or a {Puppet::Resource}. @todo Unclear if this is a new Type or a new instance of a given type (the initialization ends

with calling validate - which seems like validation of an instance of a given type, not a new
meta type.

@todo Explain what the Hash and Resource are. There seems to be two different types of

resources; one that causes the title to be set to resource.title, and one that
causes the title to be resource.ref ("for components") - what is a component?

@overload initialize(hash)

@param [Hash] 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

# File lib/puppet/type.rb, line 2193
def initialize(resource)
  resource = self.class.hash2resource(resource) unless resource.is_a?(Puppet::Resource)

  # The list of parameter/property instances.
  @parameters = {}

  # Set the title first, so any failures print correctly.
  if resource.type.to_s.downcase.to_sym == self.class.name
    self.title = resource.title
  else
    # This should only ever happen for components
    self.title = resource.ref
  end

  [:file, :line, :catalog, :exported, :virtual].each do |getter|
    setter = getter.to_s + "="
    if val = resource.send(getter)
      self.send(setter, val)
    end
  end

  @tags = resource.tags

  @original_parameters = resource.to_hash

  set_name(@original_parameters)

  set_default(:provider)

  set_parameters(@original_parameters)

  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

Creates a new meta-parameter. This creates a new meta-parameter that is added to this and all inheriting 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 [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.

@option options [Boolean] :boolean (false) specifies if this is a boolean parameter @option options [Boolean] :namevar (false) specifies if this parameter is the namevar @option options [Symbol, Array<Symbol>] :required_features specifies required provider features by name @return [Class<inherits Puppet::Parameter>] the created parameter @yield [ ] a required block that is evaluated in the scope of the new meta-parameter @api public @dsl type @todo Verify that this description is ok

# File lib/puppet/type.rb, line 326
def self.newmetaparam(name, options = {}, &block)
  @@metaparams ||= []
  @@metaparamhash ||= {}
  name = name.intern

  param = genclass(
    name,
    :parent => options[:parent] || Puppet::Parameter,
    :prefix => "MetaParam",
    :hash => @@metaparamhash,
    :array => @@metaparams,
    :attributes => options[:attributes],
    &block
  )

  # Grr.
  param.required_features = options[:required_features] if options[:required_features]

  handle_param_options(name, options)

  param.metaparam = true

  param
end

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 [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.

@option options [Boolean] :boolean (false) specifies if this is a boolean parameter @option options [Boolean] :namevar (false) specifies if this parameter is the namevar @option options [Symbol, Array<Symbol>] :required_features specifies required provider features by name @return [Class<inherits Puppet::Parameter>] the created parameter @yield [ ] a required block that is evaluated in the scope of the new parameter @api public @dsl type

# File lib/puppet/type.rb, line 435
def self.newparam(name, options = {}, &block)
  options[:attributes] ||= {}

  param = genclass(
    name,
    :parent     => options[:parent] || Puppet::Parameter,
    :attributes => options[:attributes],
    :block      => block,
    :prefix     => "Parameter",
    :array      => @parameters,
    :hash       => @paramhash
  )

  handle_param_options(name, options)

  # Grr.
  param.required_features = options[:required_features] if options[:required_features]

  param.isnamevar if options[:namevar]

  param
end

Creates a new property. @param name [Symbol] the name of the property @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 [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.

@option options [Boolean] :boolean (false) specifies if this is a boolean parameter @option options [Symbol] :retrieve the method to call on the provider (or `parent` if `provider` is not set)

to retrieve the current value of this property.

@option options [Symbol, Array<Symbol>] :required_features specifies required provider features by name @return [Class<inherits Puppet::Property>] the created property @yield [ ] a required block that is evaluated in the scope of the new property @api public @dsl type

# File lib/puppet/type.rb, line 476
def self.newproperty(name, options = {}, &block)
  name = name.intern

  # This is here for types that might still have the old method of defining
  # a parent class.
  unless options.is_a? Hash
    raise Puppet::DevError,
      "Options must be a hash, not #{options.inspect}"
  end

  raise Puppet::DevError, "Class #{self.name} already has a property named #{name}" if @validproperties.include?(name)

  if parent = options[:parent]
    options.delete(:parent)
  else
    parent = Puppet::Property
  end

  # We have to create our own, new block here because we want to define
  # an initial :retrieve method, if told to, and then eval the passed
  # block if available.
  prop = genclass(name, :parent => parent, :hash => @validproperties, :attributes => options) do
    # If they've passed a retrieve method, then override the retrieve
    # method on the class.
    if options[:retrieve]
      define_method(:retrieve) do
        provider.send(options[:retrieve])
      end
    end

    class_eval(&block) if block
  end

  # If it's the 'ensure' property, always put it first.
  if name == :ensure
    @properties.unshift prop
  else
    @properties << prop
  end

  prop
end

@return [Puppet::Parameter] Returns the parameter class associated with the given parameter name.

# File lib/puppet/type.rb, line 530
def self.paramclass(name)
  @paramhash[name]
end

@return [Array<String>] Returns the parameter names

# File lib/puppet/type.rb, line 524
def self.parameters
  return [] unless defined?(@parameters)
  @parameters.collect { |klass| klass.name }
end

@return [Puppet::Property] Returns the property class ??? associated with the given property name

# File lib/puppet/type.rb, line 535
def self.propertybyname(name)
  @validproperties[name]
end

Creates a new provider of a type. This method must be called directly on the type that it’s implementing. @todo Fix Confusing Explanations!

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 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 ??? @raise [Puppet::DevError] when the parent provider could not be found.

# File lib/puppet/type.rb, line 1757
def self.provide(name, options = {}, &block)
  name = name.intern

  if unprovide(name)
    Puppet.debug "Reloading #{name} #{self.name} provider"
  end

  parent = if pname = options[:parent]
    options.delete(:parent)
    if pname.is_a? Class
      pname
    else
      if provider = self.provider(pname)
        provider
      else
        raise Puppet::DevError,
          "Could not find parent provider #{pname} of #{name}"
      end
    end
  else
    Puppet::Provider
  end

  options[:resource_type] ||= self

  self.providify

  provider = genclass(
    name,
    :parent     => parent,
    :hash       => provider_hash,
    :prefix     => "Provider",
    :block      => block,
    :include    => feature_module,
    :extend     => feature_module,
    :attributes => options
  )

  provider
end

Returns the provider having the given name. This will load a provider if it is not already loaded. The returned provider is the first found provider having the given name, where “first found” semantics is defined by the {providerloader} in use.

@param name [String] the name of the provider to get @return [Puppet::Provider, nil] the found provider, or nil if no provider of the given name was found

# File lib/puppet/type.rb, line 1714
def self.provider(name)
  name = name.intern

  # If we don't have it yet, try loading it.
  @providerloader.load(name) unless provider_hash.has_key?(name)
  provider_hash[name]
end

@return [Hash{ ??? => Puppet::Provider}] Returns a hash of WHAT EXACTLY for this type. @see ::provider_hash_by_type method to get the same for some other type

# File lib/puppet/type.rb, line 1703
def self.provider_hash
  Puppet::Type.provider_hash_by_type(self.name)
end

@return [Hash{??? => Puppet::Provider}] Returns a hash of WHAT EXACTLY for the given type @todo what goes into this hash?

# File lib/puppet/type.rb, line 1696
def self.provider_hash_by_type(type)
  @provider_hashes ||= {}
  @provider_hashes[type] ||= {}
end

Returns a list of loaded providers by name. This method will not load/search for available providers. @return [Array<String>] list of loaded provider names

# File lib/puppet/type.rb, line 1726
def self.providers
  provider_hash.keys
end

Returns a list of one suitable provider per source, with the default provider first. @todo Needs better explanation; what does “source” mean in this context? @return [Array<Puppet::Provider>] list of providers

# File lib/puppet/type.rb, line 1169
def self.providers_by_source
  # Put the default provider first (can be nil), then the rest of the suitable providers.
  sources = []
  [defaultprovider, suitableprovider].flatten.uniq.collect do |provider|
    next if provider.nil?
    next if sources.include?(provider.source)

    sources << provider.source
    provider
  end.compact
end

Ensures there is a `:provider` parameter defined. Should only be called if there are providers. @return [void]

# File lib/puppet/type.rb, line 1801
def self.providify
  return if @paramhash.has_key? :provider

  newparam(:provider) do
    # We're using a hacky way to get the name of our type, since there doesn't
    # seem to be a correct way to introspect this at the time this code is run.
    # We expect that the class in which this code is executed will be something
    # like Puppet::Type::Ssh_authorized_key::ParameterProvider.
    desc <<-EOT
      The specific backend to use for this `#{self.to_s.split('::')[2].downcase}`
      resource. You will seldom need to specify this --- Puppet will usually
      discover the appropriate provider for your platform.
    EOT

    # This is so we can refer back to the type to get a list of
    # providers for documentation.
    class << self
      # The reference to a parent type for the parameter `:provider` used to get a list of
      # providers for documentation purposes.
      #
      attr_accessor :parenttype
    end

    # Provides the ability to add documentation to a provider.
    #
    def self.doc
      # Since we're mixing @doc with text from other sources, we must normalize
      # its indentation with scrub. But we don't need to manually scrub the
      # provider's doc string, since markdown_definitionlist sanitizes its inputs.
      scrub(@doc) + "Available providers are:\n\n" + parenttype.providers.sort { |a,b|
        a.to_s <=> b.to_s
      }.collect { |i|
        markdown_definitionlist( i, scrub(parenttype().provider(i).doc) )
      }.join
    end

    # For each resource, the provider param defaults to
    # the type's default provider
    defaultto {
      prov = @resource.class.defaultprovider
      prov.name if prov
    }

    validate do |provider_class|
      provider_class = provider_class[0] if provider_class.is_a? Array
      provider_class = provider_class.class.name if provider_class.is_a?(Puppet::Provider)

      unless @resource.class.provider(provider_class)
        raise ArgumentError, "Invalid #{@resource.class.name} provider '#{provider_class}'"
      end
    end

    munge do |provider|
      provider = provider[0] if provider.is_a? Array
      provider = provider.intern if provider.is_a? String
      @resource.provider = provider

      if provider.is_a?(Puppet::Provider)
        provider.class.name
      else
        provider
      end
    end
  end.parenttype = self
end

@todo document this, have no clue what this does… it retuns “Puppet::Type::RelationshipMetaparam.subclasses”

# File lib/puppet/type.rb, line 1536
def self.relationship_params
  RelationshipMetaparam.subclasses
end

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). @return [Array<Puppet::Provider>] Returns an array of all suitable providers.

# File lib/puppet/type.rb, line 1884
def self.suitableprovider
  providerloader.loadall if provider_hash.empty?
  provider_hash.find_all { |name, provider|
    provider.suitable?
  }.collect { |name, provider|
    provider
  }.reject { |p| p.name == :fake } # For testing
end

Returns a mapping from the title string to setting of attribute value(s). This default implementation provides a mapping of title to the one and only namevar present in the type’s definition. @note Advanced: some logic requires this mapping to be done differently, using a different

validation/pattern, breaking up the title
into several parts assigning each to an individual attribute, or even use a composite identity where
all namevars are seen as part of the unique identity (such computation is done by the {#uniqueness} method.
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

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.
The implementation in this method simply assigns the title to the one and only namevar (which is name
or a variable marked as namevar).
If there are multiple namevars (any in addition to :name?) then this method MUST be implemented
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
implemented (it seems it always is) - why take this more expensive regexp mathching route for all
other types?

@api private

# File lib/puppet/type.rb, line 401
def self.title_patterns
  case key_attributes.length
  when 0; []
  when 1;
    [ [ /(.*)/, [ [key_attributes.first] ] ] ]
  else
    raise Puppet::DevError,"you must specify title patterns when there are two or more key attributes"
  end
end

Returns the name of this type (if specified) or the parent type to_s. 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

# File lib/puppet/type.rb, line 2111
def self.to_s
  if defined?(@name)
    "Puppet::Type::#{@name.to_s.capitalize}"
  else
    super
  end
end

@todo this needs a better explanation Removes the implementation class of a given provider. @return [Object] returns what {Puppet::Util::ClassGen#rmclass} returns

# File lib/puppet/type.rb, line 1870
def self.unprovide(name)
  if @defaultprovider and @defaultprovider.name == name
    @defaultprovider = nil
  end

  rmclass(name, :hash => provider_hash, :prefix => "Provider")
end

(see validattr?) @note see comment in code - how should this be documented? Are some of the other query methods deprecated?

(or should be).

@comment This is a forward-compatibility method - it’s the validity interface we’ll use in Puppet::Resource.

# File lib/puppet/type.rb, line 580
def self.valid_parameter?(name)
  validattr?(name)
end

Creates a `validate` method that is used to validate a resource before it is operated on. The validation should raise exceptions if the validation finds errors. (It is not recommended to issue warnings as this typically just ends up in a logfile - you should fail if a validation fails). The easiest way to raise an appropriate exception is to call the method {Puppet::Util::Errors#fail} with the message as an argument.

@yield [ ] a required block called with self set to the instance of a Type class representing a resource. @return [void] @dsl type @api public

# File lib/puppet/type.rb, line 2130
def self.validate(&block)
  define_method(:validate, &block)
end

Returns whether or not the given name is the name of a property, parameter or meta-parameter @return [Boolean] true if the given attribute name is the name of an existing property, parameter or meta-parameter

# File lib/puppet/type.rb, line 542
def self.validattr?(name)
  name = name.intern
  return true if name == :name
  @validattrs ||= {}

  unless @validattrs.include?(name)
    @validattrs[name] = !!(self.validproperty?(name) or self.validparameter?(name) or self.metaparam?(name))
  end

  @validattrs[name]
end

@return [Boolean] Returns true if the given name is the name of an existing parameter

# File lib/puppet/type.rb, line 571
def self.validparameter?(name)
  raise Puppet::DevError, "Class #{self} has not defined parameters" unless defined?(@parameters)
  !!(@paramhash.include?(name) or @@metaparamhash.include?(name))
end

@return [Array<Symbol>, {}] Returns a list of valid property names, or an empty hash if there are none. @todo An empty hash is returned if there are no defined parameters (not an empty array). This looks like

a bug.

# File lib/puppet/type.rb, line 564
def self.validproperties
  return {} unless defined?(@parameters)

  @validproperties.keys
end

@return [Boolean] Returns true if the given name is the name of an existing property

# File lib/puppet/type.rb, line 555
def self.validproperty?(name)
  name = name.intern
  @validproperties.include?(name) && @validproperties[name]
end

Returns true if the given name is a reference to a provider and if this is a suitable provider for 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 @return [Boolean] true if the given name references a provider that is suitable

# File lib/puppet/type.rb, line 1737
def self.validprovider?(name)
  name = name.intern

  (provider_hash.has_key?(name) && provider_hash[name].suitable?)
end