class Chef::Formatters::Doc

Formatter similar to RSpec's documentation formatter. Uses indentation to show context.

Attributes

end_time[R]
start_time[R]

Public Class Methods

new(out, err) click to toggle source
Calls superclass method Chef::Formatters::Base::new
# File lib/chef/formatters/doc.rb, line 16
def initialize(out, err)
  super

  @updated_resources = 0
  @up_to_date_resources = 0
  @start_time = Time.now
  @end_time = @start_time
  @skipped_resources = 0
  @progress = {}
end

Public Instance Methods

compliance_input_enabled(input) click to toggle source

Called when a compliance input is enabled (by include_input)

# File lib/chef/formatters/doc.rb, line 408
def compliance_input_enabled(input)
  # puts_line("  * FIXME", :cyan)
end
compliance_input_loaded(input) click to toggle source

Called when a compliance waiver is found in a cookbook by the cookbook_compiler

# File lib/chef/formatters/doc.rb, line 388
def compliance_input_loaded(input)
  puts_line("  - #{input.cookbook_name}::#{input.pathname}", :cyan)
end
compliance_profile_enabled(profile) click to toggle source

Called when a compliance profile is enabled (by include_profile)

# File lib/chef/formatters/doc.rb, line 398
def compliance_profile_enabled(profile)
  # puts_line("  * FIXME", :cyan)
end
compliance_profile_loaded(profile) click to toggle source

Called when a compliance profile is found in a cookbook by the cookbook_compiler

# File lib/chef/formatters/doc.rb, line 382
def compliance_profile_loaded(profile)
  start_line("  - #{profile.cookbook_name}::#{profile.pathname}", :cyan)
  puts " (#{profile.version})", :cyan if profile.version
end
compliance_waiver_enabled(waiver) click to toggle source

Called when a compliance waiver is enabled (by include_waiver)

# File lib/chef/formatters/doc.rb, line 403
def compliance_waiver_enabled(waiver)
  # puts_line("  * FIXME", :cyan)
end
compliance_waiver_loaded(waiver) click to toggle source

Called when a compliance waiver is found in a cookbook by the cookbook_compiler

# File lib/chef/formatters/doc.rb, line 393
def compliance_waiver_loaded(waiver)
  puts_line("  - #{waiver.cookbook_name}::#{waiver.pathname}", :cyan)
end
converge_complete() click to toggle source

Called when the converge phase is finished.

# File lib/chef/formatters/doc.rb, line 213
def converge_complete
  unindent if @current_recipe
end
converge_failed(e) click to toggle source
# File lib/chef/formatters/doc.rb, line 217
def converge_failed(e)
  # Currently a failed converge is handled the same way as a successful converge
  converge_complete
end
converge_start(run_context) click to toggle source

Called before convergence starts

# File lib/chef/formatters/doc.rb, line 208
def converge_start(run_context)
  puts_line "Converging #{run_context.resource_collection.all_resources.size} resources"
end
cookbook_clean_complete() click to toggle source

Called when cookbook cleaning is finished.

# File lib/chef/formatters/doc.rb, line 149
def cookbook_clean_complete; end
cookbook_clean_start() click to toggle source

Called before unneeded cookbooks are removed

# File lib/chef/formatters/doc.rb, line 141
def cookbook_clean_start; end
cookbook_gem_failed(exception) click to toggle source

Called when cookbook gem installation fails

# File lib/chef/formatters/doc.rb, line 192
def cookbook_gem_failed(exception)
  unindent
end
cookbook_gem_finished() click to toggle source

Called when finished installing cookbook gems

# File lib/chef/formatters/doc.rb, line 187
def cookbook_gem_finished
  unindent
end
cookbook_gem_installing(gem, version) click to toggle source

Called when the result of installing the bundle is to install the gem

# File lib/chef/formatters/doc.rb, line 177
def cookbook_gem_installing(gem, version)
  puts_line "- Installing #{gem} #{version}", :green
end
cookbook_gem_start(gems) click to toggle source

Called when starting to collect gems from the cookbooks

# File lib/chef/formatters/doc.rb, line 171
def cookbook_gem_start(gems)
  puts_line "Installing cookbook gem dependencies:"
  indent
end
cookbook_gem_using(gem, version) click to toggle source

Called when the result of installing the bundle is to use the gem

# File lib/chef/formatters/doc.rb, line 182
def cookbook_gem_using(gem, version)
  puts_line "- Using #{gem} #{version}"
end
cookbook_resolution_complete(cookbook_collection) click to toggle source

Called when the cookbook collection is returned from the server.

# File lib/chef/formatters/doc.rb, line 138
def cookbook_resolution_complete(cookbook_collection); end
cookbook_resolution_failed(expanded_run_list, exception) click to toggle source

Called when there is an error getting the cookbook collection from the server.

