class_composer 1.0.2 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7d53fe12431ff8f1dd4c42d7282d11a64637a0c3ab573e24a7d83443a8a9cac2
-  data.tar.gz: 0376e66b2fef6bc976289dd1f4e4517830dd0a63c0e12519730efc9786865c9f
+  metadata.gz: ce164acfb44d923b971f227a236fef5388cbeef8295f8419a46f815ac8bdaa0f
+  data.tar.gz: a0adb222a5704fd56916621669c9cce3112e07a27e338ca2c5e8b51e4a91d42f
 SHA512:
-  metadata.gz: b08e706f2f55865e6d4fab779896450dab524b946412ee8e8be8a673b205a8f3ded0a438db6dbce53d8ebc06c6a88a2dc6cba5a4da3bd5e22a599a205ea9cc0f
-  data.tar.gz: bfa9491b16358fc59b221bd5ac847b861c52a6a5793dca4fc59c81a8ceef3e12c1d3148bd8679833e4c5a643e5738788a9647a1619f9aadc2171b9d497bd0f34
+  metadata.gz: fee77c510173e27b695924ff5f5ddb050e00bfb3d26e4b8f5a124576fa72554f462ca06e0ecd31abbb150b6aca339cb22fef11d46724829e0bb0f11f937d4ac8
+  data.tar.gz: 5ce561d2dcc6b3e0e87efc4e55eec8ab243aff03ae758c069ce816674378a39c6f3e8e0c36e925c013e3d255b56d714647dd6ca4a831f3cd82dc0c3306ad6abd

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,31 @@
 
 **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.1.0 (Dec 2024)
+- Default Dynamic Configuration -- Allow config options to be defaulted to other config variables. Ability to provide a Symbol of an existing `composer` or a Proc to custom define from anything in the application
+- Update how default_shown works when generating the config
+- Extract `class_methods` and `instance_methods` to their own files
+
+## 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,133 @@
+# 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"
+```
+
+### Dynamic Default
+- Required: False
+- Description: This option allows you to set a dynamic default composed of other `add_composer` values. The `dynamic_default` is lazy loaded.
+- Type: Expected value to be a Symbol mapping to another `add_composer` method or a Proc that takes an instance as an argument.
+- Note: When using `dynamic_default`, validations will lazily get run on retrieval. This means that you could have a runtime error if the dynamic value is not of the correct `allowed` type.
+
+Examples
+```ruby
+add_composer :app_name, allowed: Symbol, default: "My Cool App Name"
+
+add_composer :app_name_comms, allowed: String, dynamic_default: :app_name
+
+add_composer :app_name_website, allowed: String, dynamic_default: ->(instance) { "#{instance.app_name} + #{instance.app_name_comms}" }
+```
+
+### 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
+
+