Class: ConstConf::Tree

Inherits:
Object
  • Object
show all
Extended by:
Term::ANSIColor
Defined in:
lib/const_conf/tree.rb

Overview

A tree structure implementation for visualizing ConstConf configuration hierarchies.

The Tree class provides a hierarchical representation of ConstConf modules and settings, allowing for formatted display of configuration data with metadata including prefixes, environment variable names, default values, and configuration status. It supports colored output and proper indentation to show the relationships between nested configuration elements.

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(name, utf8: default_utf8) ⇒ Tree

Initializes a new tree node with the given name, and UTF-8 support flag.

be used for display

Parameters:

  • name (String) —

    the name of the tree node

  • utf8 (Boolean) (defaults to: default_utf8) —

    flag indicating whether UTF-8 characters should



156
157
158
159
160
 
# File 'lib/const_conf/tree.rb', line 156

def initialize(name, utf8: default_utf8)
  @name     = name
  @utf8     = utf8
  @children = []
end

Class Method Details

.configuration?(object) ⇒ Boolean (private)

Checks whether the given object is a ConstConf module.

This method determines if the provided object is a Module that includes the ConstConf concern. It returns true if the object meets these criteria, and false otherwise. In case a NameError occurs during the check, it gracefully returns false.

otherwise

Parameters:

  • object (Object) —

    the object to be checked

Returns:

  • (Boolean) —

    true if the object is a ConstConf module, false



54
55
56
57
58
 
# File 'lib/const_conf/tree.rb', line 54

def configuration?(object)
  object.is_a?(Module) && object < ConstConf
rescue NameError
  false
end

.convert_module(modul) ⇒ ConstConf::Tree (private)

Converts a ConstConf module into a tree-like structure for display purposes.

This method transforms a module that includes ConstConf configuration settings into a hierarchical tree representation. It captures the module’s name, description, prefix, and number of settings, then recursively processes nested modules and individual settings to build a complete configuration tree.

structure configuration hierarchy

Parameters:

  • modul (Module) —

    the ConstConf module to convert into a tree

Returns:



73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
 
# File 'lib/const_conf/tree.rb', line 73

def convert_module(modul)
  desc = "#{modul.description.full? { italic(' # %s' % _1) }}"
  obj  = new("#{modul.name}#{desc}")
  obj << new("prefix #{modul.prefix.inspect}")
  obj << new("#{modul.settings.size} settings")

  modul.settings.each do |env_var, setting|
    obj << convert_setting(setting)
  end

  modul.nested_module_constants.each do |const_name|
    begin
      const = modul.const_get(const_name)
      if const.is_a?(Module) && const < ConstConf
        obj << convert_module(const)
      end
    rescue NameError
    end
  end

  obj
end

.convert_setting(setting) ⇒ ConstConf::Tree (private)

Converts a configuration setting into a tree node with detailed information.

This method transforms a given configuration setting into a hierarchical representation, including its name, description, and various metadata such as environment variable name, prefix, default value, and configuration status.

Parameters:

Returns:



107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
 
# File 'lib/const_conf/tree.rb', line 107

def convert_setting(setting)
  desc = "#{setting.description.full? { italic(' # %s' % _1) }}"
  obj  = new("#{bold(setting.name)}#{desc}")

  length = (Tins::Terminal.columns / 4).clamp(20..)
  truncater = -> v { v&.to_s&.truncate_bytes(length) }

  censored = -> s { s.sensitive? ? Tins::NullPlus.new(inspect: '🤫') : s }

  checker = -> r {
    case r
    when false, nil
      '❌'
    when :unchecked_true
      '☑️ '
    else
      '✅'
    end
  }

  setting_info = <<~EOT
    prefix          #{setting.prefix.inspect}
    env var name    #{setting.env_var_name}
    env var (orig.) #{truncater.(censored.(setting).env_var.inspect)}
    default         #{truncater.(censored.(setting).default_value.inspect)}
    value           #{bold { truncater.(censored.(setting).value.inspect) }}
    sensitive       #{setting.sensitive? ? '🔒' : '⚪'}
    required        #{setting.required? ? '🔴' : '⚪'}
    configured      #{setting.configured? ? '🔧' : '⚪' }
    ignored         #{setting.ignored? ? '🙈' : '⚪'}
    active          #{setting.active? ? '🟢' : '⚪'}
    decoding        #{setting.decoding? ? '⚙️' : '⚪'}
    checked         #{checker.(setting.checked?)}
  EOT

  setting_info.each_line do |line|
    obj << new(line.chomp)
  end

  obj
end

.from_const_conf(configuration_or_setting) ⇒ ConstConf::Tree

