chamber 0.0.4 → 1.0.0

data/lib/chamber/file_set.rb

@@ -0,0 +1,265 @@
+require 'chamber/namespace_set'
+require 'chamber/file'
+require 'chamber/settings'
+
+###
+# Internal: Represents a set of settings files that should be considered for
+# processing. Whether they actually *are* processed depends on their extension
+# (only *.yml files are processed unless explicitly specified), and whether
+# their namespace matches one of the namespaces passed to the FileSet (text
+# after a dash '-' but before the extension is considered the namespace for the
+# file).
+#
+# When converted to settings, files are always processed in the order of least
+# specific to most specific.  So if there are two files:
+#
+# * /tmp/settings.yml
+# * /tmp/settings-blue.yml
+#
+# Then '/tmp/settings.yml' will be processed first and '/tmp/settings-blue.yml'
+# will be processed second (assuming a namespace with the value 'blue' was
+# passed in).
+#
+# If there are multiple namespaces, they will be process in the order that they
+# appear in the passed in hash.  So assuming two files:
+#
+# * /tmp/settings-blue.yml
+# * /tmp/settings-green.yml
+#
+# Then:
+#
+# ```ruby
+# FileSet.new files:      '/tmp/settings*.yml',
+#             namespaces: ['blue', 'green']
+# ```
+#
+# will process in this order:
+#
+# * /tmp/settings-blue.yml
+# * /tmp/settings-green.yml
+#
+# Whereas:
+#
+# ```ruby
+# FileSet.new files:      '/tmp/settings*.yml',
+#             namespaces: ['green', 'blue']
+# ```
+#
+# will process in this order:
+#
+# * /tmp/settings-green.yml
+# * /tmp/settings-blue.yml
+#
+# Examples:
+#
+#   ###
+#   # Assuming the following files exist:
+#   #
+#   # /tmp/settings.yml
+#   # /tmp/settings-blue.yml
+#   # /tmp/settings-green.yml
+#   # /tmp/settings/another.yml
+#   # /tmp/settings/another.json
+#   # /tmp/settings/yet_another-blue.yml
+#   # /tmp/settings/yet_another-green.yml
+#   #
+#
+#   ###
+#   # This will *consider* all files listed but will only process 'settings.yml'
+#   # and 'another.yml'
+#   #
+#   FileSet.new files: ['/tmp/settings.yml',
+#                       '/tmp/settings']
+#
+#   ###
+#   # This will all files in the 'settings' directory but will only process
+#   # 'another.yml' and 'yet_another-blue.yml'
+#   #
+#   FileSet.new(files:      '/tmp/settings',
+#               namespaces: {
+#                 favorite_color: 'blue' } )
+#
+#   ###
+#   # Passed in namespaces do not have to be hashes. Hash keys are used only for
+#   # human readability.
+#   #
+#   # This results in the same outcome as the example above.
+#   #
+#   FileSet.new(files:      '/tmp/settings',
+#               namespaces: ['blue'])
+#
+#   ###
+#   # This will process all files listed:
+#   #
+#   FileSet.new(files:      [
+#                             '/tmp/settings*.yml',
+#                             '/tmp/settings',
+#                           ],
+#               namespaces: %w{blue green})
+#
+#   ###
+#   # This is the only way to explicitly specify files which do not end in
+#   # a 'yml' extension.
+#   #
+#   # This is the only example thus far which will process
+#   # '/tmp/settings/another.json'
+#   #
+#   FileSet.new(files:      '/tmp/settings/*.json',
+#               namespaces: %w{blue green})
+#
+class   Chamber
+class   FileSet
+
+  def initialize(options = {})
+    self.namespaces = options.fetch(:namespaces, {})
+    self.paths      = options.fetch(:files)
+  end
+
+  ###
+  # Internal: Returns an Array of the ordered list of files that was processed
+  # by Chamber in order to get the resulting settings values.  This is useful
+  # for debugging if a given settings value isn't quite what you anticipated it
+  # should be.
+  #
+  # Returns an Array of file path strings
+  #
+  def filenames
+    @filenames ||= files.map(&:to_s)
+  end
+
+  ###
+  # Internal: Converts the FileSet into a Settings object which represents all
+  # the settings specified in all of the files in the FileSet.
+  #
+  # This can be used in one of two ways. You may either specify a block which
+  # will be passed each file's settings as they are converted, or you can choose
+  # not to pass a block, in which case it will pass back a single completed
+  # Settings object to the caller.
+  #
+  # The reason the block version is used in Chamber.settings is because we want
+  # to be able to load each settings file as it's processed so that we can use
+  # those already-processed settings in subsequently processed settings files.
+  #
+  # Examples:
+  #
+  #   ###
+  #   # Specifying a Block
+  #   #
+  #   file_set = FileSet.new files: [ '/path/to/my/settings.yml' ]
+  #
+  #   file_set.to_settings do |settings|
+  #     # do stuff with each settings
+  #   end
+  #
+  #
+  #   ###
+  #   # No Block Specified
+  #   #
+  #   file_set = FileSet.new files: [ '/path/to/my/settings.yml' ]
+  #   file_set.to_settings
+  #
+  #   # => <Chamber::Settings>
+  #
+  def to_settings
+    clean_settings = Settings.new(:namespaces => namespaces)
+
+    files.each_with_object(clean_settings) do |file, settings|
+      if block_given?
+        yield file.to_settings
+      else
+        settings.merge!(file.to_settings)
+      end
+    end
+  end
+
+  protected
+
+  attr_reader   :namespaces,
+                :paths
+
+  ###
+  # Internal: Allows the paths for the FileSet to be set. It can either be an
+  # object that responds to `#each` like an Array or one that doesn't. In which
+  # case it will be considered a single path.
+  #
+  # All paths will be converted to Pathnames.
+  #
+  def paths=(raw_paths)
+    raw_paths = [raw_paths] unless raw_paths.respond_to? :each
+
+    @paths = raw_paths.map { |path| Pathname.new(path) }
+  end
+
+  ###
+  # Internal: Allows the namespaces for the FileSet to be set.  An Array or Hash
+  # can be passed; in both cases it will be converted to a NamespaceSet.
+  #
+  def namespaces=(raw_namespaces)
+    @namespaces = NamespaceSet.new(raw_namespaces)
+  end
+
+  ###
+  # Internal: The set of files which are considered to be relevant, but with any
+  # duplicates removed.
+  #
+  def files
+    @files ||= -> do
+      sorted_relevant_files = []
+
+      file_globs.each do |glob|
+        current_glob_files  = Pathname.glob(glob)
+        relevant_glob_files = relevant_files & current_glob_files
+
+        relevant_glob_files.map! { |file| File.new( path:        file,
+                                                    namespaces:  namespaces) }
+
+        sorted_relevant_files += relevant_glob_files
+      end
+
+      sorted_relevant_files.uniq
+    end.call
+  end
+
+  private
+
+  def all_files
+    @all_files ||= Pathname.glob(file_globs).sort
+  end
+
+  def non_namespaced_files
+    @non_namespaced_files ||= all_files - namespaced_files
+  end
+
+  def relevant_files
+    @relevant_files ||= non_namespaced_files + relevant_namespaced_files
+  end
+
+  def file_globs
+    @file_globs ||= paths.map do |path|
+                      if path.directory?
+                        path + '*.yml'
+                      else
+                        path
+                      end
+                    end
+  end
+
+  def namespaced_files
+    @namespaced_files ||= all_files.select do |file|
+                            file.fnmatch? '*-*'
+                          end
+  end
+
+  def relevant_namespaced_files
+    file_holder = []
+
+    namespaces.each do |namespace|
+      file_holder << namespaced_files.select do |file|
+                       file.fnmatch? "*-#{namespace}.???"
+                     end
+    end
+
+    file_holder.flatten
+  end
+end
+end

