app_config_for 0.0.4.1 → 0.0.6.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 228991a28438bec90c4aa9f06b33850a5ee4034b01a7ec87a33c90fa77ace37d
-  data.tar.gz: eed01754e58c59c3ea8d58c23e809f8d9c3ae1b6fe5a3b24958a1a173f01a87c
+  metadata.gz: 7f85a6a8ca8b5be3a0fcbccc544519908b2f257760199a6f49c06a3100824692
+  data.tar.gz: 6de1a37f3f917450a3214fd4ba98e70d5ce2eed0485933470cc2e072b1f89e0e
 SHA512:
-  metadata.gz: d05a93814a9b8162890151e89f2e83e99f29c58478e371aeef49c63c29713a01d1c86ab3b4a28ee320d2eb639dd51879d107dd820c9f173c3bae958c626396b9
-  data.tar.gz: b9dc3d8224b2e0c05167da273faf7df940c1397022d22768af8cce85101de32993a56cc2e13bca5b2d8cb656e7885251a962486856388ad1871be9163784816e
+  metadata.gz: 4d3810ce467896ea6d8165a8a313066c2d2d8947c07e39843bdc7886ad072e6eef29ea309d2505a67b902b2d3b0a14fdde8025a0c00c6d26092583b6fe505cd5
+  data.tar.gz: 3b6c650d56e7624e673d4a840d24970e9428744478c7ac9399f398bdd6fc39ac92ad1470cb6209bae26e17c2eebfa0c200be30d8823990c79257348508b0c573

data/CHANGELOG.md

@@ -1,5 +1,48 @@
 ## [Alpha Release]
 
-## [0.0.1] - 2022-02-18
+## [0.0.1] - 2022-04-07
 
 - Initial release
+
+## [0.0.2] - 2022-04-12
+
+- Added prefix inheritance.
+- Initial inclusion vs extension support.
+- Refactored some internal behaviors.
+
+## [0.0.3] - 2022-04-12
+
+- More internal refactoring and miscellaneous bug fixes.
+
+## [0.0.4] - 2022-04-14
+
+- Reduced minimal ActiveSupport version requirements to 5.0.
+- Added a legacy support shim for older versions of ActiveSupport.
+- Multiple configuration directory support.
+- Single configuration name override support.
+- Automatically prep gems consumers with the ability to ship with a default configuration. 
+
+## [0.0.4.1] - 2022-04-15
+
+- Reduced minimal Ruby version requirements to 2.3.6
+- Bug fix: active_support/configuration_file was still being requested on older ActiveSupport installations.
+
+## [0.0.5] - 2022-04-25
+
+- Full Yard documentation.
+- Multiple config directories for file searching can be added at one time.
+- Small updates to initializations.
+- Started specs.
+- Fixed bug in progenitor_prefixes_of that prevented rails and rack prefixes from being used.
+- additional_config_directories duped by default to prevent accidental changes.
+- add_config_directory now converts its argument to a string via #to_s.
+
+## [0.0.6] - 2022-04-25
+
+- Reading and setting configuration values can now be done directly on the extending class/module.
+- Documentation updates.
+- Fallback configuration support.
+- Requesting configuration for another object that can supply it's own config_files will use those files instead of locally determining them.
+
+## [0.0.6.1] - 2022-04-25
+- Fixed issue when initializing env_prefixes in a namespaced module/class.

data/README.md

@@ -1,4 +1,4 @@
-# AppConfigFor
+# AppConfigFor [![Gem Version](https://badge.fury.io/rb/app_config_for.svg)](https://badge.fury.io/rb/app_config_for)
 
 Ruby gem providing Rails::Application#config_for style capabilities for non-rails applications, gems, and rails engines.
 
@@ -20,54 +20,52 @@ Or install it yourself as:
 
 ## Usage
 Presume a typical rails database config at ./config/database.yml  
-One environment variable ('MY_APP_ENV', 'RAILS_ENV', or 'RACK_ENV') is set to 'development'
+One environment variable ('MY_APP_ENV', 'RAILS_ENV', or 'RACK_ENV') is set to 'development' or all are non existent.
 
-#### ./config/my_app.yml
+#### ./config/sample_app.yml
 ```yml
 default: &default
-site: <%= ENV.fetch("MY_APP_SITE", 'www.slackware.com') %>
-password: Slackware#1!
+  site: <%= ENV.fetch("MY_APP_SITE", 'www.slackware.com') %>
+  password: Slackware#1!
 
 development:
-<<: *default
-username: Linux
+  <<: *default
+  username: Linux
 
 test:
-<<: *default
-username: TestingWith
+  <<: *default
+  username: TestingWith
 
 production:
-<<: *default
-username: DefinitelyUsing
+  <<: *default
+  username: DefinitelyUsing
 
 shared:
-color: 'Blue'
+  color: 'Blue'
 ```
 
-#### ./my_class.rb
+#### sample_application.rb
 ```ruby
 require 'app_config_for'
 
-module MyApp
-
+module Sample
+  class App
     extend AppConfigFor
-
-    class MyClass
-        def info
-            puts "Curent environment is #{MyApp.env}"
-
-            puts "Remote Host: #{MyApp.configured.site}"
-
-            # Can access same configuration in other ways
-            puts "Username: MyApp.config_for(:my_app)[:username]"
-            puts "Password: MyApp.config_for(MyApp).username"
-
-            # Access a different config
-            if MyApp.config_file?(:database)
-                puts "Rails database config: MyApp.config_for(:database)"
-            end
-        end
+    def info
+      puts "Current environment is #{App.env}"
+ 
+      puts "Remote Host: #{App.configured.site}"
+ 
+      # Can access same configuration in other ways
+      puts "Username: self.class.config_for(:app)[:username]"
+      puts "Password: App.config_for(App).username"
+ 
+      # Access a different config
+      if App.config_file?(:database)
+        puts "Rails database config: App.config_for(:database)"
+      end
     end
+  end
 end
 ```
 

data/lib/app_config_for/errors.rb

@@ -1,9 +1,15 @@
 module AppConfigFor
+  # Base class for all errors generated by AppConfigFor
   class Error < StandardError; end
 
+  # Raised when the configuration could not be found.
   class ConfigNotFound < Error
 
-    attr_reader :locations_searched, :original_exception
+    # The full path of every place the configuration file was looked for.
+    attr_reader :locations_searched
+    # The underlying SystemCallError that signaled the missing file.
+    # Most commonly this will be +Errno::ENOENT+.
+    attr_reader :original_exception
 
     def initialize(locations, original_exception)
       @locations_searched = Array(locations).map { |x| Pathname(x).expand_path }
@@ -12,9 +18,14 @@ module AppConfigFor
     end
   end
 
+  # Raised when there was an issue parsing the configuration file.
   class LoadError < Error
 
-    attr_reader :file, :original_exception
+    # The file that was being parsed.
+    attr_reader :file
+    # The original exception that signaled the parsing problme.
+    # Most commonly this will be a +Psych::SyntaxError+
+    attr_reader :original_exception
 
     def initialize(file, original_exception)
       @file = Pathname(file).expand_path
@@ -23,13 +34,17 @@ module AppConfigFor
     end
   end
 
+  # Raised when an attempting to utilize an unrecognized inheritance style.
   class InvalidEnvInheritanceStyle < Error
 
-    attr_reader :attempted, :valid
+    # The inheritance style that was attempted to be used.
+    attr_reader :attempted
+    # List of valid styles at the time of the attempt.
+    attr_reader :valid
 
     def initialize(attempted)
       @attempted = attempted
-      @valid = EnvPrefixInheritanceStyles.dup
+      @valid = EnvInheritanceStyles.dup
       super "Invalid inheritance style #{@attempted.inspect}. Please use one of the following: #{@valid.map(&:inspect).join(', ')}"
     end
 

data/lib/app_config_for/gem_version.rb

@@ -1,16 +1,20 @@
 module AppConfigFor
 
+  # Current version of this gem with comparable values.
+  # @return [Gem::Version]
   def self.gem_version
     Gem::Version.new(VERSION::STRING)
   end
 
+  # The rendition
   module VERSION
-    MAJOR = 0
-    MINOR = 0
-    TINY  = 4
-    PRE = 1
+    MAJOR = 0 # A field-grade officer
+    MINOR = 0 # When the semitones show up as intervals between the 2nd and 3rd degrees
+    TINY  = 6 # The number of people who use antidisestablishmentarianism in everyday conversation
+    PRE = 1   # Ante not auntie
 
-    STRING = [MAJOR, MINOR, TINY, PRE].compact.join('.')
+    # String form of the version (duh). Are you seriously reading this? I guess it is slightly more interesting that Moby-Dick.
+    STRING = [MAJOR, MINOR, TINY, PRE].compact.join('.') 
   end
 
 end

data/lib/app_config_for/legacy_support.rb

@@ -9,9 +9,19 @@ if ActiveSupport.gem_version < Gem::Version.new('6.1.0')
   require "erb"
   require "yaml"
 
+  # @note This legacy support is only included if the existing ActiveSupport version is below 6.1.0. 
+  #   If your application is using any version of ActiveSupport below 6.1.4 it is *strongly* suggested you upgrade your application due to security and bug fixes.
+  #   This backwards compatability is only enough to support AppConfigFor and is not to be considered a full backport of existing features.
+  #   This support will be removed in the future.
   module ActiveSupport
+
+    # @note This legacy support is only included if the existing ActiveSupport version is below 6.1.0. 
+    #   If your application is using any version of ActiveSupport below 6.1.4 it is *strongly* suggested you upgrade your application due to security and bug fixes.
+    #   This backwards compatability is only enough to support AppConfigFor and is not to be considered a full backport of existing features.
+    #   This support will be removed in the future.
     class EnvironmentInquirer < StringInquirer
 
+      # Default environments
       Environments = %w(development test production)
 
       def initialize(env)
@@ -22,6 +32,10 @@ if ActiveSupport.gem_version < Gem::Version.new('6.1.0')
       Environments.each { |e| define_method("#{e}?") { instance_variable_get("@#{e}") }}
     end
 
+    # @note This legacy support is only included if the existing ActiveSupport version is below 6.1.0. 
+    #   If your application is using any version of ActiveSupport below 6.1.4 it is *strongly* suggested you upgrade your application due to security and bug fixes.
+    #   This backwards compatability is only enough to support AppConfigFor and is not to be considered a full backport of existing features.
+    #   This support will be removed in the future.
     class ConfigurationFile
       def initialize(file_name)
         @file_name = file_name
@@ -29,10 +43,12 @@ if ActiveSupport.gem_version < Gem::Version.new('6.1.0')
         warn(file_name + ' contains invisible non-breaking spaces.') if @config.match?("\u00A0")
       end
 
+      # Quick and dirty parse
       def self.parse(file_name)
         new(file_name).parse
       end
 
+      # Quick and dirty parse
       def parse
         YAML.load(ERB.new(@config).result) || {}
       rescue Psych::SyntaxError => e

data/lib/app_config_for/version.rb

@@ -3,6 +3,9 @@ require_relative "gem_version"
 
 module AppConfigFor
 
+  # Current version of this gem.
+  # @return [Gem::Version]
+  # @see gem_version
   def self.version
     gem_version
   end

data/lib/app_config_for.rb

@@ -16,55 +16,251 @@ require 'active_support/core_ext/string/inflections'
 require 'active_support/core_ext/hash/indifferent_access'
 require 'active_support/ordered_options'
 require 'active_support/core_ext/object/try'
