ultra_settings 0.0.1.rc1 → 1.0.0

data/lib/ultra_settings/field.rb

@@ -5,51 +5,41 @@ module UltraSettings
   class Field
     attr_reader :name
     attr_reader :type
+    attr_reader :description
     attr_reader :default
     attr_reader :default_if
     attr_reader :env_var
-    attr_reader :setting_name
+    attr_reader :runtime_setting
     attr_reader :yaml_key
-    attr_reader :env_var_prefix
-    attr_reader :env_var_upcase
-    attr_reader :setting_prefix
-    attr_reader :setting_upcase
 
     # @param name [String, Symbol] The name of the field.
     # @param type [Symbol] The type of the field.
+    # @param description [String] The description of the field.
     # @param default [Object] The default value of the field.
     # @param default_if [Proc] A proc that returns true if the default value should be used.
     # @param env_var [String, Symbol] The name of the environment variable to use for the field.
-    # @param setting_name [String, Symbol] The name of the setting to use for the field.
+    # @param runtime_setting [String, Symbol] The name of the setting to use for the field.
     # @param yaml_key [String, Symbol] The name of the YAML key to use for the field.
-    # @param env_var_prefix [String, Symbol] The prefix to use for the environment variable name.
-    # @param env_var_upcase [Boolean] Whether or not to upcase the environment variable name.
-    # @param setting_prefix [String, Symbol] The prefix to use for the setting name.
-    # @param setting_upcase [Boolean] Whether or not to upcase the setting name.
     def initialize(
       name:,
       type: :string,
+      description: nil,
       default: nil,
       default_if: nil,
       env_var: nil,
-      setting_name: nil,
+      runtime_setting: nil,
       yaml_key: nil,
-      env_var_prefix: nil,
-      env_var_upcase: true,
-      setting_prefix: nil,
-      setting_upcase: false
+      static: false
     )
-      @name = frozen_string(name)
+      @name = name.to_s.freeze
       @type = type.to_sym
-      @default = coerce_value(default).freeze
+      @description = description&.to_s&.freeze
+      @default = Coerce.coerce_value(default, @type).freeze
       @default_if = default_if
-      @env_var = frozen_string(env_var)
-      @setting_name = frozen_string(setting_name)
-      @yaml_key = frozen_string(yaml_key)
-      @env_var_prefix = frozen_string(env_var_prefix)
-      @env_var_upcase = !!env_var_upcase
-      @setting_prefix = frozen_string(setting_prefix)
-      @setting_upcase = !!setting_upcase
+      @env_var = env_var&.to_s&.freeze
+      @runtime_setting = runtime_setting&.to_s&.freeze
+      @yaml_key = yaml_key&.to_s&.freeze
+      @static = !!static
     end
 
     # Get the value for the field from the passed in state.
@@ -58,85 +48,64 @@ module UltraSettings
     # @param settings [#[]] The runtime settings.
     # @param yaml_config [#[]] The YAML configuration.
     def value(env: nil, settings: nil, yaml_config: nil)
-      val = fetch_value(env: env, settings: settings, yaml_config: yaml_config)
-      val = coerce_value(val).freeze
-      val = @default if use_default?(val)
-      val
+      fetch_value_and_source(env: env, settings: settings, yaml_config: yaml_config).first
     end
 
-    private
-
-    def fetch_value(env:, settings:, yaml_config:)
-      value = env_value(env) if env
-      value = nil if value == ""
-
-      if value.nil? && settings
-        value = runtime_value(settings)
-        value = nil if value == ""
-      end
+    # Get the source for the field from the passed in state.
+    #
+    # @param env [Hash] The environment variables.
+    # @param settings [Hash] The runtime settings.
+    # @param yaml_config [Hash] The YAML configuration.
+    # @return [Symbol, nil] The source of the value (:env, :settings, or :yaml).
+    def source(env: nil, settings: nil, yaml_config: nil)
+      fetch_value_and_source(env: env, settings: settings, yaml_config: yaml_config).last
+    end
 
-      if value.nil? && yaml_config
-        value = yaml_value(yaml_config)
-        value = nil if value == ""
-      end
+    # Coerce the passed in value to the type of the field.
+    #
+    # @param value [Object] The value to coerce.
+    # @return [Object] The coerced value.
+    def coerce(value)
+      Coerce.coerce_value(value, @type)
+    end
 
-      value
+    # Returns true if the field is static.
+    #
+    # @return [Boolean]
+    def static?
+      @static
     end
 
-    def coerce_value(value)
-      return nil if value.nil?
+    private
+
+    def fetch_value_and_source(env:, settings:, yaml_config:)
+      source = nil
 
-      case type
-      when :integer
-        value.is_a?(Integer) ? value : value.to_s&.to_i
-      when :float
-        value.is_a?(Float) ? value : value.to_s&.to_f
-      when :boolean
-        SuperSettings::Coerce.boolean(value)
-      when :datetime
-        SuperSettings::Coerce.time(value)
-      when :array
-        Array(value).map(&:to_s)
-      when :symbol
-        value.to_s.to_sym
+      value = env[env_var] if env && env_var
+      value = nil if value == ""
+      if value.nil?
+        value = settings[runtime_setting] if settings && runtime_setting
+        value = nil if value == ""
+        if value.nil?
+          value = yaml_value(yaml_config)
+          value = nil if value == ""
+          source = :yaml unless value.nil?
+        else
+          source = :settings
+        end
       else
-        value.to_s
+        source = :env
       end
-    end
 
-    def env_value(env)
-      var_name = env_var
-      if var_name.nil?
-        var_name = "#{env_var_prefix}#{name}"
-        var_name = var_name.upcase if env_var_upcase
-      end
-      env[var_name.to_s]
-    end
+      value = coerce(value).freeze
 
-    def runtime_value(settings)
-      var_name = setting_name
-      if var_name.nil?
-        var_name = "#{setting_prefix}#{name}"
-        var_name = var_name.upcase if setting_upcase
-      end
-      settings[var_name.to_s]
+      [value, source]
     end
 
     def yaml_value(yaml_config)
-      key = (yaml_key || name)
-      yaml_config[key.to_s]
-    end
-
-    def use_default?(value)
-      if value && @default_if
-        @default_if.call(value)
-      else
-        value.nil?
-      end
-    end
+      return nil unless yaml_config && yaml_key
 
-    def frozen_string(value)
-      value&.to_s&.dup&.freeze
+      yaml_config[yaml_key]
     end
   end
 end

data/lib/ultra_settings/rack_app.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module UltraSettings
+  # Rack application for displaying the current settings in an HTML page.
+  # No setting values are displayed, but you should still add some
+  # sort of authentication if you want to use this in production.
+  class RackApp
+    def call(env)
+      [200, {"content-type" => "text/html; charset=utf8"}, [webview.render_settings]]
+    end
+
+    private
+
+    def webview
+      if ENV.fetch("RAILS_ENV", ENV.fetch("RACK_ENV", "development")) == "development"
+        @webview = nil
+      end
+      @webview ||= WebView.new
+    end
+  end
+end

data/lib/ultra_settings/railtie.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module UltraSettings
+  # Railtie to automatically configure settings for Rails applications.
+  # By default this will automatically load any configuration classes in the
+  # app/configurations directory. This can be customized by setting the
+  # `config.ultra_settings.auto_load_directories` option.
+  class Railtie < Rails::Railtie
+    config.ultra_settings = ActiveSupport::OrderedOptions.new
+    config.ultra_settings.auto_load_directories = [File.join("app", "configurations")]
+
+    config.before_configuration do
+      UltraSettings.yaml_config_env = Rails.env
+      UltraSettings.yaml_config_path = Rails.root.join("config")
+    end
+
+    # Automatically register any configuration classes in the app/configurations
+    # directory. The path to load can be customized by setting the
+    # `config.ultra_settings.auto_load_directory` option.
+    config.after_initialize do
+      Array(Rails.application.config.ultra_settings.auto_load_directories).each do |directory|
+        next unless directory
+
+        app_config_dir = Rails.root.join(directory)
+        app_config_dir.glob("**/*_configuration.rb").each do |file_path|
+          config_name = file_path.basename("_configuration.rb")
+          class_name = file_path.relative_path_from(app_config_dir).to_s.chomp(".rb").classify
+          UltraSettings.add(config_name, class_name)
+        end
+      end
+    end
+  end
+end

data/lib/ultra_settings/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module UltraSettings
+  VERSION = File.read(File.join(__dir__, "..", "..", "VERSION")).strip
+end

data/lib/ultra_settings/web_view.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module UltraSettings
+  # Helper class for rendering the settings information in an HTML page.
+  class WebView
+    attr_reader :css
+
+    def initialize
+      @index_template = erb_template("index.html.erb")
+      @layout_template = erb_template("layout.html.erb")
+      @layout_css = read_app_file("layout.css")
+      @css = read_app_file("application.css")
+      @javascript = read_app_file("application.js")
+    end
+
+    def render_settings
+      @layout_template.result(binding)
+    end
+
+    def content
+      @index_template.result(binding)
+    end
+
+    private
+
+    def erb_template(path)
+      ERB.new(read_app_file(path))
+    end
+
+    def read_app_file(path)
+      File.read(File.join(app_dir, path))
+    end
+
+    def app_dir
+      File.expand_path(File.join("..", "..", "app"), __dir__)
+    end
+  end
+end

data/lib/ultra_settings/yaml_config.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module UltraSettings
+  # Helper class to load YAML configuration files. Any ERB markup in the YAML
+  # file will be evaluated. The YAML file should be structured like this:
+  #
+  # ```yaml
+  # shared:
+  #   foo: bar
+  #   bar: baz
+  #
+  # development:
+  #   bar: qux
+  #   biz: buz
+  #
+  # test:
+  #   bar: qix
+  #   biz: biz
+  # ```
+  #
+  # The section with the key matching the environment name is merged into
+  # the shared section. In this example, the development environment would
+  # have the following configuration:
+  #
+  # ```ruby
+  # {
+  #   "foo" => "bar",
+  #   "bar" => "qux",
+  #   "biz" => "buz"
+  # }
+  # ```
+  #
+  # In addition, the keys are flattened into a one level deep hash with dots
+  # separating the keys.
+  class YamlConfig
+    def initialize(path, environment)
+      yaml = load_yaml(path)
+      @config = environment_config(yaml, environment)
+    end
+
+    def to_h
+      @config
+    end
+
+    private
+
+    def load_yaml(path)
+      yaml = File.read(path)
+
+      if yaml.include?("<%")
+        yaml = ERB.new(yaml).result
+      end
+
+      hash = YAML.load(yaml) # rubocop:disable Security/YAMLLoad
+      hash = {} unless hash.is_a?(Hash)
+      hash
+    end
+
+    def environment_config(yaml, environment)
+      shared = flatten_hash(yaml.fetch("shared", {}))
+      env = flatten_hash(yaml.fetch(environment, {}))
+      shared.merge(env)
+    end
+
+    def flatten_hash(hash, prefix = nil)
+      hash.each_with_object({}) do |(key, value), result|
+        key = key.to_s
+        key = "#{prefix}.#{key}" if prefix
+
+        if value.is_a?(Hash)
+          result.merge!(flatten_hash(value, key))
+        else
+          result[key] = value
+        end
+      end
+    end
+  end
+end

data/lib/ultra_settings.rb

@@ -1,9 +1,22 @@
 # frozen_string_literal: true
 
-require "super_settings"
+require "erb"
+require "yaml"
+require "time"
+require "pathname"
+require "singleton"
 
 require_relative "ultra_settings/configuration"
+require_relative "ultra_settings/coerce"
 require_relative "ultra_settings/field"
+require_relative "ultra_settings/rack_app"
+require_relative "ultra_settings/web_view"
+require_relative "ultra_settings/yaml_config"
+require_relative "ultra_settings/version"
+
+if defined?(Rails::Railtie)
+  require_relative "ultra_settings/railtie"
+end
 
 # This is the root namespace for UltraSettings. You can add configurations to
 # this namespace using the add method.
@@ -12,12 +25,11 @@ require_relative "ultra_settings/field"
 #   UltraSettings.add(:test)
 #   UltraSettings.test # => TestConfiguration.instance
 module UltraSettings
+  VALID_NAME__PATTERN = /\A[a-z_][a-zA-Z0-9_]*\z/
+
   @configurations = {}
   @mutex = Mutex.new
 
-  class NonStaticValueError < StandardError
-  end
-
   class << self
     # Adds a configuration to the root namespace. The configuration will be
     # available as a method on the UltraSettings module with the provide name.
@@ -29,15 +41,15 @@ module UltraSettings
     # @return [void]
     def add(name, klass = nil)
       name = name.to_s
-      unless name.match?(/\A[a-z_][a-zA-Z0-9_]*\z/)
+      unless name.match?(VALID_NAME__PATTERN)
         raise ArgementError.new("Invalid configuration name: #{name.inspect}")
       end
 
       class_name = klass&.to_s
-      class_name ||= "#{name.classify}Configuration"
+      class_name ||= "#{classify(name)}Configuration"
 
       @mutex.synchronize do
-        @configurations.delete(name)
+        @configurations[name] = class_name
 
         eval <<-RUBY, binding, __FILE__, __LINE__ + 1 # rubocop:disable Security/Eval
           def #{name}
@@ -45,93 +57,158 @@ module UltraSettings
           end
         RUBY
       end
+    end
 
-      # Control if settings can be loaded from environment variables. By default
-      # environment variables are enabled. This can also be disabled on
-      # individual Configuration classes.
-      #
-      # @param value [Boolean] Whether or not to load settings from environment variables.
-      # @return [void]
-      def environment_variables_disabled=(value)
-        Configuration.environment_variables_disabled = !!value
-      end
+    # Returns true if the provided class has been added as a configuration.
+    #
+    # @param class_name [Class, String] The name of the configuration class.
+    # @return [Boolean]
+    def include?(class_name)
+      @configurations.values.collect(&:to_s).include?(class_name.to_s)
+    end
 
-      # Control if settings can be loaded from runtime settings. By default
-      # runtime settings are enabled. This can also be disabled on individual
-      # Configuration classes.
-      #
-      # @param value [Boolean] Whether or not to load settings from runtime settings.
-      # @return [void]
-      def runtime_settings_disabled=(value)
-        Configuration.runtime_settings_disabled = !!value
-      end
+    # Control if settings can be loaded from environment variables. By default
+    # environment variables are enabled. This can also be disabled on
+    # individual Configuration classes.
+    #
+    # @param value [Boolean] Whether or not to load settings from environment variables.
+    # @return [void]
+    def environment_variables_disabled=(value)
+      Configuration.environment_variables_disabled = !!value
+    end
 
-      # Control if settings can be loaded from YAML configuration files. By
-      # default YAML configuration is enabled. This can also be disabled on
-      # individual Configuration classes.
-      #
-      # @param value [Boolean] Whether or not to load settings from YAML configuration.
-      # @return [void]
-      def yaml_config_disabled=(value)
-        Configuration.yaml_config_disabled = !!value
-      end
+    # Control if settings can be loaded from runtime settings. By default
+    # runtime settings are enabled. This can also be disabled on individual
+    # Configuration classes.
+    #
+    # @param value [Boolean] Whether or not to load settings from runtime settings.
+    # @return [void]
+    def runtime_settings_disabled=(value)
+      Configuration.runtime_settings_disabled = !!value
+    end
 
-      # Set the delimiter to use when determining environment variable names.
-      # By default this is an underscore.
-      #
-      # @param value [String] The delimiter to use.
-      # @return [void]
-      def env_var_delimiter=(value)
-        Configuration.env_var_delimiter = value.to_s
-      end
+    # Control if settings can be loaded from YAML configuration files. By
+    # default YAML configuration is enabled. This can also be disabled on
+    # individual Configuration classes.
+    #
+    # @param value [Boolean] Whether or not to load settings from YAML configuration.
+    # @return [void]
+    def yaml_config_disabled=(value)
+      Configuration.yaml_config_disabled = !!value
+    end
 
-      # Set the delimiter to use when determining setting names. By default
-      # this is a period.
-      #
-      # @param value [String] The delimiter to use.
-      def setting_delimiter=(value)
-        Configuration.setting_delimiter = value.to_s
-      end
+    # Set the environment to use when loading YAML configuration files.
+    # In a Rails application this will be the current Rails environment.
+    # Defaults to "development".
+    #
+    # @param value [String] The environment name to use.
+    def yaml_config_env=(value)
+      Configuration.yaml_config_env = value
+    end
 
-      # Control if environment variable names should be upcased. By default
-      # this is true.
-      #
-      # @param value [Boolean] Whether or not to upcase environment variable names.
-      # @return [void]
-      def env_var_upcase=(value)
-        Configuration.env_var_upcase = !!value
-      end
+    # Set the delimiter to use when determining environment variable names.
+    # By default this is an underscore.
+    #
+    # @param value [String] The delimiter to use.
+    # @return [void]
+    def env_var_delimiter=(value)
+      Configuration.env_var_delimiter = value.to_s
+    end
+
+    # Set the delimiter to use when determining setting names. By default
+    # this is a period.
+    #
+    # @param value [String] The delimiter to use.
+    def runtime_setting_delimiter=(value)
+      Configuration.runtime_setting_delimiter = value.to_s
+    end
+
+    # Control if environment variable names should be upcased. By default
+    # this is true.
+    #
+    # @param value [Boolean] Whether or not to upcase environment variable names.
+    # @return [void]
+    def env_var_upcase=(value)
+      Configuration.env_var_upcase = !!value
+    end
+
+    # Control if setting names should be upcased. By default this is false.
+    #
+    # @param value [Boolean] Whether or not to upcase setting names.
+    # @return [void]
+    def runtime_setting_upcase=(value)
+      Configuration.runtime_setting_upcase = !!value
+    end
+
+    # Set the directory to use when loading YAML configuration files.
+    # In a Rails application this will be the config directory.
+    # Otherwise it will be the current working directory.
+    #
+    # @param value [String, Pathname] The directory to use.
+    # @return [void]
+    def yaml_config_path=(value)
+      Configuration.yaml_config_path = value.to_s
+    end
+
+    # Set the object to use for runtime settings. This can be any object that
+    # responds to the [] method. If you are using the `super_settings` gem,
+    # you can set this to `SuperSettings`.
+    attr_writer :runtime_settings
 
-      # Control if setting names should be upcased. By default this is false.
-      #
-      # @param value [Boolean] Whether or not to upcase setting names.
-      # @return [void]
-      def setting_upcase=(value)
-        Configuration.setting_upcase = !!value
+    # Get the object to use for runtime settings.
+    #
+    # @return [Object, nil]
+    # @api private
+    def __runtime_settings__
+      @runtime_settings ||= nil
+    end
+
+    # Explicitly set setting values within a block. This is useful for testing
+    # or other situations where you want hard code a specific set of values.
+    #
+    # @param settings [Hash] The settings to set.
+    # @return [Object] The result of the block.
+    def override!(settings, &block)
+      settings = settings.to_a
+      config_name, values = settings.first
+      config_name = config_name.to_s
+      other_settings = settings[1..-1]
+
+      unless @configurations.include?(config_name)
+        raise ArgumentError.new("Unknown configuration: #{config_name.inspect}")
       end
 
-      # Set the directory to use when loading YAML configuration files. By
-      # default this is the config directory in the Rails root.
-      #
-      # @param value [String, Pathname] The directory to use.
-      # @return [void]
-      def yaml_config_directory=(value)
-        Configuration.yaml_config_directory = value.to_s
+      config = send(config_name)
+      config.override!(values) do
+        if other_settings.empty?
+          yield
+        else
+          override!(other_settings, &block)
+        end
       end
     end
 
+    # Get the names of all of the configurations that have been added.
+    #
+    # @return [Array<String>] The names of the configurations.
+    # @api private
+    def __configuration_names__
+      @configurations.keys
+    end
+
     private
 
     # Load a configuration class.
     def __load_config__(name, class_name)
       klass = @configurations[name]
 
-      if klass && !Rails.configuration.cache_classes
-        klass = nil if klass != class_name.constantize
+      # Hook for Rails development mode to reload the configuration class.
+      if klass && defined?(Rails.configuration.cache_classes) && !Rails.configuration.cache_classes
+        klass = class_name if klass != constantize(class_name)
       end
 
-      unless klass
-        klass = class_name.constantize
+      if klass.is_a?(String)
+        klass = constantize(class_name)
         @mutex.synchronize do
           unless klass < Configuration
             raise TypeError.new("Configuration class #{class_name} does not inherit from UltraSettings::Configuration")
@@ -142,5 +219,21 @@ module UltraSettings
 
       klass.instance
     end
+
+    def classify(name)
+      # Use the Rails classify method if it is available since it will
+      # handle custom inflections.
+      if name.respond_to?(:classify)
+        name.classify
+      else
+        name.split("_").map(&:capitalize).join.gsub("/", "::")
+      end
+    end
+
+    def constantize(class_name)
+      class_name.split("::").reduce(Object) do |mod, name|
+        mod.const_get(name)
+      end
+    end
   end
 end