Module: Lich::Common::GUI::FavoritesManager

Defined in:
documented/common/gui/favorites_manager.rb

Overview

Manages favorites-related operations for the Lich GUI login system Provides a high-level interface for favorites management operations following the established patterns from AccountManager

Class Method Summary collapse

Class Method Details

.add_favorite(data_dir, username, char_name, game_code, frontend = nil, custom_launch = :__unset) ⇒ Boolean

Adds a character to the favorites list Marks the specified character as a favorite with proper ordering

Parameters:

  • data_dir (String) —

    Directory containing entry data

  • username (String) —

    Account username

  • char_name (String) —

    Character name

  • game_code (String) —

    Game code

  • frontend (String) (defaults to: nil) —

    Frontend identifier (optional for backward compatibility)

  • custom_launch (String, nil, Symbol) (defaults to: :__unset) —

    Exact custom launch command, or :__unset for legacy matching

Returns:

  • (Boolean) —

    True if operation was successful



34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
 
# File 'documented/common/gui/favorites_manager.rb', line 34

def self.add_favorite(data_dir, username, char_name, game_code, frontend = nil, custom_launch = :__unset)
  return false if data_dir.nil? || username.nil? || char_name.nil? || game_code.nil?

  begin
    result = Lich::Common::Authentication::EntryStore.add_favorite(data_dir, username, char_name, game_code, frontend, custom_launch)

    if result
      frontend_info = frontend ? " (#{frontend})" : ""
      Lich.log "info: Added character '#{char_name}' (#{game_code})#{frontend_info} from account '#{username}' to favorites"
    else
      frontend_info = frontend ? " (#{frontend})" : ""
      Lich.log "warning: Failed to add character '#{char_name}' (#{game_code})#{frontend_info} from account '#{username}' to favorites"
    end

    result
  rescue StandardError => e
    Lich.log "error: Error in FavoritesManager.add_favorite: #{e.message}"
    false
  end
end

.create_character_id(username, char_name, game_code, frontend = nil) ⇒ Hash

Creates a character identifier hash for favorites operations Provides a consistent way to identify characters across favorites operations

Parameters:

  • username (String) —

    Account username

  • char_name (String) —

    Character name

  • game_code (String) —

    Game code

  • frontend (String) (defaults to: nil) —

    Frontend identifier (optional)

Returns:

  • (Hash) —

    Character identifier hash



294
295
296
297
298
299
300
301
 
# File 'documented/common/gui/favorites_manager.rb', line 294

def self.create_character_id(username, char_name, game_code, frontend = nil)
  {
    username: username,
    char_name: char_name,
    game_code: game_code,
    frontend: frontend
  }
end

.extract_character_id(entry_data) ⇒ Hash

Extracts character identifier from entry data Converts entry data hash to character identifier format

Parameters:

  • entry_data (Hash) —

    Character entry data

Returns:

  • (Hash) —

    Character identifier hash



308
309
310
311
312
313
314
315
316
317
 
# File 'documented/common/gui/favorites_manager.rb', line 308

def self.extract_character_id(entry_data)
  return {} unless entry_data.is_a?(Hash)

  {
    username: entry_data[:user_id],
    char_name: entry_data[:char_name],
    game_code: entry_data[:game_code],
    frontend: entry_data[:frontend]
  }
end

.favorites_available?(data_dir) ⇒ Boolean

Checks if favorites functionality is available Verifies that the data directory and required files exist

Parameters:

  • data_dir (String) —

    Directory containing entry data

Returns:

  • (Boolean) —

    True if favorites functionality is available



324
325
326
327
328
329
 
# File 'documented/common/gui/favorites_manager.rb', line 324

def self.favorites_available?(data_dir)
  return false if data_dir.nil?

  yaml_file = Lich::Common::Authentication::EntryStore.yaml_file_path(data_dir)
  File.exist?(yaml_file)
end

.favorites_count(data_dir) ⇒ Integer

Gets the count of favorite characters Returns the total number of characters marked as favorites

Parameters:

  • data_dir (String) —

    Directory containing entry data

Returns:

  • (Integer) —

    Number of favorite characters



180
181
182
183
184
185
186
187
188
189
 
# File 'documented/common/gui/favorites_manager.rb', line 180

def self.favorites_count(data_dir)
  return 0 if data_dir.nil?

  begin
    get_all_favorites(data_dir).length
  rescue StandardError => e
    Lich.log "error: Error in FavoritesManager.favorites_count: #{e.message}"
    0
  end
end

.get_account_favorites(data_dir, username) ⇒ Array

Gets favorites for a specific account Returns an array of favorite characters for the specified account

Parameters:

  • data_dir (String) —

    Directory containing entry data

  • username (String) —

    Account username

Returns:

  • (Array) —

    Array of favorite character data for the account



197
198
199
200
201
202
203
204
205
206
207
 
# File 'documented/common/gui/favorites_manager.rb', line 197

def self.(data_dir, username)
  return [] if data_dir.nil? || username.nil?

  begin
    all_favorites = get_all_favorites(data_dir)
    all_favorites.select { |fav| fav[:user_id] == username }
  rescue StandardError => e
    Lich.log "error: Error in FavoritesManager.get_account_favorites: #{e.message}"
    []
  end
end

.get_all_favorites(data_dir) ⇒ Array

Gets all favorite characters across all accounts Returns an array of favorite characters sorted by favorite order

Parameters:

  • data_dir (String) —

    Directory containing entry data

Returns:

  • (Array) —

    Array of favorite character data in legacy format



139
140
141
142
143
144
145
146
147
148
 
# File 'documented/common/gui/favorites_manager.rb', line 139

def self.get_all_favorites(data_dir)
  return [] if data_dir.nil?

  begin
    Lich::Common::Authentication::EntryStore.get_favorites(data_dir)
  rescue StandardError => e
    Lich.log "error: Error in FavoritesManager.get_all_favorites: #{e.message}"
    []
  end
end

.get_game_favorites(data_dir, game_code) ⇒ Array

Gets favorites for a specific game Returns an array of favorite characters for the specified game

Parameters:

  • data_dir (String) —

    Directory containing entry data

  • game_code (String) —

    Game code

Returns:

  • (Array) —

    Array of favorite character data for the game



215
216
217
218
219
220
221
222
223
224
225
 
# File 'documented/common/gui/favorites_manager.rb', line 215

def self.get_game_favorites(data_dir, game_code)
  return [] if data_dir.nil? || game_code.nil?

  begin
    all_favorites = get_all_favorites(data_dir)
    all_favorites.select { |fav| fav[:game_code] == game_code }
  rescue StandardError => e
    Lich.log "error: Error in FavoritesManager.get_game_favorites: #{e.message}"
    []
  end
end

.is_favorite?(data_dir, username, char_name, game_code, frontend = nil, custom_launch = :__unset) ⇒ Boolean

Checks if a character is marked as a favorite Returns true if the specified character is in the favorites list

Parameters:

  • data_dir (String) —

    Directory containing entry data

  • username (String) —

    Account username

  • char_name (String) —

    Character name

  • game_code (String) —

    Game code

  • frontend (String) (defaults to: nil) —

    Frontend identifier (optional for backward compatibility)

  • custom_launch (String, nil, Symbol) (defaults to: :__unset) —

    Exact custom launch command, or :__unset for legacy matching

Returns:

  • (Boolean) —

    True if character is a favorite



123
124
125
126
127
128
129
130
131
132
 
# File 'documented/common/gui/favorites_manager.rb', line 123

def self.is_favorite?(data_dir, username, char_name, game_code, frontend = nil, custom_launch = :__unset)
  return false if data_dir.nil? || username.nil? || char_name.nil? || game_code.nil?

  begin
    Lich::Common::Authentication::EntryStore.is_favorite?(data_dir, username, char_name, game_code, frontend, custom_launch)
  rescue StandardError => e
    Lich.log "error: Error in FavoritesManager.is_favorite?: #{e.message}"
    false
  end
end

.remove_favorite(data_dir, username, char_name, game_code, frontend = nil, custom_launch = :__unset) ⇒ Boolean

Removes a character from the favorites list Unmarks the specified character as a favorite and reorders remaining favorites

Parameters:

  • data_dir (String) —

    Directory containing entry data

  • username (String) —

    Account username

  • char_name (String) —

    Character name

  • game_code (String) —

    Game code

  • frontend (String) (defaults to: nil) —

    Frontend identifier (optional for backward compatibility)

  • custom_launch (String, nil, Symbol) (defaults to: :__unset) —

    Exact custom launch command, or :__unset for legacy matching

Returns:

  • (Boolean) —

    True if operation was successful



65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
 
# File 'documented/common/gui/favorites_manager.rb', line 65

def self.remove_favorite(data_dir, username, char_name, game_code, frontend = nil, custom_launch = :__unset)
  return false if data_dir.nil? || username.nil? || char_name.nil? || game_code.nil?

  begin
    result = Lich::Common::Authentication::EntryStore.remove_favorite(data_dir, username, char_name, game_code, frontend, custom_launch)

    if result
      frontend_info = frontend ? " (#{frontend})" : ""
      Lich.log "info: Removed character '#{char_name}' (#{game_code})#{frontend_info} from account '#{username}' from favorites"
    else
      frontend_info = frontend ? " (#{frontend})" : ""
      Lich.log "warning: Failed to remove character '#{char_name}' (#{game_code})#{frontend_info} from account '#{username}' from favorites"
    end

    result
  rescue StandardError => e
    Lich.log "error: Error in FavoritesManager.remove_favorite: #{e.message}"
    false
  end
end

