OpenSearch  -- relative searches, table file generation
Copyright (C) 2009 mcpancakes
Version: 0.1
Date: 12 April 2009


Table of Contents
=================

    I.  About
   II.  Features
  III.  Problems With Relative Search (And Why There Are Things That No Relative
          Searcher Supports)
   IV.  Using the Program
    V.  License
   VI.  Credits


I. About
========

This program is for those who would like to venture into ROM hacking, but never
could for the sheer reason that there weren't any tools available for their platform.


II. Features
============

* Relative searching
* Wildcard characters (*)
* Find both upper and lowercase characters (-autocaps <letter>)
* Table file output based on the results of a relative search (-mktbl)


III. Problems With Relative Search (And Why There Are Things That No Relative
       Searcher Supports)
=============================================================================

There are two problems with the relative search technique:

  * Multi-case searches cannot work. The program cannot assume (safely) that the set
    of uppercase letters and the set of lowercase letters are in the same relative
    location to each other in the ROM as they are in the ASCII standard.

    Note, however, that this only applies when the uppercase and lowercase characters
    are specified are next to each other in the string. When wildcards are used, it
    doesn't.

    Example:

      $ ./opensearch-0.1 "/usbhdd/Archive/ROMs/Tetris.nes" ALE*EY
      OpenSearch 0.1  Copyright (C) 2009 mcpancakes
      Input: 41 4C 45  * 45 59
      ROM:   0A 15 0E 21 0E 22
      Offset: 0x30D7 (12503)

      $ ./opensearch-0.1 "/usbhdd/Archive/ROMs/Tetris.nes" ALE*ey
      OpenSearch 0.1  Copyright (C) 2009 mcpancakes
      Input: 41 4C 45  * 65 79
      ROM:   0A 15 0E 21 0E 22
      Offset: 0x30D7 (12503)

  * Whether a character is lowercase or uppercase cannot be determined by the
    program alone.

    Example: "ALEXEY" yields the same results as "alexey" in a normal relative
    search:

      $ ./opensearch-0.1 "/usbhdd/Archive/ROMs/Tetris.nes" ALEXEY
      OpenSearch 0.1  Copyright (C) 2009 mcpancakes
      Input: 41 4C 45 58 45 59
      ROM:   0A 15 0E 21 0E 22
      Offset: 0x30D7 (12503)

      $ ./opensearch-0.1 "/usbhdd/Archive/ROMs/Tetris.nes" alexey
      OpenSearch 0.1  Copyright (C) 2009 mcpancakes
      Input: 61 6C 65 78 65 79
      ROM:   0A 15 0E 21 0E 22
      Offset: 0x30D7 (12503)

    OpenSearch will make the table file for the English alphabet of the case that you
    search for (if you dont' use -autocaps), but the rest of the table making is up
    to the user (punctuation, etc.).


IV. Using the Program
=====================

In a terminal window (command prompt in Windows):

Linux: ./opensearch-0.1 <file> <string> [optional arguments]
Windows: opensearch-0.1 <file> <string> [optional arguments]

Your string can be up to 30 characters. You can enter more, but anything after the
30th character will be ignored.

Use wildcards sparingly. Personally, I only use them to find the values for
punctuation characters, adding those to my table file manually (and even then, my
search strings are long to ensure accuracy). The wildcard support for this program
is somewhat "lazy" in that if you search "BOW*ER", when the program is looking
through the ROM, it will not compare the characters before and in front of the
wildcard (in this case W and E) with the ROMs. It just simply disregard
(non-)relativity of bytes before and after a wildcard.

For help, run the program with the "-help" argument.

Options:

  -mktbl              Create a .tbl file for the English alphabet in the case that
                      you searched for.

  -autocaps <letter>  Automatically generate the uppercase alphabet for the ROM.
                      <letter> is the letter that corresponds with the wildcard
                      directly preceding the first letter of the string.

  -disp <number>      Specify which occurrence of the string you want to be
                      returned (and subsequently used to make a table file). If
                      you use a number too high, you'll get a "String not found!"
                      message.

  -f                  If a table file for the ROM already exists, the program will
                      not automatically overwrite it. Include this flag to force the
                      overwriting.


V. License
==========

This program is licensed under the GNU GPL v3 or above. See "COPYING" for details.


VI. Credits
===========

Thanks to:

  * Documentation writers on romhacking.net and the author(s) of the "Getting Started"
    page. It was there that I read about ROM hacking for the first time and where I
    initially got interested.
  * SquidMan, for referring me to romhacking.net.
  * Abel, a guy I'd correspond with and always keep up to date on the progress of
    OpenSearch.