Class: Lich::Common::SetupFiles

Inherits:
Object
  • Object
show all
Includes:
MonitorMixin
Defined in:
documented/common/setup_files.rb

Overview

Manages YAML configuration file loading, caching, and cascading merge for lich scripts.

Supports:

  • Base YAML files (base.yaml, base-empty.yaml)
  • Character-specific YAML files (character-setup.yaml)
  • Include files with recursive resolution and circular dependency protection
  • Automatic caching with modification-time checking
  • Deep-clone protection against in-memory mutation

See Also:

Defined Under Namespace

Classes: FileInfo

Instance Method Summary collapse

Constructor Details

#initialize(debug = false) ⇒ void

Initializes a new SetupFiles instance.

Parameters:

  • debug (Boolean) (defaults to: false) —

    whether to enable debug logging



69
70
71
72
73
 
# File 'documented/common/setup_files.rb', line 69

def initialize(debug = false)
  super()
  @files_cache = {}
  @debug = debug
end

Instance Method Details

#get_data(type) ⇒ OpenStruct

Retrieves data for a specified type from the base YAML file.

Parameters:

  • type (String) —

    the type of data to retrieve

Returns:

  • (OpenStruct) —

    the data loaded from the YAML file



133
134
135
136
137
 
# File 'documented/common/setup_files.rb', line 133

def get_data(type)
  filename = to_base_filename(type)
  reload_data([filename])
  transform_data(cache_get_by_filename(filename)&.data)
end

#get_settings(character_suffixes = []) ⇒ Hash

Retrieves settings for the specified character suffixes.

Parameters:

  • character_suffixes (Array<String>) (defaults to: []) —

    an array of character suffixes to include

Returns:

  • (Hash) —

    the merged settings from all relevant YAML files



92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
 
# File 'documented/common/setup_files.rb', line 92

def get_settings(character_suffixes = [])
  character_suffixes = ['setup', character_suffixes].flatten.compact.uniq
  character_filenames = character_suffixes_to_filenames(character_suffixes)
  reload_profiles(character_filenames)

  initial_include_suffixes = character_filenames.reduce([]) do |result, filename|
    result + (cache_get_by_filename(filename)&.peek('include') || [])
  end
  initial_include_filenames = initial_include_suffixes.map { |suffix| to_include_filename(suffix) }
  include_filenames = resolve_includes_recursively(initial_include_filenames)
  safe_log "#{self.class}::#{__callee__} resolved include_filenames=#{include_filenames}" if @debug

  all_files = ['base.yaml', 'base-empty.yaml', include_filenames, character_filenames].flatten

  # Peek pass: collect union_keys from all files (always unioned across files).
  # Keys listed in union_keys get array union instead of overwrite during merge,
  # allowing includes and character files to contribute to shared lists.
  union_keys = all_files.reduce([]) do |keys, filename|
    file_keys = cache_get_by_filename(filename)&.peek('union_keys') || []
    (keys + file_keys).uniq
  end

  # Merge pass: union specified keys, overwrite everything else
  settings = all_files.reduce({}) do |result, filename|
    file_info = cache_get_by_filename(filename)
    result.merge(file_info ? file_info.data : {}) do |key, old_val, new_val|
      if union_keys.include?(key.to_s) && old_val.is_a?(Array) && new_val.is_a?(Array)
        (old_val + new_val).uniq
      else
        new_val
      end
    end
  end

  transform_settings(settings)
end

#reload ⇒ void

This method returns an undefined value.

Reloads the profiles and data for the SetupFiles instance.



141
142
143
144
 
# File 'documented/common/setup_files.rb', line 141

def reload
  reload_profiles(character_suffixes_to_filenames(['setup']))
  reload_data
end

#safe_load_yaml(filepath) ⇒ Hash

Safely loads a YAML file and returns its contents as a hash.

Parameters:

  • filepath (String) —

    the path to the YAML file

Returns:

  • (Hash) —

    the parsed YAML data

Raises:

  • (StandardError) —

    if there is an error parsing the YAML file



80
81
82
83
84
85
86
 
# File 'documented/common/setup_files.rb', line 80

def safe_load_yaml(filepath)
  OpenStruct.new(YAML.unsafe_load_file(filepath)).to_h
rescue => e
  safe_message("bold", "*** ERROR PARSING YAML FILE ***")
  safe_message("bold", e.message)
  {}
end