retrotool 0.1.0__tar.gz

retrotool-0.1.0/LICENSE

@@ -0,0 +1,24 @@
+This is free and unencumbered software released into the public domain.
+
+Anyone is free to copy, modify, publish, use, compile, sell, or
+distribute this software, either in source code form or as a compiled
+binary, for any purpose, commercial or non-commercial, and by any
+means.
+
+In jurisdictions that recognize copyright laws, the author or authors
+of this software dedicate any and all copyright interest in the
+software to the public domain. We make this dedication for the benefit
+of the public at large and to the detriment of our heirs and
+successors. We intend this dedication to be an overt act of
+relinquishment in perpetuity of all present and future rights to this
+software under copyright law.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR
+OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.
+
+For more information, please refer to <https://unlicense.org>

retrotool-0.1.0/PKG-INFO

@@ -0,0 +1,34 @@
+Metadata-Version: 2.2
+Name: retrotool
+Version: 0.1.0
+Summary: Address Conversion Tool for the Super Famicom
+Author-email: Daniel Burgess <daniel@herotechsys.com>
+License: This is free and unencumbered software released into the public domain.
+        
+        Anyone is free to copy, modify, publish, use, compile, sell, or
+        distribute this software, either in source code form or as a compiled
+        binary, for any purpose, commercial or non-commercial, and by any
+        means.
+        
+        In jurisdictions that recognize copyright laws, the author or authors
+        of this software dedicate any and all copyright interest in the
+        software to the public domain. We make this dedication for the benefit
+        of the public at large and to the detriment of our heirs and
+        successors. We intend this dedication to be an overt act of
+        relinquishment in perpetuity of all present and future rights to this
+        software under copyright law.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+        EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+        MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+        IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR
+        OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+        ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+        OTHER DEALINGS IN THE SOFTWARE.
+        
+        For more information, please refer to <https://unlicense.org>
+        
+Project-URL: Homepage, https://github.com/danielburgess/SFCRetroTools
+Requires-Python: >=3.8
+License-File: LICENSE
+Requires-Dist: chardet>=5.2.0

retrotool-0.1.0/README.md

