sabrina 0.5.5

data/lib/sabrina/bytestream/byte_output.rb

@@ -0,0 +1,112 @@
+module Sabrina
+  class Bytestream
+    # Methods that allow {Bytestream} to output the raw byte data
+    # or export it to various formats. Subclasses should override {#to_bytes}
+    # to allow generation from an internal representation if present,
+    # and add to the list of output formats if necessary.
+    module ByteOutput
+      # Outputs a raw byte string. ROM and either table and index (recommended)
+      # or offset should have been specified, otherwise the return string will
+      # be empty. This method is relied on for write and save operations.
+      #
+      # This method uses an internal cache. The cache should be wiped
+      # automatically on changes to ROM or internal data, otherwise it can
+      # be wiped manually with {RomOperations#clear_cache}.
+      #
+      # Subclasses should define {#generate_bytes} to create the bytestream
+      # from the internal representation instead and only read from the
+      # ROM if the internal representation is absent.
+      #
+      # @return [String]
+      def to_bytes
+        return @bytes_cache if @bytes_cache
+        return @bytes_cache = generate_bytes if @representation
+
+        l_offset = offset
+        if @rom && offset
+          if @lz77
+            data = @rom.read_lz77(l_offset)
+            @length_cache = data[:original_length]
+            @lz77_cache = data[:original_stream]
+            return @bytes_cache = data[:stream]
+          end
+          return @bytes_cache = @rom.read_string(l_offset) if @is_gba_string
+          return @bytes_cache = @rom.read(l_offset, @length) if @length
+        end
+
+        return ''
+      end
+
+      # Subclasses should override this to return a string of bytes generated
+      # from the representation.
+      def generate_bytes
+        @bytes_cache = present
+      end
+
+      # Subclasses should override this to update the representation from
+      # byte data.
+      def present
+        @representation ||= to_bytes
+      end
+
+      # Same as {#to_bytes}.
+      def to_b
+        to_bytes
+      end
+
+      # Returns a hexadecimal representation of the byte data, optionally
+      # grouping it into quartets if passed +true+ as a parameter.
+      #
+      # @return [String]
+      def to_hex(pretty = false)
+        h = to_bytes.each_byte.to_a.map { |x| format('%02x', x) }.join('')
+        return h unless pretty
+
+        h.scan(/......../).map { |x| x.scan(/../).join(':') }.join(' ')
+      end
+
+      # Same as {#to_hex}, but reverses the bytes before conversion.
+      #
+      # @return [String]
+      def to_hex_reverse
+        to_bytes.each_byte.to_a.map { |x| format('%02x', x) }.reverse.join('')
+      end
+
+      # Returns the byte data converted to a base-16 integer.
+      # @return [Integer]
+      def to_i
+        to_hex.hex
+      end
+
+      # Outputs the byte data as a GBA-compatible {Lz77}-compressed
+      # stream, raising an error when the data is empty.
+      # {RomOperations#write_to_rom} relies on this
+      # method when :lz77 is set to true.
+      #
+      # This method uses an internal cache. The cache should be wiped
+      # automatically on changes to ROM or internal data, otherwise it can
+      # be wiped manually with {RomOperations#clear_cache}.
+      #
+      # Subclasses should clear the internal cache by calling
+      # {RomOperations#clear_cache} whenever the internal
+      # representation has changed.
+      # @return [String]
+      def to_lz77
+        return @lz77_cache if @lz77_cache
+        b = to_bytes
+        fail 'Cannot compress empty data.' if b.empty?
+        @lz77_cache = Lz77.compress(b)
+      end
+
+      # Returns the output of {#to_hex}.
+      #
+      # Subclasses should override this to provide a concise textual
+      # representation of the internal data.
+      #
+      # @return [String]
+      def to_s
+        "#{to_hex(true)}"
+      end
+    end
+  end
+end

data/lib/sabrina/bytestream/rom_operations.rb

@@ -0,0 +1,138 @@
+module Sabrina
+  class Bytestream
+    # Methods related to writing and retrieving various ROM data.
+    module RomOperations
+      # @todo Return key +:original_length+ for {Lz77.uncompress} is currently
+      #   unreliable. Wipe and overwrite in place for table data is disabled.
+      #
+      # Writes the byte data to the ROM, trying to use first the
+      # table index and then the offset (and failing if neither is
+      # known).
+      #
+      # If the table index is known, the data will be written to an
+      # available free space on the ROM and the table will be updated.
+      #
+      # If the table data is unknown, the data will be written in place
+      # at the offset.
+      #
+      # This method will call {#reload_from_rom} and update and return
+      # the {#last_write} array.
+      #
+      # @return [Array] see {#last_write}.
+      def write_to_rom
+        old_length = calculate_length
+        b = (@lz77 ? to_lz77 : to_bytes)
+        new_length = b.length
+        old_offset = offset
+
+        unless @rom && old_offset
+          fail 'Rom and offset or table/index must be set before writing.'
+        end
+        fail 'Byte string is empty. Aborting.' if b.empty?
+        fail "Byte string too long #{new_length}. Aborting." if new_length > 10_000
+
+        @last_write = []
+
+        new_offset =
+          if !@pointer_mode || !(@table && @index)
+            @last_write << 'Bytestream#repoint: Overwriting in place.' \
+            " (#{old_offset})"
+            old_offset
+            # Wipe and overwrite disabled due to
+            # Lz77.uncompress[:original_length] inaccuracy.
+            #
+            # elsif new_length <= old_length
+            # @last_write << 'Repoint: New length less than or equal to old' \
+            #   'length, overwriting in place.'
+            # @last_write << @rom.wipe(old_offset, old_length, true)
+            # old_offset
+          else
+            o = repoint
+            @last_write << 'Bytestream#repoint: Wiping disabled in this' \
+              "version. Leaving #{old_length} bytes at #{old_offset}" \
+              " (#{ format('%06X', old_offset) }) in #{@rom} intact."
+            @last_write << "Bytestream#repoint: Repointed to #{o}" \
+              " (#{ format('%06X', o) })."
+            # @last_write << @rom.wipe(old_offset, old_length)
+            o
+          end
+
+        @last_write << @rom.write(new_offset, b)
+        clear_cache(lz77: false)
+
+        @last_write
+      end
+
+      # Wipes the internal cache AND the representation so that the data
+      # may be synced from ROM if present.
+      #
+      # @return [self]
+      def reload_from_rom
+        @representation = nil
+        clear_cache
+        present
+        self
+      end
+
+      # Wipes the internal cache so that the data may be reloaded from ROM if
+      # present.
+      #
+      # Subclasses should call this whenever the internal representation of
+      # data is changed, and define {ByteOutput#generate_bytes} to
+      # regenerate the byte data from the internal representation.
+      #
+      # @param [Hash] h
+      #   @option h [Boolean] :lz77 whether to clear the internal representation
+      #     as well (defaults to +true+).
+      # @return [self]
+      def clear_cache(h = { lz77: true })
+        @lz77_cache = nil if h.fetch(:lz77, true)
+        @length_cache = nil if h.fetch(:lz77, true) && !@lz77
+        @bytes_cache = nil
+        self
+      end
+
+      # @todo Return key +:original_length+ for {Lz77.uncompress} is currently
+      #   unreliable. Wipe and overwrite in place for table data is disabled.
+      #
+      # Returns the length of the {Lz77} data stored on the ROM if +:lz77+
+      # mode is on and a table of offset is provided. Otherwise, returns
+      # the length of the byte data.
+      #
+      # @return [Integer]
+      def calculate_length
+        return @length_cache if @length_cache
+        if @lz77 && offset
+          return @length_cache = @rom.read_lz77(offset)[:original_length]
+        end
+        to_bytes.length
+      end
+
+      private
+
+      # Assigns the data to a suitable free space on the ROM and updates
+      # the table accordingly.
+      #
+      # This will clear the internal cache.
+      #
+      # @return [Integer] The offset found.
+      def repoint
+        unless @rom && @table && @index
+          fail 'Rom, table and index must be set before repointing.'
+        end
+
+        l = (@lz77 ? to_lz77.length : to_bytes.length)
+        f_offset = @rom.find_free(l)
+
+        unless f_offset
+          fail "Bytestream#repoint: Could not find #{l} bytes of free data in" \
+            " #{@rom}. Consider using a clean rombase."
+        end
+
+        @rom.write_offset_to_table(@table, @index, f_offset)
+        clear_cache
+        f_offset
+      end
+    end
+  end
+end