Converts a ConstConf configuration or setting into a tree structure for display purposes.

This method takes either a ConstConf module or a specific setting and transforms it into a hierarchical tree representation that can be used for visualization or debugging. It delegates to specialized conversion methods based on the type of the input argument.

setting to convert

hierarchy

nor a ConstConf::Setting instance

Parameters:

  • configuration_or_setting (Object) —

    the ConstConf module or

Returns:

Raises:

  • (ArgumentError) —

    if the argument is neither a ConstConf module



30
31
32
33
34
35
36
37
38
39
 
# File 'lib/const_conf/tree.rb', line 30

def from_const_conf(configuration_or_setting)
  if configuration?(configuration_or_setting)
    convert_module(configuration_or_setting)
  elsif configuration_or_setting.is_a?(ConstConf::Setting)
    convert_setting(configuration_or_setting)
  else
    raise ArgumentError,
      "argument needs to have type ConstConf::Setting or ConstConf"
  end
end

Instance Method Details

#<<(child) ⇒ Array<ConstConf::Tree>

Adds a child node to this tree node’s collection of children.

Parameters:

Returns:



180
181
182
 
# File 'lib/const_conf/tree.rb', line 180

def <<(child)
  @children << child
end

#default_utf8 ⇒ Boolean

Checks whether UTF-8 encoding is indicated in the LANG environment variable.

This method examines the LANG environment variable to determine if it contains a UTF-8 encoding indicator, returning true if UTF-8 is detected and false otherwise.

encoding, false otherwise

Returns:

  • (Boolean) —

    true if the LANG environment variable indicates UTF-8



171
172
173
 
# File 'lib/const_conf/tree.rb', line 171

def default_utf8
  !!(ENV['LANG'] =~ /utf-8\z/i)
end

#inner_child_prefix(i) ⇒ String (private)

Returns the appropriate prefix string for a child node in a tree display.

This method determines the correct visual prefix to use when rendering tree nodes, based on whether UTF-8 encoding is enabled and if the current child is the first one in a group of siblings.

Parameters:

  • i (Integer) —

    the index of the child node in its parent’s children list

Returns:

  • (String) —

    the visual prefix string for the child node



239
240
241
242
243
244
245
 
# File 'lib/const_conf/tree.rb', line 239

def inner_child_prefix(i)
  if @utf8
    i.zero? ? "├─ " : "│  "
  else
    i.zero? ? "+- " : "|  "
  end
end

#last_child_prefix(i) ⇒ String (private)

Returns the appropriate prefix string for the last child node in a tree display.

This method determines the correct visual prefix to use when rendering the final child node in a hierarchical tree structure, based on whether UTF-8 encoding is enabled and if the current child is the first one in a group of siblings.

Parameters:

  • i (Integer) —

    the index of the child node in its parent’s children list

Returns:

  • (String) —

    the visual prefix string for the last child node



257
258
259
260
261
262
263
 
# File 'lib/const_conf/tree.rb', line 257

def last_child_prefix(i)
  if @utf8
    i.zero? ? "└─ " : "   "
  else
    i.zero? ? "`- " : "   "
  end
end

#to_ary ⇒ Array<String> Also known as: to_a

Converts the tree node into an array representation.

the tree node and its children

Returns:

  • (Array<String>) —

    an array containing the string representations of



212
213
214
 
# File 'lib/const_conf/tree.rb', line 212

def to_ary
  to_enum.to_a
end

#to_enum ⇒ Enumerator

Returns an enumerator that yields the tree node’s name, followed by its children in a hierarchical format.

Returns:

  • (Enumerator) —

    an enumerator that provides the tree structure as a sequence of strings representing nodes and their relationships



189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
 
# File 'lib/const_conf/tree.rb', line 189

def to_enum
  Enumerator.new do |y|
    y.yield @name

    @children.each_with_index do |child, child_index|
      children_enum = child.to_enum
      if child_index < @children.size - 1
        children_enum.each_with_index do |setting, i|
          y.yield "#{inner_child_prefix(i)}#{setting}"
        end
      else
        children_enum.each_with_index do |setting, i|
          y.yield "#{last_child_prefix(i)}#{setting}"
        end
      end
    end
  end
end

#to_s ⇒ String

Returns the string representation of the tree structure.

This method converts the tree node and its children into a formatted string, where each node is represented on its own line with appropriate indentation to show the hierarchical relationship between nodes.

Returns:

  • (String) —

    a multi-line string representation of the tree structure



225
226
227
 
# File 'lib/const_conf/tree.rb', line 225

def to_s
  to_ary * ?\n
end