akerl-r10k 3.14.2.1

data/lib/r10k/settings/container.rb

@@ -0,0 +1,97 @@
+# Defines a collection for application settings
+#
+# This implements a hierarchical interface to application settings. Containers
+# can define an optional parent container that will be used for default options
+# if those options aren't set on the given container.
+class R10K::Settings::Container
+
+  # @!attribute [r] valid_keys
+  #   @return [Set<Symbol>] All valid keys defined on the container or parent container.
+  attr_accessor :valid_keys
+
+  # @param parent [R10K::Settings::Container] An optional parent container
+  def initialize(parent = nil)
+    @parent = parent
+
+    @valid_keys = Set.new
+    @settings = {}
+  end
+
+  # Look up a value in the container. The lookup checks the current container,
+  # and then falls back to the parent container if it's given.
+  #
+  # @param key [Symbol] The lookup key
+  #
+  # @return [Object, nil] The retrieved value if present.
+  #
+  # @raise [R10K::Settings::Container::InvalidKey] If the looked up key isn't
+  #   a valid key.
+  def [](key)
+    validate_key! key
+
+    if @settings[key]
+      @settings[key]
+    elsif @parent && (pkey = @parent[key])
+      begin
+        @settings[key] = pkey.dup
+      rescue TypeError
+        @settings[key] = pkey
+      end
+      @settings[key]
+    end
+  end
+
+  # Set a value on the container
+  #
+  # @param key [Symbol] The lookup key
+  # @param value [Object] The value to store in the container
+  #
+  # @raise [R10K::Settings::Container::InvalidKey] If the looked up key isn't
+  #   a valid key.
+  def []=(key, value)
+    validate_key! key
+
+    @settings[key] = value
+  end
+
+  # Define a valid container key
+  #
+  # @note This should only be used by {#R10K::Settings::ClassSettings}
+  #
+  # @param key [Symbol]
+  # @return [void]
+  def add_valid_key(key)
+    @valid_keys.add(key)
+  end
+
+  # Determine if a key is a valid setting.
+  #
+  # @param key [Symbol]
+  #
+  # @return [true, false]
+  def valid_key?(key)
+    if @valid_keys.include?(key)
+      true
+    elsif @parent and @parent.valid_key?(key)
+      @valid_keys.add(key)
+      true
+    end
+  end
+
+  # Clear all existing settings in this container. Valid settings are left alone.
+  # @return [void]
+  def reset!
+    @settings = {}
+  end
+
+  private
+
+  def validate_key!(key)
+    unless valid_key?(key)
+      raise InvalidKey, _("Key %{key} is not a valid key") % {key: key}
+    end
+  end
+
+  # @api private
+  class InvalidKey < StandardError; end
+end

data/lib/r10k/settings/definition.rb