# File lib/chef/formatters/doc.rb, line 133
def cookbook_resolution_failed(expanded_run_list, exception)
  super
end
cookbook_resolution_start(expanded_run_list) click to toggle source

Called before the cookbook collection is fetched from the server.

# File lib/chef/formatters/doc.rb, line 127
def cookbook_resolution_start(expanded_run_list)
  puts_line "Resolving cookbooks for run list: #{expanded_run_list.inspect}"
end
cookbook_sync_complete() click to toggle source

Called after all cookbooks have been sync'd.

# File lib/chef/formatters/doc.rb, line 166
def cookbook_sync_complete
  unindent
end
cookbook_sync_start(cookbook_count) click to toggle source

Called before cookbook sync starts

# File lib/chef/formatters/doc.rb, line 152
def cookbook_sync_start(cookbook_count)
  puts_line "Synchronizing cookbooks:"
  indent
end
deprecation(deprecation, _location = nil) click to toggle source

(see Base#deprecation)

Calls superclass method Chef::Formatters::Base#deprecation
# File lib/chef/formatters/doc.rb, line 413
def deprecation(deprecation, _location = nil)
  if Chef::Config[:treat_deprecation_warnings_as_errors]
    super
  elsif !deprecation.silenced?
    # Save non-silenced deprecations to the screen until the end.
    deprecations[deprecation.message] ||= { url: deprecation.url, locations: Set.new }
    deprecations[deprecation.message][:locations] << deprecation.location
  end
end
elapsed_time() click to toggle source
# File lib/chef/formatters/doc.rb, line 27
def elapsed_time
  end_time - start_time
end
file_loaded(path) click to toggle source

Called after a file in a cookbook is loaded.

# File lib/chef/formatters/doc.rb, line 202
def file_loaded(path); end
handler_executed(handler) click to toggle source

Called after an individual handler has run

# File lib/chef/formatters/doc.rb, line 336
def handler_executed(handler)
  puts_line "- #{handler.class.name}"
end
handlers_completed() click to toggle source

Called after all handlers have executed

# File lib/chef/formatters/doc.rb, line 341
def handlers_completed
  unindent
  puts_line "Running handlers complete\n"
end
handlers_start(handler_count) click to toggle source

Called before handlers run

# File lib/chef/formatters/doc.rb, line 329
def handlers_start(handler_count)
  puts ""
  puts "Running handlers:"
  indent
end
indent() click to toggle source
# File lib/chef/formatters/doc.rb, line 423
def indent
  indent_by(2)
end
inputs_load_start() click to toggle source

Called when compliance input loading starts

# File lib/chef/formatters/doc.rb, line 372
def inputs_load_start
  puts_line("Loading #{Inspec::Dist::PRODUCT_NAME} input files:")
end
library_load_start(file_count) click to toggle source

Called when cookbook loading starts.

# File lib/chef/formatters/doc.rb, line 197
def library_load_start(file_count)
  puts_line "Compiling cookbooks..."
end
node_load_completed(node, expanded_run_list, config) click to toggle source

Default and override attrs from roles have been computed, but not yet applied. Normal attrs from JSON have been added to the node.

# File lib/chef/formatters/doc.rb, line 120
def node_load_completed(node, expanded_run_list, config); end
node_load_failed(node_name, exception, config) click to toggle source

Failed to load node data from the server

Calls superclass method Chef::Formatters::Base#node_load_failed
# File lib/chef/formatters/doc.rb, line 114
def node_load_failed(node_name, exception, config)
  super
end
node_load_start(node_name, config) click to toggle source
# File lib/chef/formatters/doc.rb, line 111
def node_load_start(node_name, config); end
ohai_completed(node) click to toggle source

Called right after ohai runs.

# File lib/chef/formatters/doc.rb, line 99
def ohai_completed(node); end
output_record(line) click to toggle source
# File lib/chef/formatters/doc.rb, line 288
def output_record(line); end
policyfile_loaded(policy) click to toggle source
# File lib/chef/formatters/doc.rb, line 122
def policyfile_loaded(policy)
  puts_line "Using Policyfile '#{policy["name"]}' at revision '#{policy["revision_id"]}'"
end
pretty_elapsed_time() click to toggle source
# File lib/chef/formatters/doc.rb, line 31
def pretty_elapsed_time
  time = elapsed_time
  if time < 60
    message = Time.at(time).utc.strftime("%S seconds")
  elsif time < 3600
    message = Time.at(time).utc.strftime("%M minutes %S seconds")
  else
    message = Time.at(time).utc.strftime("%H hours %M minutes %S seconds")
  end
  message
end
profiles_load_start() click to toggle source

Called when compliance profile loading starts

# File lib/chef/formatters/doc.rb, line 367
def profiles_load_start
  puts_line("Loading #{Inspec::Dist::PRODUCT_NAME} profile files:")
end
provider_requirement_failed(action, resource, exception, message) click to toggle source

Called when an assertion declared by a provider fails

# File lib/chef/formatters/doc.rb, line 357
def provider_requirement_failed(action, resource, exception, message)
  return unless message

  color = Chef::Config[:why_run] ? :yellow : :red
  [ message ].flatten.each do |line|
    start_line("* #{line}", color)
  end
end
recipe_load_complete() click to toggle source

Called when recipes have been loaded.

# File lib/chef/formatters/doc.rb, line 205
def recipe_load_complete; end
registration_completed() click to toggle source
# File lib/chef/formatters/doc.rb, line 109
def registration_completed; end
registration_start(node_name, config) click to toggle source

About to attempt to register as node_name

# File lib/chef/formatters/doc.rb, line 105
def registration_start(node_name, config)
  puts_line "Creating a new client identity for #{node_name} using the validator key."
end
removed_cookbook_file(path) click to toggle source

Called after the file at path is removed. It may be removed if the cookbook containing it was removed from the run list, or if the file was removed from the cookbook.

# File lib/chef/formatters/doc.rb, line 146
def removed_cookbook_file(path); end
resource_action_start(resource, action, notification_type = nil, notifier = nil) click to toggle source

Called before action is executed on a resource.

# File lib/chef/formatters/doc.rb, line 223
def resource_action_start(resource, action, notification_type = nil, notifier = nil)
  if resource.cookbook_name && resource.recipe_name
    resource_recipe = "#{resource.cookbook_name}::#{resource.recipe_name}"
  else
    resource_recipe = "<Dynamically Defined Resource>"
  end

  if resource_recipe != @current_recipe && !resource.enclosing_provider
    unindent if @current_recipe
    puts_line "Recipe: #{resource_recipe}"
    @current_recipe = resource_recipe
    indent
  end
  # @todo info about notifies
  start_line "* #{resource} action #{action}", stream: resource
  indent
end
resource_bypassed(resource, action, provider) click to toggle source
# File lib/chef/formatters/doc.rb, line 283
def resource_bypassed(resource, action, provider)
  puts " (Skipped: Why-Run not supported by provider #{provider.class.name})", stream: resource
  unindent
end
resource_current_state_load_bypassed(resource, action, current_resource) click to toggle source

Called when resource current state load is skipped due to the provider not supporting whyrun mode.

# File lib/chef/formatters/doc.rb, line 320
def resource_current_state_load_bypassed(resource, action, current_resource)
  puts_line("* Why-Run not supported for #{resource}, bypassing load.", :yellow)
end
resource_current_state_loaded(resource, action, current_resource) click to toggle source

Called after load_current_resource has run.

# File lib/chef/formatters/doc.rb, line 274
def resource_current_state_loaded(resource, action, current_resource); end
resource_failed(resource, action, exception) click to toggle source

Called when a resource fails and will not be retried.

Calls superclass method Chef::Formatters::Base#resource_failed
# File lib/chef/formatters/doc.rb, line 260
def resource_failed(resource, action, exception)
  super
  unindent
end
resource_failed_retriable(resource, action, retry_count, exception) click to toggle source

Called when a resource fails, but will retry.

# File lib/chef/formatters/doc.rb, line 257
def resource_failed_retriable(resource, action, retry_count, exception); end
resource_skipped(resource, action, conditional) click to toggle source

Called when a resource action has been skipped b/c of a conditional

# File lib/chef/formatters/doc.rb, line 266
def resource_skipped(resource, action, conditional)
  @skipped_resources += 1
  # TODO: more info about conditional
  puts " (skipped due to #{conditional.short_description})", stream: resource
  unindent
end
resource_up_to_date(resource, action) click to toggle source

Called when a resource has no converge actions, e.g., it was already correct.

# File lib/chef/formatters/doc.rb, line 277
def resource_up_to_date(resource, action)
  @up_to_date_resources += 1
  puts " (up to date)", stream: resource unless resource.suppress_up_to_date_messages?
  unindent
end
resource_update_applied(resource, action, update) click to toggle source

Called when a change has been made to a resource. May be called multiple times per resource, e.g., a file may have its content updated, and then its permissions updated.

# File lib/chef/formatters/doc.rb, line 293
def resource_update_applied(resource, action, update)
  prefix = Chef::Config[:why_run] ? "Would " : ""
  Array(update).each do |line|
    next if line.nil?

    output_record line
    if line.is_a? String
      start_line "- #{prefix}#{line}", :green
    elsif line.is_a? Array
      # Expanded output - delta
      # @todo should we have a resource_update_delta callback?
      line.each do |detail|
        start_line detail, :white
      end
    end
  end
end
resource_update_progress(resource, current, total, interval) click to toggle source
# File lib/chef/formatters/doc.rb, line 241
def resource_update_progress(resource, current, total, interval)
  @progress[resource] ||= -1

  percent_complete = (current.to_f / total.to_f * 100).to_i unless total.to_f == 0.0

  if percent_complete && percent_complete > @progress[resource]

    @progress[resource] = percent_complete

    if percent_complete % interval == 0
      start_line " - Progress: #{percent_complete}%", :green
    end
  end
end
resource_updated(resource, action) click to toggle source

Called after a resource has been completely converged.

# File lib/chef/formatters/doc.rb, line 312
def resource_updated(resource, action)
  @updated_resources += 1
  unindent
  puts "\n"
end
run_completed(node) click to toggle source
# File lib/chef/formatters/doc.rb, line 55
def run_completed(node)
  @end_time = Time.now
  # Print out deprecations.
  unless deprecations.empty?
    puts_line ""
    puts_line "Deprecation warnings that must be addressed before upgrading to Chef Infra #{Chef::VERSION.to_i + 1}:"
    puts_line ""
    deprecations.each do |message, details|
      locations = details[:locations]
      if locations.size == 1
        puts_line "  #{message} at 1 location:"
      else
        puts_line "  #{message} at #{locations.size} locations:"
      end
      locations.each do |location|
        prefix = "    - "
        Array(location).each do |line|
          puts_line "#{prefix}#{line}"
          prefix = "      "
        end
      end
      unless details[:url].nil?
        puts_line "   See #{details[:url]} for further details."
      end
    end
    puts_line ""
  end
  if Chef::Config[:why_run]
    puts_line "Infra Phase complete, #{@updated_resources}/#{total_resources} resources would have been updated"
  else
    puts_line "Infra Phase complete, #{@updated_resources}/#{total_resources} resources updated in #{pretty_elapsed_time}"
  end
end
run_failed(exception) click to toggle source
# File lib/chef/formatters/doc.rb, line 89
def run_failed(exception)
  @end_time = Time.now
  if Chef::Config[:why_run]
    puts_line "Infra Phase failed. #{@updated_resources} resources would have been updated"
  else
    puts_line "Infra Phase failed. #{@updated_resources} resources updated in #{pretty_elapsed_time}"
  end
end
run_start(version, run_status) click to toggle source
# File lib/chef/formatters/doc.rb, line 43
def run_start(version, run_status)
  puts_line "#{ChefUtils::Dist::Infra::PRODUCT}, version #{version}"
  puts_line "Patents: #{ChefUtils::Dist::Org::PATENTS}"
  puts_line "OpenSSL FIPS 140 mode enabled" if Chef::Config[:fips]
  puts_line "Infra Phase starting"
  puts_line "Targeting node: #{Chef::Config.target_mode.host}" if Chef::Config.target_mode?
end
skipping_registration(node_name, config) click to toggle source

Already have a client key, assuming this node has registered.

# File lib/chef/formatters/doc.rb, line 102
def skipping_registration(node_name, config); end
stream_output(stream, output, options = {}) click to toggle source
# File lib/chef/formatters/doc.rb, line 324
def stream_output(stream, output, options = {})
  print(output, { stream: stream }.merge(options))
end
synchronized_cookbook(cookbook_name, cookbook) click to toggle source

Called when cookbook cookbook has been sync'd

# File lib/chef/formatters/doc.rb, line 158
def synchronized_cookbook(cookbook_name, cookbook)
  puts_line "- #{cookbook.name} (#{cookbook.version})"
end
total_resources() click to toggle source
# File lib/chef/formatters/doc.rb, line 51
def total_resources
  @up_to_date_resources + @updated_resources + @skipped_resources
end
unindent() click to toggle source
# File lib/chef/formatters/doc.rb, line 427
def unindent
  indent_by(-2)
end
updated_cookbook_file(cookbook_name, path) click to toggle source

Called when an individual file in a cookbook has been updated

# File lib/chef/formatters/doc.rb, line 163
def updated_cookbook_file(cookbook_name, path); end
waivers_load_start() click to toggle source

Called when compliance waiver loading starts

# File lib/chef/formatters/doc.rb, line 377
def waivers_load_start
  puts_line("Loading #{Inspec::Dist::PRODUCT_NAME} waiver files:")
end
whyrun_assumption(action, resource, message) click to toggle source

Called when a provider makes an assumption after a failed assertion in whyrun mode, in order to allow execution to continue

# File lib/chef/formatters/doc.rb, line 348
def whyrun_assumption(action, resource, message)
  return unless message

  [ message ].flatten.each do |line|
    start_line("* #{line}", :yellow)
  end
end

Protected Instance Methods

deprecations() click to toggle source
# File lib/chef/formatters/doc.rb, line 433
def deprecations
  @deprecations ||= {}
end