data/lib/chamber/namespace_set.rb

@@ -0,0 +1,141 @@
+require 'set'
+
+###
+# Internal: Respresents a set of namespaces which will be processed by Chamber
+# at various stages when settings are loaded.
+#
+# The main function that this class provides is the ability to create
+# a NamespaceSet from either an array-like or hash-like object and the ability
+# to allow callables to be passed which will then be executed.
+#
+class   Chamber
+class   NamespaceSet
+  include Enumerable
+
+  ###
+  # Internal: Creates a new NamespaceSet from arrays, hashes and sets.
+  #
+  def initialize(raw_namespaces = {})
+    self.namespaces = raw_namespaces
+  end
+
+  ###
+  # Internal: Allows a NamespaceSet to be combined with some other array-like
+  # object.
+  #
+  # It does not mutate the source NamespaceSet but rather creates a new one and
+  # returns it.
+  #
+  # Examples:
+  #
+  #   # Can be an Array
+  #   namespace_set = NamespaceSet.new ['value_1', 'value_2']
+  #   namespace_set + ['value_3']
+  #   # => <NamespaceSet namespaces=['value_1', 'value_2', 'value_3']>
+  #
+  #   # Can be a Set
+  #   namespace_set = NamespaceSet.new ['value_1', 'value_2']
+  #   namespace_set + Set['value_3']
+  #   # => <NamespaceSet namespaces=['value_1', 'value_2', 'value_3']>
+  #
+  #   # Can be a object which is convertable to an Array
+  #   namespace_set = NamespaceSet.new ['value_1', 'value_2']
+  #   namespace_set + (1..3)
+  #   # => <NamespaceSet namespaces=['value_1', 'value_2', '1', '2', '3']>
+  #
+  # Returns a NamespaceSet
+  #
+  def +(other)
+    NamespaceSet.new namespaces + other.to_a
+  end
+
+  ###
+  # Internal: Iterates over each namespace value and allows it to be used in
+  # a block.
+  #
+  def each
+    namespaces.each do |namespace|
+      yield namespace
+    end
+  end
+
+  ###
+  # Internal: Converts a NamespaceSet into an Array consisting of the namespace
+  # values stored in the set.
+  #
+  # Returns an Array
+  #
+  def to_ary
+    namespaces.to_a
+  end
+
+  alias_method :to_a, :to_ary
+
+  ###
+  # Internal: Determines whether a NamespaceSet is equal to another array-like
+  # object.
+  #
+  # Returns a Boolean
+  #
+  def ==(other)
+    self.to_ary.eql? other.to_ary
+  end
+
+  ###
+  # Internal: Determines whether a NamespaceSet is equal to another
+  # NamespaceSet.
+  #
+  # Returns a Boolean
+  #
+  def eql?(other)
+    other.is_a?(        Chamber::NamespaceSet)  &&
+    self.namespaces  == other.namespaces
+  end
+
+  protected
+
+  def namespaces
+    @namespaces ||= Set.new
+  end
+
+  ###
+  # Internal: Sets the namespaces for the set from a variety of objects and
+  # processes them by checking to see if they can be 'called'.
+  #
+  # Examples:
+  #
+  #   namespace_set             = NamespaceSet.new
+  #
+  #   # Can be set to an array
+  #   namespace_set.namespaces  = %w{namespace_value_1 namespace_value_2}
+  #   # => ['namespace_value_1', 'namespace_value_2']
+  #
+  #   # Can be set to a hash
+  #   namespace_set.namespaces  = { environment:  'development',
+  #                                 hostname:     'my host' }
+  #   namespace_set.namespaces
+  #   # => ['development', 'my host']
+  #
+  #   # Can be set to a callable
+  #   namespace_set.namespaces  = { environment:  -> { 'called' } }
+  #   namespace_set.namespaces
+  #   # => ['called']
+  #
+  #   # Does not allow duplicate items
+  #   namespace_set.namespaces  = %w{namespace_value namespace_value}
+  #   namespace_set.namespaces
+  #   # => ['namespace_value']
+  #
+  def namespaces=(raw_namespaces)
+    namespace_values =  if raw_namespaces.respond_to? :values
+                          raw_namespaces.values
+                        else
+                          raw_namespaces
+                        end
+
+    @namespaces = Set.new namespace_values.map do |value|
+                    value.respond_to?(:call) ? value.call : value
+                  end
+  end
+end
+end

