Class: Chef::Formatters::Doc

Inherits:
Base show all
Defined in:
lib/chef/formatters/doc.rb

Overview

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

Instance Attribute Summary collapse

Attributes inherited from Base

#err, #out, #output

Instance Method Summary collapse

Methods inherited from Base

#attribute_file_load_failed, #attribute_file_loaded, cli_name, #cookbook_sync_failed, #definition_file_load_failed, #definition_file_loaded, #display_error, #file_load_failed, #indent_by, #is_formatter?, #is_structured_deprecation?, #library_file_load_failed, #library_file_loaded, #lwrp_file_load_failed, #lwrp_file_loaded, #print, #puts, #puts_line, #recipe_file_load_failed, #recipe_file_loaded, #recipe_not_found, #registration_failed, #run_list_expand_failed, #start_line

Methods included from ErrorMapper

cookbook_resolution_failed, cookbook_sync_failed, file_load_failed, node_load_failed, registration_failed, resource_failed, run_list_expand_failed

Methods inherited from EventDispatch::Base

#action_collection_registration, #attribute_changed, #attribute_file_load_failed, #attribute_file_loaded, #attribute_load_complete, #attribute_load_start, #compliance_load_complete, #compliance_load_start, #cookbook_compilation_complete, #cookbook_compilation_start, #cookbook_sync_failed, #definition_file_load_failed, #definition_file_loaded, #definition_load_complete, #definition_load_start, #inputs_load_complete, #key_migration_status, #library_file_load_failed, #library_file_loaded, #library_load_complete, #lwrp_file_load_failed, #lwrp_file_loaded, #lwrp_load_complete, #lwrp_load_start, #msg, #node_load_success, #ohai_plugin_file_load_failed, #ohai_plugin_file_loaded, #ohai_plugin_load_complete, #ohai_plugin_load_start, #profiles_load_complete, #recipe_file_load_failed, #recipe_file_loaded, #recipe_load_start, #recipe_not_found, #registration_failed, #resource_after_state_loaded, #resource_completed, #run_list_expand_failed, #run_list_expanded, #run_started, #stream_closed, #stream_opened, #waivers_load_complete

Constructor Details

#initialize(out, err) ⇒ Doc

Returns a new instance of Doc.



16
17
18
19
20
21
22
23
24
25
 
# 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

Instance Attribute Details

#end_time ⇒ Object (readonly)

Returns the value of attribute end_time.



12
13
14
 
# File 'lib/chef/formatters/doc.rb', line 12

def end_time
  @end_time
end

#start_time ⇒ Object (readonly)

Returns the value of attribute start_time.



12
13
14
 
# File 'lib/chef/formatters/doc.rb', line 12

def start_time
  @start_time
end

Instance Method Details

#compliance_input_enabled(input) ⇒ Object

Called when a compliance input is enabled (by include_input)



408
409
410
 
# File 'lib/chef/formatters/doc.rb', line 408

def compliance_input_enabled(input)
  # puts_line("  * FIXME", :cyan)
end

#compliance_input_loaded(input) ⇒ Object

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



388
389
390
 
# 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) ⇒ Object

Called when a compliance profile is enabled (by include_profile)



398
399
400
 
# File 'lib/chef/formatters/doc.rb', line 398

def compliance_profile_enabled(profile)
  # puts_line("  * FIXME", :cyan)
end

#compliance_profile_loaded(profile) ⇒ Object

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



382
383
384
385
 
# 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) ⇒ Object

Called when a compliance waiver is enabled (by include_waiver)



403
404
405
 
# File 'lib/chef/formatters/doc.rb', line 403

def compliance_waiver_enabled(waiver)
  # puts_line("  * FIXME", :cyan)
end

#compliance_waiver_loaded(waiver) ⇒ Object

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



393
394
395
 
# File 'lib/chef/formatters/doc.rb', line 393

def compliance_waiver_loaded(waiver)
  puts_line("  - #{waiver.cookbook_name}::#{waiver.pathname}", :cyan)
end

#converge_complete ⇒ Object

Called when the converge phase is finished.



213
214
215
 
# File 'lib/chef/formatters/doc.rb', line 213

def converge_complete
  unindent if @current_recipe
end

#converge_failed(e) ⇒ Object 



