Module: Kitchen::Configurable::ClassMethods

Defined in:
lib/kitchen/configurable.rb

Overview

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

Instance Method Summary collapse

Instance Method Details

#default_config(attr, value = nil) {|object| ... } ⇒ Object

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.

Examples:

a nil default value


default_config :i_am_nil

a primitive default value


default_config :use_sudo, true

a block to compute a default value


default_config :box_name do |subject|
  subject.instance.platform.name
end

Parameters:

  • attr (String) —

    configuration attribute name

  • value (Object, nil) (defaults to: nil) —

    static default value for attribute

Yield Parameters:

  • object (Object) —

    a reference to the instantiated object

Yield Returns:

  • (Object, nil) —

    dynamically computed value for the attribute



473
474
475
 
# File 'lib/kitchen/configurable.rb', line 473

def default_config(attr, value = nil, &block)
  defaults[attr] = block_given? ? block : value
end

#defaults ⇒ Hash

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns a hash of attribute keys and default values which has been merged with any superclass defaults.

Returns:

  • (Hash) —

    a hash of attribute keys and default values which has been merged with any superclass defaults



562
563
564
 
# File 'lib/kitchen/configurable.rb', line 562

def defaults
  @defaults ||= {}.merge(super_defaults)
end

#deprecate_config_for(attr, value = nil) {|object| ... } ⇒ Object

Set the appropriate deprecation message for a given attribute name

Examples:

the default usage


deprecate_config_for :attribute_name, "Detailed deprecation message."

using a block


deprecate_config_for :attribute_name do |subject|
  "Detailed deprecation message." if subject == true
end

Parameters:

  • attr (String) —

    configuration attribute name

  • value (Object, nil) (defaults to: nil) —

    static default value for attribute

Yield Parameters:

  • object (Object) —

    a reference to the instantiated object

Yield Returns:

  • (Object, nil) —

    dynamically computed value for the attribute



523
524
525
 
# File 'lib/kitchen/configurable.rb', line 523

def deprecate_config_for(attr, value = nil, &block)
  deprecated_attributes[attr] = block_given? ? block : value
end

#deprecated_attributes ⇒ Hash

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns a hash of attribute keys and deprecation messages which has been merged with any superclass deprecations.

Returns:

  • (Hash) —

    a hash of attribute keys and deprecation messages which has been merged with any superclass deprecations



599
600
601
 
# File 'lib/kitchen/configurable.rb', line 599

def deprecated_attributes
  @deprecated_attributes ||= {}.merge(super_deprecated_attributes)
end

#diagnose ⇒ Hash

Returns a Hash of configuration and other useful diagnostic information.

Returns:

  • (Hash) —

    a diagnostic hash



443
444
445
446
447
448
449
 
# File 'lib/kitchen/configurable.rb', line 443

def diagnose
  {
    class: name,
    version: @plugin_version ||= nil,
    api_version: @api_version ||= nil,
  }
end

#expand_path_for(attr, value = true) {|object| ... } ⇒ Object

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 invoking the Test Kitchen code.

Examples:

the default usage


expand_path_for :data_path

disabling path expansion with a falsey value


expand_path_for :relative_path, false

using a block to determine whether or not to expand


expand_path_for :relative_or_not_path do |subject|
  subject.instance.name =~ /default/
end

Parameters:

  • attr (String) —

    configuration attribute name

  • value (Object, nil) (defaults to: true) —

    whether or not to expand the file path

Yield Parameters:

  • object (Object) —

    a reference to the instantiated object

Yield Returns:

  • (Object, nil) —

    dynamically compute whether or not to perform the file expansion



503
504
505
 
# File 'lib/kitchen/configurable.rb', line 503

def expand_path_for(attr, value = true, &block)
  expanded_paths[attr] = block_given? ? block : value
end

#expanded_paths ⇒ Hash

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns 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.

Returns:

  • (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



581
582
583
 
# File 'lib/kitchen/configurable.rb', line 581

def expanded_paths
  @expanded_paths ||= {}.merge(super_expanded_paths)
end

#plugin_version(version) ⇒ Object

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.

Examples:

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

Parameters:

  • version (String) —

    a version string



435
436
437
 
# File 'lib/kitchen/configurable.rb', line 435

def plugin_version(version) # rubocop:disable Style/TrivialAccessors
  @plugin_version = version
end

#required_config(attr) {|attr, value, object| ... } ⇒ Object

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.

Examples:

a value that must not be nil or an empty String


required_config :cloud_api_token

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

Parameters:

  • attr (String) —

    configuration attribute name

Yield Parameters:

  • attr (Symbol) —

    the attribute name

  • value (Object) —

    the current value of the attribute

  • object (Object) —

    a reference to the instantiated object



546
547
548
549
550
551
552
553
554
555
556
557
 
# File 'lib/kitchen/configurable.rb', line 546

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 ⇒ Hash

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns a hash of defaults from the included class' superclass if defined in the superclass, or an empty hash otherwise.

Returns:

  • (Hash) —

    a hash of defaults from the included class' superclass if defined in the superclass, or an empty hash otherwise



569
570
571
572
573
574
575
 
# File 'lib/kitchen/configurable.rb', line 569

def super_defaults
  if superclass.respond_to?(:defaults)
    superclass.defaults
  else
    {}
  end
end

#super_deprecated_attributes ⇒ Hash

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns a hash of deprecated attributes from the superclass, or an empty hash when the superclass has none.

Returns:

  • (Hash) —

    a hash of deprecated attributes from the superclass, or an empty hash when the superclass has none



606
607
608
609
610
611
612
 
# File 'lib/kitchen/configurable.rb', line 606

def super_deprecated_attributes
  if superclass.respond_to?(:deprecated_attributes)
    superclass.deprecated_attributes
  else
    {}
  end
end

#super_expanded_paths ⇒ Hash

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns a hash of expanded paths from the included class' superclass if defined in the superclass, or an empty hash otherwise.

Returns:

  • (Hash) —

    a hash of expanded paths from the included class' superclass if defined in the superclass, or an empty hash otherwise



588
589
590
591
592
593
594
 
# File 'lib/kitchen/configurable.rb', line 588

def super_expanded_paths
  if superclass.respond_to?(:expanded_paths)
    superclass.expanded_paths
  else
    {}
  end
end

#super_validations ⇒ Hash

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns a hash of validations from the included class' superclass if defined in the superclass, or an empty hash otherwise.

Returns:

  • (Hash) —

    a hash of validations from the included class' superclass if defined in the superclass, or an empty hash otherwise



624
625
626
627
628
629
630
 
# File 'lib/kitchen/configurable.rb', line 624

def super_validations
  if superclass.respond_to?(:validations)
    superclass.validations
  else
    {}
  end
end

#validations ⇒ Hash

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns a hash of attribute keys and validation callable blocks which has been merged with any superclass validations.

Returns:

  • (Hash) —

    a hash of attribute keys and validation callable blocks which has been merged with any superclass validations



617
618
619
 
# File 'lib/kitchen/configurable.rb', line 617

def validations
  @validations ||= {}.merge(super_validations)
end