@@ -0,0 +1,198 @@
+# SFCRetroTools
+#### ===ROM Hacking Tools for the Super Famicom===
+
+This repo will contain various libraries I've created for my personal use.
+
+Currently, this only contains an Address Conversion tool, and a Pointer class which are used similarly to LunarAddress, except I don't support ZSNES save states. I could, but... does anyone even use ZSNES anymore?
+
+### Supported Address Mapping Conversions:
+* LoROM (Type 1/2)
+* HiROM
+* ExLoROM
+* ExHiROM
+* PC/Binary
+
+### Basic Usage:
+
+```python
+from retrotool.snes import SFCAddress, SFCAddressType
+
+addr = SFCAddress(0x5f800, SFCAddressType.PC)
+print(addr.all())  # all applicable conversions are shown
+print(addr.exhirom_address)  # hex-formatted EXHIROM address
+```
+```text
+=====TYPE====:=ADDRESS=
+****Binary/PC: 0x05F800
+*****(1)LoROM: 0x0BF800
+**(2/Ex)LoROM: 0x8BF800
+*****Ex/HiROM: 0xC5F800
+'0xC5F800'
+```
+
+## Short Explainer
+There are several helper methods that can be used for converting SNES/SFC addresses. Essentially, this library can be combined with any number of other tools such as script dumping, pointer table generation, address conversions built in to hex editors, etc.
+
+=======
+I plan on adding more tools as I need it, but in the meantime, 
+
+---
+
+# SFCPointer Class
+
+## Description
+The `SFCPointer` class represents a Super Famicom (SFC) pointer. Pointers can be defined, modified, and read in various ways. The class allows you to specify low, high, and bank values, and it provides methods for validation, conversion, and display.
+
+## Constructor
+
+### `init(self, low=None, high=None, bank=None)`
+
+Pointers can be defined, modified, and read in many ways. Low and high values can be used to fill part of, or the entire address, depending on what is desired.
+
+- `low`: Can be as small as 8 bit, as big as 24 bit (over 24 bit is ignored).
+- `high`: Can be 8 to 16 bit (over 16 bit is ignored).
+- `bank`: Only be 8 bit (extra data is lost).
+
+## Methods
+
+### `validate_bytes(cls, *args)`
+Validates and normalizes low, high, and bank values.
+- `args`: Low, high, and bank values.
+Returns a tuple `(low, high, bank)`.
+
+### `hex_fmt(value, pad=4, prefix='0x')`
+Formats an integer value as a hexadecimal string.
+- `value`: Integer value to be formatted.
+- `pad`: Width of the formatted string (default is 4).
+- `prefix`: Prefix for the hexadecimal string (default is '0x').
+Returns the formatted hexadecimal string.
+
+### `to_addr(addr_type)`
+Converts the `SFCPointer` to an `SFCAddress` instance.
+- `addr_type`: The address type to convert to.
+Returns an `SFCAddress` instance.
+
+### `integer_or_hex(value: Union[int, str], mask: int = 0xFF) -> int`
+Validates and normalizes input values, applying masking to the value.
+- `value`: Input value (integer or hexadecimal string).
+- `mask`: Mask to be applied (default is 0xFF).
+Returns the normalized and masked integer value.
+
+### `__set_ptr_pos(self, index, input_val)`
+Sets the value at the specified index in the full pointer.
+
+---
+
+# SFCAddressType Class
+
+## Description
+The `SFCAddressType` class defines constants representing different Super Famicom (SFC) address types.
+
+## Constants
+- `PC`: Address type for PC addresses.
+- `LOROM1`: Address type for LoROM1 addresses.
+- `LOROM2`: Address type for LoROM2 addresses.
+- `HIROM`: Address type for HiROM addresses.
+- `EXHIROM`: Address type for ExHiROM addresses.
+- `EXLOROM`: Address type for ExLoROM addresses.
+
+---
+
+# SFCAddress Class
+
+## Description
+The `SFCAddress` class provides a flexible way to handle Super Famicom (SFC) addresses. It allows for instantiation with various input types and supports multiple conversions between different address types.
+
+## Constructor
+
+```python
+__init__(self, address: Union[int, str, list, tuple], address_type: int = SFCAddressType.PC,
+         default_value='N/A', hex_prefix='0x', decimal: bool = False, header: bool = False,
+         verbose=False, lorom_fallback=True) 
+```
+         
+- `address`: Integer, hexadecimal string, list, or tuple representing the address value.
+- `address_type`: The input address type (default is SFCAddressType.PC).
+- `default_value`: The value shown while printing if the conversion fails (default is 'N/A').
+- `hex_prefix`: String prepended to the output hex value (default is '0x').
+- `decimal`: Boolean indicating the default conversion output value (default is False).
+- `header`: Indicates whether the conversion should consider a copier header (default is False).
+- `verbose`: If more console output is desired (default is False).
+- `lorom_fallback`: If LoROM 1/2 conversion fails, it will fall back to the other type.
+
+## Properties and Methods
+
+### `all(self) -> str`
+Prints a formatted representation of the address in various SFC address types.
+
+### `display_address(self, addr, fill_hex_length=True, show_prefix=True) -> Union[str, int]`
+Formats and displays the given address.
+
+### `get_address(self, address_type: Optional[int] = None) -> int`
+Returns the address in the specified type.
+
+### `to_pointer(self, addr=None) -> SFCPointer`
+Converts the given address to an SFCPointer object.
+
+### `get_address_bytes(self, address_type: Optional[SFCAddressType] = None) -> list`
+Returns a list of low, high, and bank bytes of the address.
+
+### `get_low_byte(self, address_type: Optional[int] = None) -> int`
+Returns the low byte of the address.
+
+### `get_high_byte(self, address_type: Optional[int] = None) -> int`
+Returns the high byte of the address.
+
+### `get_bank_byte(self, address_type: Optional[int] = None) -> int`
+Returns the bank byte of the address.
+
+### `pc_address(self) -> str`
+Returns the address in PC format.
+
+### `lorom1_address(self) -> str`
+Returns the address in LoROM1 format.
+
+### `lorom2_address(self) -> str`
+Returns the address in LoROM2 format.
+
+### `exlorom_address(self) -> str`
+Returns the address in ExLoROM format.
+
+### `hirom_address(self) -> str`
+Returns the address in HiROM format.
+
+### `exhirom_address(self) -> str`
+Returns the address in ExHiROM format.
+
+## Class Methods
+
+### `pc_to_lorom1(cls, pc_addr: int, verbose: bool = False) -> Optional[int]`
+Converts a PC address to LoROM1 format.
+
+### `pc_to_lorom2(cls, pc_addr: int, verbose: bool = False) -> Optional[int]`
+Converts a PC address to LoROM2 format.
+
+### `pc_to_hirom(cls, pc_addr: int, verbose: bool = False) -> Optional[int]`
+Converts a PC address to HiROM format.
+
+### `pc_to_exlorom(cls, pc_addr: int, verbose: bool = False) -> Optional[int]`
+Converts a PC address to ExLoROM format.
+
+### `pc_to_exhirom(cls, pc_addr: int, verbose: bool = False) -> Optional[int]`
+Converts a PC address to ExHiROM format.
+
+### `lorom1_to_pc(cls, snes_addr: int, verbose: bool = True, fallback=False) -> Optional[int]`
+Converts a LoROM1 address to PC format.
+
+### `lorom2_to_pc(cls, snes_addr: int, verbose: bool = True, fallback=False) -> Optional[int]`
+Converts a LoROM2 address to PC format.
+
+### `hirom_to_pc(cls, snes_addr: int1, verbose: bool = False) -> Optional[int]`
+Converts a HiROM address to PC format.
+
+### `exlorom_to_pc(cls, snes_addr: int, verbose: bool = False) -> Optional[int]`
+Converts an ExLoROM address to PC format.
+
+### `exhirom_to_pc(cls, snes_addr: int, verbose: bool = False) -> Optional[int]`
+Converts an ExHiROM address to PC format.
+

retrotool-0.1.0/pyproject.toml

@@ -0,0 +1,16 @@
+[project]
+name = "retrotool"
+version = "0.1.0"
+description = "Address Conversion Tool for the Super Famicom"
+authors = [{name = "Daniel Burgess", email = "daniel@herotechsys.com"}]
+license = {file = "LICENSE"}
+dependencies = ["chardet>=5.2.0"]  # If your package needs other libraries
+requires-python = ">=3.8"
+
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+
+[project.urls]
+"Homepage" = "https://github.com/danielburgess/SFCRetroTools"

retrotool-0.1.0/retrotool/script.py