data/lib/chamber/rails.rb

@@ -0,0 +1,3 @@
+if defined?(::Rails)
+  require 'chamber/rails/railtie'
+end

data/lib/chamber/rails/railtie.rb

@@ -0,0 +1,11 @@
+class   Chamber
+module  Rails
+class   Railtie < ::Rails::Railtie
+  initializer 'chamber.load', before: :load_environment_config do
+    Chamber.load( :basepath   => ::Rails.root.join('config'),
+                  :namespaces => {
+                    :environment => -> { ::Rails.env } })
+  end
+end
+end
+end

data/lib/chamber/settings.rb

@@ -0,0 +1,152 @@
+require 'hashie/mash'
+require 'chamber/system_environment'
+require 'chamber/namespace_set'
+
+###
+# Internal: Represents the base settings storage needed for Chamber.
+#
+class   Chamber
+class   Settings
+
+  attr_reader :namespaces
+
+  def initialize(options = {})
+    self.namespaces = options.fetch(:namespaces,  NamespaceSet.new)
+    self.data       = options.fetch(:settings,    Hashie::Mash.new)
+  end
+
+  ###
+  # Internal: Converts a Settings object into a hash that is compatible as an
+  # environment variable hash.
+  #
+  # Example:
+  #
+  #   settings = Settings.new settings: {
+  #                             my_setting:     'my value',
+  #                             my_sub_setting: {
+  #                               my_sub_sub_setting_1: 'my sub value 1',
+  #                               my_sub_sub_setting_2: 'my sub value 2',
+  #                             }
+  #   settings.to_environment
+  #   # => {
+  #     'MY_SETTING'                          => 'my value',
+  #     'MY_SUB_SETTING_MY_SUB_SUB_SETTING_1' => 'my sub value 1',
+  #     'MY_SUB_SETTING_MY_SUB_SUB_SETTING_2' => 'my sub value 2',
+  #   }
+  #
+  # Returns a Hash sorted alphabetically by the names of the keys
+  #
+  def to_environment
+    Hash[SystemEnvironment.extract_from(data).sort]
+  end
+
+  ###
+  # Internal: Converts a Settings object into a String with a format that will
+  # work well when working with the shell.
+  #
+  # Examples:
+  #
+  #   Settings.new( settings: {
+  #                   my_key:       'my value',
+  #                   my_other_key: 'my other value',
+  #                 } ).to_s
+  #   # => 'MY_KEY="my value" MY_OTHER_KEY="my other value"'
+  #
+  def to_s(options = {})
+    pair_separator       = options[:pair_separator]       || ' '
+    value_surrounder     = options[:value_surrounder]     || '"'
+    name_value_separator = options[:name_value_separator] || '='
+
+    pairs = to_environment.to_a.map do |pair|
+      %Q{#{pair[0]}#{name_value_separator}#{value_surrounder}#{pair[1]}#{value_surrounder}}
+    end
+
+    pairs.join(pair_separator)
+  end
+
+  ###
+  # Internal: Merges a Settings object with another Settings object or
+  # a hash-like object.
+  #
+  # Also, if merging Settings, it will merge the namespaces as well.
+  #
+  # Example:
+  #
+  #   settings        = Settings.new settings: { my_setting:        'my value' }
+  #   other_settings  = Settings.new settings: { my_other_setting:  'my other value' }
+  #
+  #   settings.merge! other_settings
+  #
+  #   settings
+  #   # => {
+  #     'my_setting'        => 'my value',
+  #     'my_other_setting'  => 'my other value',
+  #   }
+  #
+  # Returns a Hash
+  #
+  def merge!(other)
+    self.data       = data.merge(other.to_hash)
+    self.namespaces = (namespaces + other.namespaces) if other.respond_to? :namespaces
+  end
+
+  def eql?(other)
+    other.is_a?(        Chamber::Settings)  &&
+    self.data        == other.data          &&
+    self.namespaces  == other.namespaces
+  end
+
+  def to_hash
+    data
+  end
+
+  def method_missing(name, *args)
+    return data.public_send(name, *args) if data.respond_to?(name)
+
+    super
+  end
+
+  def respond_to_missing?(name, include_private = false)
+    data.respond_to?(name, include_private)
+  end
+
+  protected
+
+  attr_reader :raw_data
+  attr_writer :namespaces
+
+  def data
+    @data ||= Hashie::Mash.new
+  end
+
+  def data=(raw_data)
+    @raw_data = Hashie::Mash.new(raw_data)
+
+    namespace_checked_data =  if data_is_namespaced?
+                                namespace_filtered_data
+                              else
+                                self.raw_data
+                              end
+
+    @data = SystemEnvironment.inject_into(namespace_checked_data)
+  end
+
+  private
+
+  def data_is_namespaced?
+    @data_is_namespaced ||= raw_data.keys.any? { |key| namespaces.include? key }
+  end
+
+  def namespace_filtered_data
+    @namespace_filtered_data ||= -> do
+      data = Hashie::Mash.new
+
+      namespaces.each do |namespace|
+        data.merge!(raw_data[namespace]) if raw_data[namespace]
+      end
+
+      data
+    end.call
+  end
+end
+end