217
218
219
220
 
# 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) ⇒ Object

Called before convergence starts



208
209
210
 
# 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 ⇒ Object

Called when cookbook cleaning is finished.



149
 
# File 'lib/chef/formatters/doc.rb', line 149

def cookbook_clean_complete; end

#cookbook_clean_start ⇒ Object

Called before unneeded cookbooks are removed



141
 
# File 'lib/chef/formatters/doc.rb', line 141

def cookbook_clean_start; end

#cookbook_gem_failed(exception) ⇒ Object

Called when cookbook gem installation fails



192
193
194
 
# File 'lib/chef/formatters/doc.rb', line 192

def cookbook_gem_failed(exception)
  unindent
end

#cookbook_gem_finished ⇒ Object

Called when finished installing cookbook gems



187
188
189
 
# File 'lib/chef/formatters/doc.rb', line 187

def cookbook_gem_finished
  unindent
end

#cookbook_gem_installing(gem, version) ⇒ Object

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



177
178
179
 
# 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) ⇒ Object

Called when starting to collect gems from the cookbooks



171
172
173
174
 
# 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) ⇒ Object

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



182
183
184
 
# 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) ⇒ Object

Called when the cookbook collection is returned from the server.



138
 
# File 'lib/chef/formatters/doc.rb', line 138

def cookbook_resolution_complete(cookbook_collection); end

#cookbook_resolution_failed(expanded_run_list, exception) ⇒ Object

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



133
134
135
 
# File 'lib/chef/formatters/doc.rb', line 133

def cookbook_resolution_failed(expanded_run_list, exception)
  super
end

#cookbook_resolution_start(expanded_run_list) ⇒ Object

Called before the cookbook collection is fetched from the server.



127
128
129
 
# 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 ⇒ Object

Called after all cookbooks have been sync’d.



166
167
168
 
# File 'lib/chef/formatters/doc.rb', line 166

def cookbook_sync_complete
  unindent
end

#cookbook_sync_start(cookbook_count) ⇒ Object

Called before cookbook sync starts



152
153
154
155
 
# File 'lib/chef/formatters/doc.rb', line 152

def cookbook_sync_start(cookbook_count)
  puts_line "Synchronizing cookbooks:"
  indent
end

#deprecation(deprecation, _location = nil) ⇒ Object

Log a deprecation warning object.

Parameters:

  • deprecation (Chef::Deprecated::Base) —

    Deprecation object to log. In previous versions, this could be a string. Don’t do that anymore.

  • location (Object) —

    Unused, present only for compatibility.



413
414
415
416
417
418
419
420
421
 
# 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 ⇒ Object 



27
28
29
 
# File 'lib/chef/formatters/doc.rb', line 27

def elapsed_time
  end_time - start_time
end

#file_loaded(path) ⇒ Object

Called after a file in a cookbook is loaded.



202
 
# File 'lib/chef/formatters/doc.rb', line 202

def file_loaded(path); end

#handler_executed(handler) ⇒ Object

Called after an individual handler has run



336
337
338
 
# File 'lib/chef/formatters/doc.rb', line 336

def handler_executed(handler)
  puts_line "- #{handler.class.name}"
end

#handlers_completed ⇒ Object

Called after all handlers have executed



341
342
343
344
 
# File 'lib/chef/formatters/doc.rb', line 341

def handlers_completed
  unindent
  puts_line "Running handlers complete\n"
end

#handlers_start(handler_count) ⇒ Object

Called before handlers run



329
330
331
332
333
 
# File 'lib/chef/formatters/doc.rb', line 329

def handlers_start(handler_count)
  puts ""
  puts "Running handlers:"
  indent
end

#indent ⇒ Object 



423
424
425
 
# File 'lib/chef/formatters/doc.rb', line 423

def indent
  indent_by(2)
end

#inputs_load_start ⇒ Object

Called when compliance input loading starts



372
373
374
 
# 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) ⇒ Object

Called when cookbook loading starts.



197
198
199
 
# 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) ⇒ Object

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



120
 
# 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) ⇒ Object

Failed to load node data from the server



114
115
116
 
# File 'lib/chef/formatters/doc.rb', line 114

def node_load_failed(node_name, exception, config)
  super
end

#node_load_start(node_name, config) ⇒ Object 