data/lib/sabrina/children_manager.rb

@@ -0,0 +1,60 @@
+module Sabrina
+  # Implements +attr_children+, an +attr_accessor+-like macro that allows
+  # passing down attribute write calls to an arbitrary array of objects.
+  # Obviously, the child objects should support writing to the specified
+  # attributes.
+  #
+  # Classes should override +#children+ to return a meaningful array of
+  # child objects.
+  module ChildrenManager
+    # Adds a macro for attribute with children update.
+    module AttrChildren
+      private
+
+      # Takes any number of symbols and creates writers that will also
+      # pass the value down to each value in +children+.
+      def attr_writer_children(*args)
+        args.each do |x|
+          x_var = "@#{x}".to_sym
+          x_setter = "#{x}=".to_sym
+
+          lamb = generate_writer_children(x_setter, x_var)
+
+          define_method(x_setter, lamb) unless respond_to?(x_setter)
+        end
+      end
+
+      # Takes any number of symbols and creates accessors that will also
+      # pass the value down to each value in +children+.
+      def attr_children(*args)
+        attr_reader(*args)
+        attr_writer_children(*args)
+      end
+
+      def generate_writer_children(name, variable)
+        lambda do |value|
+          children.each do |c|
+            next c.method(name).call(value) if c.respond_to?(name)
+            fail "Child #{c} has no method #{name}, yet attr_children called."
+          end
+          instance_variable_set(variable, value)
+        end
+      end
+    end
+
+    class << self
+      # Magic for adding class methods when included.
+      def included(mod)
+        mod.extend(AttrChildren)
+      end
+    end
+
+    # Classes should override this to provide a meaningful array
+    # of children.
+    #
+    # @return [Array]
+    def children
+      instance_variable_defined?(:@children) ? @children : []
+    end
+  end
+end

data/lib/sabrina/config.rb

@@ -0,0 +1,112 @@
+module Sabrina
+  # This utility module handles the {Sabrina} configuration. You should not
+  # need to deal with it directly, except perhaps for ad-hoc runtime config
+  # loading.
+  #
+  # Each key present in the config can also be called as a module method,
+  # for example: +Sabrina::Config.rom_defaults+.
+  #
+  # Upon the first load of the library, a directory called +.sabrina+ should
+  # have been created in your home directory (a level above +My+ +Documents+ in
+  # Windows XP, or your Cygwin home if you are running Cygwin). This directory
+  # should contain a +sample.json+ config file.
+  #
+  # Any +.json+ files in the directory except +sample.json+ will be
+  # automatically loaded and merged into the default config. Any config file
+  # may contain only some of the necessary keys as long as the key hierarchy
+  # tree is preserved.
+  #
+  # The most obvious use of the above would likely be to supply the library with
+  # easily distributable config files for specific ROMs.
+  #
+  # Keep in mind that user config files will not be auto-updated on library
+  # updates. New versions might break support for old features or add new ones.
+  # If you run into errors, try moving the files away from +.sabrina+ and let
+  # the library generate a new sample config, then look at it to see what has
+  # changed.
+  module Config
+    # The user config directory.
+    USER_CONFIG_DIR = Dir.home + '/.sabrina/'
+
+    # A sample config file to create. This will not actually be loaded and
+    # should not be modified.
+    USER_CONFIG_SAMPLE = 'sample.json'
+
+    class << self
+      # A simple function for recursive merging of nested hashes.
+      #
+      # @param [Hash] h1
+      # @param [Hash] h2
+      # @return [Hash]
+      def deep_merge(h1, h2)
+        h1.merge(h2) do |_key, x, y|
+          x.is_a?(Hash) && y.is_a?(Hash) ? deep_merge(x, y) : y
+        end
+      end
+
+      # Loads a hash into the internal config.
+      #
+      # @param [Hash] h the option hash to be merged.
+      # @return [0]
+      def load(h)
+        @sabrina_config ||= {}
+        @sabrina_config = deep_merge(@sabrina_config, h)
+
+        @sabrina_config.each_key do |key|
+          m = key.downcase.to_sym
+          next if respond_to?(m)
+          define_singleton_method(m) { @sabrina_config[key] }
+        end
+
+        0
+      end
+
+      # Creates {USER_CONFIG_DIR}, and {USER_CONFIG_SAMPLE} if the directory
+      # is empty.
+      #
+      # @return [0]
+      def create_user_config
+        FileUtils.mkpath(USER_CONFIG_DIR) unless Dir.exist?(USER_CONFIG_DIR)
+
+        c = @sabrina_config
+        c.delete_if { |key, _val| key.to_s.start_with?('charmap') }
+
+        f = File.new(USER_CONFIG_DIR + USER_CONFIG_SAMPLE, 'w+b')
+        f.write(JSON.pretty_generate(c), symbolize_names: true)
+        f.close
+        0
+      end
+
+      # Loads all .json files from {USER_CONFIG_DIR}, exempting
+      # {USER_CONFIG_SAMPLE}.
+      #
+      # @return [0]
+      def load_user_config
+        files = Dir[USER_CONFIG_DIR + '*.json']
+
+        # create_user_config if files.empty?
+
+        files.each do |x|
+          next if x.end_with?(USER_CONFIG_SAMPLE)
+          load(JSON.parse(File.read(x)))
+        end
+        0
+      end
+
+      # Returns a hash of all config keys for a ROM type identified by the
+      # 4-byte +id+.
+      #
+      # @param [String] id
+      # @return [Hash]
+      def rom_params(id)
+        defs = @sabrina_config[:rom_defaults]
+
+        params = @sabrina_config[:rom_data].fetch(id.to_sym) do
+          fail "Unsupported ROM type: \'#{id}\'."
+        end
+
+        defs.merge(params)
+      end
+    end
+  end
+end

