Class: ConstConf::Setting

Inherits:
Object
  • Object
show all
Extended by:
SettingAccessor
Includes:
DSLKit::BlockSelf
Defined in:
lib/const_conf/setting.rb

Overview

A configuration setting definition that encapsulates the properties and behavior of a single environment variable-based setting.

The Setting class provides a structured way to define, validate, and retrieve configuration values from environment variables, including support for default values, required validation, decoding logic, and descriptive metadata.

Examples:

Defining a configuration setting

Setting.new(name: 'DATABASE_URL', prefix: 'APP') { |s|
  description = 'The database connection string'
  required true
}

Instance Attribute Summary collapse

Attributes included from SettingAccessor

#setter_mode

Instance Method Summary collapse

Methods included from SettingAccessor

enable_setter_mode, setting_accessor

Constructor Details

#initialize(name:, prefix: nil) { ... } ⇒ Setting

Initializes a new Setting instance with the given name and prefix.

constructing environment variable names

Parameters:

  • name (Array<String>, String) —

    the name components for the setting

  • prefix (String, nil) (defaults to: nil) —

    the optional upcassed prefix to use when

Yields:

  • [] optional block to configure the setting



24
25
26
27
28
29
30
 
# File 'lib/const_conf/setting.rb', line 24

def initialize(name:, prefix: nil, &block)
  @parent_namespace = block_self(&block)
  @name             = Array(name) * '::'
  self.prefix(prefix)

  block and self.class.enable_setter_mode { instance_eval(&block) }
end

Instance Attribute Details

#name ⇒ String (readonly)

The name reader accessor returns the name of the setting.

Returns:

  • (String) —

    the constructed environment variable name



35
36
37
 
# File 'lib/const_conf/setting.rb', line 35

def name
  @name
end

#parent_namespace ⇒ Module? (readonly)

The parent_namespace reader accessor returns the parent namespace of the setting.

Returns:

  • (Module, nil) —

    the parent namespace module, or nil if not set



41
42
43
 
# File 'lib/const_conf/setting.rb', line 41

def parent_namespace
  @parent_namespace
end

Instance Method Details

#activated ⇒ Object

The activated reader and writer accessor for configuration settings.

This method provides access to the activated state of a configuration setting, which determines whether the setting should be considered active based on its current value or other conditions. It defaults to :present? of not set.

Returns:

  • (Object) —

    the updated activated state value

See Also:



58
 
# File 'lib/const_conf/setting.rb', line 58

setting_accessor :activated, :present?

#active? ⇒ Boolean

Checks if the configuration setting is active based on its activated state.

This method evaluates whether the configuration setting is considered active by examining its activated property. If activated is set to true, it checks if the setting's value is present. If activated is a Symbol, it sends that symbol as a message to the value and returns the result. If activated is a Proc, it evaluates the proc with or without the value depending on its arity. For any other value, it returns false.

state, false otherwise

Returns:

  • (Boolean) —

    true if the setting is active according to its activated



71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
 
# File 'lib/const_conf/setting.rb', line 71

def active?
  case activated
  when true
    value.present?
  when Symbol
    !!value.send(activated)
  when Proc
    if activated.arity == 1
      !!activated.(value)
    else
      !!activated.()
    end
  else
    false
  end
end

#check ⇒ Proc, Object

Sets or retrieves the confirmation check logic for the configuration setting.

This method provides access to the check configuration, which is used to 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 defaults to true, if not set otherwise.

Returns:

  • (Proc, Object) —

    the current check configuration value



98
 
# File 'lib/const_conf/setting.rb', line 98

setting_accessor :check, -> setting { :unchecked_true }

#checked? ⇒ Boolean, Symbol

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? ||.

Returns:

  • (Boolean, Symbol) —

    true if the setting's check logic evaluates to true, false if not. If no check was defined, returns :unchecked_true. @see check



121
122
123
 
# File 'lib/const_conf/setting.rb', line 121

def checked?
  instance_eval(&check)
end

#configured? ⇒ Boolean

Checks if the configuration setting has been configured with a value.

This method determines whether the configuration setting has been provided with a value, either through an environment variable or a default value. It returns true if a valid value is present, and false otherwise.

Returns:

  • (Boolean) —

    true if the setting has been configured with a value, false otherwise



282
283
284
 
# File 'lib/const_conf/setting.rb', line 282

def configured?
  !configured_value.nil?
end

#configured_value ⇒ String?

Returns the configured value for the setting, considering ignore status and environment variable presence.

ignored and the environment variable is set, nil otherwise

