module Kitchen::Configurable::ClassMethods

Class methods which will be mixed in on inclusion of Configurable module.

Public Instance Methods

default_config(attr, value = nil, &block) click to toggle source

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
defaults() click to toggle source

@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
deprecate_config_for(attr, value = nil, &block) click to toggle source

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
deprecated_attributes() click to toggle source
# File lib/kitchen/configurable.rb, line 585
def deprecated_attributes
  @deprecated_attributes ||= {}.merge(super_deprecated_attributes)
end
diagnose() click to toggle source

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
expand_path_for(attr, value = true, &block) click to toggle source

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
expanded_paths() click to toggle source

@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
plugin_version(version) click to toggle source

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
required_config(attr, &block) click to toggle source

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
super_defaults() click to toggle source

@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
super_deprecated_attributes() click to toggle source
# File lib/kitchen/configurable.rb, line 589
def super_deprecated_attributes
  if superclass.respond_to?(:deprecated_attributes)
    superclass.deprecated_attributes
  else
    {}
  end
end
super_expanded_paths() click to toggle source

@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
super_validations() click to toggle source

@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
validations() click to toggle source

@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