class Puppet::Provider

Returns the absolute path to the executable for the command referenced by the given name. @raise [Puppet::DevError] if the name does not reference an existing command. @return [String] the absolute path to the found executable for the command @see which @api public

    # File lib/puppet/provider.rb
126 def self.command(name)
127   name = name.intern
128 
129   command = @commands[name] if defined?(@commands)    
130   command = superclass.command(name) if !command && superclass.respond_to?(:command)
131 
132   unless command
133     raise Puppet::DevError, _("No command %{command} defined for provider %{provider}") % { command: name, provider: self.name }
134   end
135 
136   which(command)
137 end

Confines this provider to be suitable only on hosts where the given commands are present. Also see {Puppet::Confiner#confine} for other types of confinement of a provider by use of other types of predicates.

@note It is preferred if the commands are not entered with absolute paths as this allows puppet

to search for them using the PATH variable.

@param command_specs [Hash{String => String}] Map of name to command that the provider will

be executing on the system. Each command is specified with a name and the path of the executable.

@return [void] @see optional_commands @api public

    # File lib/puppet/provider.rb
152 def self.commands(command_specs)
153   command_specs.each do |name, path|
154     has_command(name, path)
155   end
156 end

@return [Boolean] Return whether the given feature has been declared or not.

    # File lib/puppet/provider.rb
251 def self.declared_feature?(name)
252   defined?(@declared_features) and @declared_features.include?(name)
253 end

@return [Boolean] Returns whether this implementation satisfies all of the default requirements or not.

Returns false if there is no matching defaultfor

@see Provider.defaultfor

    # File lib/puppet/provider.rb
259 def self.default?
260   default_match ? true : false
261 end

Look through the array of defaultfor hashes and return the first match. @return [Hash<{String => Object}>] the matching hash specified by a defaultfor @see Provider.defaultfor @api private

    # File lib/puppet/provider.rb
267 def self.default_match
268   return nil if some_default_match(@notdefaults) # Blacklist means this provider cannot be a default
269   some_default_match(@defaults)
270 end

Sets a facts filter that determine which of several suitable providers should be picked by default. This selection only kicks in if there is more than one suitable provider. To filter on multiple facts the given hash may contain more than one fact name/value entry. The filter picks the provider if all the fact/value entries match the current set of facts. (In case there are still more than one provider after this filtering, the first found is picked). @param hash [Hash<{String => Object}>] hash of fact name to fact value. @return [void]

    # File lib/puppet/provider.rb
320 def self.defaultfor(hash)
321   @defaults << hash
322 end

(see Puppet::Util::Execution.execpipe)

    # File lib/puppet/provider.rb
117 def self.execpipe(*args, &block)
118   Puppet::Util::Execution.execpipe(*args, &block)
119 end

(see Puppet::Util::Execution.execute)

    # File lib/puppet/provider.rb
106 def self.execute(*args)
107   Puppet::Util::Execution.execute(*args)
108 end

Compare a fact value against one or more supplied value @param [Symbol] fact a fact to query to match against one of the given values @param [Array, Regexp, String] values one or more values to compare to the

value of the given fact

@return [Boolean] whether or not the fact value matches one of the supplied

values. Given one or more Regexp instances, fact is compared via the basic
pattern-matching operator.

    # File lib/puppet/provider.rb
292 def self.fact_match(fact, values)
293   fact_val = Puppet.runtime[:facter].value(fact).to_s.downcase
294   if fact_val.empty?
295     return false
296   else
297     values = [values] unless values.is_a?(Array)
298     values.any? do |value|
299       if value.is_a?(Regexp)
300         fact_val =~ value
301       else
302         fact_val.intern == value.to_s.downcase.intern
303       end
304     end
305   end
306 end

Creates a convenience method for invocation of a command.

This generates a Provider method that allows easy execution of the command. The generated method may take arguments that will be passed through to the executable as the command line arguments when it is invoked.

@example Use it like this:

has_command(:echo, "/bin/echo")
def some_method
  echo("arg 1", "arg 2")
end

@comment the . . . below is intentional to avoid the three dots to become an illegible ellipsis char. @example . . . or like this

has_command(:echo, "/bin/echo") do
  is_optional
  environment :HOME => "/var/tmp", :PWD => "/tmp"
end

@param name [Symbol] The name of the command (will become the name of the generated method that executes the command) @param path [String] The path to the executable for the command @yield [ ] A block that configures the command (see {Puppet::Provider::Command}) @comment a yield [ ] produces {|| …} in the signature, do not remove the space. @note the name ´has_command´ looks odd in an API context, but makes more sense when seen in the internal

DSL context where a Provider is declaratively defined.

@api public

    # File lib/puppet/provider.rb
202 def self.has_command(name, path, &block)
203   name = name.intern
204   command = CommandDefiner.define(name, path, self, &block)
205 
206   @commands[name] = command.executable
207 
208   # Now define the class and instance methods.
209   create_class_and_instance_method(name) do |*args|
210     return command.execute(*args)
211   end
212 end

Initializes defaults and commands (i.e. clears them). @return [void]

    # File lib/puppet/provider.rb
351 def self.initvars
352   @defaults = []
353   @notdefaults = []
354   @commands = {}
355 end

Returns a list of system resources (entities) this provider may/can manage. This is a query mechanism that lists entities that the provider may manage on a given system. It is is directly used in query services, but is also the foundation for other services; prefetching, and purging.

As an example, a package provider lists all installed packages. (In contrast, the File provider does not list all files on the file-system as that would make execution incredibly slow). An implementation of this method should be made if it is possible to quickly (with a single system call) provide all instances.

An implementation of this method should only cache the values of properties if they are discovered as part of the process for finding existing resources. Resource properties that require additional commands (than those used to determine existence/identity) should be implemented in their respective getter method. (This is important from a performance perspective; it may be expensive to compute, as well as wasteful as all discovered resources may perhaps not be managed).

An implementation may return an empty list (naturally with the effect that it is not possible to query for manageable entities).

By implementing this method, it is possible to use the `resources´ resource type to specify purging of all non managed entities.

@note The returned instances are instance of some subclass of Provider, not resources. @return [Array<Puppet::Provider>] a list of providers referencing the system entities @abstract this method must be implemented by a subclass and this super method should never be called as it raises an exception. @raise [Puppet::DevError] Error indicating that the method should have been implemented by subclass. @see prefetch

    # File lib/puppet/provider.rb
384 def self.instances
385   raise Puppet::DevError, _("To support listing resources of this type the '%{provider}' provider needs to implement an 'instances' class method returning the current set of resources. We recommend porting your module to the simpler Resource API instead: https://puppet.com/search/docs?keys=resource+api") % { provider: self.name }
386 end

Creates getter- and setter- methods for each property supported by the resource type. Call this method to generate simple accessors for all properties supported by the resource type. These simple accessors lookup and sets values in the property hash. The generated methods may be overridden by more advanced implementations if something else than a straight forward getter/setter pair of methods is required. (i.e. define such overriding methods after this method has been called)

An implementor of a provider that makes use of `prefetch` and `flush` can use this method since it uses the internal `@property_hash` variable to store values. An implementation would then update the system state on a call to `flush` based on the current values in the `@property_hash`.

@return [void]

    # File lib/puppet/provider.rb
401 def self.mk_resource_methods
402   [resource_type.validproperties, resource_type.parameters].flatten.each do |attr|
403     attr = attr.intern
404     next if attr == :name
405     define_method(attr) do
406       if @property_hash[attr].nil?
407         :absent
408       else
409         @property_hash[attr]
410       end
411     end
412 
413     define_method(attr.to_s + "=") do |val|
414       @property_hash[attr] = val
415     end
416   end
417 end

Creates a new provider that is optionally initialized from a resource or a hash of properties. If no argument is specified, a new non specific provider is initialized. If a resource is given it is remembered for further operations. If a hash is used it becomes the internal `@property_hash` structure of the provider - this hash holds the current state property values of system entities as they are being discovered by querying or other operations (typically getters).

@todo The use of a hash as a parameter needs a better explanation; why is this done? What is the intent? @param resource [Puppet::Resource, Hash] optional resource or hash

    # File lib/puppet/provider.rb
520 def initialize(resource = nil)
521   if resource.is_a?(Hash)
522     # We don't use a duplicate here, because some providers (ParsedFile, at least)
523     # use the hash here for later events.
524     @property_hash = resource
525   elsif resource
526     @resource = resource
527     @property_hash = {}
528   else
529     @property_hash = {}
530   end
531 end

Defines optional commands. Since Puppet 2.7.8 this is typically not needed as evaluation of provider suitability is lazy (when a resource is evaluated) and the absence of commands that will be present after other resources have been applied no longer needs to be specified as optional. @param [Hash{String => String}] hash Named commands that the provider will

be executing on the system. Each command is specified with a name and the path of the executable.

(@see has_command) @see commands @api public

    # File lib/puppet/provider.rb
168 def self.optional_commands(hash)
169   hash.each do |name, target|
170     has_command(name, target) do
171       is_optional
172     end
173   end
174 end

@return [String] Returns the data source, which is the provider name if no other source has been set. @todo Unclear what “the source” is used for?

    # File lib/puppet/provider.rb
440 def self.source
441   @source ||= self.name
442 end

@return [Integer] Returns a numeric specificity for this provider based on how many requirements it has

and number of _ancestors_. The higher the number the more specific the provider.

The number of requirements is based on the hash size of the matching {Provider.defaultfor}.

The ancestors is the Ruby Module::ancestors method and the number of classes returned is used to boost the score. The intent is that if two providers are equal, but one is more “derived” than the other (i.e. includes more classes), it should win because it is more specific). @note Because of how this value is

calculated there could be surprising side effects if a provider included an excessive amount of classes.

    # File lib/puppet/provider.rb
338 def self.specificity
339   # This strange piece of logic attempts to figure out how many parent providers there
340   # are to increase the score. What is will actually do is count all classes that Ruby Module::ancestors
341   # returns (which can be other classes than those the parent chain) - in a way, an odd measure of the
342   # complexity of a provider).
343   match = default_match
344   length = match ? match.length : 0
345 
346   (length * 100) + ancestors.select { |a| a.is_a? Class }.length
347 end

Returns true if the given attribute/parameter is supported by the provider. The check is made that the parameter is a valid parameter for the resource type, and then if all its required features (if any) are supported by the provider.

@param param [Class, Puppet::Parameter] the parameter class, or a parameter instance @return [Boolean] Returns whether this provider supports the given parameter or not. @raise [Puppet::DevError] if the given parameter is not valid for the resource type

    # File lib/puppet/provider.rb
452 def self.supports_parameter?(param)
453   if param.is_a?(Class)
454     klass = param
455   else
456     klass = resource_type.attrclass(param)
457     unless klass
458       raise Puppet::DevError, _("'%{parameter_name}' is not a valid parameter for %{resource_type}") % { parameter_name: param, resource_type: resource_type.name }
459     end
460   end
461   features = klass.required_features
462   return true unless features
463 
464   !!satisfies?(*features)
465 end

This method is used to generate a method for a command. @return [void] @api private

    # File lib/puppet/provider.rb
425 def self.create_class_and_instance_method(name, &block)
426   unless singleton_class.method_defined?(name)
427     meta_def(name, &block)
428   end
429 
430   unless method_defined?(name)
431     define_method(name) do |*args|
432       self.class.send(name, *args)
433     end
434   end
435 end

Compares this provider against another provider. Comparison is only possible with another provider (no other class). The ordering is based on the class name of the two providers.

@return [-1,0,+1, nil] A comparison result -1, 0, +1 if this is before other, equal or after other. Returns

nil oif not comparable to other.

@see Comparable

    # File lib/puppet/provider.rb
578 def <=>(other)
579   # We can only have ordering against other providers.
580   return nil unless other.is_a? Puppet::Provider
581   # Otherwise, order by the providers class name.
582   return self.class.name <=> other.class.name
583 end

Clears this provider instance to allow GC to clean up.

    # File lib/puppet/provider.rb
494 def clear
495   @resource = nil
496 end

(see command)

    # File lib/puppet/provider.rb
499 def command(name)
500   self.class.command(name)
501 end

Convenience methods - see class method with the same name. @return (see self.execpipe)

    # File lib/puppet/provider.rb
112 def execpipe(*args, &block)
113   Puppet::Util::Execution.execpipe(*args, &block)
114 end

Convenience methods - see class method with the same name. @return (see self.execute)

    # File lib/puppet/provider.rb
101 def execute(*args)
102   Puppet::Util::Execution.execute(*args)
103 end

Returns the value of a parameter value, or `:absent` if it is not defined. @param param [Puppet::Parameter] the parameter to obtain the value of @return [Object] the value of the parameter or `:absent` if not defined.

    # File lib/puppet/provider.rb
507 def get(param)
508   @property_hash[param.intern] || :absent
509 end

@return [String] Returns a human readable string with information about the resource and the provider.

    # File lib/puppet/provider.rb
565 def inspect
566   to_s
567 end

Returns the name of the resource this provider is operating on. @return [String] the name of the resource instance (e.g. the file path of a File). @raise [Puppet::DevError] if no resource is set, or no name defined.

    # File lib/puppet/provider.rb
537 def name
538   n = @property_hash[:name]
539   if n
540     return n
541   elsif self.resource
542     resource.name
543   else
544     raise Puppet::DevError, _("No resource and no name in property hash in %{class_name} instance") % { class_name: self.class.name }
545   end
546 end

Sets the given parameters values as the current values for those parameters. Other parameters are unchanged. @param [Array<Puppet::Parameter>] params the parameters with values that should be set @return [void]

    # File lib/puppet/provider.rb
553 def set(params)
554   params.each do |param, value|
555     @property_hash[param.intern] = value
556   end
557 end

@return [String] Returns a human readable string with information about the resource and the provider.

    # File lib/puppet/provider.rb
560 def to_s
561   "#{@resource}(provider=#{self.class.name})"
562 end