.reorder_favorites(data_dir, ordered_favorites) ⇒ Boolean

Reorders favorites based on provided character list Updates the favorite order for all favorites based on new ordering

Parameters:

  • data_dir (String) —

    Directory containing entry data

  • ordered_favorites (Array) —

    Array of hashes with username, char_name, game_code

Returns:

  • (Boolean) —

    True if operation was successful



156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
 
# File 'documented/common/gui/favorites_manager.rb', line 156

def self.reorder_favorites(data_dir, ordered_favorites)
  return false if data_dir.nil? || ordered_favorites.nil?

  begin
    result = Lich::Common::Authentication::EntryStore.reorder_favorites(data_dir, ordered_favorites)

    if result
      Lich.log "info: Successfully reordered #{ordered_favorites.length} favorites"
    else
      Lich.log "warning: Failed to reorder favorites"
    end

    result
  rescue StandardError => e
    Lich.log "error: Error in FavoritesManager.reorder_favorites: #{e.message}"
    false
  end
end

.toggle_favorite(data_dir, username, char_name, game_code, frontend = nil, custom_launch = :__unset) ⇒ Boolean

Toggles the favorite status of a character Adds to favorites if not currently a favorite, removes if it is a favorite

Parameters:

  • data_dir (String) —

    Directory containing entry data

  • username (String) —

    Account username

  • char_name (String) —

    Character name

  • game_code (String) —

    Game code

  • frontend (String) (defaults to: nil) —

    Frontend identifier (optional for backward compatibility)

  • custom_launch (String, nil, Symbol) (defaults to: :__unset) —

    Exact custom launch command, or :__unset for legacy matching

Returns:

  • (Boolean) —

    True if character is now a favorite, false if not



96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
 
# File 'documented/common/gui/favorites_manager.rb', line 96

def self.toggle_favorite(data_dir, username, char_name, game_code, frontend = nil, custom_launch = :__unset)
  return false if data_dir.nil? || username.nil? || char_name.nil? || game_code.nil?

  begin
    if is_favorite?(data_dir, username, char_name, game_code, frontend, custom_launch)
      remove_favorite(data_dir, username, char_name, game_code, frontend, custom_launch)
      false
    else
      add_favorite(data_dir, username, char_name, game_code, frontend, custom_launch)
      true
    end
  rescue StandardError => e
    Lich.log "error: Error in FavoritesManager.toggle_favorite: #{e.message}"
    false
  end
end

.validate_and_cleanup_favorites(data_dir) ⇒ Hash

Validates favorites data integrity Checks that all favorites reference valid characters and removes orphaned favorites

Parameters:

  • data_dir (String) —

    Directory containing entry data

Returns:

  • (Hash) —

    Hash with validation results and cleanup statistics



232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
 
# File 'documented/common/gui/favorites_manager.rb', line 232

def self.validate_and_cleanup_favorites(data_dir)
  return { valid: false, cleaned: 0, errors: ['Invalid data directory'] } if data_dir.nil?

  begin
    # Load all entry data to validate against
    entry_data = Lich::Common::Authentication::EntryStore.load_saved_entries(data_dir, false)
    favorites = get_all_favorites(data_dir)

    cleaned_count = 0
    errors = []

    favorites.each do |favorite|
      # Check if the character still exists in the entry data
      character_exists = entry_data.any? do |entry|
        entry[:user_id] == favorite[:user_id] &&
          entry[:char_name] == favorite[:char_name] &&
          entry[:game_code] == favorite[:game_code] &&
          (favorite[:frontend].nil? || entry[:frontend] == favorite[:frontend]) &&
          entry[:custom_launch] == favorite[:custom_launch]
      end

      unless character_exists
        # Remove orphaned favorite
        if remove_favorite(
          data_dir,
          favorite[:user_id],
          favorite[:char_name],
          favorite[:game_code],
          favorite[:frontend],
          favorite[:custom_launch]
        )
          cleaned_count += 1
          frontend_info = favorite[:frontend] ? " (#{favorite[:frontend]})" : ""
          Lich.log "info: Removed orphaned favorite: #{favorite[:char_name]} (#{favorite[:game_code]})#{frontend_info} from #{favorite[:user_id]}"
        else
          frontend_info = favorite[:frontend] ? " (#{favorite[:frontend]})" : ""
          errors << "Failed to remove orphaned favorite: #{favorite[:char_name]} (#{favorite[:game_code]})#{frontend_info} from #{favorite[:user_id]}"
        end
      end
    end

    {
      valid: true,
      total_favorites: favorites.length,
      cleaned: cleaned_count,
      remaining: favorites.length - cleaned_count,
      errors: errors
    }
  rescue StandardError => e
    Lich.log "error: Error in FavoritesManager.validate_and_cleanup_favorites: #{e.message}"
    { valid: false, cleaned: 0, errors: [e.message] }
  end
end