module Kitchen::Configurable::ClassMethods
Class methods which will be mixed in on inclusion of Configurable
module.
Public Instance Methods
Sets a sane default value for a configuration attribute. These values can be overridden by provided configuration or in a subclass with another default_config
declaration.
@example a nil default value
default_config :i_am_nil
@example a primitive default value
default_config :use_sudo, true
@example a block to compute a default value
default_config :box_name do |subject| subject.instance.platform.name end
@param attr [String] configuration attribute name @param value [Object, nil] static default value for attribute @yieldparam object [Object] a reference to the instantiated object @yieldreturn [Object, nil] dynamically computed value for the attribute
# File lib/kitchen/configurable.rb, line 462 def default_config(attr, value = nil, &block) defaults[attr] = block_given? ? block : value end
@return [Hash] a hash of attribute keys and default values which has
been merged with any superclass defaults
@api private
# File lib/kitchen/configurable.rb, line 551 def defaults @defaults ||= {}.merge(super_defaults) end
Set the appropriate deprecation message for a given attribute name
@example the default usage
deprecate_config_for :attribute_name, "Detailed deprecation message."
@example using a block
deprecate_config_for :attribute_name do |subject| "Detailed deprecation message." if subject == true end
@param attr [String] configuration attribute name @param value [Object, nil] static default value for attribute @yieldparam object [Object] a reference to the instantiated object @yieldreturn [Object, nil] dynamically computed value for the attribute
# File lib/kitchen/configurable.rb, line 512 def deprecate_config_for(attr, value = nil, &block) deprecated_attributes[attr] = block_given? ? block : value end
# File lib/kitchen/configurable.rb, line 585 def deprecated_attributes @deprecated_attributes ||= {}.merge(super_deprecated_attributes) end
Returns a Hash
of configuration and other useful diagnostic information.
@return [Hash] a diagnostic hash
# File lib/kitchen/configurable.rb, line 432 def diagnose { class: name, version: @plugin_version ||= nil, api_version: @api_version ||= nil, } end
Ensures that an attribute which is a path will be fully expanded at the right time. This helps make the configuration unambiguous and much easier to debug and diagnose.
Note that the file path expansion is only intended for paths on the local workstation invking the Test Kitchen
code.
@example the default usage
expand_path_for :data_path
@example disabling path expansion with a falsey value
expand_path_for :relative_path, false
@example using a block to determine whether or not to expand
expand_path_for :relative_or_not_path do |subject| subject.instance.name =~ /default/ end
@param attr [String] configuration attribute name @param value [Object, nil] whether or not to exand the file path @yieldparam object [Object] a reference to the instantiated object @yieldreturn [Object, nil] dynamically compute whether or not to
perform the file expansion
# File lib/kitchen/configurable.rb, line 492 def expand_path_for(attr, value = true, &block) expanded_paths[attr] = block_given? ? block : value end
@return [Hash] a hash of attribute keys and truthy/falsey values to
determine if said attribute needs to be fully file path expanded, which has been merged with any superclass expanded paths
@api private
# File lib/kitchen/configurable.rb, line 570 def expanded_paths @expanded_paths ||= {}.merge(super_expanded_paths) end
Sets the loaded version of this plugin, usually corresponding to the RubyGems version of the plugin's library. If the plugin does not set this value, then `nil` will be used and reported.
@example setting a version used by RubyGems
require "kitchen/driver/vagrant_version" module Kitchen module Driver class Vagrant < Kitchen::Driver::Base plugin_version Kitchen::Driver::VAGRANT_VERSION end end end
@param version [String] a version string
# File lib/kitchen/configurable.rb, line 424 def plugin_version(version) # rubocop:disable Style/TrivialAccessors @plugin_version = version end
Ensures that an attribute must have a non-nil, non-empty String value. The default behavior will be to raise a user error and thereby halting further configuration processing. Good use cases for require_config might be cloud provider credential keys and other similar data.
@example a value that must not be nil or an empty String
required_config :cloud_api_token
@example using a block to use custom validation logic
required_config :email do |attr, value, subject| raise UserError, "Must be an email address" unless value =~ /@/ end
@param attr [String] configuration attribute name @yieldparam attr [Symbol] the attribute name @yieldparam value [Object] the current value of the attribute @yieldparam object [Object] a reference to the instantiated object
# File lib/kitchen/configurable.rb, line 535 def required_config(attr, &block) unless block_given? klass = self block = lambda do |_, value, thing| if value.nil? || value.to_s.empty? attribute = "#{klass}#{thing.instance.to_str}#config[:#{attr}]" raise UserError, "#{attribute} cannot be blank" end end end validations[attr] = block end
@return [Hash] a hash of defaults from the included class' superclass
if defined in the superclass, or an empty hash otherwise
@api private
# File lib/kitchen/configurable.rb, line 558 def super_defaults if superclass.respond_to?(:defaults) superclass.defaults else {} end end
# File lib/kitchen/configurable.rb, line 589 def super_deprecated_attributes if superclass.respond_to?(:deprecated_attributes) superclass.deprecated_attributes else {} end end
@return [Hash] a hash of expanded paths from the included class'
superclass if defined in the superclass, or an empty hash otherwise
@api private
# File lib/kitchen/configurable.rb, line 577 def super_expanded_paths if superclass.respond_to?(:expanded_paths) superclass.expanded_paths else {} end end
@return [Hash] a hash of validations from the included class'
superclass if defined in the superclass, or an empty hash otherwise
@api private
# File lib/kitchen/configurable.rb, line 607 def super_validations if superclass.respond_to?(:validations) superclass.validations else {} end end
@return [Hash] a hash of attribute keys and valudation callable blocks
which has been merged with any superclass valudations
@api private
# File lib/kitchen/configurable.rb, line 600 def validations @validations ||= {}.merge(super_validations) end