-
+require 'active_support/backtrace_cleaner'
+
+# {<img src="https://badge.fury.io/rb/app_config_for.svg" alt="Gem Version" />}[https://badge.fury.io/rb/app_config_for]
+# 
+# Ruby gem providing Rails::Application#config_for style capabilities for non-rails applications, gems, and rails engines.  
+# It respects RAILS_ENV and RACK_ENV while providing additional capabilities beyond Rails::Application#config_for.
+# 
+# = Usage
+# Typical usage will be done by extension but inclusion is also supported.
+# 
+# Presume a typical rails database config at ./config/database.yml
+# 
+# One environment variable ('MY_APP_ENV', 'RAILS_ENV', or 'RACK_ENV') is set to 'development' or all are non existent.
+#
+# ==== ./config/sample_app.yml
+#  default: &default
+#    site: <%= ENV.fetch("MY_APP_SITE", 'www.slackware.com') %>
+#    password: Slackware#1!
+# 
+#  development:
+#  <<: *default
+#  username: Linux
+# 
+#  test:
+#  <<: *default
+#  username: TestingWith
+# 
+#  production:
+#  <<: *default
+#  username: DefinitelyUsing
+# 
+#  shared:
+#  color: 'Blue'
+# 
+# === sample_application.rb
+#  require 'app_config_for'
+# 
+#  module Sample
+#    class App
+#      extend AppConfigFor
+#      def info
+#        puts "Current environment is #{App.env}"
+#
+#        # Access the configuration in various ways depending on need/preference.
+#        puts "Remote Host: #{App.site}"
+#        puts "Username:    #{App.configured.username}"
+#        puts "Password:    #{App.config_for(App).password}"
+#        puts "Domain:      #{self.class.config_for(:app)[:domain]}"
+# 
+#        # Access a different config
+#        if App.config_file?(:database)
+#          adapter_name = App.config_for(:database).adapter
+#          puts "Rails is using the #{adapter_name} adapter."
+#        end
+#      end
+#    end
+#  end
+# 
 module AppConfigFor
-
-  EnvPrefixInheritanceStyles = %i(none namespace class namespace_class class_namespace)
-
+  # Types of hierarchical traversal used to determine the runtime environment.
+  # * +:none+ - No inheritance active
+  # * +:namespace+ - Inheritance by lexical namespace
+  # * +:class+ - Inheritance by class hierarchy
+  # * +:namespace_class+ - Namespace inheritance combined with class inheritance
+  # * +:class_namespace+ - Class inheritance combined with namespace inheritance
+  EnvInheritanceStyles = [:none, :namespace, :class, :namespace_class, :class_namespace]
+
+  # AppConfigFor can be included instead of extended. If this occurs, instances of the class will have their
+  # own list of prefixes. The default class prefix will be automatically added to the list.
   def initialize(*args)
     add_env_prefix
     super
   end
 
-  def add_env_prefix(prefix = nil, at_beginning = true)
-    env_prefixes(false, false).send(at_beginning ? :unshift : :push, AppConfigFor.prefix_from(prefix || self)).uniq!
+  # Add multiple additional directories to be used when searching for the config file.
+  # Any duplicates will be ignored.
+  # @param additional_directories [Array<#to_s>] additional directories to add
+  # @param at_beginning [Boolean] where to insert the new directories with respect to existing prefixes
+  #   * +true+ - Add to the beginning of the list.
+  #   * +false+ - Add to the end of the list.
+  # @return [Array<Pathname>] updated array of additional config directories
+  # @see #additional_config_directories Additional config directories
+  # @see #config_directories All config directories
+  def add_config_directories(*additional_directories, at_beginning: true)
+    additional_directories = additional_directories.flatten.map { |d| Pathname.new(d.to_s) }
+    directories = additional_config_directories(false).send(at_beginning ? :unshift : :push, additional_directories)
+    directories.flatten!
+    directories.uniq!
+    directories.dup
+  end
+
+  # Add an single additional directory to be used when searching for the config file.
+  # Any duplicates will be ignored.
+  # @param additional_directory [#to_s] additional directory to add
+  # @param at_beginning [Boolean] where to insert the new directory with respect to existing prefixes
+  #   * +true+ - Add to the beginning of the list.
+  #   * +false+ - Add to the end of the list.
+  # @return [Array<Pathname>] updated array of additional config directories
+  # @see #additional_config_directories Additional config directories
+  # @see #config_directories All config directories
+  def add_config_directory(additional_directory, at_beginning = true)
+    add_config_directories additional_directory, at_beginning: at_beginning
+  end
+
+  # Add an additional base name to be used when locating the config file.
+  # @param config_name [Object] Object to extract a config name from.
+  # @param at_beginning [Boolean] where to insert the new config name with respect to existing names.
+  #   * +true+ - Add to the beginning of the list.
+  #   * +false+ - Add to the end of the list.
+  # @return [Array<Object>] current config names
+  # @see yml_name_from How the name of the yml file is determined
+  def add_config_name(config_name, at_beginning = true)
+    add_config_names config_name, at_beginning: at_beginning
+  end
+
+  # Add multiple additional base names to be used when locating the config file.
+  # @param config_names [Array<Object>] Array of objects to extract a config name from.
+  # @param at_beginning [Boolean] where to insert the new config names with respect to existing names.
+  #   * +true+ - Add to the beginning of the list.
+  #   * +false+ - Add to the end of the list.
+  # @return [Array<Object>] current config names
+  # @see yml_name_from How the name of the yml file is determined
+  def add_config_names(*config_names, at_beginning: true)
+    names = config_names(false).send(at_beginning ? :unshift : :push, config_names)
+    names.flatten!
+    names.uniq!
+    names.dup
   end
 
-  def add_config_directory(new_directory)
-    (additional_config_directories << Pathname.new(new_directory).expand_path).uniq!
+  # Add an additional environmental prefix to be used when determining current environment.
+  # @param prefix [Symbol, Object] Prefix to add.  
+  #  +nil+ is treated as +self+   
+  #  Non symbols are converted via {.prefix_from AppConfigFor.prefix_from}.  
+  # @param at_beginning [Boolean] where to insert the new prefix with respect to existing prefixes
+  #   * +true+ - Add to the beginning of the list.
+  #   * +false+ - Add to the end of the list.
+  # @return [Array<Symbol>] Current prefixes (without inheritance)
+  # @see #env_prefixes Current prefixes
+  def add_env_prefix(prefix = nil, at_beginning = true)
+    env_prefixes(false, false).send(at_beginning ? :unshift : :push, AppConfigFor.prefix_from(prefix || self)).uniq!
+    env_prefixes(false)
   end
 
-  def additional_config_directories
+  # Directories to be checked in addition to the defaults when searching for the config file.
+  # @param dup [Boolean] Return a duplicated array to prevent accidental side effects
+  # @return [Array<Pathname>]
+  # @see #add_config_directory Adding config directories
+  # @see #config_directories All config directories
+  def additional_config_directories(dup = true)
     @additional_config_directories ||= []
+    dup ? @additional_config_directories.dup : @additional_config_directories
   end
 