Returns:

  • (String, nil) —

    the environment variable value if the setting is not



266
267
268
269
270
271
272
 
# File 'lib/const_conf/setting.rb', line 266

def configured_value
  if ignored
    nil
  else
    env_var
  end
end

#configured_value_or_default_value ⇒ Object?

Returns the configured value for the setting, or falls back to the default value if not configured.

default value, or nil if neither is set

Returns:

  • (Object, nil) —

    the configured value if present, otherwise the



291
292
293
 
# File 'lib/const_conf/setting.rb', line 291

def configured_value_or_default_value
  configured_value || default_value
end

#confirm! ⇒ ConstConf::Setting

Confirms that the configuration setting and its parent module meet all required criteria.

This method ensures that the setting has a description, that its parent module (if it's a ConstConf module) has a description, that any required values are provided, and that the setting passes its confirmation check. It raises appropriate exceptions if any of these validation rules are not satisfied.

Returns:

Raises:

  • (ConstConf::RequiredDescriptionNotConfigured) —

    if the setting's description is blank or the parent module's description is missing

  • (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.

  • (ConstConf::SettingCheckFailed) —

    if the setting's check fails



327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
 
# File 'lib/const_conf/setting.rb', line 327

def confirm!
  if parent_namespace.is_a?(Module) && parent_namespace < ConstConf
    parent_namespace.description.present? or
      raise ConstConf::RequiredDescriptionNotConfigured,
      "required description for ConstConf module #{parent_namespace} not configured"
  end
  if description.blank?
    raise ConstConf::RequiredDescriptionNotConfigured,
      "required description for setting #{env_var_name} not configured"
  end
  if required? && !value_provided?
    raise ConstConf::RequiredValueNotConfigured,
      "required value for #{env_var_name} not configured"
  end
  unless checked?
    raise ConstConf::SettingCheckFailed, "check failed for #{name} setting"
  end
  self
end

#decode(value = nil) ⇒ Proc?

Sets or retrieves the decoding configuration for the setting.

Parameters:

  • value (Proc, nil) (defaults to: nil) —

    the decoding configuration value

    • Proc: A function that transforms the raw environment variable value
    • nil: No decoding applied

Returns:

  • (Proc, nil) —

    the current decoding configuration value

See Also:



194
 
# File 'lib/const_conf/setting.rb', line 194

setting_accessor :decode

#decoding? ⇒ Boolean

Returns true if the setting has a Proc-based decoding configuration, false otherwise.

Returns:

  • (Boolean) —

    true if the setting has a Proc-based decoding configuration, false otherwise



200
201
202
 
# File 'lib/const_conf/setting.rb', line 200

def decoding?
  !!decode&.is_a?(Proc)
end

#default_value ⇒ Object

Returns the default value for the configuration option, evaluating it if it's a Proc.

default if it's a Proc

Returns:

  • (Object) —

    the default value, or the result of evaluating the



215
216
217
218
219
220
221
222
 
# File 'lib/const_conf/setting.rb', line 215

def default_value
  case default
  when Proc
    default.()
  else
    default
  end
end

#description ⇒ String

Sets or retrieves the description for the configuration setting.

Returns:

  • (String) —

    the current description value



184
 
# File 'lib/const_conf/setting.rb', line 184

setting_accessor :description

#env_var ⇒ String?

Retrieves the value of the environment variable associated with this configuration option.

or nil if not set

Returns:

  • (String, nil) —

    the value of the environment variable if it exists,



257
258
259
 
# File 'lib/const_conf/setting.rb', line 257

def env_var
  ENV[env_var_name]
end

#env_var_name ⇒ String

Generates the environment variable name for this configuration option by constructing it from the configured prefix and name components, replacing namespace separators with underscores.

Returns:

  • (String) —

    the constructed environment variable name



247
248
249
250
 
# File 'lib/const_conf/setting.rb', line 247

def env_var_name
  prefix = @prefix.full? { "#{_1}::" }.to_s
  name.sub(/^#{parent_namespace}::/,  prefix).gsub(/::/, ?_)
end

#ignored? ⇒ Boolean

Checks if the configuration setting is marked as ignored.

This method returns true if the setting has been explicitly marked to be ignored when reading values from environment variables, indicating that it should be skipped during configuration processing.

Returns:

  • (Boolean) —

    true if the setting is ignored, false otherwise



238
239
240
 
# File 'lib/const_conf/setting.rb', line 238

def ignored?
  !!ignored
end

#inspect ⇒ String

The inspect method returns a string representation of the object, with special handling for IRB colorization.

Returns:

  • (String) —

    the string representation of the object, optionally stripped of ANSI color codes when used in IRB with colorization enabled



382
383
384
385
386
387
388
 
# File 'lib/const_conf/setting.rb', line 382

def inspect
  if defined?(IRB) && IRB.conf[:USE_COLORIZE]
    Term::ANSIColor.uncolor(to_s)
  else
    to_s
  end
end

#inspect_original ⇒ Object

The original inspect method.



374
 
# File 'lib/const_conf/setting.rb', line 374

alias inspect_original inspect

#prefix ⇒ String?

The prefix reader accessor returns the configured prefix for the setting.

Returns:

  • (String, nil) —

    the prefix value, or nil if not set



46
47
 
# File 'lib/const_conf/setting.rb', line 46

setting_accessor :prefix,
transform: -> value { value.ask_and_send_or_self(:upcase) }

#required ⇒ Boolean, Proc

Sets whether the setting is required.

Parameters:

  • value (Boolean, Proc) —

    the value to set for the required flag

    • true/false: Simple boolean requirement check
    • Proc: Dynamic validation logic that can be evaluated in two ways:
      • With arity 1: Called with the setting's value (e.g., ->(value) { value.present? })
      • With arity 0: Called without arguments (e.g., -> { some_value.present? })

Returns:

  • (Boolean, Proc) —

    returns the value that was set @method required(value = nil, &block) @see #required?



145
 
# File 'lib/const_conf/setting.rb', line 145

setting_accessor :required, false

#required? ⇒ Boolean

Checks if the setting has a required value configured or as a default value.

This method evaluates whether the configuration setting is marked as required and determines if a valid value is present. It handles different forms of required specification including boolean flags and Proc objects that can perform dynamic validation based on the current value or context.

Returns:

  • (Boolean) —

    true if the setting is marked as required and has a valid value according to its validation logic, false otherwise



157
158
159
160
161
162
163
164
165
166
167
168
 
# File 'lib/const_conf/setting.rb', line 157

def required?
  !!case required
    when Proc
      if required.arity == 1
        required.(configured_value_or_default_value)
      else
        required.()
      end
    else
      required
    end
end

#sensitive ⇒ Boolean Also known as: sensitive?

Sets or retrieves the sensitive flag for the configuration setting.

When true, the setting's value is masked as 🤫 in the #view output to protect confidential data such as passwords, API keys, and tokens.

Parameters:

  • value (Boolean) —

    true to mark the setting as sensitive

Returns:

  • (Boolean) —

    the current sensitivity flag



177
 
# File 'lib/const_conf/setting.rb', line 177

setting_accessor :sensitive, false

#to_s ⇒ String

Returns the string representation of the tree structure.

This method generates a formatted string representation of the tree node and its children, including the node's name and any associated value, with proper indentation to show the hierarchical relationship between nodes.

Returns:

  • (String) —

    a multi-line string representation of the tree structure



367
368
369
370
371
 
# File 'lib/const_conf/setting.rb', line 367

def to_s
  io = StringIO.new
  view(io:)
  io.string
end

#value ⇒ Object

Retrieves the effective value for the configuration setting.

This method determines the appropriate value for the configuration setting by first checking if the setting is not ignored and an environment variable value is present. If so, it uses the environment variable value. Otherwise, it falls back to the default value. The resulting value is then passed through any configured decoding logic.

Returns:

  • (Object) —

    the effective configuration value after applying any decoding logic, or the default value if no environment variable is set



305
306
307
 
# File 'lib/const_conf/setting.rb', line 305

def value
  decoded_value(configured_value_or_default_value)
end

#value_provided? ⇒ Boolean

Checks if a configuration setting has been provided with a valid value.

value or a default value that is not nil, false otherwise

Returns:

  • (Boolean) —

    true if the setting has either an environment variable



129
130
131
 
# File 'lib/const_conf/setting.rb', line 129

def value_provided?
  !configured_value_or_default_value.nil?
end

#view(io: nil) ⇒ Object

Displays a textual representation of this configuration setting.

This method generates a formatted tree-like view of the current configuration setting, including its name, description, environment variable name, and associated metadata such as prefix, default value, and configuration status. The output can be directed to a specified IO object or displayed to the standard output.

Parameters:

  • io (IO, nil) (defaults to: nil) —

    the IO object to write the output to; if nil, uses STDOUT



356
357
358
 
# File 'lib/const_conf/setting.rb', line 356

def view(io: nil)
  parent_namespace.view(object: self, io:)
end