rgss_db 1.0.0

data/lib/rgss_db/model/data_file.rb

@@ -0,0 +1,516 @@
+# frozen_string_literal: true
+
+module RgssDb
+  # Label used for data files that allows objects selection
+  # @return [String]
+  DATA_FILE_CUSTOM_LABEL = "_custom"
+
+  # RPG Maker actors data file (glob pattern)
+  # @return [String]
+  DATA_FILE_ACTORS = "Actors"
+
+  # RPG Maker animations data file (glob pattern)
+  # @return [String]
+  DATA_FILE_ANIMATIONS = "Animations"
+
+  # RPG Maker areas data file (glob pattern)
+  # @return [String]
+  DATA_FILE_AREAS = "Areas"
+
+  # RPG Maker armors data file (glob pattern)
+  # @return [String]
+  DATA_FILE_ARMORS = "Armors"
+
+  # RPG Maker classes data file (glob pattern)
+  # @return [String]
+  DATA_FILE_CLASSES = "Classes"
+
+  # RPG Maker common events data file (glob pattern)
+  # @return [String]
+  DATA_FILE_COMMON_EVENTS = "CommonEvents"
+
+  # RPG Maker enemies data file (glob pattern)
+  # @return [String]
+  DATA_FILE_ENEMIES = "Enemies"
+
+  # RPG Maker items data file (glob pattern)
+  # @return [String]
+  DATA_FILE_ITEMS = "Items"
+
+  # RPG Maker maps data file (glob pattern)
+  # @return [String]
+  DATA_FILE_MAPS = "Map[0-9][0-9][1-9]"
+
+  # RPG Maker map infos data file (glob pattern)
+  # @return [String]
+  DATA_FILE_MAP_INFOS = "MapInfos"
+
+  # RPG Maker skills data file (glob pattern)
+  # @return [String]
+  DATA_FILE_SKILLS = "Skills"
+
+  # RPG Maker states data file (glob pattern)
+  # @return [String]
+  DATA_FILE_STATES = "States"
+
+  # RPG Maker system data file (glob pattern)
+  # @return [String]
+  DATA_FILE_SYSTEM = "System"
+
+  # RPG Maker tilesets data file (glob pattern)
+  # @return [String]
+  DATA_FILE_TILESETS = "Tilesets"
+
+  # RPG Maker troops data file (glob pattern)
+  # @return [String]
+  DATA_FILE_TROOPS = "Troops"
+
+  # RPG Maker weapons data file (glob pattern)
+  # @return [String]
+  DATA_FILE_WEAPONS = "Weapons"
+
+  #
+  # RPG Maker base data file
+  #
+  # This class saves the object as is, without any treatment
+  #
+  class DataFile
+    include Comparable
+
+    # Data file type
+    # @return [String]
+    attr_reader :type
+
+    # Data file path
+    # @return [String]
+    attr_reader :file_path
+
+    # Data file object IDs list
+    # @return [Array<Integer>]
+    attr_reader :object_ids
+
+    # Data file object (not processed)
+    # @return [Object]
+    attr_reader :object
+
+    #
+    # Constructor
+    #
+    # @param type [String] Data file type
+    # @param file_path [String] Data file path
+    # @param object [Object] Data file object
+    #
+    def initialize(type, file_path, object)
+      @type = type
+      @file_path = file_path
+      @object = object
+      @object_ids = []
+    end
+
+    #
+    # Checks if the given file matches this data file path
+    #
+    # The check is case insensitive
+    #
+    # @param [String] file File path
+    #
+    # @return [Boolean]
+    #
+    def file_path?(file)
+      @file_path.casecmp?(file)
+    end
+
+    #
+    # Checks if the given file base name matches this data file base name
+    #
+    # The check is case insensitive
+    #
+    # @param file [String] File path
+    #
+    # @return [Boolean]
+    #
+    def file?(file)
+      File.basename(@file_path).casecmp?(File.basename(file))
+    end
+
+    #
+    # Checks if the given data type matches this data file type
+    #
+    # The check is case insensitive
+    #
+    # @param [String] data_type
+    #
+    # @return [Boolean]
+    #
+    def type?(data_type)
+      File.fnmatch(@type, data_type, File::FNM_CASEFOLD)
+    end
+
+    #
+    # Checks whether this data file instance supports object selection or not
+    #
+    # @return [Boolean]
+    #
+    def customizable?
+      !to_list.nil?
+    end
+
+    #
+    # Checks whether this data file instance is mergeable or not
+    #
+    # @return [Boolean]
+    #
+    def mergeable?
+      !to_merge.nil?
+    end
+
+    #
+    # Checks whether all objects are included in the serialization process
+    #
+    # @return [Boolean]
+    #
+    def all_objects?
+      true
+    end
+
+    #
+    # Updates the list of object IDs for this data file
+    #
+    # Any duped ID is auto. removed from the list
+    #
+    # @param object_ids [Array<Integer>]
+    #
+    def object_ids_update(*object_ids)
+      @object_ids = object_ids.flatten.uniq
+    end
+
+    #
+    # Clears the current list of object IDs
+    #
+    def object_ids_clear
+      @object_ids.clear
+    end
+
+    #
+    # Gets the data file name
+    #
+    # @return [String]
+    #
+    def file
+      File.basename(@file_path)
+    end
+
+    #
+    # Process the data file's file name for serialization
+    #
+    # The extension is automatically removed
+    #
+    # @return [String]
+    #
+    def serialize_file_name
+      base_name = File.basename(@file_path, ".*")
+      if all_objects?
+        base_name
+      else
+        base_name.concat(DATA_FILE_CUSTOM_LABEL)
+      end
+    end
+
+    #
+    # Merges the given data file contents with this data file
+    #
+    # @param [DataFile] data_file
+    #
+    # @raise [StandardError] Data file cannot be merged
+    #
+    def merge(data_file)
+      raise "cannot merge data file: '#{data_file}' because it is not supported!"
+    end
+
+    #
+    # Serializes the data file's object
+    #
+    # This method performs the necessary logic to the object for serialization
+    #
+    # By default, it returns the object as is
+    #
+    # @return [Object]
+    #
+    def serialize
+      @object
+    end
+
+    #
+    # Converts the given object list to object IDs for this data file
+    #
+    # The given list must be instances of this data file's contents
+    #
+    # By default it returns an empty array
+    #
+    # @param list [Array] List of objects
+    #
+    # @return [Array<Integer>]
+    #
+    def convert_list_to_ids(list)
+      []
+    end
+
+    #
+    # Gets a list of objects prepared to be merged
+    #
+    # Returns ``nil`` by default
+    #
+    # @return [Array<Object>]
+    #
+    def to_merge
+      nil
+    end
+
+    #
+    # Gets a list of objects to perform a selection
+    #
+    # If the data file does not allow this behavior it returns ``nil``
+    #
+    # Returns ``nil`` by default
+    #
+    # @return [Array<Object>]
+    #
+    def to_list
+      nil
+    end
+
+    #
+    # Converts this instance to a string
+    #
+    # @return [String]
+    #
+    def to_s
+      File.basename(@file_path)
+    end
+
+    #
+    # Comparable operator (case insensitive)
+    #
+    # @param [Object] other Other
+    #
+    # @return [Integer]
+    #
+    def <=>(other)
+      return @file_path.downcase <=> other.file_path.downcase if other.is_a?(DataFile)
+
+      @file_path.downcase <=> other.downcase if other.is_a?(String)
+    end
+  end
+
+  #
+  # RPG Maker array data file
+  #
+  # This class expects the object to be an array
+  #
+  class DataFileArray < DataFile
+    # Data file object (not processed)
+    # @return [Array]
+    attr_reader :object
+
+    #
+    # Checks whether all objects are included in the serialization process
+    #
+    # @return [Boolean]
+    #
+    def all_objects?
+      object_ids.empty? || object_ids.size == object.compact.size
+    end
+
+    #
+    # Merges the given data file contents with this data file
+    #
+    # @param [DataFile] data_file
+    #
+    # @raise [StandardError] Data file cannot be merged
+    #
+    def merge(data_file)
+      raise "cannot merge data file: '#{data_file}' because it is not supported!" unless data_file.is_a?(DataFileArray)
+
+      object.push(*data_file.to_merge)
+    end
+
+    #
+    # Serializes the data file's object
+    #
+    # This method prepares the object as an array
+    #
+    # The first element is always ``nil`` (required for RPG Maker)
+    #
+    # Object IDs list is used to filter the selected items on the data file
+    #
+    # @return [Array<Object>]
+    #
+    def serialize
+      # Applies the selected object IDs (if any)
+      processed_object = all_objects? ? object.dup : object.dup.values_at(*object_ids)
+
+      # Returns the formatted object (with a safe-check)
+      processed_object.first.nil? ? processed_object : processed_object.unshift(nil)
+    end
+
+    #
+    # Converts the given object list to object IDs for this data file
+    #
+    # The given list must be instances of this data file's array
+    #
+    # @param list [Array] List of objects
+    #
+    # @return [Array<Integer>]
+    #
+    def convert_list_to_ids(list)
+      list.map { |i| object.index(i) }
+    end
+
+    #
+    # Gets a list of objects prepared to be merged
+    #
+    # @return [Array<Object>]
+    #
+    def to_merge
+      object.compact
+    end
+
+    #
+    # Gets a list of objects to perform a selection
+    #
+    # @return [Array<Object>]
+    #
+    def to_list
+      # Data files needs to be compacted because TTY does not allow to create zero index based lists
+      # for some data files, the first element is nil because they are created in RPG Maker database starting at 1
+      # If this array is not compacted, it will cause an index mismatch later when selecting objects
+      object.compact
+    end
+  end
+
+  #
+  # RPG Maker hash data file
+  #
+  # This class expects the object to be a hash
+  #
+  class DataFileHash < DataFile
+    # Data file object (not processed)
+    # @return [Hash]
+    attr_reader :object
+
+    #
+    # Checks whether all objects are included in the serialization process
+    #
+    # @return [Boolean]
+    #
+    def all_objects?
+      object_ids.empty? || object.all? { |key, value| object_ids.include?(key) }
+    end
+
+    #
+    # Merges the given data file contents with this data file
+    #
+    # @param [DataFile] data_file
+    #
+    # @raise [StandardError] Data file cannot be merged
+    #
+    def merge(data_file)
+      raise "cannot merge data file: '#{data_file}' because it is not supported!" unless data_file.is_a?(DataFileHash)
+
+      data_file.to_merge.each_pair do |key, value|
+        object.store(key, value)
+      end
+    end
+
+    #
+    # Serializes the data file's object
+    #
+    # This method prepares the object as a hash
+    #
+    # Object IDs list is used to filter the correct
+    #
+    # @return [Hash]
+    #
+    def serialize
+      # Dups the original object
+      processed_object = object.dup
+
+      # Applies the selected object IDs (if any)
+      processed_object = processed_object.filter { |key, value| object_ids.include?(key) } unless all_objects?
+
+      # Returns the formatted object
+      processed_object
+    end
+
+    #
+    # Converts the given list to object IDs for this data file
+    #
+    # The list must be an array of this data file hash values or keys
+    #
+    # @param list [Array] List of objects
+    #
+    # @return [Array<Object>]
+    #
+    def convert_list_to_ids(list)
+      list.map { |i| object.key?(i) ? i : object.key(i) }
+    end
+
+    #
+    # Gets a list of objects prepared to be merged
+    #
+    # @return [Hash]
+    #
+    def to_merge
+      object
+    end
+
+    #
+    # Gets a list of objects to perform a selection
+    #
+    # @return [Array<Object>]
+    #
+    def to_list
+      # Data files needs to be compacted because TTY does not allow to create zero index based lists
+      # for some data files, the first element is nil because they are created in RPG Maker database starting at 1
+      # If this array is not compacted, it will cause an index mismatch later when auto-selecting objects
+      object.values
+    end
+  end
+
+  #
+  # RPG Maker numbered hash data file
+  #
+  # This class expects the object to be a hash
+  #
+  # This class forces hash keys to be a number for the data files:
+  # - Areas
+  # - MapInfos
+  #
+  # **Reason: Creating a DataFileHash instance from a MapInfos/Areas JSON file provokes undesired behavior.**
+  #
+  # JSON only allows key names to be strings, so all keys of the hash will be converted to string.
+  #
+  # This is undesired behavior because RPG Maker editor requires the MapInfos and Areas hash keys to be numbers.
+  #
+  # So we need to convert all keys read from the JSON file to integers when importing the JSON file into the
+  # RPG Maker database, hence the inclusion of this class specification from DataFileHash.
+  #
+  # Otherwise the RPG Maker editor will fail to show the maps and areas even though data still exists.
+  #
+  class DataFileHashNumber < DataFileHash
+    #
+    # Serializes the data file's object
+    #
+    # This method prepares the object as a hash
+    #
+    # Object IDs list is used to filter the correct
+    #
+    # @return [Hash]
+    #
+    def serialize
+      super.transform_keys do |key|
+        key.to_s.to_i
+      end
+    end
+  end
+end

data/lib/rgss_db/model/data_file_factory.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+require_relative "./data_file"
+
+module RgssDb
+  #
+  # Data file factory module
+  #
+  module DataFileFactory
+    # List of all data files types
+    # @return [Array<String>]
+    FACTORY_ALL_TYPES = [
+      DATA_FILE_ACTORS,
+      DATA_FILE_ANIMATIONS,
+      DATA_FILE_AREAS,
+      DATA_FILE_ARMORS,
+      DATA_FILE_CLASSES,
+      DATA_FILE_COMMON_EVENTS,
+      DATA_FILE_ENEMIES,
+      DATA_FILE_ITEMS,
+      DATA_FILE_MAP_INFOS,
+      DATA_FILE_MAPS,
+      DATA_FILE_SKILLS,
+      DATA_FILE_STATES,
+      DATA_FILE_SYSTEM,
+      DATA_FILE_TILESETS,
+      DATA_FILE_TROOPS,
+      DATA_FILE_WEAPONS
+    ].freeze
+
+    # List of data files handled using an array
+    #
+    # Some RPG Maker database files are saved as arrays (Actors, Weapons, Items...)
+    # @return [Array<String>]
+    FACTORY_ARRAY = [
+      DATA_FILE_ACTORS, DATA_FILE_ANIMATIONS,
+      DATA_FILE_ARMORS, DATA_FILE_CLASSES, DATA_FILE_COMMON_EVENTS,
+      DATA_FILE_ENEMIES, DATA_FILE_ITEMS, DATA_FILE_SKILLS,
+      DATA_FILE_STATES, DATA_FILE_TILESETS, DATA_FILE_TROOPS,
+      DATA_FILE_WEAPONS
+    ].freeze
+
+    # List of data files handled using a hash
+    # @return [Array<String>]
+    FACTORY_HASH = [].freeze
+
+    # List of data files handled using a number hash
+    # @return [Array<String>]
+    FACTORY_HASH_NUMBER = [
+      DATA_FILE_AREAS,
+      DATA_FILE_MAP_INFOS
+    ].freeze
+
+    #
+    # Creates a data file instance based on the given file entry
+    #
+    # The database file type is auto. determined using the ``data_file`` path
+    #
+    # @param data_file [String] Data file entry
+    # @param object [Object] Deserialized data file object
+    #
+    # @return [DataFile]
+    #
+    # @raise [StandardError] No type found
+    #
+    def self.create_data_file(data_file, object)
+      type = determine_data_file_type(data_file)
+      raise "could not find a valid data file type for the file: '#{data_file}'" if type.nil?
+
+      # Checks for a specific data file usage (bulk-check)
+      return DataFileArray.new(type, data_file, object) if FACTORY_ARRAY.any? { |f| f.casecmp?(type) }
+      return DataFileHash.new(type, data_file, object) if FACTORY_HASH.any? { |f| f.casecmp?(type) }
+      return DataFileHashNumber.new(type, data_file, object) if FACTORY_HASH_NUMBER.any? { |f| f.casecmp?(type) }
+
+      # Assume a base data file (map data files will use this)
+      DataFile.new(type, data_file, object)
+    end
+
+    #
+    # Determines the type of the data file
+    #
+    # Returns ``nil`` if a valid type cannot be found
+    #
+    # @param [String] data_file Data file entry
+    #
+    # @return [String]
+    #
+    def self.determine_data_file_type(data_file)
+      # Gets the data file name without extensions (and custom label, if any)
+      data_file_name = File.basename(data_file, ".*").gsub(DATA_FILE_CUSTOM_LABEL, "")
+      FACTORY_ALL_TYPES.find { |type| File.fnmatch(type, data_file_name, File::FNM_CASEFOLD) }
+    end
+  end
+end