const_conf 0.8.1 → 0.8.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5bd3638ecc438cef844c87bf0cceeaa962a6863091724d71c3f8f278bada70f6
-  data.tar.gz: bd088bffdd006036e972c563d7551fa487b715e44b22a245e4071faa511d246c
+  metadata.gz: 783442195899da65976c312008a1dbc0277e523159702d8582e5933a1f40750c
+  data.tar.gz: a019c8c9d8b0eaa6eebe12ce15a5a3772d47bbec121a0eb7c323de25e13edc59
 SHA512:
-  metadata.gz: 9f3909e1e564af3d3fc333d32e07f533642e5d2cac974beb0fb4479417621bc43a13e31a833d83889fa55fb900bbe105e839197385026431ac0cae90cdd22d1d
-  data.tar.gz: 740272c69d8b046e08131c80d9df806dd12eb12939f6256e357a4815157cc6878cae076eba4835395d4bf271f59fa948e63c22311faf169036d70070db785ff4
+  metadata.gz: 1a9b3cc846abe1a7196bae1d51090349be3de081e80ce733a4ea947f66026f53f4cd99893d2144c17917b78c56c149e28382e63a8046b65b0f51f08325450f9b
+  data.tar.gz: d7331a496fd34232f3986f1d5940a8af108c2ff965c4e2af7d800acc3b1eda109424234f727cdc5260d82c89a84e0f52be4d3babf4c57b20b39cff85e6b25f64

data/CHANGES.md

@@ -1,5 +1,33 @@
 # Changes
 
+## 2026-08-20 v0.8.2
+
+*   Documented block calling contexts for `decode`, `required`, and `check` in
+    the README, clarifying differences between plain `Proc` calls and
+    `instance_eval` within the `Setting` context.
+*   Improved test result feedback by adding emoji-based status messages and
+    descriptive cleanup steps, including conditional checks using the `RESULT`
+    variable and cleaner file deletion commands.
+*   Updated setting validation documentation to clarify `instance_eval` arity
+    rules for the `check` block, fixed typos in `required?` and `sensitive`
+    accessor descriptions, and clarified that `sensitive` masks values in
+    `view` output.
+*   Corrected guidance for guarding absent values to use `value.blank?` instead
+    of `value.nil?`.
+*   Rewrote the `?` predicate section in the README to explain the `FOO::BAR`
+    (constant) and `FOO::BAR?` (predicate) access pattern, and added a "How
+    concepts compose" section with a scenario table for `confirm!`, constants,
+    and predicates.
+*   Fixed a typo in the README truthy value description, correcting "truty" to
+    `truthy`.
+*   Added a YARD note to `ConstConf::Setting#checked?` explaining that it is
+    evaluated unconditionally in `ConstConf::Setting#confirm!`, even when no
+    value is supplied.
+*   Clarified the distinction between `required` and blank values in the
+    README, noting that `required true` only guards against `nil`, and updated
+    the `@raise` YARD doc for `ConstConf::RequiredValueNotConfigured` to
+    explicitly state that blank values satisfy the check.
+
 ## 2026-08-04 v0.8.1
 
 ### Changed

data/README.md

@@ -99,8 +99,18 @@ end
 
 ### Note that **Predicate Methods (`?`)** are defined
 
-If a setting is `active?`, the predicate method returns a truthy value, which
-then can be used like this:
+For each setting, ConstConf defines a deliberate pair:
+
+- **`FOO::BAR`** — the constant. Holds the resolved value from `ENV` or
+  `default`. Always returns whatever was configured (or `nil`). This is
+  what the environment variable *is*.
+- **`FOO::BAR?`** — the predicate. Returns the value *only if* `active?`
+  is true; otherwise returns `nil`. This is what your code is *allowed to
+  use*.
+
+They share the same name because they share the same source. The predicate
+is an opt-in gate on the constant, letting you evaluate the configuration
+conditionally:
 
 ```ruby
 # Check if active?
@@ -111,7 +121,8 @@ else
 end
 ```
 
-Or `nil` is returned, which can then be handled accordingly.
+When `active?` is false (value is `nil` or blank under the default
+`:present?` activation), the predicate short-circuits to `nil`.
 
 ### Note that **Getter Methods (`!`)** are also defined
 
@@ -158,7 +169,7 @@ Key indicators in the view:
 | 🔴  | ⚪  | Required settings that must be configured|
 | 🔧  | ⚪  | Configured values from ENV |
 | 🙈  | ⚪  | ENV var was ignored |
