const_conf 0.0.0

data/lib/const_conf/tree.rb

@@ -0,0 +1,265 @@
+module ConstConf
+  # A tree structure implementation for visualizing ConstConf configuration
+  # hierarchies.
+  #
+  # The Tree class provides a hierarchical representation of ConstConf modules
+  # and settings, allowing for formatted display of configuration data with
+  # metadata including prefixes, environment variable names, default values,
+  # and configuration status. It supports colored output and proper indentation
+  # to show the relationships between nested configuration elements.
+  class Tree
+    class << self
+      include Term::ANSIColor
+
+      # Converts a ConstConf configuration or setting into a tree structure for
+      # display purposes.
+      #
+      # This method takes either a ConstConf module or a specific setting and
+      # transforms it into a hierarchical tree representation that can be used
+      # for visualization or debugging. It delegates to specialized conversion
+      # methods based on the type of the input argument.
+      #
+      # @param configuration_or_setting [Object] the ConstConf module or
+      # setting to convert
+      #
+      # @return [ConstConf::Tree] a tree object representing the configuration
+      # hierarchy
+      #
+      # @raise [ArgumentError] if the argument is neither a ConstConf module
+      # nor a ConstConf::Setting instance
+      def from_const_conf(configuration_or_setting)
+        if configuration?(configuration_or_setting)
+          convert_module(configuration_or_setting)
+        elsif configuration_or_setting.is_a?(ConstConf::Setting)
+          convert_setting(configuration_or_setting)
+        else
+          raise ArgumentError,
+            "argument needs to have type ConstConf::Setting or ConstConf"
+        end
+      end
+
+      private
+
+      # Checks whether the given object is a ConstConf module.
+      #
+      # This method determines if the provided object is a Module that includes
+      # the ConstConf concern. It returns true if the object meets these
+      # criteria, and false otherwise. In case a NameError occurs during the
+      # check, it gracefully returns false.
+      #
+      # @param object [ Object ] the object to be checked
+      #
+      # @return [ Boolean ] true if the object is a ConstConf module, false
+      # otherwise
+      def configuration?(object)
+        object.is_a?(Module) && object < ConstConf
+      rescue NameError
+        false
+      end
+
+      # Converts a ConstConf module into a tree-like structure for display
+      # purposes.
+      #
+      # This method transforms a module that includes ConstConf configuration
+      # settings into a hierarchical tree representation. It captures the
+      # module's name, description, prefix, and number of settings, then
+      # recursively processes nested modules and individual settings to build a
+      # complete configuration tree.
+      #
+      # @param modul [Module] the ConstConf module to convert into a tree
+      # structure
+      # @return [ConstConf::Tree] a tree object representing the module's
+      # configuration hierarchy
+      def convert_module(modul)
+        desc = "#{modul.description.full? { italic(' # %s' % it) }}"
+        obj  = new("#{modul.name}#{desc}")
+        obj << new("prefix #{modul.prefix.inspect}")
+        obj << new("#{modul.settings.size} settings")
+
+        modul.settings.each do |env_var, setting|
+          obj << convert_setting(setting)
+        end
+
+        modul.constants.sort.each do |const_name|
+          begin
+            const = modul.const_get(const_name)
+            if const.is_a?(Module) && const < ConstConf
+              obj << convert_module(const)
+            end
+          rescue NameError
+          end
+        end
+
+        obj
+      end
+
+      # Converts a configuration setting into a tree node with detailed
+      # information.
+      #
+      # This method transforms a given configuration setting into a
+      # hierarchical representation, including its name, description, and
+      # various metadata such as environment variable name, prefix, default
+      # value, and configuration status.
+      #
+      # @param setting [ConstConf::Setting] the configuration setting to convert
+      #
+      # @return [ConstConf::Tree] a tree node representing the configuration setting
+      def convert_setting(setting)
+        desc = "#{setting.description.full? { italic(' # %s' % it) }}"
+        obj  = new("#{bold(setting.name)}#{desc}")
+
+        length = (Tins::Terminal.columns / 4).clamp(20..)
+        truncater = -> v { v&.to_s&.truncate_bytes(length) }
+
+        censored = -> s { s.sensitive? ? Tins::NullPlus.new(inspect: '🤫') : s }
+
+        checker = -> r {
+          case r
+          when false, nil
+            '❌'
+          when :unchecked_true
+            '☑️ '
+          else
+            '✅'
+          end
+        }
+
+        setting_info = <<~EOT
+          prefix          #{setting.prefix.inspect}
+          env var name    #{setting.env_var_name}
+          env var (orig.) #{truncater.(censored.(setting).env_var.inspect)}
+          default         #{truncater.(censored.(setting).default_value.inspect)}
+          value           #{truncater.(censored.(setting).value.inspect)}
+          sensitive       #{setting.sensitive? ? '🔒' : '⚪'}
+          required        #{setting.required? ? '🔴' : '⚪'}
+          configured      #{setting.configured? ? '🔧' : '⚪' }
+          ignored         #{setting.ignored? ? '🙈' : '⚪'}
+          active          #{setting.active? ? '🟢' : '⚪'}
+          decoding        #{setting.decoding? ? '⚙️' : '⚪'}
+          checked         #{checker.(setting.checked?)}
+        EOT
+
+        setting_info.each_line do |line|
+          obj << new(line.chomp)
+        end
+
+        obj
+      end
+    end
+
+    # Initializes a new tree node with the given name, and UTF-8 support
+    # flag.
+    #
+    # @param name [ String ] the name of the tree node
+    # @param utf8 [ Boolean ] flag indicating whether UTF-8 characters should
+    # be used for display
+    def initialize(name, utf8: default_utf8)
+      @name     = name
+      @utf8     = utf8
+      @children = []
+    end
+
+    # Checks whether UTF-8 encoding is indicated in the LANG environment
+    # variable.
+    #
+    # This method examines the LANG environment variable to determine if it
+    # contains a UTF-8 encoding indicator, returning true if UTF-8 is detected
+    # and false otherwise.
+    #
+    # @return [Boolean] true if the LANG environment variable indicates UTF-8
+    # encoding, false otherwise
+    def default_utf8
+      !!(ENV['LANG'] =~ /utf-8\z/i)
+    end
+
+    # Adds a child node to this tree node's collection of children.
+    #
+    # @param child [ ConstConf::Tree ] the child tree node to be added
+    #
+    # @return [ Array<ConstConf::Tree> ] the updated array of child nodes
+    def <<(child)
+      @children << child
+    end
+
+    # Returns an enumerator that yields the tree node's name,
+    # followed by its children in a hierarchical format.
+    #
+    # @return [Enumerator] an enumerator that provides the tree structure
+    #   as a sequence of strings representing nodes and their relationships
+    def to_enum
+      Enumerator.new do |y|
+        y.yield @name
+
+        @children.each_with_index do |child, child_index|
+          children_enum = child.to_enum
+          if child_index < @children.size - 1
+            children_enum.each_with_index do |setting, i|
+              y.yield "#{inner_child_prefix(i)}#{setting}"
+            end
+          else
+            children_enum.each_with_index do |setting, i|
+              y.yield "#{last_child_prefix(i)}#{setting}"
+            end
+          end
+        end
+      end
+    end
+
+    # Converts the tree node into an array representation.
+    #
+    # @return [Array<String>] an array containing the string representations of
+    # the tree node and its children
+    def to_ary
+      to_enum.to_a
+    end
+
+    alias to_a to_ary
+
+    # Returns the string representation of the tree structure.
+    #
+    # This method converts the tree node and its children into a formatted
+    # string, where each node is represented on its own line with appropriate
+    # indentation to show the hierarchical relationship between nodes.
+    #
+    # @return [String] a multi-line string representation of the tree structure
+    def to_s
+      to_ary * ?\n
+    end
+
+    private
+
+    # Returns the appropriate prefix string for a child node in a tree display.
+    #
+    # This method determines the correct visual prefix to use when rendering
+    # tree nodes, based on whether UTF-8 encoding is enabled and if the current
+    # child is the first one in a group of siblings.
+    #
+    # @param i [ Integer ] the index of the child node in its parent's children list
+    # @return [ String ] the visual prefix string for the child node
+    def inner_child_prefix(i)
+      if @utf8
+        i.zero? ? "├─ " : "│  "
+      else
+        i.zero? ? "+- " : "|  "
+      end
+    end
+
+    # Returns the appropriate prefix string for the last child node in a tree
+    # display.
+    #
+    # This method determines the correct visual prefix to use when rendering
+    # the final child node in a hierarchical tree structure, based on whether
+    # UTF-8 encoding is enabled and if the current child is the first one in a
+    # group of siblings.
+    #
+    # @param i [Integer] the index of the child node in its parent's children list
+    # @return [String] the visual prefix string for the last child node
+    def last_child_prefix(i)
+      if @utf8
+        i.zero? ? "└─ " : "   "
+      else
+        i.zero? ? "`- " : "   "
+      end
+    end
+  end
+end

data/lib/const_conf/version.rb

@@ -0,0 +1,8 @@
+module ConstConf
+  # ConstConf version
+  VERSION         = '0.0.0'
+  VERSION_ARRAY   = VERSION.split('.').map(&:to_i) # :nodoc:
+  VERSION_MAJOR   = VERSION_ARRAY[0] # :nodoc:
+  VERSION_MINOR   = VERSION_ARRAY[1] # :nodoc:
+  VERSION_BUILD   = VERSION_ARRAY[2] # :nodoc:
+end

data/lib/const_conf/yaml_plugin.rb

@@ -0,0 +1,30 @@
+require 'complex_config'
+
+module ConstConf::YAMLPlugin
+  include ComplexConfig::Provider::Shortcuts
+
+  def yaml(path, required: false, env: false)
+    if File.exist?(path)
+      ConstConf.monitor.synchronize do
+        config_dir = File.dirname(path)
+        ComplexConfig::Provider.config_dir = config_dir
+        ext        = File.extname(path)
+        name       = File.basename(path, ext)
+        if env
+          env == true and env = ENV['RAILS_ENV']
+          if env
+            complex_config_with_env(name, env)
+          else
+            raise ConstConf::RequiredValueNotConfigured,
+              "need an environment string specified, via env var RAILS_ENV or manually"
+          end
+        else
+          complex_config(name)
+        end
+      end
+    elsif required
+      raise ConstConf::RequiredValueNotConfigured,
+        "YAML file required at path #{path.to_s.inspect}"
+    end
+  end
+end

data/lib/const_conf.rb

@@ -0,0 +1,401 @@
+require 'tins/xt'
+require 'rails'
+
+# A configuration management module that provides environment variable-based
+# settings with validation and thread-safe operations.
+#
+# ConstConf enables defining configuration settings through environment
+# variables, including support for default values, required validation,
+# decoding logic, and descriptive metadata. It offers thread-safe registration
+# and retrieval of configuration values while providing integration with Rails
+# application initialization cycles.
+module ConstConf
+end
+require 'const_conf/setting_accessor'
+require 'const_conf/errors'
+require 'const_conf/setting'
+require 'const_conf/file_plugin'
+require 'const_conf/dir_plugin'
+require 'const_conf/json_plugin'
+require 'const_conf/yaml_plugin'
+require 'const_conf/env_dir_extension'
+require 'const_conf/tree'
+require 'const_conf/railtie'
+
+module ConstConf
+  include ConstConf::Errors
+
+  class << self
+    # Returns the monitor instance for thread synchronization.
+    #
+    # This method provides a singleton Monitor instance that can be used to
+    # synchronize access to shared resources across threads. It ensures that
+    # only one thread can execute critical sections of code at a time.
+    #
+    # @return [Monitor] the singleton Monitor instance used for thread synchronization
+    def monitor
+      @monitor ||= Monitor.new
+    end
+
+    # The module_files accessor provides read and write access to the
+    # module_files instance variable.
+    #
+    # This method serves as a getter and setter for the module_files attribute,
+    # which stores a hash mapping modules to their corresponding file paths.
+    #
+    # @return [Hash, nil] the current value of the module_files instance variable
+    attr_accessor :module_files
+
+    # Registers a module-file mapping in the global registry.
+    #
+    # This method associates a module with its corresponding file path in the
+    # global module_files hash. The registration is performed in a thread-safe
+    # manner using the monitor for synchronization.
+    #
+    # @param configuration [ Module ] the module to register
+    # @param file [ String ] the file path associated with the module
+    def register(configuration, file)
+      monitor.synchronize do
+        module_files[configuration] ||= file
+      end
+    end
+
+    # Destroys all registered configuration modules and returns their file
+    # paths.
+    #
+    # This method synchronizes access to the global configuration registry and
+    # removes all registered modules from their respective parent namespaces.
+    # It collects the file paths associated with each module before removing
+    # them, returning an array of the collected file paths.
+    #
+    # @return [Array<String>] an array containing the file paths of the destroyed modules
+    def destroy
+      monitor.synchronize do
+        files = []
+        while pair = ConstConf.module_files.shift
+          modul, file = pair
+          if modul.module_parent.const_defined?(modul.name)
+            modul.module_parent.send(:remove_const, modul.name)
+          end
+          files << file
+        end
+        files
+      end
+    end
+
+    # Reloads all registered configuration modules by destroying them and
+    # re-loading their associated files.
+    #
+    # This method ensures that all configuration modules currently registered
+    # with ConstConf are destroyed and then reloaded from their respective
+    # files. It performs this operation in a thread-safe manner using the
+    # monitor for synchronization.
+    def reload
+      monitor.synchronize { destroy.each { load it } }
+      nil
+    end
+  end
+  self.module_files = {}
+
+  extend ActiveSupport::Concern
+
+  class_methods do
+    extend ConstConf::SettingAccessor
+
+    # The plugin method includes a module into the ConstConf::Setting class.
+    #
+    # This method allows for extending the functionality of configuration
+    # settings by including additional modules that provide extra behavior or
+    # methods. It is typically used to add custom validation, encoding, or
+    # other capabilities to settings defined within the ConstConf system.
+    #
+    # @param plugin [ Module ] the module to be included in ConstConf::Setting
+    #
+    # @return [ Class ] returns the current class (self) to allow for method chaining
+    def plugin(plugin)
+      ConstConf::Setting.class_eval { include plugin }
+      self
+    end
+
+    # Handles the addition of constants to a module, configuring them as
+    # settings when appropriate.
+    #
+    # This method is invoked automatically when a constant is added to a module
+    # that includes ConstConf. It processes the constant by checking if it's a
+    # Module and including ConstConf in it. If there's a pending configuration
+    # block for the constant, it creates a Setting instance, registers it, and
+    # sets the constant's value accordingly. It also defines helper methods to
+    # query the setting and its configuration status.
+    #
+    # @param id [ Symbol ] the name of the constant being added
+    def const_added(id)
+      if const = const_get(id) and const.is_a?(Module)
+        const.class_eval do
+          include ConstConf
+        end
+        prefix = [ self, *module_parents ].find {
+          !it.prefix.nil? and break it.prefix
+        }
+        const.prefix [ prefix, const.name.sub(/.*::/, '') ].select(&:present?) * ?_
+      end
+      ConstConf.monitor.synchronize do
+        if setting_block = last_setting
+          self.last_setting = nil
+          remove_const(id)
+          prefix = [ self, *module_parents ].find {
+            !it.prefix.nil? and break it.prefix
+          }
+          setting = Setting.new(name: [ name, id ], prefix:, &setting_block)
+          if previous_setting = outer_configuration.setting_for(setting.env_var_name)
+            raise ConstConf::SettingAlreadyDefined,
+              "setting for env var #{setting.env_var_name} already defined in #{previous_setting.name}"
+          end
+          settings[setting.env_var_name] = setting
+          const_set id, setting.value
+          my_configuration = self
+          singleton_class.class_eval {
+            define_method("#{id}!") { setting }
+            my_configuration.send("#{id}!")
+            define_method("#{id}?") { (setting.value if setting.active?) }
+            my_configuration.send("#{id}?")
+          }
+          setting.confirm!
+        end
+      end
+      super if defined? super
+    end
+
+    # Sets or retrieves the description for a ConstConf module.
+    #
+    # This method provides access to the description attribute of a
+    # configuration setting, which can be used to document the purpose and
+    # usage of the module or nested module.
+    #
+    # @return [String, nil] the current description value
+    setting_accessor :description
+
+    # Declares a thread-local variable named last_setting.
+    #
+    # This method sets up a thread-local variable that can be used to store
+    # temporary state within the current thread. It is typically used to
+    # hold transient data that should not persist across threads.
+    #
+    # @param name [Symbol] the name of the thread-local variable to declare
+    # @return [Object]
+    thread_local :last_setting
+
+    # Returns the settings hash for the configuration module.
+    #
+    # This method provides access to the internal hash that stores all configuration
+    # settings defined within the module. It ensures the hash is initialized before
+    # returning it, guaranteeing that subsequent accesses will return the same hash
+    # instance.
+    #
+    # @return [Hash<String, ConstConf::Setting>] the hash containing all settings
+    #   for this configuration module, keyed by their environment variable names
+    def settings
+      @settings ||= {}
+    end
+
+    # The prefix reader accessor returns the configured prefix for the setting.
+    #
+    # @return [String, nil] the prefix value, or nil if not set
+    setting_accessor(
+      :prefix,
+      transform: -> value { value.ask_and_send_or_self(:upcase) }
+    ) do
+      if module_parent == Object
+        name.underscore.upcase
+      end
+    end
+
+    # Sets the configuration block for the next constant definition.
+    #
+    # @param block [Proc] the configuration block to be stored
+    # @return [nil] always returns nil
+    def set(&block)
+      if module_parent == Object and
+          file = caller_locations.first.absolute_path and
+          File.exist?(file)
+        then
+        ConstConf.register self, file
+      end
+      self.last_setting = block
+      nil
+    end
+
+    # Finds the outer configuration module in the hierarchy.
+    #
+    # This method traverses up the module inheritance chain from the current
+    # module, examining each module in reverse order of its parents, until it
+    # finds a module that includes the ConstConf concern. This is useful for
+    # identifying the top-level configuration module that contains the current
+    # one.
+    #
+    # @return [ Module, nil ] the outer configuration module if found, or nil if none exists
+    def outer_configuration
+      [ self, *module_parents ].reverse_each.find { it < ConstConf }
+    end
+
+    # Returns an array containing all nested configuration modules recursively,
+    # including itself.
+    #
+    # This method collects all configuration modules within the current module
+    # and its hierarchy, returning them as an array. It utilizes the
+    # each_nested_configuration iterator to traverse the module structure and
+    # accumulate each configuration module into a result array.
+    #
+    # @return [Array<Module>] an array of all nested configuration modules
+    #   found within the current module's hierarchy
+    def all_configurations
+      each_nested_configuration.reduce([]) { |array, configuration|
+        array << configuration
+      }
+    end
+
+    # Returns an array of the directly nested configuration modules that
+    # include ConstConf.
+    #
+    # This method iterates through all constants defined in the current module,
+    # identifies those that are modules and inherit from ConstConf, and returns
+    # them as an array. It filters out any non-module constants or modules that
+    # do not include the ConstConf concern.
+    #
+    # @return [ Array<Module> ] an array containing nested configuration
+    # modules that inherit from ConstConf
+    def nested_configurations
+      constants.map { |c|
+        begin
+          m = const_get(c)
+        rescue NameError
+          next
+        end
+        m.is_a?(Module) or next
+        m < ConstConf or next
+        m
+      }.compact
+    end
+
+    # Finds a configuration setting by its environment variable name across
+    # nested modules.
+    #
+    # This method searches through the specified modules and their nested
+    # modules to locate a configuration setting that matches the given
+    # environment variable name. It iterates through the module hierarchy to
+    # find the setting, checking each module's settings hash for a match.
+    #
+    # @param name [ String, Symbol ] the environment variable name to search for
+    # @param modules [ Array<Module> ] the array of modules to search within, defaults to [ self ]
+    #
+    # @return [ ConstConf::Setting, nil ] the matching setting object if found, or nil if not found
+    def setting_for(name)
+      name = name.to_s
+      each_nested_configuration do |modul,|
+        modul.settings.each { |env_var_name, setting|
+          env_var_name == name and return setting
+        }
+      end
+      nil
+    end
+
+    # Returns an array of all environment variable names used in the
+    # configuration.
+    #
+    # This method collects all the environment variable names from the settings
+    # defined within the current module and its nested modules. It traverses
+    # the module hierarchy to gather these names, ensuring that each setting's
+    # environment variable name is included in the final result.
+    #
+    # @return [Array<String>] an array containing all the environment variable names
+    #   used in the configuration settings across the module and its nested modules
+    def env_var_names
+      names = Set[]
+      each_nested_configuration do |modul,|
+        names.merge(Array(modul.settings.keys))
+      end
+      names.to_a
+    end
+
+    # Returns a hash containing all environment variable values for the
+    # configuration settings.
+    #
+    # This method collects all the environment variable names from the settings
+    # defined within the current module and its nested modules, then retrieves
+    # the effective value for each setting. The result is a hash where keys are
+    # environment variable names and values are their corresponding
+    # configuration values.
+    #
+    # @return [ Hash<String, Object> ] a hash mapping environment variable names to their values
+    def env_vars
+      env_var_names.each_with_object({}) do |n, hash|
+        hash[n] = setting_value_for(n)
+      end
+    end
+
+    # Retrieves the effective value for a configuration setting identified by its
+    # environment variable name.
+    #
+    # This method looks up a configuration setting using the provided environment
+    # variable name and returns its effective value, which is determined by
+    # checking the environment variable and falling back to the default value if
+    # not set.
+    #
+    # @param name [String, Symbol] the environment variable name used to identify the setting
+    #
+    # @return [Object] the effective configuration value for the specified setting,
+    #   or the default value if the environment variable is not set
+    def setting_value_for(name)
+      setting = setting_for(name)
+      setting&.value
+    end
+    alias [] setting_value_for
+
+    # Displays a textual representation of a configuration object or setting.
+    #
+    # This method generates a formatted tree-like view of either a ConstConf
+    # module or a specific setting, including metadata such as names,
+    # descriptions, environment variable names, and configuration status. The
+    # output can be directed to a specified IO object or displayed to the
+    # standard output.
+    #
+    # @param object [Object] the ConstConf module or setting to display
+    # @param io [IO, nil] the IO object to write the output to; if nil, uses STDOUT
+    def view(object: self, io: nil)
+      output = ConstConf::Tree.from_const_conf(object).to_a
+      if io
+        io.puts output
+      elsif output.size < Tins::Terminal.lines
+        STDOUT.puts output
+      else
+        IO.popen(ENV.fetch('PAGER', 'less -r'), ?w) do |f|
+          f.puts output
+          f.close_write
+        end
+      end
+    end
+
+    # Iterates over a configuration module and its nested configurations in a
+    # depth-first manner.
+    #
+    # This method yields each configuration module, including the receiver and all nested modules,
+    # in a depth-first traversal order. It is used internally to process all configuration
+    # settings across a module hierarchy.
+    #
+    # @yield [ configuration ] yields each configuration module in the hierarchy
+    # @yieldparam configuration [ Module ] a configuration module from the hierarchy
+    #
+    # @return [ Enumerator ] returns an enumerator if no block is given,
+    # otherwise nil.
+    def each_nested_configuration(&block)
+      return enum_for(:each_nested_configuration) unless block_given?
+      configuration_modules = [ self ]
+      while configuration = configuration_modules.shift
+        yield configuration
+        configuration.nested_configurations.each do
+          configuration_modules.member?(it) and next
+          configuration_modules << it
+        end
+      end
+    end
+  end
+end