111
 
# File 'lib/chef/formatters/doc.rb', line 111

def node_load_start(node_name, config); end

#ohai_completed(node) ⇒ Object

Called right after ohai runs.



99
 
# File 'lib/chef/formatters/doc.rb', line 99

def ohai_completed(node); end

#output_record(line) ⇒ Object 



288
 
# File 'lib/chef/formatters/doc.rb', line 288

def output_record(line); end

#policyfile_loaded(policy) ⇒ Object 



122
123
124
 
# 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 ⇒ Object 



31
32
33
34
35
36
37
38
39
40
41
 
# 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 ⇒ Object

Called when compliance profile loading starts



367
368
369
 
# 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) ⇒ Object

Called when an assertion declared by a provider fails



357
358
359
360
361
362
363
364
 
# 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 ⇒ Object

Called when recipes have been loaded.



205
 
# File 'lib/chef/formatters/doc.rb', line 205

def recipe_load_complete; end

#registration_completed ⇒ Object 



109
 
# File 'lib/chef/formatters/doc.rb', line 109

def registration_completed; end

#registration_start(node_name, config) ⇒ Object

About to attempt to register as node_name



105
106
107
 
# 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) ⇒ Object

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.



146
 
# File 'lib/chef/formatters/doc.rb', line 146

def removed_cookbook_file(path); end

#resource_action_start(resource, action, notification_type = nil, notifier = nil) ⇒ Object

Called before action is executed on a resource.



223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
 
# 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) ⇒ Object 



283
284
285
286
 
# 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) ⇒ Object

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



320
321
322
 
# 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) ⇒ Object

Called after #load_current_resource has run.



274
 
# File 'lib/chef/formatters/doc.rb', line 274

def resource_current_state_loaded(resource, action, current_resource); end

#resource_failed(resource, action, exception) ⇒ Object

Called when a resource fails and will not be retried.



260
261
262
263
 
# 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) ⇒ Object

Called when a resource fails, but will retry.



257
 
# File 'lib/chef/formatters/doc.rb', line 257

def resource_failed_retriable(resource, action, retry_count, exception); end

#resource_skipped(resource, action, conditional) ⇒ Object

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



266
267
268
269
270
271
 
# 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) ⇒ Object

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



277
278
279
280
281
 
# 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) ⇒ Object

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.



293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
 
# 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) ⇒ Object 



241
242
243
244
245
246
247
248
249
250
251
252
253
254
 
# 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) ⇒ Object

Called after a resource has been completely converged.



312
313
314
315
316
 
# File 'lib/chef/formatters/doc.rb', line 312

def resource_updated(resource, action)
  @updated_resources += 1
  unindent
  puts "\n"
end

#run_completed(node) ⇒ Object 



55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
 
# 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 #{ChefUtils::Dist::Infra::PRODUCT} #{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) ⇒ Object 



89
90
91
92
93
94
95
96
 
# 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) ⇒ Object 



43
44
45
46
47
48
49
 
# 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) ⇒ Object

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



102
 
# File 'lib/chef/formatters/doc.rb', line 102

def skipping_registration(node_name, config); end

#stream_output(stream, output, options = {}) ⇒ Object 



324
325
326
 
# 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) ⇒ Object

Called when cookbook cookbook has been sync’d



158
159
160
 
# File 'lib/chef/formatters/doc.rb', line 158

def synchronized_cookbook(cookbook_name, cookbook)
  puts_line "- #{cookbook.name} (#{cookbook.version})"
end

#total_resources ⇒ Object 



51
52
53
 
# File 'lib/chef/formatters/doc.rb', line 51

def total_resources
  @up_to_date_resources + @updated_resources + @skipped_resources
end

#unindent ⇒ Object 



427
428
429
 
# File 'lib/chef/formatters/doc.rb', line 427

def unindent
  indent_by(-2)
end

#updated_cookbook_file(cookbook_name, path) ⇒ Object

Called when an individual file in a cookbook has been updated



163
 
# File 'lib/chef/formatters/doc.rb', line 163

def updated_cookbook_file(cookbook_name, path); end

#waivers_load_start ⇒ Object

Called when compliance waiver loading starts



377
378
379
 
# 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) ⇒ Object

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



348
349
350
351
352
353
354
 
# 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