@@ -0,0 +1,313 @@
+
+
+class Table:
+    def __init__(self, table_file):
+        """
+        Load and interpret the table file, set up class variables
+        :param table_file: the path to the table file
+        """
+        enc, val_map, char_map, err_count, cnt = self._load_table(table_file)
+        self.__val_map = val_map
+        self.__chr_map = char_map
+        self.__errors = err_count
+        self.__parsed_lines = cnt
+        self.__file_name = table_file
+        self.__encoding = enc
+
+    def _load_table(self, table_file, enc=None):
+        """
+        Load a given table file. Supports encoding type overrides.
+        :param table_file: the path to the table file
+        :param enc: Optional Encoding type
+        :return: encoding, value_map, character_map, error_count, line_count
+        """
+        enc = enc if enc is not None else self.detect_encoding(table_file)
+        val_map = {}
+        char_map = {}
+        err_count = 0
+        cnt = 1
+        with open(table_file, encoding=enc) as to:
+            line = to.readline()
+            while line:
+                try:
+                    # split the line using the '=' sign, ignore all else including
+                    line_data = line.split('=')
+                    if len(line_data) == 2:
+                        # value first, character second
+                        val = line_data[0]
+                        ch = line_data[1]
+
+                        # character will have new line codes removed unless the backslash-escape '\\' is used
+                        ch = ch.replace('\n', '').replace('\r', '').replace('\\n', '\n')
+
+                        # supports variable filling for table files
+                        if self.exists(val, '**'):
+                            # fill the table with equivalent values for a byte range
+                            for d in range(0, 256):
+                                prep_ch = ch.replace('**', self.hex(d))
+                                prep_val = val.replace('**', self.hex(d))
+                                if self.exists(val, '%%'):
+                                    for e in range(0, 256):
+                                        ch_val = prep_ch.replace('%%', self.hex(e))
+                                        val_val = prep_val.replace('%%', self.hex(e))
+
+                                        self._set_maps(val_val, ch_val, val_map, char_map)
+                                else:
+                                    self._set_maps(prep_val, prep_ch, val_map, char_map)
+                        else:
+                            self._set_maps(val, ch, val_map, char_map)
+                except Exception as ex:
+                    print(f"ERROR: {repr(ex)}")
+                    err_count += 1
+                # read next line and increment line count
+                line = to.readline()
+                cnt += 1
+        return enc, val_map, char_map, err_count, cnt
+
+    @staticmethod
+    def _set_maps(in_val, in_ch, val_map, char_map):
+        """
+        Add the value and character to the map objects
+        :param in_val: value
+        :param in_ch: character
+        :param val_map: value map
+        :param char_map: character map
+        """
+        dec_val = int(in_val, 16)
+
+        if dec_val not in val_map.keys():
+            val_map[dec_val] = in_ch
+        if in_ch not in char_map.keys():
+            char_map[in_ch] = dec_val
+
+    @property
+    def encoding(self):
+        return self.__encoding
+
+    @staticmethod
+    def exists(str_val: str, search: str):
+        """
+        Search a given string for another string
+        :param str_val: searchable string
+        :param search: Value to search for
+        :return: True/False
+        """
+        try:
+            str_val.index(search)
+            return True
+        except ValueError:
+            return False
+
+    def get_value(self, word: str, infer_value=True):
+        """
+        Return value for a string
+        :param word: character/word string
+        :param infer_value: if the word comes in [00] format
+        :return: The value or None
+        """
+        if type(word) is not str:
+            raise ValueError("Value must be a string!")
+        if word in self.__chr_map.keys():
+            return self.__chr_map[word]
+        if infer_value and '[' in word and ']' in word:
+            try:
+                word = word.replace('[', '').replace(']', '')
+                return int(word, 16)
+            except:
+                print("Warning: Value could not be determined.")
+        return None
+
+    def get_chars(self, value: int, return_hex_repr=True):
+        if value in self.__val_map.keys():
+            return self.__val_map[value]
+        return f'[{self.hex(value)}]' if return_hex_repr else None
+
+    @staticmethod
+    def hex(value):
+        """
+        Return a hex representation
+        Only currently supports up to 64 bit encoded characters
+        :param value: the input value
+        :return: String representation of the given value
+        """
+        if value < 0x100:
+            pad = 2
+        elif value < 0x10000:
+            pad = 4
+        elif value < 0x1000000:
+            pad = 6
+        elif value < 0x100000000:
+            pad = 8
+        else:
+            raise ValueError("Error: Table Value is not supported!")
+        return f'{value:0{pad}X}'
+
+    @staticmethod
+    def byte_size(value: int):
+        """
+        Get the number of bytes representing the value
+        :param value: integer value
+        :return: number of bytes
+        """
+        from math import log
+        if value == 0:
+            return 1
+        return int(log(value, 256)) + 1
+
+    @staticmethod
+    def __get_byte_multiplier(value):
+        if value == 0:
+            return 1
+        final = '1'
+        for i in range(0, value):
+            final += '00'
+        return int(final, 16)
+
+    @staticmethod
+    def bytes_to_val(byte_list: list, reverse=False):
+        final_val = 0
+        if reverse:
+            byte_list.reverse()
+        for b in range(0, len(byte_list)):
+            final_val |= (byte_list[b] << (b * 8))  # self.__get_byte_multiplier(b)
+        return final_val
+
+    def interpret_binary(self, input_filename, max_bytes=3):
+        with open(input_filename, "rb") as data_file:
+            bin_data = list(data_file.read())
+        return self.interpret_binary_data(bin_data, max_bytes)
+
+    def interpret_binary_data(self, bin_data, max_bytes=3, trim_bytes=None):
+        final_string = ''
+        i = 0
+
+        # can trim certain expected bytes from the end of each output string
+        if trim_bytes is not None:
+            if type(trim_bytes) is int:
+                trim_bytes = [trim_bytes]
+            if trim_bytes is not None and len(trim_bytes) > 0:
+                exclude_count = 0
+                for i in range(len(bin_data), 0):
+                    if bin_data[i] in trim_bytes:
+                        exclude_count += 1
+                    else:
+                        break
+                if exclude_count > 0:
+                    bin_data = bin_data[:len(bin_data)-exclude_count]
+
+        while i <= len(bin_data) + 1:
+            len_check = max_bytes
+            char = None
+            found_char = False
+            while len_check > 0:
+                end_check = i + len_check
+                val = self.bytes_to_val(bin_data[i: end_check], True)
+                char = self.get_chars(val, False)
+                if char:
+                    found_char = True
+                    i += (len_check - 1)
+                    len_check = 0
+                else:
+                    len_check -= 1
+
+            if not found_char:
+                char = self.get_chars(bin_data[i], True)
+            if char is None:
+                print(f"ERROR - Unable to resolve byte ({hex(bin_data[i])})???")
+            else:
+                final_string += char
+            i += 1
+        return final_string
+
+    def has_char(self, bin_data):
+        """
+        Check for a valid character using all given bytes
+        :param bin_data: the list of bytes
+        :return: if there is a valid character using these bytes
+        """
+        # get the value by OR'ing and shifting the bytes together
+        val = self.bytes_to_val(bin_data)
+
+        # check for valid value...
+        if len(bin_data) > 1 and val in bin_data:
+            # in the case of [00, 00] or [00, 90] or etc.
+            # the total value cannot equal a single byte value
+            return None
+
+        # using the value, check for a defined character
+        char = self.get_chars(val, False)
+
+        return char
+
+    def check_for_lone_byte(self, bin_data, index, value=0x0):
+        """
+        Used to check for the end of a text block
+        :param bin_data: a list of values
+        :param index: current list index
+        :param value: check for this value
+        :return: if the value is found,
+        check to see if it is part of a larger value
+        """
+        start1 = index - 3
+        start2 = index - 2
+        end0 = index + 1
+
+        if bin_data[index] == value:
+            char1 = self.has_char(bin_data[start1: end0])
+            char2 = self.has_char(bin_data[start2: end0])
+
+            if char1 is not None or char2 is not None:
+                return 0, char1 or char2
+
+            return -1, None
+
+        return 0, None
+
+    @staticmethod
+    def detect_encoding(file_path, lines=80):
+        """
+        Given a file, use the first X number of lines to detect the encoding
+        :param file_path: path to text file
+        :param lines: defaults to 80
+        :return: the assumed file encoding using chardet
+        """
+        import chardet
+        with open(file_path, 'rb') as f:
+            raw_data = b''.join([f.readline() for _ in range(lines)])
+        return chardet.detect(raw_data)['encoding']
+
+    def dump_script(self, filename: str, dict_data: list, deduplicate=True):
+        """
+        Dump the script using a table from a list of mapped data (id, addr, data)
+        :param filename: the output file path
+        :param dict_data: a list of mapped data (id (formatted), addr (must be int), data (list of binary data))
+        :param deduplicate: only supported if the addr key is given. will only display pointer map for data in the dump
+        """
+        line1 = True
+        nl = "\n"
+        with open(filename, 'w', encoding=self.encoding) as of:
+            dumped_addrs = []
+            for data in dict_data:
+                of.write(f"{'' if line1 else nl}<<{data.get('id')}>>{nl}")
+                addr = data.get('addr', None)
+                if deduplicate and addr is not None:
+                    if addr not in dumped_addrs:
+                        dumped_addrs.append(addr)
+                        of.write(self.interpret_binary_data(data['data']))
+                else:
+                    of.write(self.interpret_binary_data(data['data']))
+                line1 = False
+
+    @staticmethod
+    def export_csv(filename, dict_data: list):
+        import csv
+        csv_columns = dict_data[0].keys()
+        csv_file = f"./{filename}.csv"
+        try:
+            with open(csv_file, 'w', newline='') as csvfile:
+                writer = csv.DictWriter(csvfile, fieldnames=csv_columns)
+                writer.writeheader()
+                for data in dict_data:
+                    writer.writerow(data)
+        except IOError:
+            print("I/O error")