@@ -0,0 +1,124 @@
+require 'r10k/settings/helpers'
+require 'r10k/util/setopts'
+
+module R10K
+  module Settings
+
+    # Define a single setting and additional attributes like descriptions,
+    # default values, and validation.
+    class Definition
+      require 'r10k/settings/uri_definition'
+      require 'r10k/settings/enum_definition'
+
+      include R10K::Settings::Helpers
+      include R10K::Util::Setopts
+
+      # @!attribute [r] name
+      #   @return [String] The name of this setting
+      attr_reader :name
+
+      # @!attribute [r] value
+      #   @return [Object] An explicitly set value. This should only be used if
+      #     an optional default value should not be used; otherwise use {#resolve}.
+      attr_reader :value
+
+      # @!attribute [r] desc
+      #   @return [String] An optional documentation string for this setting.
+      attr_reader :desc
+
+      # @param name [Symbol] The name of the setting for this definition.
+      # @param opts [Hash] Additional options for this definition to control
+      #   validation, normalization, and the like.
+      #
+      # @option opts [Proc, Object] :default An optional proc or object for
+      #   this setting. If no value has been set and the default is a Proc then
+      #   it will be called and the result will be returned, otherwise if the
+      #   value is not set the default value itself is returned.
+      #
+      # @options opts [Proc] :validate An optional proc that can be used to
+      #   validate an assigned value. Default values are not assigned.
+      #
+      # @options opts [Proc] :normalize An optional proc that can be used to
+      #   normalize an explicitly assigned value.
+      def initialize(name, opts = {})
+        @name = name
+        setopts(opts, allowed_initialize_opts)
+      end
+
+      # Assign new values, perform validation checks, and return the final
+      # values for this collection
+      def evaluate(newvalue)
+        assign(newvalue)
+        validate
+        resolve
+      end
+
+      # Store an explicit value for this definition
+      #
+      # If a :normalize hook has been given then it will be called with the
+      # new value and the returned value will be stored.
+      #
+      # @param newvalue [Object] The value to store for this setting
+      # @return [void]
+      def assign(newvalue)
+        if @normalize
+          @value = @normalize.call(newvalue)
+        else
+          @value = newvalue
+        end
+      end
+
+      # Call any validation hooks for this definition.
+      #
+      # The :validate hook will be called if the hook has been set and an
+      # explicit value has been assigned to this definition. Validation
+      # failures should be indicated by the :validate hook raising an exception.
+      #
+      # @raise [Exception] An exception class indicating that validation failed.
+      # @return [nil]
+      def validate
+        if @value && @validate
+          @validate.call(@value)
+        end
+        nil
+      end
+
+      # Compute the final value of this setting. If a value has not been
+      # assigned the default value will be used.
+      #
+      # @return [Object] The final value of this definition.
+      def resolve
+        if !@value.nil?
+          @value
+        elsif !@default.nil?
+          if @default == :inherit
+            # walk all the way up to root, starting with grandparent
+            ancestor = parent
+
+            while ancestor = ancestor.parent
+              return ancestor[@name].resolve if ancestor.respond_to?(:[]) && ancestor[@name]
+            end
+          elsif @default.is_a?(Proc)
+            @default.call
+          else
+            @default
+          end
+        end
+      end
+
+      private
+
+      # Subclasses may define additional params that are accepted at
+      # initialization; they should override this method to add any
+      # additional fields that should be respected.
+      def allowed_initialize_opts
+        {
+          :desc      => true,
+          :default   => true,
+          :validate  => true,
+          :normalize => true,
+        }
+      end
+    end
+  end
+end

data/lib/r10k/settings/enum_definition.rb

@@ -0,0 +1,30 @@
+require 'r10k/settings/definition'
+
+module R10K
+  module Settings
+    class EnumDefinition < R10K::Settings::Definition
+
+      def validate
+        if @value
+          if @multi && @value.respond_to?(:select)
+            invalid = @value.select { |val| !@enum.include?(val) }
+
+            if invalid.size > 0
+              raise ArgumentError, _("Setting %{name} may only contain %{enums}; the disallowed values %{invalid} were present") % {name: @name, enums: @enum.inspect, invalid: invalid.inspect}
+            end
+          else
+            if !@enum.include?(@value)
+              raise ArgumentError, _("Setting %{name} should be one of %{enums}, not '%{value}'") % {name: @name, enums: @enum.inspect, value: @value}
+            end
+          end
+        end
+      end
+
+      private
+
+      def allowed_initialize_opts
+        super.merge({:enum => true, :multi => true})
+      end
+    end
+  end
+end

data/lib/r10k/settings/helpers.rb

@@ -0,0 +1,38 @@
+require 'r10k/errors'
+require 'r10k/settings/collection'
+
+module R10K
+  module Settings
+    module Helpers
+      def self.included(klass)
+        klass.send(:include, InstanceMethods)
+        klass.send(:extend, ClassMethods)
+      end
+
+      module InstanceMethods
+        # Assign a parent collection to this setting. Parent may only be
+        # assigned once.
+        #
+        # @param new_parent [R10K::Settings::Collection] Parent collection
+        def parent=(new_parent)
+          unless @parent.nil?
+            raise R10K::Error.new(_("%{class} instances cannot be reassigned to a new parent.") % {class: self.class} )
+          end
+
+          unless new_parent.is_a?(R10K::Settings::Collection) || new_parent.is_a?(R10K::Settings::List)
+            raise R10K::Error.new(_("%{class} instances may only belong to a settings collection or list.") % {class: self.class} )
+          end
+
+          @parent = new_parent
+        end
+
+        def parent
+          @parent
+        end
+      end
+
+      module ClassMethods
+      end
+    end
+  end
+end