+  # Clear all additional config directories and set to the directory given.
+  # @param directory [#to_s] additional directory to use
+  # @return [Array<Pathname>] updated array of additional config directories
+  # @see #additional_config_directories Additional config directories
+  # @see #config_directories All config directories
+  def config_directory=(directory)
+    additional_config_directories(false).clear
+    add_config_directory(directory)
+  end
+  alias_method :config_directories=, :config_directory=
+
+  # All directories that will be used when searching for the config file. Search order is as follows:
+  # 1. Rails configuration directories if Rails is present.
+  # 2. Engine configuration directories if extended by an engine.
+  # 3. Additional configuration directories.
+  # 4. ./config within the current working directory.
+  # All paths are expanded at time of call.
+  # @return [Array<Pathname>] directories in the order they will be searched.
+  # @see #add_config_directory Adding config directories
   def config_directories
     directories = ['Rails'.safe_constantize&.application&.paths, try(:paths)].compact.map { |root| root["config"].existent.first }.compact
-    directories.map! { |directory| Pathname.new(directory).expand_path }
     directories.concat additional_config_directories
     directories.push(Pathname.getwd + 'config')
-    directories.uniq
+    directories.map { |directory| Pathname.new(directory).expand_path }.uniq
   end
 
-  def config_file(name = nil)
+  # Configuration file that will be used.
+  # This is the first file from {#config_files} that exists or +nil+ if none exists.
+  # @param name [Symbol, Object] Name of the config to load.  
+  #  Conversion to a file name will occur using {.yml_name_from AppConfigFor.yml_name_from}.  
+  #  If name is +nil+ {#config_names} will be used.
+  # @param fallback [Symbol, Object] If not +nil+, attempt to load a fallback configuration if the requested one cannot be found.  
+  # @return [Pathname, nil]
+  def config_file(name = nil, fallback = nil)
     unless name.is_a?(Pathname)
       config_files(name).find(&:exist?)
     else
       name.exist? ? name.expand_path : nil
-    end
+    end.yield_self { |file| file || fallback && config_file(fallback) }
   end
 
+  # The list of potential config files that will be searched for and the order in which they will be searched.
+  # @param name [Symbol, Object] Name of the config to load.  
+  #  Conversion to a file name will occur using {.yml_name_from AppConfigFor.yml_name_from}.  
+  #  If name is +nil+, {#config_names} will be used.  
+  #  If name is object that responds to +config_files+, it will be called instead.
+  # @return [Array<Pathname>]
   def config_files(name = nil)
-    name = AppConfigFor.yml_name_from(name || config_name)
-    config_directories.map { |directory| directory + name }
+    if name.respond_to?(:config_files) && name != self
+      name.config_files
+    else
+      names = (name && name != self && Array(name) || config_names).map { |name| AppConfigFor.yml_name_from(name) }
+      config_directories.map { |directory| names.map { |name| directory + name } }.flatten
+    end
   end
 
-  def config_file?(name = nil)
-    !config_file(name).blank?
+  # Does a config file exit?
+  # @param name [Symbol, Object] Name of the config to load.  
+  #  Conversion to a file name will occur using {.yml_name_from AppConfigFor.yml_name_from}.  
+  #  If name is +nil+ {#config_names} will be used.
+  # @param fallback [Symbol, Object] If not +nil+, attempt to load a fallback configuration if the requested one cannot be found.  
+  # @return [Boolean]
+  def config_file?(name = nil, fallback = nil)
+    !config_file(name, fallback).blank?
   end
 
-  def config_for(name, env: nil)
-    config, shared = config_options(name).fetch_values((env || self.env).to_sym, :shared) {nil}
+  # Configuration settings for the current environment.
+  # Shared sections in the yml config file are automatically merged into the returned configuration.
+  # @param name [Symbol, Object] Name of the config to load.  
+  #  Conversion to a file name will occur using {.yml_name_from AppConfigFor.yml_name_from}.  
+  #  If name is +nil+ {#config_names} will be used.
+  # @param env [Symbol, String] name of environment to use. +nil+ will use the current environment settings from {#env}
+  # @param fallback [Symbol, Object] If not +nil+, attempt to load a fallback configuration if the requested one cannot be found.  
+  # @return [ActiveSupport::OrderedOptions]
+  # @raise ConfigNotFound - No configuration file could be located.
+  # @raise LoadError - A configuration file was found but could not be properly read.
+  # @see yml_name_from How the name of the yml file is determined
+  # @see #env The current runtime environment
+  # @example
+  #   config_for(:my_app)              # Load my_app.yml and extract the section relative to the current environment.
+  #   config_for(:my_app).log_level    # Get the configured logging level from my_app.yml for the current environment.
+  #   config_for("MyApp", env: 'test') # Load my_app.yml and extract the 'test' section.
+  #
+  #   module Other
+  #     class App
+  #     end
+  #   end
+  #   # Load other_app.yml and extract the 'production' section.
+  #   # Notice that Other::App does not need to extend AppConfigFor
+  #   config_for(Other::App, env: :production)
+  def config_for(name, env: nil, fallback: nil)
+    config, shared = config_options(name, fallback).fetch_values((env || self.env).to_sym, :shared) { nil }
     config ||= shared
 
     if config.is_a?(Hash)
@@ -75,43 +271,201 @@ module AppConfigFor
     config
   end
 
-  def config_name
-    @config_name ||= self
+  # Clear all config names and set to the name given.
+  # Set the base name of the config file to use.
+  # @param new_config_name [Object] Any object. Actual name will be determined using {.yml_name_from AppConfigFor.yml_name_for}
+  # @return [Array<Object>] current config names
+  # @see yml_name_from How the name of the yml file is determined
+  def config_name=(new_config_name)
+    config_names(false).clear
+    add_config_names(new_config_name)
   end
+  alias_method :config_names=, :config_name=
 
-  def config_name=(new_config_name)
-    @config_name = new_config_name
+  # Base names of the configuration file.
+  # Defaults to: +[self]+
+  def config_names(dup = true)
+    @config_names ||= [self]
+    dup ? @config_names.dup : @config_names
   end
 