retrotool-0.1.0/retrotool/snes.py

@@ -0,0 +1,578 @@
+from typing import Optional, Union
+from functools import lru_cache
+"""
+Version 2021.3
+by DackR
+"""
+
+
+class SFCPointer:
+    def __init__(self, low=None, high=None, bank=None):
+        """
+        Pointers can be defined, modified, and read in many ways.
+        low and high values can be used to fill part of, or the entire address, depending on what is desired
+        :param low: can be as small as 8 bit, as big as 24 bit (over 24 bit is ignored)
+        :param high: can be 8 to 16 bit (over 16 bit is ignored)
+        :param bank: only be 8 bit (extra data is lost)
+        """
+        self.__full_pointer = [0x0, 0x0, 0x0]
+        valid = self.validate_bytes(low, high, bank)
+        self.__set_ptr_pos(0, valid)
+        self.__set_ptr_pos(1, valid)
+        self.__set_ptr_pos(2, valid)
+
+    def __str__(self):
+        """
+        return the formatted address
+        """
+        return self.hex_fmt(self.full_address, 6) if self.full_address > 0xFFFF else self.hex_fmt(self.short_address, 4)
+
+    def __repr__(self):
+        return str(self)
+
+    @classmethod
+    def validate_bytes(cls, *args):
+        """
+        Values are passed in as positional arguments, low, high, and bank
+        low value can be the entire 24 bit address if no other args are passed in
+        high value can be the bank and high bytes if no bank byte is passed in
+        bank value can only be 8 bits and values higher are truncated
+        """
+        low = args[0] if len(args) > 0 else 0x0
+        high = args[1] if len(args) > 1 else 0x0
+        bank = args[2] if len(args) > 2 else 0x0
+        if low:
+            low = cls.integer_or_hex(low, 0xFFFFFF)
+            if low > 0xFFFF and not (high and bank):
+                bank = SFCAddress.bank_byte(low)
+                high = SFCAddress.high_byte(low)
+                low = SFCAddress.low_byte(low)
+            elif low > 0xFF and not high:
+                high = SFCAddress.high_byte(low)
+                low = SFCAddress.low_byte(low)
+        if high:
+            high = cls.integer_or_hex(high, 0xFFFF)
+            if high > 0xFF and not bank:
+                bank = SFCAddress.high_byte(high)
+                high = SFCAddress.low_byte(high)
+        if bank:
+            bank = cls.integer_or_hex(bank)
+        return low, high, bank
+
+    @staticmethod
+    def hex_fmt(value, pad=4, prefix='0x'):
+        """
+        Produce a formatted, hex value.
+        default is padded with a prefix
+        :param value: integer value to format as hex string
+        :param pad: padded up to 4 characters by default
+        :param prefix: prefix the hex string with any string -- '0x' by default
+        """
+        return f'{prefix}{value:0{pad}X}'
+
+    @property
+    def full_address(self):
+        return (self.__full_pointer[0]) + (self.__full_pointer[1] * 0x100) + (self.__full_pointer[2] * 0x10000)
+
+    @property
+    def full_hex(self):
+        return self.hex_fmt(self.full_address, 6)
+
+    @property
+    def short_address(self):
+        return (self.__full_pointer[0]) + (self.__full_pointer[1] * 0x100)
+
+    @property
+    def short_hex(self):
+        return self.hex_fmt(self.short_address)
+
+    @property
+    def short(self):
+        return self.__full_pointer[:2]
+
+    @short.setter
+    def short(self, value):
+        self.__full_pointer = [0x0, 0x0, 0x0]
+        self.__check_list_tuple(value)
+        self.__set_ptr_pos(0, value)
+        self.__set_ptr_pos(1, value)
+
+    @property
+    def full(self):
+        return self.__full_pointer
+
+    @full.setter
+    def full(self, value):
+        self.__full_pointer = [0x0, 0x0, 0x0]
+        self.__check_list_tuple(value)
+        self.__set_ptr_pos(0, value)
+        self.__set_ptr_pos(1, value)
+        self.__set_ptr_pos(2, value)
+
+    @property
+    def low(self):
+        return self.__full_pointer[0]
+
+    @low.setter
+    def low(self, value):
+        self.__full_pointer[0] = self.integer_or_hex(value)
+
+    @property
+    def high(self):
+        return self.__full_pointer[1]
+
+    @high.setter
+    def high(self, value):
+        self.__full_pointer[1] = self.integer_or_hex(value)
+
+    @property
+    def bank(self):
+        return self.__full_pointer[2]
+
+    @bank.setter
+    def bank(self, value):
+        self.__full_pointer[2] = self.integer_or_hex(value)
+
+    def to_addr(self, addr_type):
+        return SFCAddress(self.full_address, addr_type)
+
+    @staticmethod
+    def __check_list_tuple(value):
+        if not (type(value) is list or type(value) is tuple):
+            raise ValueError("Cannot assign any value but type of list or tuple.")
+        if not len(value) >= 1:
+            raise ValueError("List/Tuple length must be at least 1.")
+
+    def __set_ptr_pos(self, index, input_val):
+        if len(input_val) > index:
+            self.__full_pointer[index] = self.integer_or_hex(input_val[index])
+
+    @staticmethod
+    def integer_or_hex(value: Union[int, str], mask: int = 0xFF) -> int:
+        """
+        validation for input values, also applies masking to the value
+        :param value:
+        :param mask: value is logical and'ed to the mask
+        :return: normalized, and masked integer
+        """
+        if type(value) is str:
+            if value.upper().startswith('0X'):
+                value = value.replace('0X', '')
+            try:
+                value = int(value, 16)
+            except ValueError as ex:
+                raise ValueError('`address` parameter must be an integer or a hexadecimal string!')
+        elif type(value) is not int:
+            raise ValueError('`address` parameter must be an integer or a hexadecimal string!')
+        return value & mask
+
+
+class SFCAddressType:
+    PC = 0
+    LOROM1 = 1
+    LOROM2 = 2
+    HIROM = 3
+    EXHIROM = 4
+    EXLOROM = 5
+
+
+class SFCAddress:
+    def __init__(self, address: Union[int, str, list, tuple], address_type: int = SFCAddressType.PC,
+                 default_value='N/A', hex_prefix='0x', decimal: bool = False, header: bool = False,
+                 verbose=False, lorom_fallback=True):
+        """
+        Class can be instantiated in case multiple conversions are desired.
+        :param address: integer/hexadecimal address value
+        :param address_type: the input address type-- defaults to PC
+        :param default_value: the value that is shown while printing values if the conversion failed
+        :param hex_prefix: this string is prepended to the output hex value-- defaults to 0x (ex: 0x0BC018)
+        :param decimal: boolean value to indicate the default conversion output value-- defaults to False
+        :param header: indicate whether the conversion should take a copier header into account-- default False
+        :param verbose: if more console output is desired-- default False
+        :param lorom_fallback: if LoROM 1/2 conversion fails, they will fall back to the other type
+        """
+        self.__header = header
+        self.__prefix = hex_prefix
+        self.__show_hex = not decimal
+        self.__default = default_value
+        self.__verbose = verbose
+        self.__lorom_fallback = lorom_fallback
+        self.__initial_type = address_type
+
+        if type(address) is not list and type(address) is not tuple:
+            address = SFCPointer.integer_or_hex(address, 0xFFFFFF)
+        else:
+            ptr = SFCPointer(*address)
+            address = ptr.full_address
+
+        self.__given_address = address
+
+        if address_type == SFCAddressType.PC:
+            self.__address = address if not header else header - 512
+        elif address_type == SFCAddressType.LOROM1:
+            self.__address = self.lorom1_to_pc(address, self.__verbose, self.__lorom_fallback)
+        elif address_type == SFCAddressType.LOROM2:
+            self.__address = self.lorom2_to_pc(address, self.__verbose, self.__lorom_fallback)
+        elif address_type == SFCAddressType.HIROM:
+            self.__address = self.hirom_to_pc(address)
+        elif address_type == SFCAddressType.EXHIROM:
+            self.__address = self.exhirom_to_pc(address)
+        elif address_type == SFCAddressType.EXLOROM:
+            self.__address = self.exlorom_to_pc(address)
+        else:
+            raise ValueError('`address_type` parameter is invalid!')
+        if verbose:
+            print(self.all())
+
+    def all(self):
+        """
+        Return a text representation of the current object using all possible conversions
+        """
+        hirom = self.hirom_address
+        exhirom = self.exhirom_address
+        lorom = self.lorom1_address
+        exlorom = self.exlorom_address
+        lorom2 = self.lorom2_address
+        my_repr = f"=====TYPE====:=ADDRESS=\r\n****Binary/PC: {self.pc_address}"
+        if lorom == exlorom:
+            if lorom2 == lorom:
+                my_repr += f"\r\n(1/2/Ex)LoROM: {lorom}"
+            else:
+                my_repr += f"\r\n**(1/Ex)LoROM: {lorom}\r\n*****(2)LoROM: {lorom2}"
+        elif lorom2 == exlorom:
+            my_repr += f"\r\n*****(1)LoROM: {lorom}\r\n**(2/Ex)LoROM: {lorom2}"
+        else:
+            my_repr += f"\r\n*****(1)LoROM: {lorom}\r\n*****(2)LoROM: {lorom2}\r\n******ExLoROM: {exlorom}"
+
+        my_repr += f"\r\n*****Ex/HiROM: {hirom}" if hirom == exhirom else \
+            f"\r\n********HiROM: {hirom}\r\n******ExHiROM: {exhirom}"
+
+        return my_repr
+
+    def __str__(self):
+        return self.display_address(self.get_address(self.__initial_type))
+
+    def __repr__(self):
+        return f"{self.pc_address}({self.__address})"
+
+    @lru_cache(0xFFFFFF)
+    def display_address(self, addr, fill_hex_length=True, show_prefix=True):
+        if addr is not None:
+            if self.__show_hex:
+                addr = hex(addr).upper().replace('0X', '')
+                if fill_hex_length:
+                    while len(addr) < 6:
+                        addr = f"0{addr}"
+                if show_prefix:
+                    addr = f"{self.__prefix}{addr}"
+            return addr
+        return self.__default
+
+    @lru_cache(0xFFFFFF)
+    def get_address(self, address_type: Optional[int] = None) -> int:
+        addr = 0
+        if address_type is None:
+            address_type = self.__initial_type
+
+        if address_type == SFCAddressType.PC:
+            addr = self.__address
+        elif address_type == SFCAddressType.LOROM1:
+            addr = self.pc_to_lorom1(self.__address)
+        elif address_type == SFCAddressType.LOROM2:
+            addr = self.pc_to_lorom2(self.__address)
+        elif address_type == SFCAddressType.HIROM:
+            addr = self.pc_to_hirom(self.__address)
+        elif address_type == SFCAddressType.EXHIROM:
+            addr = self.pc_to_exhirom(self.__address)
+        elif address_type == SFCAddressType.EXLOROM:
+            addr = self.pc_to_exlorom(self.__address)
+        return addr
+
+    def to_pointer(self, addr=None):
+        if addr is None:
+            addr = self.__address
+        return SFCPointer(addr)
+
+    @lru_cache(0xFFFFFF)
+    def get_address_bytes(self, address_type: Optional[SFCAddressType] = None) -> list:
+        return [self.get_low_byte(address_type), self.get_high_byte(address_type), self.get_bank_byte(address_type)]
+
+    @lru_cache(0xFFFFFF)
+    def get_low_byte(self, address_type: Optional[int] = None) -> int:
+        addr = self.get_address(address_type)
+        return self.low_byte(addr)
+
+    @staticmethod
+    @lru_cache(0xFFFFFF)
+    def low_byte(addr: int):
+        """
+        Return a single (lowest) byte for a given address
+        """
+        return addr & 0xFF
+
+    @lru_cache(0xFFFFFF)
+    def get_high_byte(self, address_type: Optional[int] = None) -> int:
+        addr = self.get_address(address_type)
+        return self.high_byte(addr)
+
+    @staticmethod
+    @lru_cache(0xFFFFFF)
+    def high_byte(addr: int):
+        return int(addr / 0x100) & 0xFF
+
+    @lru_cache(0xFFFFFF)
+    def get_bank_byte(self, address_type: Optional[int] = None) -> int:
+        addr = self.get_address(address_type)
+        return self.bank_byte(addr)
+
+    @staticmethod
+    @lru_cache(0xFFFFFF)
+    def bank_byte(addr: int):
+        return int(addr / 0x10000) & 0xFF
+
+    @property
+    @lru_cache(0xFFFFFF)
+    def pc_address(self):
+        return self.display_address(self.__address if not self.__header else self.__address + 512)
+
+    @property
+    @lru_cache(0xFFFFFF)
+    def lorom1_address(self):
+        return self.display_address(self.pc_to_lorom1(self.__address))
+
+    @property
+    @lru_cache(0xFFFFFF)
+    def lorom2_address(self):
+        return self.display_address(self.pc_to_lorom2(self.__address))
+
+    @property
+    @lru_cache(0xFFFFFF)
+    def exlorom_address(self):
+        return self.display_address(self.pc_to_exlorom(self.__address))
+
+    @property
+    @lru_cache(0xFFFFFF)
+    def hirom_address(self):
+        return self.display_address(self.pc_to_hirom(self.__address))
+
+    @property
+    @lru_cache(0xFFFFFF)
+    def exhirom_address(self):
+        return self.display_address(self.pc_to_exhirom(self.__address))
+
+    @classmethod
+    @lru_cache(0xFFFFFF)
+    def pc_to_lorom1(cls, pc_addr: int, verbose: bool = False) -> Optional[int]:
+        if pc_addr is None:
+            if verbose:
+                print("pc_to_lorom1: Given Address is invalid.")
+            return None
+        if pc_addr >= 0x400000:
+            return None
+
+        snes_addr = ((pc_addr << 1) & 0x7F0000) | ((pc_addr | 0x8000) & 0xFFFF)
+
+        if pc_addr >= 0x380000:
+            snes_addr += 0x800000
+
+        return snes_addr
+
+    @classmethod
+    @lru_cache(0xFFFFFF)
+    def pc_to_lorom2(cls, pc_addr: int, verbose: bool = False) -> Optional[int]:
+        if pc_addr is None:
+            if verbose:
+                print("pc_to_lorom2: Given Address is invalid.")
+            return None
+        if pc_addr >= 0x400000:
+            return None
+
+        return (((pc_addr << 1) & 0x7F0000) | ((pc_addr | 0x8000) & 0xFFFF)) + 0x800000
+
+    @classmethod
+    @lru_cache(0xFFFFFF)
+    def pc_to_hirom(cls, pc_addr: int, verbose: bool = False) -> Optional[int]:
+        if pc_addr is None:
+            if verbose:
+                print("pc_to_hirom: Given Address is invalid.")
+            return None
+        if pc_addr >= 0x400000:
+            return None
+
+        return pc_addr | 0xC00000
+
+    @classmethod
+    @lru_cache(0xFFFFFF)
+    def pc_to_exlorom(cls, pc_addr: int, verbose: bool = False) -> Optional[int]:
+        if pc_addr is None:
+            if verbose:
+                print("pc_to_exlorom: Given Address is invalid.")
+            return None
+        if pc_addr >= 0x7F0000:
+            return None
+
+        snes_addr = ((pc_addr << 1) & 0x7F0000) | ((pc_addr | 0x8000) & 0xFFFF)
+
+        if pc_addr < 0x400000:
+            snes_addr += 0x800000
+
+        return snes_addr
+
+    @classmethod
+    @lru_cache(0xFFFFFF)
+    def pc_to_exhirom(cls, pc_addr: int, verbose: bool = False) -> Optional[int]:
+        if pc_addr is None:
+            if verbose:
+                print("pc_to_exhirom: Given Address is invalid.")
+            return None
+        if pc_addr >= 0x7E0000:
+            return None
+
+        snes_addr = pc_addr
+        if pc_addr < 0x400000:
+            snes_addr |= 0xC00000
+        # elif pc_addr >= 0x7E0000:
+        #     snes_addr -= 0x400000
+
+        return snes_addr
+
+    @classmethod
+    @lru_cache(0xFFFFFF)
+    def lorom1_to_pc(cls, snes_addr: int, verbose: bool = True, fallback=False) -> Optional[int]:
+        if snes_addr is None:
+            if verbose:
+                print("lorom1_to_pc: Given Address is invalid.")
+            return None
+        if not (0x8000 <= snes_addr <= 0x6FFFFF):
+            if verbose:
+                print("Not a valid LoROM1 address!")
+            return cls.lorom2_to_pc(snes_addr, verbose) if fallback else None
+
+        return snes_addr & 0x7FFF | ((snes_addr & 0x7F0000) >> 1)
+
+    @classmethod
+    @lru_cache(0xFFFFFF)
+    def lorom2_to_pc(cls, snes_addr: int, verbose: bool = True, fallback=False) -> Optional[int]:
+        if snes_addr is None:
+            if verbose:
+                print("lorom2_to_pc: Given Address is invalid.")
+            return None
+        if not (0x808000 <= snes_addr <= 0xFFFFFF):
+            if verbose:
+                print("Not a valid LoROM2 address!")
+            return cls.lorom1_to_pc(snes_addr, verbose) if fallback else None
+
+        return snes_addr & 0x7FFF | ((snes_addr & 0x7F0000) >> 1)
+
+    @classmethod
+    @lru_cache(0xFFFFFF)
+    def hirom_to_pc(cls, snes_addr: int, verbose: bool = False) -> Optional[int]:
+        if snes_addr is None:
+            if verbose:
+                print("hirom_to_pc: Given Address is invalid.")
+            return None
+
+        if not (0xC00000 <= snes_addr <= 0xFFFFFF):
+            print("Invalid HiROM Address!")
+            return None
+
+        return snes_addr & 0x3FFFFF
+
+    @classmethod
+    @lru_cache(0xFFFFFF)
+    def exlorom_to_pc(cls, snes_addr: int, verbose: bool = False) -> Optional[int]:
+        if snes_addr is None:
+            if verbose:
+                print("exlorom_to_pc: Given Address is invalid.")
+            return None
+        if not ((0x808000 <= snes_addr <= 0xFFFFFF) or (0x008000 <= snes_addr <= 0x7DFFFF)):
+            print("Invalid ExLoROM Address!")
+            return None
+
+        pc_addr = snes_addr & 0x7FFF | ((snes_addr & 0x7F0000) >> 1)
+
+        if snes_addr < 0x800000:
+            pc_addr += 0x400000
+
+        return pc_addr
+
+    @classmethod
+    @lru_cache(0xFFFFFF)
+    def exhirom_to_pc(cls, snes_addr: int, verbose: bool = False) -> Optional[int]:
+        if snes_addr is None:
+            if verbose:
+                print("exhirom_to_pc: Given Address is invalid.")
+            return None
+        if not ((0xC00000 <= snes_addr <= 0xFFFFFF) or (0x400000 <= snes_addr <= 0x7DFFFF)):
+            print("Invalid ExHiROM Address!")
+            return None
+
+        pc_addr = snes_addr & 0x3FFFFF
+        if snes_addr < 0xC00000:
+            pc_addr += 0x400000
+
+        return pc_addr
+
+
+def lorom_to_hirom(in_data: list):
+    """
+    Converts a full binary rom file (list of bytes) from lorom to hirom format (doubles every bank)
+    Quick and dirty.
+    :param in_data: the original data
+    :return: the hirom data
+    """
+    final_data = [0xFF] * (len(in_data) * 2)
+
+    div = 0x8000
+    pcs = int(len(in_data) / div)
+
+    for c in range(0, pcs):
+        for d in range(0, div):
+            pc_pos = d + (c * div)
+            hirom_pos = d + (c * 0x10000)
+            final_data[hirom_pos] = 0xFF if c == 0 else in_data[pc_pos]
+            final_data[hirom_pos + div] = in_data[pc_pos]
+    return final_data
+
+
+def run_test(function1, function2, i, name, verbose_progress, **kwargs):
+    addr = function1(i)
+    conv = function2(addr, **kwargs) if addr else 0
+    if verbose_progress and addr:
+        print(f"{hex(i)}->{hex(addr)}->{hex(conv) if conv is not None else 'ERR'} - {name}")
+    if addr and not i == conv:
+        print(f"{hex(i)}->{hex(addr)}->{hex(conv) if conv is not None else 'ERR'}"
+              f" - {name} Back-Conversion Failed!")
+        return False
+    return True
+
+
+def test_conv(start=0, end=0x7FFFFF, step=0x8000, verbose=True, stop_on_failure=True, lorom1_kwargs=None):
+    fail_count = 0
+    lorom1_kwargs = lorom1_kwargs if lorom1_kwargs else {'fallback': True, 'verbose': True}
+    for i in range(start, end, step):
+        if not run_test(SFCAddress.pc_to_lorom1, SFCAddress.lorom1_to_pc, i, "LOROM1", verbose,
+                        **lorom1_kwargs):
+            fail_count += 1
+
+        if not run_test(SFCAddress.pc_to_lorom2, SFCAddress.lorom2_to_pc, i, "LOROM2", verbose):
+            fail_count += 1
+
+        if not run_test(SFCAddress.pc_to_hirom, SFCAddress.hirom_to_pc, i, "HIROM", verbose):
+            fail_count += 1
+
+        if not run_test(SFCAddress.pc_to_exlorom, SFCAddress.exlorom_to_pc, i, "EXLOROM", verbose):
+            fail_count += 1
+
+        if not run_test(SFCAddress.pc_to_exhirom, SFCAddress.exhirom_to_pc, i, "EXHIROM", verbose):
+            fail_count += 1
+
+        if stop_on_failure and fail_count > 0:
+            break
+        if verbose:
+            print("...")
+
+    if not fail_count:
+        print("ALL TESTS PASSED!")
+    else:
+        print(f"ENCOUNTERED {fail_count} FAILURES!")

