const_conf 0.8.1 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5bd3638ecc438cef844c87bf0cceeaa962a6863091724d71c3f8f278bada70f6
-  data.tar.gz: bd088bffdd006036e972c563d7551fa487b715e44b22a245e4071faa511d246c
+  metadata.gz: bce56d92973da4818e0e6fcd37343ea5e27a3902d0dbec7f6ad352dec69705ba
+  data.tar.gz: 317afdeca380f7847900eb421f06ced5342b60776a1c370c194408a3536b8285
 SHA512:
-  metadata.gz: 9f3909e1e564af3d3fc333d32e07f533642e5d2cac974beb0fb4479417621bc43a13e31a833d83889fa55fb900bbe105e839197385026431ac0cae90cdd22d1d
-  data.tar.gz: 740272c69d8b046e08131c80d9df806dd12eb12939f6256e357a4815157cc6878cae076eba4835395d4bf271f59fa948e63c22311faf169036d70070db785ff4
+  metadata.gz: 8591d5703c6fbe796e220c8c3ecf31330e12981b3cf3806e191cde8efe0bd5410d762d37e4d7fcf7f55b746080155d4a795361470efbc4562553de48b0de9158
+  data.tar.gz: 628a002745c8cd17970496b51dc977bab3d6cabd662afe02c7d14286594bb2f75f58424fc8aa7eaac7f114ab1ebe6c1c0c077cf9790e92e6ab4e9000b52d69b6

data/CHANGES.md

@@ -1,5 +1,42 @@
 # Changes
 
+## 2026-10-01 v0.9.0
+
+*   Add `pager:` keyword argument to `ConstConf.view` and `Setting#view`,
+    allowing callers to override the pager command used for long output;
+    defaults to `ENV['PAGER']` or `less -r`
+*   Add YARD `@param pager` documentation to both `view` methods
+*   Add spec verifying that a custom `pager:` string is passed through to
+    `IO.popen`
+
+## 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.9.0 ruby lib
 
 Gem::Specification.new do |s|
   s.name = "const_conf".freeze
-  s.version = "0.8.1".freeze
+  s.version = "0.9.0".freeze
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0".freeze) if s.respond_to? :required_rubygems_version=
   s.require_paths = ["lib".freeze]
@@ -17,7 +17,7 @@ Gem::Specification.new do |s|
   s.licenses = ["MIT".freeze]
   s.rdoc_options = ["--title".freeze, "ConstConf - Clean DSL for config settings with validation and Rails integration".freeze, "--main".freeze, "README.md".freeze]
   s.required_ruby_version = Gem::Requirement.new(">= 3.2".freeze)
-  s.rubygems_version = "4.0.17".freeze
+  s.rubygems_version = "4.0.20".freeze
   s.summary = "Clean DSL for config settings with validation and Rails integration".freeze
   s.test_files = ["spec/const_conf/dir_plugin_spec.rb".freeze, "spec/const_conf/env_dir_extension_spec.rb".freeze, "spec/const_conf/file_plugin_spec.rb".freeze, "spec/const_conf/json_plugin_spec.rb".freeze, "spec/const_conf/setting_accessor_spec.rb".freeze, "spec/const_conf/setting_spec.rb".freeze, "spec/const_conf/tree_spec.rb".freeze, "spec/const_conf/yaml_plugin_spec.rb".freeze, "spec/const_conf_spec.rb".freeze, "spec/spec_helper.rb".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
@@ -332,8 +353,11 @@ class ConstConf::Setting
   # standard output.
   #
   # @param io [IO, nil] the IO object to write the output to; if nil, uses STDOUT
-  def view(io: nil)
-    parent_namespace.view(object: self, io:)
+  # @param pager [String, nil] the pager command to use when output exceeds
+  # terminal height; if nil, falls back to the PAGER environment variable or
+  # `less -r`
+  def view(io: nil, pager: nil)
+    parent_namespace.view(object: self, io:, pager:)
   end
 
   # Returns the string representation of the tree structure.

data/lib/const_conf/version.rb

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

data/lib/const_conf.rb

@@ -410,14 +410,17 @@ module ConstConf
     # @param object [Object] the ConstConf module or setting to display
     # @param io [IO, nil] the IO object to write the output to; if nil, uses
     # STDOUT
-    def view(object: self, io: nil)
+    # @param pager [String, nil] the pager command for long output; if nil,
+    #   falls back to the `PAGER` environment variable or `less -r`
+    def view(object: self, io: nil, pager: nil)
+      pager ||= ENV.fetch('PAGER', 'less -r')
       output = ConstConf::Tree.from_const_conf(object).to_a
       if io
         io.puts output
       elsif output.size < Tins::Terminal.lines
         STDOUT.puts output
       else
-        IO.popen(ENV.fetch('PAGER', 'less -r'), ?w) do |f|
+        IO.popen(pager, ?w) do |f|
           f.puts output
           f.close_write
         end

data/spec/const_conf_spec.rb

@@ -265,6 +265,12 @@ describe ConstConf do
             )
             TestConstConf.view
           end
+
+          it 'passes custom pager to IO.popen' do
+            allow(Tins::Terminal).to receive(:lines).and_return(0)
+            expect(IO).to receive(:popen).with('my-custom-pager', ?w)
+            TestConstConf.view(pager: 'my-custom-pager')
+          end
         end
 
         describe '.documentation' do

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: const_conf
 version: !ruby/object:Gem::Version
-  version: 0.8.1
+  version: 0.9.0
 platform: ruby
 authors:
 - Florian Frank
@@ -229,7 +229,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.17
+rubygems_version: 4.0.20
 specification_version: 4
 summary: Clean DSL for config settings with validation and Rails integration
 test_files: