class_composer 1.0.2 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7d53fe12431ff8f1dd4c42d7282d11a64637a0c3ab573e24a7d83443a8a9cac2
-  data.tar.gz: 0376e66b2fef6bc976289dd1f4e4517830dd0a63c0e12519730efc9786865c9f
+  metadata.gz: dd01814260b83eaa363cdbdff3d1f078ee85b7d6850841a847e7d89edcef6e29
+  data.tar.gz: 43d27db959b1dfdbd364cc1be9af76d0debe4786031822d290d7dac6292afefd
 SHA512:
-  metadata.gz: b08e706f2f55865e6d4fab779896450dab524b946412ee8e8be8a673b205a8f3ded0a438db6dbce53d8ebc06c6a88a2dc6cba5a4da3bd5e22a599a205ea9cc0f
-  data.tar.gz: bfa9491b16358fc59b221bd5ac847b861c52a6a5793dca4fc59c81a8ceef3e12c1d3148bd8679833e4c5a643e5738788a9647a1619f9aadc2171b9d497bd0f34
+  metadata.gz: 2802e0cae4ad7be7d5f866436250e24e89e5ef032d1196d0951b517e18de28b7db6473f757277f239519c167de6de3f15f10a19853fdef9818ae2e400e13e3af
+  data.tar.gz: 175613d8ea5f331652eabad44e6090fb16f50703dbcb099dfb72bf96a5a2cd564eb8b3c491ed411124e908adada075ec6603b6b85a41f64e9661195b665e9b00

data/.circleci/config.yml

@@ -10,10 +10,10 @@ workflows:
       - cst/enforce-gem-version-bump
       - cst/rspec-ruby:
           rspec-system-args: "SIMPLE_COV_RUN=true"
-          cc-report-collect-ruby: "2.7.5"
+          cc-report-collect-ruby: "3.3.5"
           matrix:
             parameters:
-              ruby-version: ["2.7.5" , "3.0.0", "3.0.3"]
+              ruby-version: ["3.1.5" , "3.2.4", "3.3.5"]
             alias: required-matrix-tests
           name: test-ruby<< matrix.ruby-version >>
       - cst/publish-gem:

data/.gitignore

@@ -7,6 +7,7 @@
 /spec/reports/
 /tmp/
 .DS_Store
+spec/examples.txt
 
 # rspec failure tracking
 .rspec_status

data/CHANGELOG.md

@@ -4,12 +4,26 @@
 
 **Major:** x - Major Releases with new features that constitute a breaking change
 
-**Minor:** x.x - Minor changes or features added which are backwords compatible
+**Minor:** x.x - Minor changes or features added which are backwards compatible
 
 **Patch:** x.x.x - Patch Updates
 
 # Release Notes
 
-|  Date | Version  | Description  |
-|---|---|---|
-| June 2022  | v1.0.0  | Initial launch of Composer
+## v2.0.0 (Nov 2024)
+- Minimum Ruby Version bumped to v3.1
+- Initializer File Generator
+  - Add(`desc:`) key to your configs and ClassComposer can create a Initializer for you with all options
+  - Automatically will track new options added
+- Options added:
+  - `desc:` -- Describe what the configuration is doing. Recommended but optional
+  - `default_shown:` With Config Initializer file Generation, you can add a custom value to display as the default (For example: Use this options with ENV variables or sensitive arguments)
+  - `&block`: Provide a block to the composer class method. This block gets executed on assignment after validation.
+- Methods Added:
+  - `add_composer_blocking`(Class): Recommended composer method to use when default is another ClassComposer included class (See Readme for more details)
+  - `class_composer_assign_defaults!` (Instance): Class Composer values are lazily loaded. This option allows you to load configured options by calling a method (See Readme for more details)
+  - `class_composer_freeze_objects!`(Instance): Call this instance method if you want to make the instance immutable to changes. Helpful to ensure all changes are made before the application code runs (See Readme for more details)
+  - `composer_generate_config`(Instance): Create the Configuration text for an initializer file. (See Readme for more details)
+
+## v1.0.0 June 2022
+- Initial Launch!

data/Dockerfile

