class Puppet::Provider::ParsedFile

This provider can be used as the parent class for a provider that parses and generates files. Its content must be loaded via the ‘prefetch’ method, and the file will be written when ‘flush’ is called on the provider instance. At this point, the file is written once for every provider instance.

Once the provider prefetches the data, it’s the resource’s job to copy that data over to the @is variables.

Attributes

default_target[RW]

target[RW]

property_hash[RW]

Public Instance Methods

create() click to toggle source

# File lib/puppet/provider/parsedfile.rb, line 394
def create
  @resource.class.validproperties.each do |property|
    if value = @resource.should(property)
      @property_hash[property] = value
    end
  end
  mark_target_modified
  (@resource.class.name.to_s + "_created").intern
end

destroy() click to toggle source

# File lib/puppet/provider/parsedfile.rb, line 404
def destroy
  # We use the method here so it marks the target as modified.
  self.ensure = :absent
  (@resource.class.name.to_s + "_deleted").intern
end

exists?() click to toggle source

# File lib/puppet/provider/parsedfile.rb, line 410
def exists?
  !(@property_hash[:ensure] == :absent or @property_hash[:ensure].nil?)
end

flush() click to toggle source

Write our data to disk.

# File lib/puppet/provider/parsedfile.rb, line 415
def flush
  # Make sure we've got a target and name set.

  # If the target isn't set, then this is our first modification, so
  # mark it for flushing.
  unless @property_hash[:target]
    @property_hash[:target] = @resource.should(:target) || self.class.default_target
    self.class.modified(@property_hash[:target])
  end
  @resource.class.key_attributes.each do |attr|
    @property_hash[attr] ||= @resource[attr]
  end

  self.class.flush(@property_hash)
end

prefetch() click to toggle source

Retrieve the current state from disk.

# File lib/puppet/provider/parsedfile.rb, line 441
def prefetch
  raise Puppet::DevError, "Somehow got told to prefetch with no resource set" unless @resource
  self.class.prefetch(@resource[:name] => @resource)
end

record_type() click to toggle source

# File lib/puppet/provider/parsedfile.rb, line 446
def record_type
  @property_hash[:record_type]
end

Public Class Methods

backup_target(target) click to toggle source

Make sure our file is backed up, but only back it up once per transaction. We cheat and rely on the fact that @records is created on each prefetch.

# File lib/puppet/provider/parsedfile.rb, line 80
def self.backup_target(target)
  return nil unless target_object(target).respond_to?(:backup)

  @backup_stats ||= {}
  return nil if @backup_stats[target] == @records.object_id

  target_object(target).backup
  @backup_stats[target] = @records.object_id
end

clean(hash) click to toggle source

# File lib/puppet/provider/parsedfile.rb, line 22
def self.clean(hash)
  newhash = hash.dup
  [:record_type, :on_disk].each do |p|
    newhash.delete(p) if newhash.include?(p)
  end

  newhash
end

clear() click to toggle source

# File lib/puppet/provider/parsedfile.rb, line 31
def self.clear
  @target_objects.clear
  @records.clear
end

default_mode() click to toggle source

The mode for generated files if they are newly created. No mode will be set on existing files.

@abstract Providers inheriting parsedfile can override this method

to provide a mode. The value should be suitable for File.chmod

# File lib/puppet/provider/parsedfile.rb, line 325
def self.default_mode
  nil
end

drop_native_header() click to toggle source

How to handle third party headers. @api private @abstract Providers based on ParsedFile that make use of the support for

third party headers may override this method to return +true+.
When this is done, headers that are matched by the native_header_regex
are not written back to disk.

@see ::native_header_regex

# File lib/puppet/provider/parsedfile.rb, line 136
def self.drop_native_header
  false
end

filetype() click to toggle source

# File lib/puppet/provider/parsedfile.rb, line 36
def self.filetype
  @filetype ||= Puppet::Util::FileType.filetype(:flat)
end

filetype=(type) click to toggle source

# File lib/puppet/provider/parsedfile.rb, line 40
def self.filetype=(type)
  if type.is_a?(Class)
    @filetype = type
  elsif klass = Puppet::Util::FileType.filetype(type)
    @filetype = klass
  else
    raise ArgumentError, "Invalid filetype #{type}"
  end
end

flush(record) click to toggle source

Flush all of the targets for which there are modified records. The only reason we pass a record here is so that we can add it to the stack if necessary – it’s passed from the instance calling ‘flush’.

# File lib/puppet/provider/parsedfile.rb, line 53
def self.flush(record)
  # Make sure this record is on the list to be flushed.
  unless record[:on_disk]
    record[:on_disk] = true
    @records << record

    # If we've just added the record, then make sure our
    # target will get flushed.
    modified(record[:target] || default_target)
  end

  return unless defined?(@modified) and ! @modified.empty?

  flushed = []
  begin
    @modified.sort { |a,b| a.to_s <=> b.to_s }.uniq.each do |target|
      Puppet.debug "Flushing #{@resource_type.name} provider target #{target}"
      flushed << target
      flush_target(target)
    end
  ensure
    @modified.reject! { |t| flushed.include?(t) }
  end