-| 🟢  | ⚪  | Setting is active (? method returns truty value) |
+| 🟢  | ⚪  | Setting is active (? method returns truthy value) |
 | ⚙️   | ⚪  | Decoding logic applied to transform raw input |
 | ✅  ┊ ☑️   | ❌ | Validation checks have passed or failed |
 
@@ -357,6 +368,10 @@ functionality.
 - **Usage**: `decode(&:chomp)` removes whitespace, `decode { YAML.load(it) }`
   parses YAML
 - **Indicator**: Shows ⚙️ in view output when active
+- **Block context**: Unlike `check`, the decode block is called as a plain
+  Proc (`decode.(raw_value)`). The block receives the raw (pre-decode) value
+  from the environment variable or default. Use `it` or a block parameter to
+  access the value.
 
 #### **Required** (`required?`)
 
@@ -366,6 +381,14 @@ functionality.
 - **Usage**: `required true` (always required) or `required { !Rails.env.test?
   }` (conditional)
 - **Indicator**: Shows 🔴 in view output when required and not satisfied
+- **Note**: `required true` only guards against `nil`. A blank string like
+  `""` will pass `confirm!` but cause the `?` predicate to return `nil`.
+  Use `check { value.present? }` or `required ->(v) { v.present? }` if you
+  need non-blank validation.
+- **Block context**: A Proc-based `required` is called with the raw
+  (pre-decode) value when arity is 1: `required ->(v) { v.present? }`.
+  An arity-0 Proc runs without arguments:
+  `required { !Rails.env.test? }`.
 
 #### **Configured** (`configured?`)
 
@@ -385,6 +408,13 @@ functionality.
   - **☑️** = No custom check defined (passes by default - `:unchecked_true`)
   - **✅** = Custom check explicitly passes (returns `true`)
   - **❌** = Custom check explicitly fails (returns `false`)
+- **Note**: `checked?` is evaluated unconditionally in `confirm!`, even
+  when no value is supplied. If your check should pass for absent values,
+  guard with `value.nil? ||`.
+- **Block context**: The check block is evaluated via `instance_eval` in the
+  Setting's context, so bare method calls like `value` and `configured?`
+  resolve to this setting. An arity-1 block (`->(s) { ... }`) also receives
+  the Setting instance as its argument.
 
 #### **Active** (`active?`)
 
@@ -409,6 +439,42 @@ These concepts work together to provide a comprehensive configuration
 management system that tracks the complete lifecycle and status of each setting
 from definition through validation and usage.
 
+### How concepts compose
+
+`FOO::BAR?` is defined as `(setting.value if setting.active?)`. So it returns
+a truthy value only when `active?` is true *and* `value` is truthy. With the
+default `activated` of `:present?`, that means the resolved value must be
+non-nil and non-blank.
+
+This is a different question from `confirm!`. At definition time, `confirm!`
+asks: "did you supply a non-nil value?" (`required` + `value_provided?`).
+At usage time, `FOO::BAR?` asks: "is this value actually usable?" (`active?`).
+A setting can pass `confirm!` (value exists) yet `FOO::BAR?` still returns
+`nil` (value is blank). These are independent axes, not redundant ones.
+
+For example:
+
+```ruby
+module FOO
+  include ConstConf
+  description 'Foo config'
+
+  BAR = set do
+    description 'A bar setting'
+    required true
+  end
+end
+```
+
+| Scenario | `confirm!` | `FOO::BAR` | `FOO::BAR?` |
+|---|---|---|---|
+| `ENV['FOO_BAR']` unset | ❌ raises `RequiredValueNotConfigured` | — | — |
+| `ENV['FOO_BAR'] = ""` | ✅ passes (non-nil) | `""` | `nil` (blank → not active) |
+| `ENV['FOO_BAR'] = "hello"` | ✅ passes | `"hello"` | `"hello"` |
+
+This shows how `required`, `check`, and `active?` each guard a different
+aspect: existence, validity, and usability.
+
 ### Advanced Usage Examples
 
 #### Nested Configuration Modules

data/const_conf.gemspec

@@ -1,9 +1,9 @@
 # -*- encoding: utf-8 -*-
-# stub: const_conf 0.8.1 ruby lib
+# stub: const_conf 0.8.2 ruby lib
 
 Gem::Specification.new do |s|
   s.name = "const_conf".freeze