retrotool-0.1.0/retrotool.egg-info/PKG-INFO

@@ -0,0 +1,34 @@
+Metadata-Version: 2.2
+Name: retrotool
+Version: 0.1.0
+Summary: Address Conversion Tool for the Super Famicom
+Author-email: Daniel Burgess <daniel@herotechsys.com>
+License: This is free and unencumbered software released into the public domain.
+        
+        Anyone is free to copy, modify, publish, use, compile, sell, or
+        distribute this software, either in source code form or as a compiled
+        binary, for any purpose, commercial or non-commercial, and by any
+        means.
+        
+        In jurisdictions that recognize copyright laws, the author or authors
+        of this software dedicate any and all copyright interest in the
+        software to the public domain. We make this dedication for the benefit
+        of the public at large and to the detriment of our heirs and
+        successors. We intend this dedication to be an overt act of
+        relinquishment in perpetuity of all present and future rights to this
+        software under copyright law.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+        EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+        MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+        IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR
+        OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+        ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+        OTHER DEALINGS IN THE SOFTWARE.
+        
+        For more information, please refer to <https://unlicense.org>
+        
+Project-URL: Homepage, https://github.com/danielburgess/SFCRetroTools
+Requires-Python: >=3.8
+License-File: LICENSE
+Requires-Dist: chardet>=5.2.0

retrotool-0.1.0/retrotool.egg-info/SOURCES.txt

@@ -0,0 +1,10 @@
+LICENSE
+README.md
+pyproject.toml
+retrotool/script.py
+retrotool/snes.py
+retrotool.egg-info/PKG-INFO
+retrotool.egg-info/SOURCES.txt
+retrotool.egg-info/dependency_links.txt
+retrotool.egg-info/requires.txt
+retrotool.egg-info/top_level.txt

retrotool-0.1.0/retrotool.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

retrotool-0.1.0/retrotool.egg-info/requires.txt

@@ -0,0 +1 @@
+chardet>=5.2.0

retrotool-0.1.0/retrotool.egg-info/top_level.txt

@@ -0,0 +1 @@
+retrotool

retrotool-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+