-  def config_options(name = nil)
-    file = name.is_a?(Pathname) ? name : config_file(name)
-    ActiveSupport::ConfigurationFile.parse(file.to_s).deep_symbolize_keys
+  # Configuration for all environments parsed from the {#config_file}.
+  # @param name [Symbol, Object] Name of the config to load.  
+  #  Conversion to a file name will occur using {.yml_name_from AppConfigFor.yml_name_from}.  
+  #  If name is +nil+ {#config_names} will be used.
+  # @param fallback [Symbol, Object] If not +nil+, attempt to load a fallback configuration if the requested one cannot be found.  
+  # @return [Hash]
+  # @raise ConfigNotFound - No configuration file could be located.
+  # @raise LoadError - A configuration file was found but could not be properly read.
+  def config_options(name = nil, fallback = nil)
+    file = config_file(name, fallback).to_s
+    ActiveSupport::ConfigurationFile.parse(file).deep_symbolize_keys
   rescue SystemCallError => exception
-    raise ConfigNotFound.new(name.is_a?(Pathname) ? name : config_files(name), exception)
+    locations = name.is_a?(Pathname) ? Array(name) : config_files(name)
+    locations += config_files(fallback) if fallback
+    raise ConfigNotFound.new(locations, exception)
   rescue => exception
     raise file ? LoadError.new(file, exception) : exception
   end
 
-  def configured(reload = false, env: nil)
-    @configured = config_for(nil, env: env) if reload || @configured.nil?
+  # Convenience method for {config_for}(+self+). Caches the result for faster access.
+  # @param reload [Boolean] Update the cached config by rereading the configuration file.
+  # @return [ActiveSupport::OrderedOptions]
+  # @raise ConfigNotFound - No configuration file could be located.
+  # @raise LoadError - A configuration file was found but could not be properly read.
+  # @example
+  #   module Sample
+  #     class App
+  #       extend AppConfigFor
+  #       @@logger = Logger.new($stdout, level: configured.level)
+  #     end
+  #   end
+  #   Sample::App.configured.url    # Get the configured url from my_app.yml for the current environment
+  # @see #method_missing Accessing configuration values directly from the extending class/module
+  def configured(reload = false)
+    if reload || !@configured
+      # @disable_local_missing = true # Disable local method missing to prevent recursion
+      @configured = config_for(nil, env: env(reload))
+      # @disable_local_missing = false # Reenable local method missing since no exception occurred.
+    end
     @configured
   end
 
+  # Convenience method for {configured}(+true+).
+  # @return [ActiveSupport::OrderedOptions]
+  # @raise ConfigNotFound - No configuration file could be located.
+  # @raise LoadError - A configuration file was found but could not be properly read.
+  # @example
+  #   module Sample
+  #     class App
+  #       extend AppConfigFor
+  #       mattr_accessor :logger, default: Logger.new($stdout)
+  #       logger.level = configured.log_level
+  #     end
+  #   end
+  #   # Switch to production
+  #   ENV['SAMPLE_APP_ENV'] = 'production'
+  #   # Update the log level with the production values
+  #   Sample::App.logger.level = Sample::App.configured!.log_level
+  def configured!
+    configured(true)
+  end
+
+  # Check for the existence of a configuration setting. Handles exceptions and recursion.
+  # @param key [#to_s] Key to check for
+  # @return [Boolean]
+  #   * +true+ - Configuration has the key
+  #   * +false+ - If one of the following: 
+  #     1. Configuration does not have the key
+  #     2. Called recursively while retrieving the configuration
+  #     3. An exception is raised while retrieving the configuration
+  # @note This is primarily used internally during {#respond_to_missing?} and {#method_missing} calls.
+  def configured?(key)
+    if @disable_local_missing
+      false
+    else
+      @disable_local_missing = true
+      begin
+        configured.has_key?(key.to_s.to_sym)
+      rescue Exception # One of the few times you ever want to catch this exception and not reraise it.
+        false
+      ensure
+        @disable_local_missing = false
+      end
+    end
+  end
+
+  # Returns the current runtime environment. Caches the result.
+  # @param reload [Boolean] Update the cached env by requerying the environment
+  # @return [ActiveSupport::EnvironmentInquirer]
+  # @example
+  #   module Sample
+  #     extend AppConfigFor
+  #   end
+  #   Sample.env              # => 'development'
+  #   Sample.env.development? # => true
+  #   Sample.env.production?  # => false
   def env(reload = false)
-    @env = ActiveSupport::EnvironmentInquirer.new(AppConfigFor.env_name(env_prefixes)) if reload || @env.nil?
+    @env = ActiveSupport::EnvironmentInquirer.new(env_name) if reload || @env.nil?
     @env
   end
 
-  def env_prefix_inheritance
-    @env_prefix_inheritance ||= :namespace
+  # Convenience method for {env}(+true+).
+  # @return [ActiveSupport::EnvironmentInquirer]
+  # @example
+  #   module Sample
+  #     extend AppConfigFor
+  #   end
+  #   Sample.env              # => 'development'
+  #   Sample.env.development? # => true
+  #   Sample.env.production?  # => false
+  #   # Switch to production
+  #   ENV['SAMPLE_APP_ENV'] = 'production'
+  #   Sample.env.production?  # => false
+  #   Sample.env!.production? # => true
+  def env!
+    env(true)
+  end
+
+  # Set the runtime environment (without affecting environment variables)
+  # @param environment [#to_s]
+  # @return [ActiveSupport::EnvironmentInquirer]
+  # @example
+  #   ENV['SAMPLE_ENV'] = 'test'
+  #   module Sample
+  #     extend AppConfigFor
+  #   end
+  #   Sample.env        # => 'test'
+  #   Sample.env = 'development'
+  #   Sample.env        # => 'development'
+  #   ENV['SAMPLE_ENV'] # => 'test'
+  def env=(environment)
+    @env = ActiveSupport::EnvironmentInquirer.new(environment.to_s)
+  end
+
+  # Current runtime environment inheritance style. Defaults to +:namespace+.
+  # @return [Symbol]
+  def env_inheritance
+    @env_inheritance ||= :namespace
+  end
+
+  # Set the runtime environment inheritance.
+  # @param style [#to_s] New inheritance style
+  # @return [Symbol]
+  # @raise InvalidEnvInheritanceStyle - Attempt to set a style that is not one of the {EnvInheritanceStyles}.
+  # @see .verified_style! Valid inheritance styles
+  def env_inheritance=(style)
+    @env_inheritance = AppConfigFor.verified_style!(style)
   end
 