data/lib/sabrina/config/charmap_in.rb

@@ -0,0 +1,81 @@
+Sabrina::Config.load(
+  charmap_in: {
+    ' ' => '00',
+    '<' => '85',
+    '>' => '86',
+    '0' => 'A1',
+    '1' => 'A2',
+    '2' => 'A3',
+    '3' => 'A4',
+    '4' => 'A5',
+    '5' => 'A6',
+    '6' => 'A7',
+    '7' => 'A8',
+    '8' => 'A9',
+    '9' => 'AA',
+    '!' => 'AB',
+    '?' => 'B6',
+    '.' => 'AD',
+    '-' => 'AE',
+    "\'" => 'B4',
+    '♂' => 'B5',
+    '♀' => 'B6',
+    '$' => 'B7',
+    ',' => 'B8',
+    '*' => 'B9',
+    '/' => 'BA',
+    'A' => 'BB',
+    'B' => 'BC',
+    'C' => 'BD',
+    'D' => 'BE',
+    'E' => 'BF',
+    'F' => 'C0',
+    'G' => 'C1',
+    'H' => 'C2',
+    'I' => 'C3',
+    'J' => 'C4',
+    'K' => 'C5',
+    'L' => 'C6',
+    'M' => 'C7',
+    'N' => 'C8',
+    'O' => 'C9',
+    'P' => 'CA',
+    'Q' => 'CB',
+    'R' => 'CC',
+    'S' => 'CD',
+    'T' => 'CE',
+    'U' => 'CF',
+    'V' => 'D0',
+    'W' => 'D1',
+    'X' => 'D2',
+    'Y' => 'D3',
+    'Z' => 'D4',
+    'a' => 'D5',
+    'b' => 'D6',
+    'c' => 'D7',
+    'd' => 'D8',
+    'e' => 'D9',
+    'f' => 'DA',
+    'g' => 'DB',
+    'h' => 'DC',
+    'i' => 'DD',
+    'j' => 'DE',
+    'k' => 'DF',
+    'l' => 'E0',
+    'm' => 'E1',
+    'n' => 'E2',
+    'o' => 'E3',
+    'p' => 'E4',
+    'q' => 'E5',
+    'r' => 'E6',
+    's' => 'E7',
+    't' => 'E8',
+    'u' => 'E9',
+    'v' => 'EA',
+    'w' => 'EB',
+    'x' => 'EC',
+    'y' => 'ED',
+    'z' => 'EE',
+    "\n" => 'FE'
+  }
+)