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

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

Class Method Summary collapse

Class Method Details

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

Adds a character to the favorites list.

Examples:

FavoritesManager.add_favorite("/path/to/data", "user123", "Hero", "game_001")

Parameters:

  • data_dir (String) —

    The directory where data is stored.

  • username (String) —

    The username associated with the character.

  • char_name (String) —

    The name of the character to add.

  • game_code (String) —

    The game code of the character.

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

    The frontend associated with the character (optional).

Returns:

  • (Boolean) —

    Returns true if the character was added successfully, false otherwise.

Raises:

  • (StandardError) —

    If an error occurs during the operation.



16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
 
# File 'documented/common/gui/favorites_manager.rb', line 16

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

  begin
    result = YamlState.add_favorite(data_dir, username, char_name, game_code, frontend)

    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 ID hash from the provided parameters.

Examples:

FavoritesManager.create_character_id("user123", "Hero", "game_001")

Parameters:

  • username (String) —

    The username associated with the character.

  • char_name (String) —

    The name of the character.

  • game_code (String) —

    The game code of the character.

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

    The frontend associated with the character (optional).

Returns:

  • (Hash) —

    A hash representing the character ID.



274
275
276
277
278
279
280
281
 
# File 'documented/common/gui/favorites_manager.rb', line 274

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 ID information from the provided entry data.

Examples:

FavoritesManager.extract_character_id({:user_id => "user123", :char_name => "Hero", :game_code => "game_001"})

Parameters:

  • entry_data (Hash) —

    The entry data containing character information.

Returns:

  • (Hash) —

    A hash representing the extracted character ID.



288
289
290
291
292
293
294
295
296
297
 
# File 'documented/common/gui/favorites_manager.rb', line 288

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 are available in the specified data directory.

Examples:

FavoritesManager.favorites_available?("/path/to/data")

Parameters:

  • data_dir (String) —

    The directory where data is stored.

Returns:

  • (Boolean) —

    Returns true if favorites are available, false otherwise.



304
305
306
307
308
309
 
# File 'documented/common/gui/favorites_manager.rb', line 304

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

  yaml_file = Lich::Common::GUI::YamlState.yaml_file_path(data_dir)
  File.exist?(yaml_file)
end

.favorites_count(data_dir) ⇒ Integer

Counts the number of favorites in the specified data directory.

Examples:

FavoritesManager.favorites_count("/path/to/data")

Parameters:

  • data_dir (String) —

    The directory where data is stored.

Returns:

  • (Integer) —

    The count of favorites.

Raises:

  • (StandardError) —

    If an error occurs during the operation.



165
166
167
168
169
170
171
172
173
174
 
# File 'documented/common/gui/favorites_manager.rb', line 165

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<Hash>

Retrieves all favorites for a specific account.

Examples:

FavoritesManager.("/path/to/data", "user123")

Parameters:

  • data_dir (String) —

    The directory where data is stored.

  • username (String) —

    The username associated with the account.

Returns:

  • (Array<Hash>) —

    An array of favorite characters for the account.

Raises:

  • (StandardError) —

    If an error occurs during the operation.



183
184
185
186
187
188
189
190
191
192
193
 
# File 'documented/common/gui/favorites_manager.rb', line 183

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<Hash>

Retrieves all favorites for a given data directory.

Examples:

FavoritesManager.get_all_favorites("/path/to/data")

Parameters:

  • data_dir (String) —

    The directory where data is stored.

Returns:

  • (Array<Hash>) —

    An array of favorite characters.

Raises:

  • (StandardError) —

    If an error occurs during the operation.



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

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

  begin
    YamlState.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<Hash>

Retrieves all favorites for a specific game.

Examples:

FavoritesManager.get_game_favorites("/path/to/data", "game_001")

Parameters:

  • data_dir (String) —

    The directory where data is stored.

  • game_code (String) —

    The game code to filter favorites.

Returns:

  • (Array<Hash>) —

    An array of favorite characters for the game.

Raises:

  • (StandardError) —

    If an error occurs during the operation.



202
203
204
205
206
207
208
209
210
211
212
 
# File 'documented/common/gui/favorites_manager.rb', line 202

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) ⇒ Boolean

Checks if a character is in the favorites list.

Examples:

FavoritesManager.is_favorite?("/path/to/data", "user123", "Hero", "game_001")

Parameters:

  • data_dir (String) —

    The directory where data is stored.

  • username (String) —

    The username associated with the character.

  • char_name (String) —

    The name of the character to check.

  • game_code (String) —

    The game code of the character.

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

    The frontend associated with the character (optional).

Returns:

  • (Boolean) —

    Returns true if the character is a favorite, false otherwise.

Raises:

  • (StandardError) —

    If an error occurs during the operation.



105
106
107
108
109
110
111
112
113
114
 
# File 'documented/common/gui/favorites_manager.rb', line 105

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

  begin
    YamlState.is_favorite?(data_dir, username, char_name, game_code, frontend)
  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) ⇒ Boolean

Removes a character from the favorites list.

Examples:

FavoritesManager.remove_favorite("/path/to/data", "user123", "Hero", "game_001")

Parameters:

  • data_dir (String) —

    The directory where data is stored.

  • username (String) —

    The username associated with the character.

  • char_name (String) —

    The name of the character to remove.

  • game_code (String) —

    The game code of the character.

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

    The frontend associated with the character (optional).

Returns:

  • (Boolean) —

    Returns true if the character was removed successfully, false otherwise.

Raises:

  • (StandardError) —

    If an error occurs during the operation.



47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
 
# File 'documented/common/gui/favorites_manager.rb', line 47

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

  begin
    result = YamlState.remove_favorite(data_dir, username, char_name, game_code, frontend)

    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 the favorites list based on the provided order.

Examples:

FavoritesManager.reorder_favorites("/path/to/data", [{:user_id => "user123", :char_name => "Hero", :game_code => "game_001"}])

Parameters:

  • data_dir (String) —

    The directory where data is stored.

  • ordered_favorites (Array<Hash>) —

    The ordered list of favorites.

Returns:

  • (Boolean) —

    Returns true if the reordering was successful, false otherwise.

Raises:

  • (StandardError) —

    If an error occurs during the operation.



140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
 
# File 'documented/common/gui/favorites_manager.rb', line 140

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

  begin
    result = YamlState.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) ⇒ Boolean

Toggles a character’s favorite status.

Examples:

FavoritesManager.toggle_favorite("/path/to/data", "user123", "Hero", "game_001")

Parameters:

  • data_dir (String) —

    The directory where data is stored.

  • username (String) —

    The username associated with the character.

  • char_name (String) —

    The name of the character to toggle.

  • game_code (String) —

    The game code of the character.

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

    The frontend associated with the character (optional).

Returns:

  • (Boolean) —

    Returns true if the character is now a favorite, false if it was removed.

Raises:

  • (StandardError) —

    If an error occurs during the operation.



78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
 
# File 'documented/common/gui/favorites_manager.rb', line 78

def self.toggle_favorite(data_dir, username, char_name, game_code, frontend = nil)
  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)
      remove_favorite(data_dir, username, char_name, game_code, frontend)
      false
    else
      add_favorite(data_dir, username, char_name, game_code, frontend)
      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 and cleans up orphaned favorites in the specified data directory.

Examples:

FavoritesManager.validate_and_cleanup_favorites("/path/to/data")

Parameters:

  • data_dir (String) —

    The directory where data is stored.

Returns:

  • (Hash) —

    A hash containing validation results and cleanup statistics.

Raises:

  • (StandardError) —

    If an error occurs during the operation.



220
221
222
223
224
225
226
227
228
229
230
231
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
 
# File 'documented/common/gui/favorites_manager.rb', line 220

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 = YamlState.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])
      end

      unless character_exists
        # Remove orphaned favorite
        if remove_favorite(data_dir, favorite[:user_id], favorite[:char_name], favorite[:game_code], favorite[:frontend])
          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