-  def env_prefix_inheritance=(style)
-    @env_prefix_inheritance = AppConfigFor.verified_style!(style)
+  # The name of the current runtime environment for this object.
+  #
+  # Convenience method for {.env_name AppConfigFor.env_name}({#env_prefixes env_prefixes})
+  #
+  # If no value can be found, the default is 'development'.
+  # @return [String] current runtime environment.
+  # @see #env_prefixes Environment variable prefixes
+  def env_name
+    AppConfigFor.env_name(env_prefixes)
   end
 
+  # Prefixes used to determine the environment name.
+  #
+  # A prefix of :some_app will will cause AppConfigFor to react to the environment variable +'SOME_APP_ENV'+
+  # The order of the prefixes will be the order in which AppConfigFor searches the environment variables.
+  # A prefix for +self+ is automatically added at the time of extension/inclusion of AppConfigFor.
+  #
+  # @param all [Boolean] Combine current prefixes with inherited prefixes.
+  # @param dup [Boolean] Return a duplicate of the internal array to prevent accidental modification.
+  # @return [Array<Symbol>] Environment prefixes for this object.
+  # @see add_env_prefix Adding a prefix
+  # @see remove_env_prefix Removing a prefix
+  # @see env_name Current runtime environment
   def env_prefixes(all = true, dup = true)
-    @env_prefixes ||= []
+    unless @env_prefixes
+      @env_prefixes = []
+      add_env_prefix
+    end
     if all
       @env_prefixes + AppConfigFor.progenitor_prefixes_of(self)
     else
@@ -119,6 +473,48 @@ module AppConfigFor
     end
   end
 
+  # Allow access to configuration getters and setters directly from the extending class/module.
+  # @example
+  #   class Sample
+  #     extend AppConfigFor
+  #   end
+  # 
+  #   # Presuming config/sample.yml contains a configuration for 'log_level' and 'status' but no other keys.
+  #   Sample.log_level          # => :production
+  #   Sample.log_level = :debug 
+  #   Sample.log_level          # => :debug
+  # 
+  #   # You are allowed to set the value prior reading it should the need should arise.
+  #   Sample.status = 'active'  
+  #   Sample.status             # => 'active'
+  # 
+  #   # However, you cannot invent new keys with these methods.
+  #   Sample.something_else     # => NoMethodError(undefined method `something_else' for Sample)
+  #   Sample.something_else = 1 # => NoMethodError(undefined method `something_else=' for Sample)
+  # @note Values can be written or read prior to the loading of the configuration presuming the configuration can load without error.
+  def method_missing(name, *args, &block)
+    if configured?(name.to_s.split('=').first.to_sym)
+      configured.send(name, *args, &block)
+    else
+      begin
+        super
+      rescue Exception => e
+        # Remove the call to super from the backtrace to make it more apparent where the failure occurred,
+        super_line = Regexp.new("#{__FILE__}:#{__LINE__ - 3}") 
+        e.set_backtrace(ActiveSupport::BacktraceCleaner.new.tap { |bc| bc.add_silencer { |line| line =~ super_line } }.clean(e.backtrace))
+        raise e
+      end
+    end
+  end
+  
+  # Remove an environmental prefix from the existing list. 
+  # @param prefix [Symbol, Object] Prefix to remove.  
+  #  +nil+ is treated as +self+   
+  #  Non symbols are converted via {.prefix_from AppConfigFor.prefix_from}.  
+  # @param all [Boolean] Remove this prefix throughout the entire inheritance chain.  
+  #  +USE WITH CAUTION:+ When +true+ this will affect other consumers of AppConfigFor by altering their env prefix values.
+  # @return [Array<Symbol>] Current prefixes (without inheritance)
+  # @see #env_prefixes Current prefixes
   def remove_env_prefix(prefix, all = false)
     if all
       remove_env_prefix(prefix)
@@ -126,24 +522,70 @@ module AppConfigFor
     else
       env_prefixes(false, false).delete(AppConfigFor.prefix_from(prefix))
     end
+    env_prefixes(all)
   end
 
+  # Return true if the missing method is a configuration getter or setter.
+  # @see #method_missing Accessing configuration values directly from the extending class/module
+  def respond_to_missing?(name, *args)
+    configured?(name.to_s.split('=').first.to_sym) || super
+  end
+  
   class << self
 
+    # Add an additional environmental prefix to be used when determining current environment.
+    # @param prefix [Symbol, Object] Prefix to add.  
+    #  Non symbols are converted via {.prefix_from}.  
+    # @param at_beginning [Boolean] where to insert the new prefix with respect to existing prefixes.
+    #   * +true+ - Add to the beginning of the list.
+    #   * +false+ - Add to the end of the list.
+    # @return [Array<Symbol>] Current prefixes (without inheritance)
+    # @see env_prefixes Current prefixes
+    # @note Prefixes added here will affect all consumers of AppConfigFor. For targeted changes see: {#add_env_prefix}
     def add_env_prefix(prefix, at_beginning = true)
       env_prefixes(false, false).send(at_beginning ? :unshift : :push, prefix_from(prefix)).uniq!
+      env_prefixes(false)
     end
 
+    # The name of the current runtime environment. This is value of the first non blank environment variable.
+    # If no value can be found, the default is 'development'.
+    # Prefixes like +:some_app+, +:rails+, and +:rack+ convert to +'SOME_APP_ENV'+, +'RAILS_ENV'+, and +'RACK_ENV'+ respectively.
+    # @param prefixes [Array<#to_s>] List of prefixes of environment variables to check.
+    # @return [String] current runtime environment.
+    # @see env_prefixes Current prefixes
     def env_name(prefixes = env_prefixes)
-      prefixes.inject(nil) { |current_env, name| current_env || ENV["#{name.to_s.upcase}_ENV"].presence } || 'development'
+      Array(prefixes).inject(nil) { |current_env, name| current_env || ENV["#{name.to_s.upcase}_ENV"].presence } || 'development'
     end
 
-    def env_prefixes(_all = true, dup = true)
-      # all is ignored as we are at the end of the chain
+    # Prefixes used to determine the environment name.
+    #
+    # A prefix of :some_app will will cause AppConfigFor to react to the environment variable +'SOME_APP_ENV'+
+    # The order of the prefixes will be the order in which AppConfigFor searches the environment variables.
+    #
+    # @param _ Ignored. Unlike {#env_prefixes}, the first parameter is ignored as there is no inheritance at this point.
+    # @param dup[Boolean] Return a duplicate of the internal array to prevent accidental modification.
+    # @return [Array<Symbol>] Defaults to +[:rails, :rack]+
+    # @see env_name Current runtime environment
+    def env_prefixes(_ = true, dup = true)
       @env_prefixes ||= [:rails, :rack]
       dup ? @env_prefixes.dup : @env_prefixes
     end
 
+    # Lexical namespace of an object.
+    # Strings are considered to hold the #name of a Class or Module.
+    # Anything not a String, Class, or Module will return the namespace of the class of the object.
+    # @param object [Module, Class, String, Object]
+    # @return [Module, Class, nil] +nil+ is returned if there is no surrounding namespace.
+    # @example
+    #   module Some
+    #     class App
+    #     end
+    #   end
+    #
+    #   namespace_of(Some::App)      # => Some
+    #   namespace_of('Some::App')    # => Some
+    #   namespace_of(Some::App.new)  # => Some
+    #   namespace_of(Some)           # => nil
     def namespace_of(object)
       case object
       when String
@@ -155,11 +597,42 @@ module AppConfigFor
       end.deconstantize.safe_constantize
     end
 
-    # Not used internally, this is a convenience method to study what progenitors are used during namespace dives
+    # Array of all hierarchical lexical namespaces of an object. Uses {.namespace_of}
+    # @param object [Module, Class, String, Object]
+    # @return [Array<Module, Class>]
+    # @example
+    #   module Some
+    #     class App
+    #       class Connection
+    #       end
+    #     end
+    #   end
+    #
+    #   namespaces_of(Some::App::Connection) # => [Some::App, Some]
+    #   namespaces_of(Some) # => []
     def namespaces_of(object)
       (object = [namespace_of(object)]).each { |x| x && object << namespace_of(x) }[0..-2]
     end
 
+    # Parent of an object.
+    # While similar to inheritance it provides a meaningful value for strings and other objects.
+    # Classes return super classes.
+    # Strings are treated as a name of a class and an attempt is made to locate that class (not the superclass of the named class).
+    # All other objects return the class of the object.
+    # @param object [Class, String, Object]
+    # @return [Class, nil] +nil+ is returned if a string is given that is not the name of a class.
+    # @example
+    #   module Some
+    #     class Base
+    #     end
+    #     class App < Base
+    #     end
+    #   end
+    #
+    #   parent_of(Some::App)     # => Some::Base
+    #   parent_of(Some::App.new) # => Some::App
+    #   parent_of('Some::App')   # => Some::App
+    #   parent_of('wtf')         # => nil
     def parent_of(object)
       case object
       when String
@@ -171,11 +644,49 @@ module AppConfigFor
       end
     end
 
-    # Not used internally, this is a convenience method to study what progenitors are used during class dives
+    # List of all hierarchical parents of an object. Uses {.parents_of}
+    # @param object [Class, String, Object]
+    # @return [Array<Class>]
+    #
+    # @example
+    #   module Some
+    #     class Base
+    #     end
+    #     class App < Base
+    #     end
+    #   end
+    #
+    #   parents_of(Some::App)     # => [Some::Base, Object, BasicObject]
+    #   parents_of(Some::App.new) # => [Some::App, Some::Base, Object, BasicObject]
+    #   parents_of('Some::App')   # => [Some::App, Some::Base, Object, BasicObject]
+    #   parents_of('wtf')         # => []
     def parents_of(object)
       (object = [parent_of(object)]).each { |x| x && object << parent_of(x) }[0..-2]
     end
 
+    # Converts an object to a prefix symbol.
+    # Non symbols are converted to underscored symbols with '/' characters changed to underscores.
+    # Conversion by object type is as follows:
+    # * Symbol -> symbol
+    # * Module -> module.name
+    # * Class -> class.name
+    # * String -> string
+    # * Pathname -> pathname.basename (Without an extension)
+    # * other -> other.class.name
+    # @param object [Symbol, Module, Class, String, Pathname, Object] object to convert to a prefix
+    # @return [Symbol]
+    # @example
+    #   module Some
+    #     class App
+    #     end
+    #   end
+    #
+    #   # All of the following return :some_app
+    #   prefix_from(Some::App)
+    #   prefix_from('Some::App')
+    #   prefix_from(Some::App.new)
+    #   prefix_from(:some_app)
+    #   prefix_from(Pathname.new('/foo/bar/some_app.yml'))
     def prefix_from(object)
       if object.is_a?(Symbol)
         object
@@ -186,26 +697,51 @@ module AppConfigFor
         when String
           object
         when Pathname
-          object.basename.to_s
+          object.basename('.*').to_s
         else
           object.class.name
         end.underscore.gsub('/','_').to_sym
      end
     end
 
+    # The first env_prefix aware namespace/parent of an object. 
+    # Search is dependant on the inheritance style given.
+    # @param object [Object] Object to retrieve the progenitor of.
+    # @param style [#to_s] Type of hierarchical traversal.
+    # @return [Object, nil] +nil+ is returned if there is no progenitor.
+    # @raise InvalidEnvInheritanceStyle - Attempt to use a style that is not one of the {EnvInheritanceStyles}.
+    # @see .verified_style! Valid inheritance styles
     def progenitor_of(object, style = nil)
       style = verified_style!(style, object)
-      command = {namespace: :namespace_of, class: :parent_of}[style] # Todo, deal with the other styles by doing nothing and not crashing or something.
+      command = {namespace: :namespace_of, class: :parent_of}[style.to_s.split('_').first.to_sym]
       object && command && send(command, object).yield_self { |n| n && (n.respond_to?(:env_prefixes) ? n : progenitor_of(n)) }
     end
 
+    # Extract the env_prefixes from the progenitor of the given object.
+    # @param object [Object] Object to retrieve the {.progenitor_of} and subsequently the {#env_prefixes}.
+    # @param style [#to_s] Type of hierarchical traversal.
+    # @param all [Boolean] Return inherited prefixes.  
+    #   If there is no progenitor of the object and all is +true+ then {.env_prefixes AppConfigFor.env_prefixes} will be returned.
+    # @return [Array<Symbol>] Environment prefixes for this object.
+    # @raise InvalidEnvInheritanceStyle - Attempt to use a style that is not one of the {EnvInheritanceStyles}.
+    # @see .env_prefixes Default prefixes
+    # @see .verified_style! Valid inheritance styles
     def progenitor_prefixes_of(object, style = nil, all = true)