-  s.version = "0.8.1".freeze
+  s.version = "0.8.2".freeze
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0".freeze) if s.respond_to? :required_rubygems_version=
   s.require_paths = ["lib".freeze]

data/lib/const_conf/setting.rb

@@ -92,16 +92,32 @@ class ConstConf::Setting
   # validate that a setting meets certain criteria beyond basic required and
   # default value checks. The check can be a Proc that evaluates to true,
   # :unchecked_true (truthy), or false, allowing for custom validation logic. It
-  # deffaults to true, if not set otherwise.
+  # defaults to true, if not set otherwise.
   #
   # @return [Proc, Object] the current check configuration value
   setting_accessor :check, -> setting { :unchecked_true }
 
   # Checks if the configuration setting passes its validation check.
   #
+  # The check block is evaluated via {#instance_eval} in the context of this
+  # Setting instance, so bare method calls (e.g. `value`, `configured?`)
+  # resolve to this setting. Standard Ruby `instance_eval` arity rules apply:
+  #
+  # - **Arity 0**: The block runs with `self` set to this Setting instance
+  #   and receives no arguments. Access setting properties directly:
+  #   `check { value.blank? || value.scheme == 'redis' }`
+  #
+  # - **Arity 1**: The block receives this Setting instance as its sole
+  #   argument as well. Use it when you prefer explicit receiver access:
+  #   `check ->(s) { s.value.blank? || s.value.scheme == 'redis' }`
+  #
+  # Note: {#checked?} is evaluated unconditionally in {#confirm!}, even when
+  # no value is supplied. If your check should pass for absent values, guard
+  # with `value.blank? ||`.
+  #
   # @return [Boolean, Symbol] true if the setting's check logic evaluates to
-  # true, # false or false if not. I no check was defined, returns
-  # :unchecked_true. @see check
+  #   true, false if not. If no check was defined, returns
+  #   :unchecked_true. @see check
   def checked?
     instance_eval(&check)
   end
@@ -124,8 +140,8 @@ class ConstConf::Setting
   #     * With arity 0: Called without arguments (e.g., `-> {
   #     some_value.present? }`)
   # @return [Boolean, Proc] returns the value that was set
-  # @method required(value = nil, &block)
-  # @see #required?
+  #   @method required(value = nil, &block)
+  #   @see #required?
   setting_accessor :required, false
 
   # Checks if the setting has a required value configured or as a default
@@ -151,10 +167,13 @@ class ConstConf::Setting
       end
   end
 
-  # Checks if the setting has a required value configured.
+  # Sets or retrieves the sensitive flag for the configuration setting.
   #
-  # @return [Boolean] true if the setting is marked as required and has a valid
-  # value, false otherwise
+  # When true, the setting's value is masked as 🤫 in the {#view} output
+  # to protect confidential data such as passwords, API keys, and tokens.
+  #
+  # @param value [Boolean] true to mark the setting as sensitive
+  # @return [Boolean] the current sensitivity flag
   setting_accessor :sensitive, false
 
   alias sensitive? sensitive
@@ -300,8 +319,10 @@ class ConstConf::Setting
   #
   # @raise [ ConstConf::RequiredDescriptionNotConfigured ] if the setting's description
   #   is blank or the parent module's description is missing
-  # @raise [ ConstConf::RequiredValueNotConfigured ] if the setting is required but no
-  #   value is provided
+  # @raise [ ConstConf::RequiredValueNotConfigured ] if the setting is required
+  #   but no non-nil value is provided. Note that blank values (e.g. `""` or
+  #   `"   "`) satisfy this check; use {#check} or a Proc-based {#required}
+  #   to also reject them.
   # @raise [ ConstConf::SettingCheckFailed ] if the setting's check fails
   def confirm!
     if parent_namespace.is_a?(Module) && parent_namespace < ConstConf

data/lib/const_conf/version.rb

@@ -1,6 +1,6 @@
 module ConstConf
   # ConstConf version
-  VERSION         = '0.8.1'
+  VERSION         = '0.8.2'
   VERSION_ARRAY   = VERSION.split('.').map(&:to_i) # :nodoc:
   VERSION_MAJOR   = VERSION_ARRAY[0] # :nodoc:
   VERSION_MINOR   = VERSION_ARRAY[1] # :nodoc:

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: const_conf
 version: !ruby/object:Gem::Version
-  version: 0.8.1
+  version: 0.8.2
 platform: ruby
 authors:
 - Florian Frank