end

flush_target(target) click to toggle source

Flush all of the records relating to a specific target.

# File lib/puppet/provider/parsedfile.rb, line 91
def self.flush_target(target)
  backup_target(target)

  records = target_records(target).reject { |r|
    r[:ensure] == :absent
  }

  target_object(target).write(to_file(records))
end

header() click to toggle source

Return the header placed at the top of each generated file, warning users that modifying this file manually is probably a bad idea.

# File lib/puppet/provider/parsedfile.rb, line 103
  def self.header
%Q{# HEADER: This file was autogenerated at #{Time.now}
# HEADER: by puppet.  While it can still be managed manually, it
# HEADER: is definitely not recommended.\n}
  end

initvars() click to toggle source

Add another type var.

# File lib/puppet/provider/parsedfile.rb, line 141
def self.initvars
  @records = []
  @target_objects = {}

  @target = nil

  # Default to flat files
  @filetype ||= Puppet::Util::FileType.filetype(:flat)
  super
end

instances() click to toggle source

Return a list of all of the records we can find.

# File lib/puppet/provider/parsedfile.rb, line 153
def self.instances
  targets.collect do |target|
    prefetch_target(target)
  end.flatten.reject { |r| skip_record?(r) }.collect do |record|
    new(record)
  end
end

match_providers_with_resources(resources) click to toggle source

Match a list of catalog resources with provider instances

@api private

@param [Array<Puppet::Resource>] resources A list of resources using this class as a provider

# File lib/puppet/provider/parsedfile.rb, line 219
def self.match_providers_with_resources(resources)
  return unless resources
  matchers = resources.dup
  @records.each do |record|
    # Skip things like comments and blank lines
    next if skip_record?(record)

    if (resource = resource_for_record(record, resources))
      resource.provider = new(record)
    elsif respond_to?(:match)
      if resource = match(record, matchers)
        matchers.delete(resource.title)
        record[:name] = resource[:name]
        resource.provider = new(record)
      end
    end
  end
end

mk_resource_methods() click to toggle source

Override the default method with a lot more functionality.

# File lib/puppet/provider/parsedfile.rb, line 162
def self.mk_resource_methods
  [resource_type.validproperties, resource_type.parameters].flatten.each do |attr|
    attr = attr.intern
    define_method(attr) do
      # If it's not a valid field for this record type (which can happen
      # when different platforms support different fields), then just
      # return the should value, so the resource shuts up.
      if @property_hash[attr] or self.class.valid_attr?(self.class.name, attr)
        @property_hash[attr] || :absent
      else
        if defined?(@resource)
          @resource.should(attr)
        else
          nil
        end
      end
    end

    define_method(attr.to_s + "=") do |val|
      mark_target_modified
      @property_hash[attr] = val
    end
  end
end

modified(target) click to toggle source

Mark a target as modified so we know to flush it. This only gets used within the attr= methods.

# File lib/puppet/provider/parsedfile.rb, line 195
def self.modified(target)
  @modified ||= []
  @modified << target unless @modified.include?(target)
end

native_header_regex() click to toggle source

An optional regular expression matched by third party headers.

For example, this can be used to filter the vixie cron headers as erronously exported by older cron versions.

@api private @abstract Providers based on ParsedFile may implement this to make it

possible to identify a header maintained by a third party tool.
The provider can then allow that header to remain near the top of the
written file, or remove it after composing the file content.
If implemented, the function must return a Regexp object.
The expression must be tailored to match exactly one third party header.

@see ::drop_native_header @note When specifying regular expressions in multiline mode, avoid

greedy repititions such as '.*' (use .*? instead). Otherwise, the
provider may drop file content between sparse headers.

# File lib/puppet/provider/parsedfile.rb, line 125
def self.native_header_regex
  nil
end

new(record) click to toggle source

# File lib/puppet/provider/parsedfile.rb, line 431
def initialize(record)
  super

  # The 'record' could be a resource or a record, depending on how the provider
  # is initialized.  If we got an empty property hash (probably because the resource
  # is just being initialized), then we want to set up some defaults.
  @property_hash = self.class.record?(resource[:name]) || {:record_type => self.class.name, :ensure => :absent} if @property_hash.empty?
end

prefetch(resources = nil) click to toggle source

Retrieve all of the data from disk. There are three ways to know which files to retrieve: We might have a list of file objects already set up, there might be instances of our associated resource and they will have a path parameter set, and we will have a default path set. We need to turn those three locations into a list of files, prefetch each one, and make sure they’re associated with each appropriate resource instance.

# File lib/puppet/provider/parsedfile.rb, line 207
def self.prefetch(resources = nil)
  # Reset the record list.
  @records = prefetch_all_targets(resources)

  match_providers_with_resources(resources)
end

prefetch_all_targets(resources) click to toggle source

# File lib/puppet/provider/parsedfile.rb, line 253
def self.prefetch_all_targets(resources)
  records = []
  targets(resources).each do |target|
    records += prefetch_target(target)
  end
  records
end

prefetch_target(target) click to toggle source

Prefetch an individual target.

# File lib/puppet/provider/parsedfile.rb, line 262
def self.prefetch_target(target)

  begin
    target_records = retrieve(target)
  rescue Puppet::Util::FileType::FileReadError => detail
    puts detail.backtrace if Puppet[:trace]
    Puppet.err "Could not prefetch #{self.resource_type.name} provider '#{self.name}' target '#{target}': #{detail}. Treating as empty"
    target_records = []
  end

  target_records.each do |r|
    r[:on_disk] = true
    r[:target] = target
    r[:ensure] = :present
  end

  target_records = prefetch_hook(target_records) if respond_to?(:prefetch_hook)

  raise Puppet::DevError, "Prefetching #{target} for provider #{self.name} returned nil" unless target_records

  target_records
end

record?(name) click to toggle source

Is there an existing record with this name?

# File lib/puppet/provider/parsedfile.rb, line 286
def self.record?(name)
  return nil unless @records
  @records.find { |r| r[:name] == name }
end

resource_for_record(record, resources) click to toggle source

Look up a resource based on a parsed file record

@api private

@param [Hash<Symbol, Object>] record @param [Array<Puppet::Resource>] resources

@return [Puppet::Resource, nil] The resource if found, else nil

# File lib/puppet/provider/parsedfile.rb, line 246
def self.resource_for_record(record, resources)
  name = record[:name]
  if name
    resources[name]
  end
end

resource_type=(resource) click to toggle source

Always make the resource methods.

# File lib/puppet/provider/parsedfile.rb, line 188
def self.resource_type=(resource)
  super
  mk_resource_methods
end

retrieve(path) click to toggle source

Retrieve the text for the file. Returns nil in the unlikely event that it doesn’t exist.

# File lib/puppet/provider/parsedfile.rb, line 293
def self.retrieve(path)
  # XXX We need to be doing something special here in case of failure.
  text = target_object(path).read
  if text.nil? or text == ""
    # there is no file
    return []
  else
    # Set the target, for logging.
    old = @target
    begin
      @target = path
      return self.parse(text)
    rescue Puppet::Error => detail
      detail.file = @target if detail.respond_to?(:file=)
      raise detail
    ensure
      @target = old
    end
  end
end

skip_record?(record) click to toggle source

Should we skip the record? Basically, we skip text records. This is only here so subclasses can override it.

# File lib/puppet/provider/parsedfile.rb, line 316
def self.skip_record?(record)
  record_type(record[:record_type]).text?
end

target_object(target) click to toggle source

Initialize the object if necessary.

# File lib/puppet/provider/parsedfile.rb, line 330
def self.target_object(target)
  # only send the default mode if the actual provider defined it,
  # because certain filetypes (e.g. the crontab variants) do not
  # expect it in their initialize method
  if default_mode
    @target_objects[target] ||= filetype.new(target, default_mode)
  else
    @target_objects[target] ||= filetype.new(target)
  end

  @target_objects[target]
end

target_records(target) click to toggle source

Find all of the records for a given target

# File lib/puppet/provider/parsedfile.rb, line 344
def self.target_records(target)
  @records.find_all { |r| r[:target] == target }
end

targets(resources = nil) click to toggle source

Find a list of all of the targets that we should be reading. This is used to figure out what targets we need to prefetch.

# File lib/puppet/provider/parsedfile.rb, line 350
def self.targets(resources = nil)
  targets = []
  # First get the default target
  raise Puppet::DevError, "Parsed Providers must define a default target" unless self.default_target
  targets << self.default_target

  # Then get each of the file objects
  targets += @target_objects.keys

  # Lastly, check the file from any resource instances
  if resources
    resources.each do |name, resource|
      if value = resource.should(:target)
        targets << value
      end
    end
  end

  targets.uniq.compact
end

to_file(records) click to toggle source

Compose file contents from the set of records.

If self.native_header_regex is not nil, possible vendor headers are identified by matching the return value against the expression. If one (or several consecutive) such headers, are found, they are either moved in front of the self.header if self.drop_native_header is false (this is the default), or removed from the return value otherwise.

@api private

# File lib/puppet/provider/parsedfile.rb, line 380
def self.to_file(records)
  text = super
  if native_header_regex and (match = text.match(native_header_regex))
    if drop_native_header
      # concatenate the text in front of and after the native header
      text = match.pre_match + match.post_match
    else
      native_header = match[0]
      return native_header + header + match.pre_match + match.post_match
    end
  end
  header + text
end