-      Array(progenitor_of(object, style)&.env_prefixes(all))
+      Array((progenitor_of(object, style) || all && AppConfigFor).try(:env_prefixes, all))
     end
 
-    def progenitors_of(object, style = nil, terminate = true)
+    # List of hierarchical progenitors of an object.
+    # Hierarchical precedence is controlled by the style.
+    # @param object [Object] Object to get the progenitors from
+    # @param style [#to_s] Type of hierarchical traversal.
+    # @param unique [Boolean] Remove duplicate progenitors.
+    # @return [Array<Object>]
+    # @raise InvalidEnvInheritanceStyle - Attempt to use a style that is not one of the {EnvInheritanceStyles}.
+    # @see progenitor_of Progenitor of an object
+    # @see .verified_style! Valid inheritance styles
+    def progenitors_of(object, style = nil, unique = true)
       style = verified_style!(style, object)
-      terminate = terminate && style != :none
+      unique = unique && style != :none
       if object && style != :none
         styles = style.to_s.split('_')
         if styles.size > 1
@@ -215,19 +751,59 @@ module AppConfigFor
         end
       else
         []
-      end.yield_self { |result| terminate ? result.reverse.uniq.reverse + [self] : result }
+      end.yield_self { |result| unique ? result.reverse.uniq.reverse + [self] : result }
     end
 
-    def remove_env_prefix(prefix, all = false)
-      env_prefixes(all, false).delete(prefix_from(prefix))
+    # Remove an environmental prefix from the existing list. 
+    # @param prefix [Symbol, Object] Prefix to remove.  
+    #  Non symbols are converted via {.prefix_from AppConfigFor.prefix_from}.  
+    # @param _ Ignored. Unlike {#remove_env_prefix}, the first parameter is ignored as there is no inheritance at this point.
+    # @return [Array<Symbol>] Current prefixes (without inheritance)
+    # @note Prefixes removed here will affect all consumers of AppConfigFor. For targeted changes see: {#remove_env_prefix}
+    def remove_env_prefix(prefix, _ = false)
+      env_prefixes(false, false).delete(prefix_from(prefix))
+      env_prefixes(false)
     end
 
-    def verified_style!(style, object = nil)
-      style ||= object.respond_to?(:env_prefix_inheritance) ? object.send(:env_prefix_inheritance) : :namespace
+    # Verifies the inheritance style. If style is nil, the object, if given, will be queried for its env_inheritance.
+    # Otherwise the style will default to +:namespace:+
+    # @param style [#to_s] Inheritance style to verify.
+    # @param object [Object] Object to query for env_inheritance if style is nil.
+    # return [Symbol] A valid inheritance style.
+    # @raise InvalidEnvInheritanceStyle - An invalid inheritance style was received.
+    def verified_style!(style = nil, object = nil)
+      style ||= object.respond_to?(:env_inheritance) && object.env_inheritance || :namespace
       style = style.try(:to_sym) || style.to_s.to_sym
-      EnvPrefixInheritanceStyles.include?(style) ? style : raise(InvalidEnvInheritanceStyle.new(style))
+      EnvInheritanceStyles.include?(style) ? style : raise(InvalidEnvInheritanceStyle.new(style))
     end
 
+    # Determine the name of the yml file from the object given. No pathing is assumed.
+    # Anything not a Pathname is converted to an underscored string with '/' characters changed to underscores and a '.yml' extension
+    # @param object [Object] Object to determine a yml name from.
+    #
+    # Determination by object type is as follows:
+    # * Pathname -> pathname
+    # * Module -> module.name
+    # * Class -> class.name
+    # * String -> string
+    # * Symbol -> symbol.to_s
+    # * other -> other.class.name
+    # @return [String, Pathname]
+    # @example
+    #   module Some
+    #     class App
+    #     end
+    #   end
+    #
+    #   # All of the following return 'some_app.yml'
+    #   yml_name_from(Some::App)
+    #   yml_name_from(Some::App.new)
+    #   yml_name_from(:some_app)
+    #   yml_name_from('Some/App')
+    #   yml_name_from('Some::App')
+    #
+    #   # Pathnames receive no conversion
+    #   yml_name_from(Pathname.new('not/a/yml_file.txt')) # => #<Pathname:not/a/yml_file.txt>
     def yml_name_from(object)
       if object.is_a?(Pathname)
         object
@@ -235,7 +811,9 @@ module AppConfigFor
         case object
         when Module
           object.name
-        when String, Symbol
+        when String
+          object
+        when Symbol
           object.to_s
         else
           object.class.name
@@ -245,8 +823,8 @@ module AppConfigFor
 
     private
 
-    def prep_base(base)
-      base.add_env_prefix
+    # Add the config directory from the gem installation if this is a gem.
+    def add_gem_directory(base)
       gem = Gem.loaded_specs[base.name.underscore]
       base.add_config_directory(gem.gem_dir + '/config') if gem
     end
@@ -254,14 +832,13 @@ module AppConfigFor
     def extended(base)
       # Todo: Add the ability to check the default environments directly from base if the methods don't yet exist.
       # ie: base.development? is the same as base.env.development?
-      prep_base(base)
+      add_gem_directory(base)
     end
 
     def included(base)
-      prep_base(base)
+      add_gem_directory(base)
     end
 
   end
 
-end
-
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: app_config_for
 version: !ruby/object:Gem::Version
-  version: 0.0.4.1
+  version: 0.0.6.1
 platform: ruby
 authors:
 - Frank Hall
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2022-04-15 00:00:00.000000000 Z
+date: 2022-04-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -87,8 +87,8 @@ licenses:
 - MIT
 metadata:
   homepage_uri: https://github.com/ChapterHouse/app_config_for
-  source_code_uri: https://github.com/ChapterHouse/app_config_for/tree/v0.0.4.1
-  changelog_uri: https://github.com/ChapterHouse/app_config_for/blob/v0.0.4.1/CHANGELOG.md
+  source_code_uri: https://github.com/ChapterHouse/app_config_for/tree/v0.0.6.1
+  changelog_uri: https://github.com/ChapterHouse/app_config_for/blob/v0.0.6.1/CHANGELOG.md
 post_install_message:
 rdoc_options: []
 require_paths: