class_composer 1.0.2 → 2.1.0

data/docs/freezing.md

@@ -0,0 +1,58 @@
+# Freezing ClassComposer
+
+`ClassComposer` provides a simple way to freeze instances of its classes. Freezing can help ensure that configurations do not change during the life of the script or application.
+
+Different behaviors are available when a user attempts to change a composed item after the instance has been frozen
+
+## Allowed Options:
+### Behavior:
+- Required: When `&block` is nil, behavior is required
+- Description: The behavior ClassComposer should enact when a composed item tries to get changed
+- Type: Symbol [:raise, :log_and_allow, :log_and_skip]
+
+### Children:
+- Required: false
+- Description: Any ClassComposed item that includes `ClassComposer::Generator` is considered a nested Child. When option set to true, We will iterate the tree and set all child instances to the same behavior as the parent. One stop shop to freeze all nested configuration
+- Type: Boolean
+
+### Block
+- Required: When `behavior` is nil, block is required
+- Description: Custom behavior tailored to your use case. For example, In test, maybe you raise, but production maybe you allow
+- Type: Passed in block, Return `true` to allow the variable to get set. Return `false` to not allow the variable to get set
+
+
+```ruby
+MyCoolEngine.config.class_composer_freeze_objects!(children: true) do |instance, key|
+  if Rails.staging?
+    # allow the variable to get set in staging
+    Rails.logger("Yikes! you are changing a config variable after boot. We will honor this")
+    true
+  elsif Rails.prod?
+    # disallow the variable to get set in prod
+    Rails.logger("Yikes! you are changing a config variable after boot. We will NOT honor this")
+    false
+  else
+    raise Error, "Cant change value on #{instance.class} for key. Please change"
+  end
+end
+```
+
+## Usage
+
+### Rails Engine
+When building out a complex nested configuration structure for a Rails Engine, you may want to ensure changes to the configuration do not occur after the Rails App runs its initializers. As example code, this can get added to your `*engine.rb` file
+
+```ruby
+# MyCoolEngine.config is the location of the config instance
+# Assign Defaults must get run first otherwise Lazily loaded objects will run into failure
+
+# Run after Rails loads the initializes and environment files
+# Ensures User has already set their desired config before we lock this down
+initializer "my_cool_engine.config.instantiate", after: :load_config_initializers do |_app|
+  # ensure defaults are instantiated and all variables are assigned
+  MyCoolEngine.config.class_composer_assign_defaults!(children: true)
+
+  # Now that we can confirm all variables are defined, freeze all objects an their children
+  MyCoolEngine.config.class_composer_freeze_objects!(behavior: :raise, children: true)
+end
+```

data/docs/generating_initializer.md

@@ -0,0 +1,74 @@
+# Generating Initializer
+
+Generating an initializer can help ensure that all users understand all potential configuration options without searching the codebase.
+
+This generation will add both [Basic Composer Options](basic_composer.md) and [Composer Blocking Options](composer_blocking.md) to a configuration file.
+
+The file output will show show assignment to all default values. Additionally all lines are commented out so the User can
+
+
+```ruby
+class LoginStrategy
+  include ClassComposer::Generator
+
+  add_composer :password_regex, allowed: Regexp, default: /\A\w{6,20}\z/, desc: "Password must include valid characters between 6 and 20 in length"
+
+  add_composer :username_length, allowed: Integer, default: 10
+
+  add_composer :type, allowed: String, default: "plain_text"
+end
+
+class LockableStrategy
+  include ClassComposer::Generator
+
+  add_composer :enable, default: false, allowed: [TrueClass, FalseClass], desc: "By default Lockable Strategy is disabled."
+  add_composer :password_attempts, default: 10, allowed: Integer, desc: "Max password attempts before the account is locked"
+end
+
+class AppConfiguration
+  include ClassComposer::Generator
+
+  add_composer :login, allowed: LoginStrategy, default: LoginStrategy.new, desc: "Login Strategy for my Application"
+
+  add_composer_blocking :lockable, composer_class: LockableStrategy, enable_attr: :enable, desc: "Lock Strategy for my Application. By default this is disabled"
+end
+
+puts AppConfiguration.composer_generate_config(wrapping: "MyApplication.configure")
+
+----
+
+=begin
+This configuration files lists all the configuration options available.
+To change the default value, uncomment the line and change the value.
+Please take note: Values set as `=` to a config variable are the current default values when none is assigned
+=end
+
+MyApplication.configure do |config|
+  # ### Block to configure Login ###
+  # Login Strategy for my Application
+  # config.with_login do |login_config|
+    # Password must include valid characters between 6 and 20 in length: [Regexp]
+    # login_config.password_regex = (?-mix:\A\w{6,20}\z)
+
+    # login_config.username_length = 10
+
+    # login_config.type = "plain_text"
+  # end
+
+  # ### Block to configure Lockable ###
+  # Lock Strategy for my Application. By default this is disabled
+  # When using the block, the enable flag will automatically get set to true
+  # config.with_lockable do |lockable_config|
+    # By default Lockable Strategy is disabled.: [TrueClass, FalseClass]
+    # lockable_config.enable = false
+
+    # Max password attempts before the account is locked: [Integer]
+    # lockable_config.password_attempts = 10
+  # end
+end
+```
+
+## Usage Applications
+### Rails Generator
+Are you building an Engine or a Gem that requires custom configuration. This code can easily help downstream users understand exactly what options are available to them to configure your Engine/Gem.
+

data/lib/class_composer/generate_config.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+module ClassComposer
+  class GenerateConfig
+    attr_reader :instance
+    NOTICE = <<~HEREDOC
+    =begin
+    This configuration files lists all the configuration options available.
+    To change the default value, uncomment the line and change the value.
+    Please take note: Values set as `=` to a config variable are the current default values when none is assigned
+    =end
+    HEREDOC
+
+    def initialize(instance:)
+      raise ArgumentError, ":instance class (#{instance}) must include ClassComposer::Generator. It does not" unless instance.include?(ClassComposer::Generator)
+
+      @instance = instance
+    end
+
+    def execute(wrapping:, require_file:, space_count: 1, config_name: "config")
+      mapping = instance.composer_mapping
+      generated_config = generate(mapping:, space_count:, demeters_deep:[config_name])
+
+      stringified = ""
+      stringified += "require \"#{require_file}\"\n\n" if require_file
+      stringified += NOTICE
+      stringified += "\n"
+      stringified += "#{wrapping} do |#{config_name}|\n"
+      flattened_config = generated_config.flatten(1).map { _1.join(" ") }
+      flattened_config.pop if flattened_config[-1] == ""
+
+      stringified += flattened_config.join("\n")
+      stringified += "\nend"
+      stringified
+    end
+
+    private
+
+    def generate(mapping:, space_count:, demeters_deep:)
+      mapping.map do |key, metadata|
+        if blocking_attributes = metadata[:blocking_attributes]
+          if children = metadata[:children]
+            do_block = "#{key}_config"
+            blocking(key:, do_block:, metadata:, space_count:, demeters_deep:, blocking_attributes:) do
+              generate(mapping: children.first, space_count: space_count + 2, demeters_deep: [do_block])
+            end
+          else
+            []
+          end
+        elsif children = metadata[:children]
+          config_prepend = demeters_deep + [key]
+          children_config = []
+          if desc = metadata[:desc]
+            children_config << spec_child_description(space_count:, desc:, key:)
+          end
+
+          children.each do |child|
+            children_config += generate(mapping: child, space_count:, demeters_deep: config_prepend)
+          end
+
+          children_config.flatten(1)
+        else
+          spec(key:, metadata:, space_count:, demeters_deep:)
+        end
+      end
+    end
+
+    def spec_child_description(space_count:, desc:, key:)
+      base = "#########"
+      length = base.length * 2 + 4 + key.capitalize.length
+
+      [
+        [prepending(space_count),"#" * length],
+        [prepending(space_count),"##{" " * (length - 2)}#" ],
+        [prepending(space_count), "#{base}  #{key.capitalize}  #{base}"],
+        [prepending(space_count),"##{" " * (length - 2)}#" ],
+        [prepending(space_count),"#" * length],
+        [prepending(space_count), "## #{desc}"],
+        [],
+      ]
+    end
+
+    def blocking(key:, do_block:, metadata:, space_count:, demeters_deep:, blocking_attributes:)
+      config = concat_demeter_with_key(blocking_attributes[:block_name], demeters_deep)
+      values = [
+        [prepending(space_count), "### Block to configure #{key.to_s.split("_").map {_1.capitalize}.join(" ")} ###"],
+        [prepending(space_count), metadata[:desc]],
+      ]
+      values << [prepending(space_count), "When using the block, the #{blocking_attributes[:enable_attr]} flag will automatically get set to true"] if blocking_attributes[:enable_attr]
+      values << [prepending(space_count), config, "do", "|#{do_block}|"]
+
+      values += yield.flatten(1)
+      values.pop if values[-1] == [""]
+      values << [prepending(space_count), "end"]
+
+      values << [""]
+    end
+
+    def spec(key:, metadata:, space_count:, demeters_deep:)
+      config = concat_demeter_with_key(key, demeters_deep)
+
+      if metadata[:default_shown]
+         default = metadata[:default_shown]
+      elsif metadata[:dynamic_default]
+        if Symbol === metadata[:dynamic_default]
+          default = concat_demeter_with_key(metadata[:dynamic_default], demeters_deep)
+        else
+          default = " # Proc provided for :dynamic_default parameter. :default_shown parameter not provided"
+        end
+      elsif metadata[:allowed].include?(String)
+        default = "\"#{metadata[:default]}\""
+      else
+        default = custom_case(metadata[:default])
+      end
+      arr = []
+
+      arr << [prepending(space_count), "#{metadata[:desc]}: #{(metadata[:allowed] - [ClassComposer::DefaultObject])}"] if metadata[:desc]
+      arr <<[prepending(space_count), config, "=", default]
+      arr << [""]
+
+      arr
+    end
+
+    def custom_case(default)
+      case default
+      when Symbol
+        default.inspect
+      when (ActiveSupport::Duration rescue NilClass)
+        default.inspect.gsub(" ", ".")
+      else
+        default
+      end
+    end
+
+    def prepending(space_count)
+      "#{" " * space_count}#"
+    end
+
+    def concat_demeter_with_key(key, demeters_deep)
+      (demeters_deep + ["#{key}"]).join(".")
+    end
+  end
+end

data/lib/class_composer/generator/class_methods.rb

@@ -0,0 +1,233 @@
+# frozen_string_literal: true
+
+module ClassComposer
+  module Generator
+    module ClassMethods
+      COMPOSER_VALIDATE_METHOD_NAME = ->(name) { :"__composer_#{name}_is_valid__?" }
+      COMPOSER_ASSIGNED_ATTR_NAME = ->(name) { :"@__composer_#{name}_value_assigned__" }
+      COMPOSER_ASSIGNED_ARRAY_METHODS = ->(name) { :"@__composer_#{name}_array_methods_set__" }
+      COMPOSER_ALLOWED_FROZEN_TYPE_ARGS = [:raise, :log]
+
+      def add_composer_blocking(name, composer_class:, desc: nil, block_prepend: "with", enable_attr: nil)
+        unless composer_class.include?(ClassComposer::Generator)
+          raise ClassComposer::Error, ".add_composer_blocking passed `composer_class:` that does not include ClassComposer::Generator. Passed argument must include ClassComposer::Generator"
+        end
+
+        blocking_name = "#{block_prepend}_#{name}"
+        blocking_attributes = { block_name: blocking_name, enable_attr: enable_attr }
+        add_composer(name, allowed: composer_class, default: composer_class.new, desc: desc, blocking_attributes: blocking_attributes)
+
+        define_method(blocking_name) do |&blk|
+          instance = public_send(:"#{name}")
+          instance.public_send(:"#{enable_attr}=", true) if enable_attr
+
+          blk.(instance) if blk
+
+          method(:"#{name}=").call(instance)
+        end
+
+        if enable_attr
+          define_method("#{name}?") do
+            public_send(:"#{name}").public_send(enable_attr)
+          end
+        end
+      end
+
+      def add_composer(name, allowed:, desc: nil, validator: ->(_) { true }, validation_error_klass: ::ClassComposer::ValidatorError, error_klass: ::ClassComposer::Error, blocking_attributes: nil, default_shown: nil, **params, &blk)
+        default =
+          if params.has_key?(:default)
+            params[:default]
+          else
+            ClassComposer::DefaultObject
+          end
+
+        if params[:default] && params[:dynamic_default]
+          raise Error, "Composer :#{name} had both the `:default` and `:dynamic_default` assigned. Only one allowed"
+        end
+
+        if dynamic_default = params[:dynamic_default]
+          if ![Proc, Symbol].include?(dynamic_default.class)
+            raise Error, "Composer :#{name} defined `:dynamic_default: #{dynamic_default}`. Expected value to be a Symbol mapped to a composer element or a Proc"
+          end
+
+          if Symbol === dynamic_default && composer_mapping[dynamic_default].nil?
+            raise Error, "Composer :#{name} defined `dynamic_default: #{dynamic_default}`. #{dynamic_default} is not defined. Please ensure that all dynamic_default's are defined before setting them"
+          end
+        end
+
+        if allowed.is_a?(Array)
+          allowed << ClassComposer::DefaultObject
+        else
+          allowed = [allowed, ClassComposer::DefaultObject]
+        end
+
+        if allowed.select { _1.include?(ClassComposer::Generator) }.count > 1
+          raise Error, "Allowed arguments has multiple classes that include ClassComposer::Generator. Max 1 is allowed"
+        end
+
+        validate_proc = __composer_validator_proc__(validator: validator, allowed: allowed, name: name, error_klass: error_klass)
+        __composer_validate_options__!(name: name, validate_proc: validate_proc, default: default, validation_error_klass: validation_error_klass, error_klass: error_klass)
+
+        array_proc = __composer_array_proc__(name: name, validator: validator, allowed: allowed, params: params)
+        __composer_assignment__(name: name, allowed: allowed, params: params, validator: validate_proc, array_proc: array_proc, validation_error_klass: validation_error_klass, error_klass: error_klass, &blk)
+        __composer_retrieval__(name: name, allowed: allowed, default: default, array_proc: array_proc, params: params, validator: validate_proc, validation_error_klass: validation_error_klass)
+
+        # Add to mapping
+        __add_to_composer_mapping__(name: name, default: default, allowed: allowed, desc: desc, blocking_attributes: blocking_attributes, default_shown: default_shown, dynamic_default: params[:dynamic_default])
+      end
+
+      def composer_mapping
+        @composer_mapping ||= {}
+      end
+
+      def composer_generate_config(wrapping:, require_file: nil, space_count: 2)
+        @composer_generate_config ||= GenerateConfig.new(instance: self)
+
+        @composer_generate_config.execute(wrapping:, require_file:, space_count:)
+      end
+
+      def __add_to_composer_mapping__(name:, default:, allowed:, desc:, blocking_attributes:, default_shown: nil, dynamic_default: nil)
+        children = Array(allowed).select { _1.include?(ClassComposer::Generator) }.map do |allowed_class|
+          allowed_class.composer_mapping
+        end
+
+        composer_mapping[name] = {
+          desc: desc,
+          children: children.empty? ? nil : children,
+          dynamic_default: dynamic_default,
+          default_shown: default_shown,
+          default: (default.to_s.start_with?("#<") ? default.class : default),
+          blocking_attributes: blocking_attributes,
+          allowed: allowed,
+        }.compact
+      end
+
+      def __composer_validate_options__!(name:, validate_proc:, default:, params: {}, validation_error_klass:, error_klass:)
+        unless validate_proc.(default)
+          raise validation_error_klass, "Default value [#{default}] for #{self.class}.#{name} is not valid"
+        end
+
+        if instance_methods.include?(name.to_sym)
+          raise error_klass, "[#{name}] is already defined. Ensure composer names are all uniq and do not class with class instance methods"
+        end
+      end
+
+      def __composer_array_proc__(name:, validator:, allowed:, params:)
+        Proc.new do |value, _itself|
+          _itself.send(:"#{name}=", value)
+        end
+      end
+
+      # create assignment method for the incoming name
+      def __composer_assignment__(name:, params:, allowed:, validator:, array_proc:, validation_error_klass:, error_klass:, &blk)
+        define_method(:"#{name}=") do |value|
+          case class_composer_frozen!(name)
+          when false
+            # false is returned when the instance is frozen AND we do not allow the operation to proceed
+            return
+          when true
+            # true is returned when the instance is frozen AND we allow the operation to proceed
+          when nil
+            # nil is returned when the instance is not frozen
+          end
+
+          is_valid = self.class.__run_validation_item(name: name, validator: validator, allowed: allowed, value: value, params: params)
+
+          if is_valid[:valid]
+            instance_variable_set(COMPOSER_ASSIGNED_ATTR_NAME.(name), true)
+            instance_variable_set(:"@#{name}", value)
+          else
+            raise validation_error_klass, is_valid[:message].compact.join(" ")
+          end
+
+          if value.is_a?(Array) && !value.instance_variable_get(COMPOSER_ASSIGNED_ARRAY_METHODS.(name))
+            _itself = itself
+            value.define_singleton_method(:<<) do |val|
+              array_proc.(super(val), _itself)
+            end
+            value.instance_variable_set(COMPOSER_ASSIGNED_ARRAY_METHODS.(name), true)
+          end
+
+          if blk
+            yield(name, value)
+          end
+
+          value
+        end
+      end
+
+      def __run_validation_item(validator:, name:, value:, allowed:, params:)
+        if validator.(value)
+          return { valid: true }
+        end
+
+        message = ["#{self.class}.#{name} failed validation. #{name} is expected to be #{allowed}. Received [#{value}](#{value.class})"]
+        message << (params[:invalid_message].is_a?(Proc) ? params[:invalid_message].(value) : params[:invalid_message].to_s)
+
+        { valid: false, message: message }
+      end
+
+      # retrieve the value for the name -- Or return the default value
+      def __composer_retrieval__(name:, default:, array_proc:, allowed:, params:, validator:, validation_error_klass:)
+        define_method(:"#{name}") do
+          value = instance_variable_get(:"@#{name}")
+          return value if instance_variable_get(COMPOSER_ASSIGNED_ATTR_NAME.(name))
+
+          if dynamic_default = params[:dynamic_default]
+            if Proc === dynamic_default
+              value = dynamic_default.(self)
+            else
+              # We know the method exists because we already checked validity from within
+              # `compose_mapping` on add_composer creation
+              value = method(:"#{dynamic_default}").()
+            end
+            is_valid = self.class.__run_validation_item(name: name, validator: validator, allowed: allowed, value: value, params: params)
+
+            if is_valid[:valid]
+              instance_variable_set(COMPOSER_ASSIGNED_ATTR_NAME.(name), true)
+              instance_variable_set(:"@#{name}", value)
+            else
+              raise validation_error_klass, is_valid[:message].compact.join(" ")
+            end
+
+            return value
+          end
+
+          if default.is_a?(Array) && !default.instance_variable_get(COMPOSER_ASSIGNED_ARRAY_METHODS.(name))
+            _itself = itself
+            default.define_singleton_method(:<<) do |value|
+              array_proc.(super(value), _itself)
+            end
+            default.instance_variable_set(COMPOSER_ASSIGNED_ARRAY_METHODS.(name), true)
+          end
+
+          default == ClassComposer::DefaultObject ? ClassComposer::DefaultObject.value : default
+        end
+      end
+
+      # create validator method for incoming name
+      def __composer_validator_proc__(validator:, allowed:, name:, error_klass:)
+        if validator && !validator.is_a?(Proc)
+          raise error_klass, "Expected validator to be a Proc. Received [#{validator.class}]"
+        end
+
+        # Proc will validate the entire attribute -- Full assignment must occur before validate is called
+        Proc.new do |value|
+          begin
+            allow =
+              if allowed.is_a?(Array)
+                allowed.include?(value.class)
+              else
+                allowed == value.class
+              end
+            # order is important -- Do not run validator if it is the default object
+            # Default object will likely raise an error if there is a custom validator
+            (allowed.include?(ClassComposer::DefaultObject) && value == ClassComposer::DefaultObject) || (allow && validator.(value))
+          rescue StandardError => e
+            raise error_klass, "#{e} occurred during validation for value [#{value}]. Check custom validator for #{name}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/class_composer/generator/instance_methods.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module ClassComposer
+  module Generator
+    module InstanceMethods
+      def class_composer_frozen!(key)
+        # when nil, we allow changes to the instance methods
+        return if @class_composer_frozen.nil?
+
+        # When frozen is a proc, we let the user decide how to handle
+        # The return value decides if the value can be changed or not
+        if Proc === @class_composer_frozen
+          return @class_composer_frozen.(self, key)
+        end
+
+        msg = "#{self.class} instance methods are frozen. Attempted to change variable [#{key}]."
+        case @class_composer_frozen
+        when FROZEN_LOG_AND_ALLOW
+          msg += " This operation will proceed."
+          Kernel.warn(msg)
+          return true
+        when FROZEN_LOG_AND_SKIP
+          msg += " This operation will NOT proceed."
+          Kernel.warn(msg)
+          return false
+        when FROZEN_RAISE
+          raise Error, msg
+        end
+      end
+
+      def class_composer_assign_defaults!(children: false)
+        self.class.composer_mapping.each do |key, metadata|
+          assigned_value = method(:"#{key}").call
+          method(:"#{key}=").call(assigned_value)
+
+          if children && metadata[:children]
+            method(:"#{key}").call().class_composer_assign_defaults!(children: children)
+          end
+        end
+
+        nil
+      end
+
+      def class_composer_freeze_objects!(behavior: nil, children: false, &block)
+        if behavior && block
+          raise ArgumentError, "`behavior` and `block` can not both be present. Choose one"
+        end
+
+        if behavior.nil? && block.nil?
+          raise ArgumentError, "`behavior` or `block` must be present."
+        end
+
+        if block
+          @class_composer_frozen = block
+        else
+          if !FROZEN_TYPES.include?(behavior)
+            raise Error, "Unknown behavior [#{behavior}]. Expected one of #{FROZEN_TYPES}."
+          end
+          @class_composer_frozen = behavior
+        end
+
+        # If children is set, iterate the children, otherwise exit early
+        return if children == false
+
+        self.class.composer_mapping.each do |key, metadata|
+          next unless metadata[:children]
+
+          method(:"#{key}").call().class_composer_freeze_objects!(behavior:, children:, &block)
+        end
+      end
+    end
+  end
+end