data/lib/r10k/settings/list.rb

@@ -0,0 +1,107 @@
+require 'r10k/settings/helpers'
+require 'r10k/settings/collection'
+require 'r10k/errors'
+require 'r10k/util/setopts'
+
+module R10K
+  module Settings
+
+    # A container for an arbitrarily long list of other settings.
+    class List
+      include R10K::Settings::Helpers
+      include R10K::Util::Setopts
+
+      # @!attribute [r] name
+      #   @return [String] The name of this collection
+      attr_reader :name
+
+      # @param name [Symbol] The name of the setting for this definition.
+      # @param item_proc [#call] An object whose #call method will return a
+      #   new instance of another R10K::Settings class to hold each item
+      #   added to this list.
+      # @param opts [Hash] Additional options for this definition to control
+      #   validation, normalization, and the like.
+      #
+      # @options opts [String] :desc Extended description of this setting.
+      # @options opts [Array] :default Initial/default contents of the list.
+      def initialize(name, item_proc, opts = {})
+        @name = name
+        @item_proc = item_proc
+        @items = []
+
+        setopts(opts, allowed_initialize_opts)
+      end
+
+      # Takes an array of key/value pairs and assigns each into a
+      # new instance created by invoking @item_proc.
+      #
+      # @param items [Array] List of items to add to this list.
+      def assign(items)
+        return if items.nil?
+
+        items.each do |values|
+          new_item = @item_proc.call
+          new_item.parent = self
+          new_item.assign(values)
+          @items << new_item
+        end
+      end
+
+      # Validate all items in the list and return validation errors
+      #
+      # @return [nil, Hash] If all validation passed nil will be returned; if
+      #   validation failed then a hash of those errors will be returned.
+      def validate
+        errors = {}
+
+        @items.each_with_index do |item, idx|
+          begin
+            item.validate
+          rescue => error
+            errors[idx+1] = error
+          end
+        end
+
+        if !errors.empty?
+          raise ValidationError.new(_("Validation failed for '%{name}' settings list") % {name: @name}, :errors => errors)
+        end
+      end
+
+      # Evaluate all items in the list and return a frozen array of the final values.
+      # @return [Array]
+      def resolve
+        @items.collect { |item| item.resolve }.freeze
+      end
+
+      class ValidationError < R10K::Error
+        attr_reader :errors
+
+        def initialize(mesg, options = {})
+          super
+          @errors = options[:errors]
+        end
+
+        def format
+          struct = []
+          struct << "#{message}:"
+          @errors.each do |item, error|
+            struct << indent(structure_exception("Item #{item}", error))
+          end
+          struct.join("\n")
+        end
+      end
+
+      private
+
+      # Subclasses may define additional params that are accepted at
+      # initialization; they should override this method to add any
+      # additional fields that should be respected.
+      def allowed_initialize_opts
+        {
+          :desc      => true,
+          :default   => true,
+        }
+      end
+    end
+  end
+end

data/lib/r10k/settings/loader.rb

@@ -0,0 +1,99 @@
+require 'r10k/logging'
+require 'r10k/errors'
+require 'yaml'
+
+module R10K
+  module Settings
+    # Look for the r10k configuration file in standard locations.
+    #
+    # r10k.yaml is checked for in the following locations:
+    #   - $PWD/r10k.yaml
+    #   - /etc/puppetlabs/r10k/r10k.yaml
+    #   - /etc/r10k.yaml
+    class Loader
+
+      def self.search(override = nil)
+        new.search(override)
+      end
+
+      include R10K::Logging
+
+      attr_reader :loadpath
+
+      CONFIG_FILE = 'r10k.yaml'
+      DEFAULT_LOCATION = File.join('/etc/puppetlabs/r10k', CONFIG_FILE)
+      OLD_DEFAULT_LOCATION = File.join('/etc', CONFIG_FILE)
+
+      def initialize
+        @loadpath = []
+        populate_loadpath
+      end
+
+      # Find the first valid config file.
+      #
+      # @param override [String, nil] An optional path that when is truthy
+      #   will be preferred over all other files, to make it easy to
+      #   optionally supply an explicit configuration file that will always
+      #   be used when set.
+      # @return [String, nil] The path to the first valid configfile, or nil
+      #   if no file was found.
+      def search(override = nil)
+        return override if override
+
+        # If both default files are present, issue a warning.
+        if (File.file? DEFAULT_LOCATION) && (File.file? OLD_DEFAULT_LOCATION)
+          logger.warn _("Both %{default_path} and %{old_default_path} configuration files exist.") % {default_path: DEFAULT_LOCATION, old_default_path: OLD_DEFAULT_LOCATION}
+          logger.warn _("%{default_path} will be used.") % {default_path: DEFAULT_LOCATION}
+        end
+
+        path = @loadpath.find {|filename| File.file? filename}
+
+        if path == OLD_DEFAULT_LOCATION
+          logger.warn _("The r10k configuration file at %{old_default_path} is deprecated.") % {old_default_path: OLD_DEFAULT_LOCATION}
+          logger.warn _("Please move your r10k configuration to %{default_path}.") % {default_path: DEFAULT_LOCATION}
+        end
+
+        path
+      end
+
+      def read(override = nil)
+        path = search(override)
+
+        if path.nil?
+          raise ConfigError, _("No configuration file given, no config file found in current directory, and no global config present")
+        end
+
+        begin
+          contents = ::YAML.load_file(path)
+        rescue => e
+          raise ConfigError, _("Couldn't load config file: %{error_msg}") % {error_msg: e.message}
+        end
+
+        if !contents
+          raise ConfigError, _("File exists at #{path} but doesn't contain any YAML") % {path: path}
+        end
+        R10K::Util::SymbolizeKeys.symbolize_keys!(contents, true)
+        contents
+      end
+
+      private
+
+      def populate_loadpath
+
+        # Add the current directory for r10k.yaml
+        @loadpath << File.join(Dir.getwd, CONFIG_FILE)
+
+        # Add the AIO location for of r10k.yaml
+        @loadpath << DEFAULT_LOCATION
+
+        # Add the old default location last.
+        @loadpath << OLD_DEFAULT_LOCATION
+
+        @loadpath
+      end
+
+      class ConfigError < R10K::Error
+      end
+    end
+  end
+end

data/lib/r10k/settings/mixin.rb

@@ -0,0 +1,54 @@
+module R10K::Settings::Mixin
+
+  def self.included(klass)
+    klass.send(:include, InstanceMethods)
+    klass.send(:extend, ClassMethods)
+  end
+
+  module InstanceMethods
+
+    # @return [R10K::Settings::Container] A settings container for the given instance.
+    def settings
+      @settings ||= R10K::Settings::Container.new(self.class.settings)
+    end
+  end
+
+  module ClassMethods
+
+    # Define a setting and optional default on the extending class.
+    #
+    # @param key [Symbol]
+    # @param default [Object]
+    #
+    # @return [void]
+    def def_setting_attr(key, default = nil)
+      defaults.add_valid_key(key)
+      defaults[key] = default if default
+    end
+
+    # A singleton settings container for storing immutable default configuration
+    # on the extending class.
+    #
+    # @return [R10K::Settings::Container]
+    def defaults
+      @defaults ||= R10K::Settings::Container.new
+    end
+
+    # A singleton settings container for storing manual setting configurations
+    # on the extending class.
+    #
+    # @return [R10K::Settings::Container]
+    def settings
+      @settings ||= R10K::Settings::Container.new(defaults)
+    end
+
+    # Allow subclasses to use the settings of the parent class as default values
+    #
+    # @return [void]
+    def inherited(subclass)
+      subclass.instance_eval do
+        @settings = R10K::Settings::Container.new(superclass.settings)
+      end
+    end
+  end
+end

data/lib/r10k/settings/uri_definition.rb

@@ -0,0 +1,19 @@
+require 'r10k/settings/definition'
+require 'uri'
+
+module R10K
+  module Settings
+    class URIDefinition < R10K::Settings::Definition
+      def validate
+        if @value
+          begin
+            URI.parse(@value)
+          rescue URI::Error
+            raise ArgumentError, _("Setting %{name} requires a URL but '%{value}' could not be parsed as a URL") % {name: @name, value: @value}
+          end
+        end
+        super
+      end
+    end
+  end
+end