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

true, # false or false if not. I no check was defined, returns :unchecked_true. @see check

Returns:

  • (Boolean, Symbol) —

    true if the setting’s check logic evaluates to



105
106
107
 
# File 'lib/const_conf/setting.rb', line 105

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



265
266
267
 
# File 'lib/const_conf/setting.rb', line 265

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



247
248
249
250
251
252
253
254
255
 
# File 'lib/const_conf/setting.rb', line 247

def configured_value
  if ignored
    nil
  elsif env_var.nil?
    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



274
275
276
 
# File 'lib/const_conf/setting.rb', line 274

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:



308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
 
# File 'lib/const_conf/setting.rb', line 308

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:



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

setting_accessor :decode

#decoded_value(value_arg) ⇒ Object (private)

Decodes a value using the configured decoder if present, otherwise returns the value as-is.

configured

Parameters:

  • value_arg (Object) —

    the value to be decoded

Returns:

  • (Object) —

    the decoded value or the original value if no decoding is



378
379
380
381
382
383
384
 
# File 'lib/const_conf/setting.rb', line 378

def decoded_value(value_arg)
  if decode.is_a?(Proc)
    decode.(value_arg)
  else
    value_arg
  end
end

#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



181
182
183
 
# File 'lib/const_conf/setting.rb', line 181

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



196
197
198
199
200
201
202
203
 
# File 'lib/const_conf/setting.rb', line 196

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



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

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,



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

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



228
229
230
231
 
# File 'lib/const_conf/setting.rb', line 228

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



219
220
221
 
# File 'lib/const_conf/setting.rb', line 219

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



363
364
365
366
367
368
369
 
# File 'lib/const_conf/setting.rb', line 363

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.



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

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(value = nil, &block) ⇒ Boolean, Proc

Sets whether the setting is required.

Parameters:

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

    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

See Also:



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

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



141
142
143
144
145
146
147
148
149
150
151
152
 
# File 'lib/const_conf/setting.rb', line 141

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?

Checks if the setting has a required value configured.

value, false otherwise

Returns:

  • (Boolean) —

    true if the setting is marked as required and has a valid



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

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



348
349
350
351
352
 
# File 'lib/const_conf/setting.rb', line 348

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



288
289
290
 
# File 'lib/const_conf/setting.rb', line 288

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



113
114
115
 
# File 'lib/const_conf/setting.rb', line 113

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



337
338
339
 
# File 'lib/const_conf/setting.rb', line 337

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