@@ -1,4 +1,4 @@
-FROM ruby:3.0.1
+FROM ruby:3.3.6
 RUN cd /tmp && curl -L --output ghr.tar.gz https://github.com/tcnksm/ghr/releases/download/v0.12.0/ghr_v0.12.0_linux_amd64.tar.gz && \
     tar -xzvf ghr.tar.gz && chmod +x ghr_v0.12.0_linux_amd64/ghr && mv ghr_v0.12.0_linux_amd64/ghr /usr/local/bin/ghr && rm -rf /tmp/*
 

data/Gemfile

@@ -5,8 +5,8 @@ source "https://rubygems.org"
 # Specify your gem's dependencies in GEMNAME.gemspec
 gemspec
 
-gem 'faker'
-gem 'pry'
-gem 'rspec', '~> 3.0'
-gem 'rspec_junit_formatter'
-gem 'simplecov', require: false, group: :test
+gem "faker"
+gem "pry"
+gem "rspec"
+gem "rspec_junit_formatter"
+gem "simplecov"

data/Gemfile.lock

@@ -1,60 +1,54 @@
 PATH
   remote: .
   specs:
-    class_composer (0.1.0)
+    class_composer (2.0.0)
 
 GEM
   remote: https://rubygems.org/
   specs:
-    byebug (11.1.3)
     coderay (1.1.3)
-    concurrent-ruby (1.1.10)
-    diff-lcs (1.5.0)
-    docile (1.4.0)
-    faker (2.21.0)
+    concurrent-ruby (1.3.4)
+    diff-lcs (1.5.1)
+    docile (1.4.1)
+    faker (3.5.1)
       i18n (>= 1.8.11, < 2)
-    i18n (1.10.0)
+    i18n (1.14.6)
       concurrent-ruby (~> 1.0)
-    method_source (1.0.0)
-    pry (0.13.1)
+    method_source (1.1.0)
+    pry (0.15.0)
       coderay (~> 1.1)
       method_source (~> 1.0)
-    pry-byebug (3.9.0)
-      byebug (~> 11.0)
-      pry (~> 0.13.0)
-    rake (12.3.3)
-    rspec (3.11.0)
-      rspec-core (~> 3.11.0)
-      rspec-expectations (~> 3.11.0)
-      rspec-mocks (~> 3.11.0)
-    rspec-core (3.11.0)
-      rspec-support (~> 3.11.0)
-    rspec-expectations (3.11.0)
+    rspec (3.13.0)
+      rspec-core (~> 3.13.0)
+      rspec-expectations (~> 3.13.0)
+      rspec-mocks (~> 3.13.0)
+    rspec-core (3.13.2)
+      rspec-support (~> 3.13.0)
+    rspec-expectations (3.13.3)
       diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.11.0)
-    rspec-mocks (3.11.1)
+      rspec-support (~> 3.13.0)
+    rspec-mocks (3.13.2)
       diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.11.0)
-    rspec-support (3.11.0)
-    rspec_junit_formatter (0.5.1)
+      rspec-support (~> 3.13.0)
+    rspec-support (3.13.1)
+    rspec_junit_formatter (0.6.0)
       rspec-core (>= 2, < 4, != 2.12.0)
-    simplecov (0.21.2)
+    simplecov (0.22.0)
       docile (~> 1.1)
       simplecov-html (~> 0.11)
       simplecov_json_formatter (~> 0.1)
-    simplecov-html (0.12.3)
+    simplecov-html (0.13.1)
     simplecov_json_formatter (0.1.4)
 
 PLATFORMS
+  aarch64-linux
   x86_64-linux
 
 DEPENDENCIES
   class_composer!
   faker
   pry
-  pry-byebug
-  rake (~> 12.0)
-  rspec (~> 3.0)
+  rspec
   rspec_junit_formatter
   simplecov
 

data/README.md

@@ -22,7 +22,7 @@ Or install it yourself as:
 
 ## Usage
 
-### Basic
+### Basic Add Composer
 
 `add_composer` is the driving method behind the composer gem. It will
 - Add a setter Method
@@ -32,144 +32,32 @@ Or install it yourself as:
 
 In short, Composer will behave similarly to `attr_accessor`
 
+Check out [Basic Composer](docs/basic_composer.md) for usage details
 
-```ruby
-require 'class_composer'
-
-class MyConfigurableClass
-  include ClassComposer::Generator
-
-  ALLOWED_FIBONACCI = [0, 2, 8, 13, 34]
-
-  add_composer :status, allowed: Integer, default: 35
-  add_composer :number, allowed: Integer, default: 0, validator: -> (val) { val < 50 }
-  # when no default is provided, nil will be returned
-  add_composer :fibbonacci, allowed: Array, validator: ->(val) { val.all? {|i| i.is_a?(Integer) } && val.all? { |i| ALLOWED_FIBONACCI.include?(i) } }, invalid_message: ->(val) { "We only allow #{ALLOWED_FIBONACCI} numbers. Received #{val}" }
-  # Allowed can be passed an array of allowed class types
-  add_composer :type, allowed: [Proc, Integer], default: 35
-end
-
-instance = MyConfigurableClass.new
-instance.type
-=> 35
-instance.number = 75
-ClassComposer::ValidatorError: MyConfigurableClass.number failed validation. number is expected to be Integer.
-from /gem/lib/class_composer/generator.rb:71:in `block in __composer_assignment__`
-instance.number = 15
-=> 15
-instance.number
-=> 15
-instance.fibbonacci
-=> nil
-instance.fibbonacci = [1,2,3]
-ClassComposer::ValidatorError: MyConfigurableClass.fibbonacci failed validation. fibbonacci is expected to be [Array]. We only allow [0, 2, 8, 13, 34] numbers. Received [1, 2, 3]
-from /gem/lib/class_composer/generator.rb:71:in `block in __composer_assignment__`
-instance.fibbonacci = [0,13,34]
-=> [0, 13, 34]
-instance.fibbonacci
-=> [0, 13, 34]
-```
+### Usage with Arrays
 
-### KWarg Options
+Composer allows interactions with arrays in a native way. When the allowed type is `Array`, ClassComposer will add a custom method `<<` to overwrite the native Array method. This ensures that ClassComposer Validations run when adding to the Array.
 
-```
-allowed
-  - Required: True
-  - What: Expected value of the name of the composed method
-  - Type: Array of Class types or Single Class type
-
-validator
-  - Required: False
-  - What: Custom way to validate the value of the composed method
-  - Type: Proc
-  - Default: ->(_) { true }
-  - By default validation happens on the `allowed` KWARG first and then the passed in validator function. Proc should expect that the type passed in is one of `allowed`
-
-validation_error_klass
-  - Required: false
-  - What: Class to raise when a validation error occurs from `allowed` KWarg or from the passed in `validator` proc
-  - Type: Class
-  - Default: ClassComposer::ValidatorError
-
-validation_error_klass
-  - Required: false
-  - What: Class to raise when a errors occur outside of validation. This can be for composer method errors or proc errors during validation
-  - Type: Class
-  - Default: ClassComposer::Error
-
-default
-  - Required: false
-  - What: This is the default value to set for the composed method
-  - Type: Should match the `allowed` KWarg
-  - Default: nil
-  - Note: When no default value is provided, the return value from the getter will be `nil`. However, this does not mean that NilClass will be an acceptable value during the setter method
-
-invalid_message
-  - Required: False
-  - What: Message to add to the base invalid setter method
-  - Type: Proc or String
-    - Proc: ->(val) { } # where val is the failed value of the setter method
+For more information, check out [Array Usage](docs/array_usage.md)
 
-```
+### Freezing Objects
 
-### Advanced
+Sometimes you want freeze an instance of a Configuration. Freezing it will make it immutable from changes Users may try to make.
 
-#### Usage with Array as Allowed
-Arrays are treated special with the composed methods. `ClassComposer` will inject a custom method `<<` so that it can be treated as a regular array with the added benefit of validation still occuring.
+For more information, check out [Freezing Class Composer Instances](docs/freezing.md)
 
-```ruby
-class CustomArrayClass
-  include ClassComposer::Generator
+### Complex usage: Composer Blocking
 
-  add_composer :array, allowed: Array, default: [], validator: ->(val) { val.sum < 40 }, invalid_message: ->(val) { "Array sum of [#{val.sum}] must be less than 40" }
-end
+Composer blocking builds on top of the [Basic Composer](docs/basic_composer.md) to help with nested Configurations that include `ClassCompser::Generator`.
+Nested configuration's allow complex configurations for entire projects to work seamlessly together.
 
-instance = CustomArrayClass.new
-instance.array << 1
-instance.array << 2
-instance.array
-=> [1, 2]
-instance.array << 50
-ClassComposer::ValidatorError: CustomArrayClass.array failed validation. array is expected to be Array. Array sum of [53] must be less than 40
-
-```
-
-#### Usage with complex configuration
-
-```ruby
-class ComplexDependencies
-  include ClassComposer::Generator
-
-  add_composer :use_scope, allowed: [TrueClass, FalseClass], default: false
-  add_composer :scope, allowed: Proc
-
-  def scope
-    # skip unless use_scope is explicitly set
-    return -> {} unless @use_scope
-
-    # use passed in scope if present
-    # Otherwise default to blank default
-    @scope || -> {}
-  end
-end
-```
-Adding custom methods allows for higher level of complexity. The methods can be used and accessed just as an `attr_accessor` would.
+For Examples and use cases, check out [Composer Blocking](docs/composer_blocking.md)
 
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run
-`rake rspec` to run the tests. You can also run `bin/console` for an interactive
-prompt that will allow you to experiment. Run `bundle exec class_composer` to use
-the gem in this directory, ignoring other installed copies of this gem.
-
-To install this gem onto your local machine, run `bundle exec rake install`.
-
-To release a new version:
-
-1. Update the version number in [lib/class_composer/version.rb]
-2. Update [CHANGELOG.md]
-3. Merge to the main branch. This will trigger an automatic build in CircleCI
-   and push the new gem to the repo.
+`bundle exec rspec` to run the tests. You can also run `bin/console` for an interactive
+prompt that will allow you to experiment.
 
 ## Contributing
 

data/bin/setup

@@ -5,6 +5,4 @@ set -vx
 
 bundle install
 
-lefthook install
-
 # Do any other automated setup that you need to do here

data/class_composer.gemspec

@@ -13,7 +13,7 @@ Gem::Specification.new do |spec|
   spec.homepage    = "https://github.com/matt-taylor/class_composer"
   spec.license     = "MIT"
 
-  spec.required_ruby_version = Gem::Requirement.new(">= 2.7")
+  spec.required_ruby_version = Gem::Requirement.new(">= 3.1")
 
   spec.metadata = {
     "homepage_uri" => spec.homepage,
@@ -25,12 +25,5 @@ Gem::Specification.new do |spec|
   spec.files = Dir.chdir(File.expand_path(__dir__)) do
     %x(git ls-files -z).split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
   end
-  spec.bindir = "exe"
-  spec.executables = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
-
-  spec.add_development_dependency "pry-byebug"
-  spec.add_development_dependency "rake", "~> 12.0"
-  spec.add_development_dependency "rspec", "~> 3.0"
-  spec.add_development_dependency "simplecov", "~> 0.17.0"
 end

data/docker-compose.yml

@@ -1,5 +1,3 @@
-version: '3'
-
 services:
   class-composer:
     command: tail -f /dev/null

data/docs/array_usage.md

@@ -0,0 +1,25 @@
+# Usage with Array
+
+For more details on basic setup, visit [Basic Composer Page](basic_composer.md)
+
+---
+
+Arrays are treated special with the composed methods. `ClassComposer` will inject a custom method `<<` so that it can be treated as a regular array with the added benefit of validation still occurring.
+
+
+```ruby
+class CustomArrayClass
+  include ClassComposer::Generator
+
+  add_composer :array, allowed: Array, default: [], validator: ->(val) { val.sum < 40 }, invalid_message: ->(val) { "Array sum of [#{val.sum}] must be less than 40" }
+end
+
+instance = CustomArrayClass.new
+instance.array << 1
+instance.array << 2
+instance.array
+=> [1, 2]
+instance.array << 50
+ClassComposer::ValidatorError: CustomArrayClass.array failed validation. array is expected to be Array. Array sum of [53] must be less than 40
+
+```

data/docs/basic_composer.md

@@ -0,0 +1,118 @@
+# Add Composer
+
+`ClassComposer` by default is a DRY way to compose configurations for a class. It provides re-usable validations to ensure variables are set correctly. It is lazily loaded by default and has some wicked options available
+
+```ruby
+require "class_composer"
+class MyCoolClass
+  include ClassComposer::Generator
+
+  add_composer :status, allowed: Symbol, default: :in_progress
+end
+```
+
+
+## Available Options:
+
+### Allowed
+- Required: Yes
+- Description: This defines allowed types for this composed item. If `===` fails, it will return a runtime error
+- Type: Type of allowed assignments. Or an Array of allowed assignments --
+
+Examples:
+
+```ruby
+add_composer :status, allowed: Symbol, default: :in_progress
+
+add_composer :status, allowed: [Symbol, String], default: :in_progress
+```
+
+### Default
+- Required: False
+- Description: This option allows you to set a sane default for configuration while still allowing others to overwrite the value
+- Type: It _should_ be one of the `allowed` types to ensure it passes validation
+
+Examples
+```ruby
+add_composer :status, allowed: Symbol, default: :different_default
+
+add_composer :status, allowed: Symbol, default: "This type does not match Symbol. This default value will raise error"
+```
+
+### Description
+- Required: False (Recommend)
+- Description: This option provides a human readable description of what the current configuration option does. This value is useful when [Generating an Initializer](generating_initializer.md)
+- Type: String
+
+```ruby
+add_composer :status, allowed: Symbol, default: :in_progress, desc: "This config value is the current status for the entity."
+```
+
+
+### Default Shown
+- Required: False (Recommend)
+- Description: This option is helpful when the `default` value is a class or retrieved from an ENV variable. It will overload the `default` value when [Generating an Initializer](generating_initializer.md)
+- Type: String
+
+```ruby
+add_composer :status, allowed: Symbol, default: :in_progress, desc: "This config value is the current status for the entity.", default_shown: "completed"
+```
+
+### Provide a Block
+- Required: False
+- Description: The optional block will get executed after all validations have completed successful. This is a valuable option when you need to do a secondary action after the value is assigned/changed.
+- Type: Proc that accepts (`key`, `value`)
+
+```ruby
+BLOCK = Proc.new do |key, value|
+  User.send_mail("Your Status has changed to #{key}")
+end
+
+add_composer :status, allowed: Symbol, default: :in_progress, desc: "This config value is the current status for the entity.", default_shown: "completed", &BLOCK
+```
+
+### Validator
+- Required: False
+- Description: This option provides additional validation to do on the item during assignment.
+- Type: Proc that returns a truthy or falsey value. Truthy response will pass validation. Falsey response will fail validation and raise a runtime error
+- Default: `->(_) { true }`
+
+Examples:
+```ruby
+add_composer :status, allowed: Symbol, default: :in_progress, validator: ->(value) { [:backlog,:in_progress, :complete].include?(value) }
+```
+
+### Invalid Message
+- Required: False (Recommended with `validator`)
+- Description: When provided, you can add a custom validation message to the runtime error. Recommended when `validator` is provided
+- Type: Proc that returns a string to add to validation message
+
+Examples:
+```ruby
+ALLOWED = [:backlog,:in_progress, :complete]
+add_composer :status, allowed: Symbol, default: :in_progress, validator: ->(value) { ALLOWED.include?(value) }, invalid_message: ->(value) { "Value must be one of #{ALLOWED}" }
+```
+
+### Validation Error Class
+- Required False
+- Description: The default error to raise when validation fails.
+- Default: `ClassComposer::ValidatorError`
+- Type: Class that has `StandardError` Ancestor
+
+### Error Class
+- Required: False
+- Description: The default error class to raise when errors outside of ClassComposer occur. EG during custom validation
+- Default: `ClassComposer::Error`
+- Type: Class that has `StandardError` ancestor
+
+Examples:
+```ruby
+ALLOWED = [:backlog,:in_progress, :complete]
+add_composer :status, allowed: Symbol, default: :in_progress, validator: ->(value) { UNDEFINED_VARIABLE.include?(value) } validation_error_klass: Exception
+# Will raise with `Exception`
+```
+
+---
+
+To see some complete Examples, visit [Basic Composer Example](basic_composer_example,md)
+

data/docs/basic_composer_example.md

@@ -0,0 +1,35 @@
+```ruby
+require 'class_composer'
+
+class MyConfigurableClass
+  include ClassComposer::Generator
+
+  ALLOWED_FIBONACCI = [0, 2, 8, 13, 34]
+
+  add_composer :status, allowed: Integer, default: 35
+  add_composer :number, allowed: Integer, default: 0, validator: -> (val) { val < 50 }
+  # when no default is provided, nil will be returned
+  add_composer :fibbonacci, allowed: Array, validator: ->(val) { val.all? {|i| i.is_a?(Integer) } && val.all? { |i| ALLOWED_FIBONACCI.include?(i) } }, invalid_message: ->(val) { "We only allow #{ALLOWED_FIBONACCI} numbers. Received #{val}" }
+  # Allowed can be passed an array of allowed class types
+  add_composer :type, allowed: [Proc, Integer], default: 35
+end
+
+instance = MyConfigurableClass.new
+instance.type
+=> 35
+instance.number = 75
+ClassComposer::ValidatorError: MyConfigurableClass.number failed validation. number is expected to be Integer.
+from /gem/lib/class_composer/generator.rb:71:in `block in __composer_assignment__`
+instance.number = 15
+=> 15
+instance.number
+=> 15
+instance.fibbonacci
+=> nil
+instance.fibbonacci = [1,2,3]
+ClassComposer::ValidatorError: MyConfigurableClass.fibbonacci failed validation. fibbonacci is expected to be [Array]. We only allow [0, 2, 8, 13, 34] numbers. Received [1, 2, 3]
+from /gem/lib/class_composer/generator.rb:71:in `block in __composer_assignment__`
+instance.fibbonacci = [0,13,34]
+=> [0, 13, 34]
+instance.fibbonacci
+=> [0, 13, 34]

data/docs/composer_blocking.md

@@ -0,0 +1,84 @@
+# Composer Blocking
+
+Composer Blocking enhances nested configuration's that utilize `ClassComposer::Generator`. It is a method that provides additional validations and usability.
+
+Basic Example:
+```ruby
+require "class_composer"
+
+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_blocking :login, composer_class: LoginStrategy, 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
+
+instance = AppConfiguration.new
+instance.with_login! do |login|
+  login.type = "oauth"
+  login.username_length = 20
+end
+instance.login.type
+=> "oauth"
+instance.login.type = "plain_text"
+=> "plain_text"
+
+instance.lockable?
+=> false
+# Calling the block automatically enables the config when passed the `enable_attr`
+instance.with_lockable! do |lock|
+  lock.password_attempts = 5
+end
+instance.lockable?
+=> true
+```
+
+## What does it produce?
+### Configuration Blocking Method
+Provides easy invocation for setting a nested composer configuration. By providing a block, you can easily and cleanly set your options for a specific composer item.
+
+### Check for composer Enable
+When the `enable_attr` method is provided, you can easily check if the composer instance is enabled by invoking `item_name?`. This convenience method can be used throughout the application to easily check which code paths to go down
+
+## Allowed Options
+
+### Composer Class
+- Required: True
+- Description: This is the Class object that includes `ClassComposer::Generator`. If the inclusion is missing, the method will raise an runtime error.
+- Type: Class that includes `ClassComposer::Generator`
+
+### Description
+- Required: False (Recommend)
+- Description: This option provides a human readable description of what the current configuration option does. This value is useful when [Generating an Initializer](generating_initializer.md)
+- Type: String
+
+### Block Prepend
+- Required: False
+- Description: By default, Composer Blocking prepends blocks with `with_`. This options allows you to set a custom prepended name
+- Default: `with`
+- Type: String or Symbol
+
+### Enable Attr
+- Required: False
+- Description: When passed the `enable_attr:`, Class composer will enable the composer instance when called with a block and provide a convenience method `item_name?` to check for if the item is enabled.
+- Type: String or Symbol
+
+

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_blocking :login, composer_class: LoginStrategy, 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,125 @@
+# 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
+          # binding.pry
+
+          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[:allowed].include?(String)
+        default = "\"#{metadata[:default]}\""
+      else
+        default = 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 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.rb

@@ -1,38 +1,170 @@
 # frozen_string_literal: true
 
 require "class_composer/default_object"
+require "class_composer/generate_config"
 
 module ClassComposer
+  FROZEN_TYPES = [
+    DEFAULT_FROZEN_TYPE = FROZEN_RAISE = :raise,
+    FROZEN_LOG_AND_ALLOW = :log_and_allow,
+    FROZEN_LOG_AND_SKIP = :log_and_skip,
+  ]
   module Generator
     def self.included(base)
       base.extend(ClassMethods)
+      base.include(InstanceMethods)
+    end
+
+    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
 
     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)
 
-      def add_composer(name, allowed:, accessor: true, validator: ->(_) { true }, validation_error_klass: ::ClassComposer::ValidatorError, error_klass: ::ClassComposer::Error, **params)
+        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
-            if allowed.is_a?(Array)
-              allowed << ClassComposer::DefaultObject
-            else
-              allowed = [allowed, ClassComposer::DefaultObject]
-            end
             ClassComposer::DefaultObject
           end
 
-        allowed.include?(ClassComposer::DefaultObject)
+        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)
+        __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, default: default, array_proc: array_proc)
+
+        # Add to mapping
+        __add_to_composer_mapping__(name: name, default: default, allowed: allowed, desc: desc, blocking_attributes: blocking_attributes, default_shown: default_shown)
+      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)
+        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,
+          default: default_shown || (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:)
@@ -52,22 +184,27 @@ module ClassComposer
       end
 
       # create assignment method for the incoming name
-      def __composer_assignment__(name:, params:, allowed:, validator:, array_proc:, validation_error_klass:, error_klass:)
+      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 = validator.(value)
 
           if is_valid
             instance_variable_set(COMPOSER_ASSIGNED_ATTR_NAME.(name), true)
             instance_variable_set(:"@#{name}", value)
           else
-            message = ["#{self.class}.#{name} failed validation. #{name} is expected to be #{allowed}."]
+            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)
-            if value.is_a?(Array)
-              # we assigned the array value...pop it from the array
-              # must be done after the message is created so that failing value can get passed appropriately
-              value.pop
-            end
             raise validation_error_klass, message.compact.join(" ")
           end
 
@@ -79,6 +216,10 @@ module ClassComposer
             value.instance_variable_set(COMPOSER_ASSIGNED_ARRAY_METHODS.(name), true)
           end
 
+          if blk
+            yield(name, value)
+          end
+
           value
         end
       end
@@ -120,7 +261,7 @@ module ClassComposer
             # 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} occured during validation for value [#{value}]. Check custom validator for #{name}"
+            raise error_klass, "#{e} occurred during validation for value [#{value}]. Check custom validator for #{name}"
           end
         end
       end

data/lib/class_composer/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ClassComposer
-  VERSION = "1.0.2"
+  VERSION = "2.0.0"
 end

metadata

@@ -1,71 +1,15 @@
 --- !ruby/object:Gem::Specification
 name: class_composer
 version: !ruby/object:Gem::Version
-  version: 1.0.2
+  version: 2.0.0
 platform: ruby
 authors:
 - Matt Taylor
 autorequire: 
-bindir: exe
+bindir: bin
 cert_chain: []
-date: 2022-07-04 00:00:00.000000000 Z
-dependencies:
-- !ruby/object:Gem::Dependency
-  name: pry-byebug
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: rake
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '12.0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '12.0'
-- !ruby/object:Gem::Dependency
-  name: rspec
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '3.0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '3.0'
-- !ruby/object:Gem::Dependency
-  name: simplecov
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 0.17.0
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 0.17.0
+date: 2024-12-01 00:00:00.000000000 Z
+dependencies: []
 description: Compose configurations for any class.
 email:
 - mattius.taylor@gmail.com
@@ -89,8 +33,15 @@ files:
 - bin/setup
 - class_composer.gemspec
 - docker-compose.yml
+- docs/array_usage.md
+- docs/basic_composer.md
+- docs/basic_composer_example.md
+- docs/composer_blocking.md
+- docs/freezing.md
+- docs/generating_initializer.md
 - lib/class_composer.rb
 - lib/class_composer/default_object.rb
+- lib/class_composer/generate_config.rb
 - lib/class_composer/generator.rb
 - lib/class_composer/version.rb
 homepage: https://github.com/matt-taylor/class_composer
@@ -107,14 +58,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '2.7'
+      version: '3.1'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.11
+rubygems_version: 3.5.9
 signing_key: 
 specification_version: 4
 summary: Easily compose a class via inline code or passed in YAML config. Add instance