### Quick Start: Create BPS patch

Source: https://github.com/marcrobledo/rompatcher.js/blob/master/_autodocs/CLI-USAGE.md

Example of how to create a more efficient BPS patch.

```bash
node index.js create game_original.bin game_modified.bin -f bps
```

--------------------------------

### Quick Start: Apply a patch

Source: https://github.com/marcrobledo/rompatcher.js/blob/master/_autodocs/CLI-USAGE.md

Example of how to apply an IPS patch to a ROM file.

```bash
node index.js patch game.bin patch.ips
```

--------------------------------

### Examples: Basic usage

Source: https://github.com/marcrobledo/rompatcher.js/blob/master/_autodocs/CLI-USAGE.md

Basic example of patching a ROM file.

```bash
node index.js patch game.smc game.ips
```

--------------------------------

### Quick Start: Create a patch

Source: https://github.com/marcrobledo/rompatcher.js/blob/master/_autodocs/CLI-USAGE.md

Example of how to create an IPS patch between two ROM files.

```bash
node index.js create game_original.bin game_modified.bin
```

--------------------------------

### Examples: Add header and validate

Source: https://github.com/marcrobledo/rompatcher.js/blob/master/_autodocs/CLI-USAGE.md

Example of injecting a header, validating checksum, and applying a patch.

```bash
node index.js patch game.nes game.ips -h1 -v
```

--------------------------------

### BPS format Example

Source: https://github.com/marcrobledo/rompatcher.js/blob/master/_autodocs/CLI-USAGE.md

Example of creating a patch using the recommended BPS format.

```bash
node index.js create original.bin modified.bin -f bps
# Output: modified.bin.bps
# Efficient, validates checksums
```

--------------------------------

### RUP format Example

Source: https://github.com/marcrobledo/rompatcher.js/blob/master/_autodocs/CLI-USAGE.md

Example of creating a patch using the RUP format, which supports metadata.

```bash
node index.js create original.bin modified.bin -f rup
# Output: modified.bin.rup
# Supports author, title, description
```

--------------------------------

### Installation

Source: https://github.com/marcrobledo/rompatcher.js/blob/master/_autodocs/CLI-USAGE.md

Commands to install and verify the Rom Patcher JS package.

```bash
# Install from repository
npm install

# Or install globally as command-line tool
npm install -g .

# Verify installation
node index.js --help
```

--------------------------------

### EBP format Example

Source: https://github.com/marcrobledo/rompatcher.js/blob/master/_autodocs/CLI-USAGE.md

Example of creating a patch using the EBP format, compatible with EBPatcher.

```bash
node index.js create original.bin modified.bin -f ebp
# Output: modified.bin.ebp
# EBPatcher compatible
```

--------------------------------

### Examples: Overwrite original (careful!)

Source: https://github.com/marcrobledo/rompatcher.js/blob/master/_autodocs/CLI-USAGE.md

Example showing how to overwrite the original ROM file with the patched version, with a caution.

```bash
node index.js patch game.bin game.ips -s false
```

--------------------------------

### Default format (IPS) Example

Source: https://github.com/marcrobledo/rompatcher.js/blob/master/_autodocs/CLI-USAGE.md

Example of creating a patch using the default IPS format.

```bash
node index.js create original.bin modified.bin
# Output: modified.bin.ips
# Max ROM: 16 MB, basic format
```

--------------------------------

### Create and apply patch in pipeline

Source: https://github.com/marcrobledo/rompatcher.js/blob/master/_autodocs/CLI-USAGE.md

Example of creating a patch and then immediately verifying it works using a pipeline.

```bash
# Create patch, then verify it works
node index.js create original.bin modified.bin -f bps && \
node index.js patch original.bin modified.bin.bps -v
```

--------------------------------

### Examples: Validate before patching

Source: https://github.com/marcrobledo/rompatcher.js/blob/master/_autodocs/CLI-USAGE.md

Example of patching a ROM file after validating its checksum.

```bash
node index.js patch game.smc game.bps -v
```

--------------------------------

### Examples: Remove header, patch, fix checksum

Source: https://github.com/marcrobledo/rompatcher.js/blob/master/_autodocs/CLI-USAGE.md

Example demonstrating a complex patching scenario: removing header, validating, patching, and fixing checksum.

```bash
node index.js patch game_headered.smc game.bps -h0 -f -v
```

--------------------------------

### Create Command Example: Create UPS Patch

Source: https://github.com/marcrobledo/rompatcher.js/blob/master/_autodocs/configuration.md

Example of creating a UPS patch.

```bash
# Create UPS patch
node index.js create original.bin modified.bin -f ups
```

--------------------------------

### Examples: Fix checksum after patching

Source: https://github.com/marcrobledo/rompatcher.js/blob/master/_autodocs/CLI-USAGE.md

Example of applying a patch and then fixing the ROM's checksum.

```bash
node index.js patch game.gbc game.ips -f
```

--------------------------------

### Create Command Example: Create IPS Patch

Source: https://github.com/marcrobledo/rompatcher.js/blob/master/_autodocs/configuration.md

Example of creating an IPS patch.

```bash
# Create IPS patch (default)
node index.js create original.bin modified.bin
```

--------------------------------

### Example 2: Create patch for NES modification

Source: https://github.com/marcrobledo/rompatcher.js/blob/master/_autodocs/CLI-USAGE.md

Creates a BPS patch from a modified NES ROM and then tests it.

```bash
# Create a patch from modified NES ROM
node index.js create original.nes modified.nes -f bps

# Test the patch
node index.js patch original.nes modified.nes.bps -v

# Output patch file: modified.nes.bps
```

--------------------------------

### Create Command Example: Create BPS Patch

Source: https://github.com/marcrobledo/rompatcher.js/blob/master/_autodocs/configuration.md

Example of creating a BPS patch.

```bash
# Create BPS patch (more efficient)
node index.js create original.bin modified.bin -f bps
```

--------------------------------

### Example 3: ROM with header issues

Source: https://github.com/marcrobledo/rompatcher.js/blob/master/_autodocs/CLI-USAGE.md

Demonstrates how to handle ROMs with header issues when patching, using header injection or removal options.

```bash
# Try with header injection (for patches requiring headers)
node index.js patch game.smc patch.ips -h1

# If that fails, try removing header (for patches requiring headerless)
node index.js patch game.smc patch.ips -h0

# Or both: remove original header, add new one
node index.js patch game_headered.smc patch.ips -h0 -h1
```

--------------------------------

### UPS format Example

Source: https://github.com/marcrobledo/rompatcher.js/blob/master/_autodocs/CLI-USAGE.md

Example of creating a patch using the UPS format, which is reversible.

```bash
node index.js create original.bin modified.bin -f ups
# Output: modified.bin.ups
# Can be applied or reversed
```

--------------------------------

### Create Command Example: Create EBP Patch

Source: https://github.com/marcrobledo/rompatcher.js/blob/master/_autodocs/configuration.md

Example of creating an EBP patch for Earthbound hacks with metadata.

```bash
# Create EBP patch (Earthbound with metadata)
node index.js create original.bin modified.bin -f ebp
```

--------------------------------

### Document patches

Source: https://github.com/marcrobledo/rompatcher.js/blob/master/_autodocs/CLI-USAGE.md

Example of creating a README file for a patch collection, including creation date and MD5 checksum.

```bash
# Keep README with patch info
echo "Game v1.0 Patch (BPS format)" > patches/README.md
echo "Created: $(date)" >> patches/README.md
echo "MD5: $(md5sum patches/game_v1.0.bps)" >> patches/README.md
```

--------------------------------

### Create Command Example: Create RUP Patch

Source: https://github.com/marcrobledo/rompatcher.js/blob/master/_autodocs/configuration.md

Example of creating a RUP patch with metadata support.

```bash
# Create RUP patch (with metadata support)
node index.js create original.bin modified.bin -f rup
```

--------------------------------

### Organize patch collection

Source: https://github.com/marcrobledo/rompatcher.js/blob/master/_autodocs/CLI-USAGE.md

Example of creating a directory for patches and moving created patches into it with descriptive filenames.

```bash
# Create organized patch directory
mkdir patches
node index.js create roms/original.bin roms/modified.bin -f bps
mv roms/modified.bin.bps patches/game_v1.0.bps
```

--------------------------------

### Patch Command Example: Basic Patching

Source: https://github.com/marcrobledo/rompatcher.js/blob/master/_autodocs/configuration.md

Example of basic ROM patching.

```bash
# Basic patching
node index.js patch game.bin game.ips
```

--------------------------------

### Example 6: Quality assurance workflow

Source: https://github.com/marcrobledo/rompatcher.js/blob/master/_autodocs/CLI-USAGE.md

A workflow for creating, testing, and verifying a patch before distribution.

```bash
# 1. Create patch from modifications
node index.js create original.bin modified.bin -f bps

# 2. Test patch on fresh copy
cp original.bin test.bin
node index.js patch test.bin modified.bin.bps -v

# 3. Verify result matches expected
# (compare test (patched).bin with modified.bin)

# 4. If successful, distribute modified.bin.bps
```

--------------------------------

### BinFile Constructor Example

Source: https://github.com/marcrobledo/rompatcher.js/blob/master/_autodocs/api-reference/BinFile.md

Demonstrates creating a BinFile instance from various sources in different environments.

```javascript
const binFile = require('./rom-patcher-js/modules/BinFile');

// Browser: from file input
const binFile = new BinFile(document.querySelector('input[type="file"]'));

// Browser: async loading
const binFile = new BinFile(file, function(loadedFile) {
    console.log('File loaded:', loadedFile.fileName);
});

// Node.js: from filesystem
const binFile = new BinFile('rom.bin');

// Create empty file
const newFile = new BinFile(1024 * 1024);

// Clone existing file
const clone = new BinFile(existingFile);
```

--------------------------------

### Out of memory troubleshooting

Source: https://github.com/marcrobledo/rompatcher.js/blob/master/_autodocs/CLI-USAGE.md

Example of running Node.js with increased memory allocation for handling very large files.

```bash
# For very large files, Node.js may need more memory
node --max-old-space-size=4096 index.js patch huge_rom.bin patch.bps
```

--------------------------------

### Patch Command Example: With Validation and Checksum Fix

Source: https://github.com/marcrobledo/rompatcher.js/blob/master/_autodocs/configuration.md

Example of ROM patching with checksum validation and fix.

```bash
# With validation and checksum fix
node index.js patch game.bin game.ips -v -f
```

--------------------------------

### Example 5: Batch processing script

Source: https://github.com/marcrobledo/rompatcher.js/blob/master/_autodocs/CLI-USAGE.md

A bash script for patching multiple ROMs with a single patch file.

```bash
#!/bin/bash
# batch_patch.sh

PATCH_FILE="$1"

for rom in *.bin; do
    echo "Patching $rom..."
    node index.js patch "$rom" "$PATCH_FILE" -v -f
done
```

```bash
chmod +x batch_patch.sh
./batch_patch.sh game.bps
```

--------------------------------

### Command Reference: patch - Add header

Source: https://github.com/marcrobledo/rompatcher.js/blob/master/_autodocs/CLI-USAGE.md

Example of applying a patch and injecting a header for headerless ROMs.

```bash
node index.js patch game.nes patch.ips -h1
```

--------------------------------

### Installation and Usage

Source: https://github.com/marcrobledo/rompatcher.js/blob/master/_autodocs/configuration.md

Instructions for installing RomPatcher.js dependencies and running the patch command directly or after global installation.

```bash
# Install dependencies
npm install

# Run directly
node index.js patch "my_rom.bin" "my_patch.ips"

# Or install globally and use RomPatcher command
npm install -g .
RomPatcher patch "my_rom.bin" "my_patch.ips"
```

--------------------------------

### Module not found troubleshooting

Source: https://github.com/marcrobledo/rompatcher.js/blob/master/_autodocs/CLI-USAGE.md

Commands to ensure project dependencies are installed and the node_modules directory exists.

```bash
# Ensure dependencies installed
npm install

# Check node_modules exists
ls node_modules
```

--------------------------------

### Example 1: Patch a SNES ROM

Source: https://github.com/marcrobledo/rompatcher.js/blob/master/_autodocs/CLI-USAGE.md

Applies a BPS patch to a SNES ROM, including validation and header checksum fix.

```bash
# Apply a BPS patch to a SNES ROM
node index.js patch game.smc patch.bps -v -f

# This will:
# 1. Validate the ROM checksum
# 2. Apply the patch
# 3. Fix the SNES header checksum
# Output: game (patched).smc
```

--------------------------------

### Command Reference: patch - Fix checksum

Source: https://github.com/marcrobledo/rompatcher.js/blob/master/_autodocs/CLI-USAGE.md

Example of applying a patch and fixing the ROM header checksum.

```bash
node index.js patch game.gbc patch.ips -f
```

--------------------------------

### Command Reference: patch - Validate checksum

Source: https://github.com/marcrobledo/rompatcher.js/blob/master/_autodocs/CLI-USAGE.md

Example of applying a patch while validating the ROM checksum.

```bash
node index.js patch game.bin patch.ips -v
```

--------------------------------

### Patch Command Example: Add Header, Validate, and Fix Checksum

Source: https://github.com/marcrobledo/rompatcher.js/blob/master/_autodocs/configuration.md

Example of ROM patching with header addition, validation, and checksum fix.

```bash
# Add header, validate, and fix checksum
node index.js patch game.smc game.bps -h1 -v -f
```

--------------------------------

### Patch Command Example: Remove Header Before Patching

Source: https://github.com/marcrobledo/rompatcher.js/blob/master/_autodocs/configuration.md

Example of ROM patching with header removal.

```bash
# Remove header before patching
node index.js patch game_headered.nes game.ips -h0
```

--------------------------------

### Timing long operations

Source: https://github.com/marcrobledo/rompatcher.js/blob/master/_autodocs/CLI-USAGE.md

Example of using the 'time' command to measure the duration of patching operations.

```bash
# See how long patching takes
time node index.js patch large_rom.bin patch.bps -v
```

--------------------------------

### Command Reference: patch - Remove header

Source: https://github.com/marcrobledo/rompatcher.js/blob/master/_autodocs/CLI-USAGE.md

Example of applying a patch and removing a header from a ROM.

```bash
node index.js patch game_headered.smc patch.ips -h0
```

--------------------------------

### Workflow 3: Batch processing

Source: https://github.com/marcrobledo/rompatcher.js/blob/master/_autodocs/configuration.md

Example of using a bash loop to create patches for multiple ROM files.

```bash
# Create patches for multiple ROMs
for rom in original/*.bin; do
    modified="${rom/original/modded}"
    node index.js create "$rom" "$modified" -f bps
done
```

--------------------------------

### BinFile push() Method Example

Source: https://github.com/marcrobledo/rompatcher.js/blob/master/_autodocs/api-reference/BinFile.md

Shows how to save the current file position onto a stack before moving and later returning to it with pop().

```javascript
binFile.push();
binFile.seek(0x100); // read from another location
binFile.pop();       // return to saved position
```

--------------------------------

### BinFile Constructor Error Example (Node.js)

Source: https://github.com/marcrobledo/rompatcher.js/blob/master/_autodocs/errors.md

Example demonstrating a BinFile constructor error for a non-existent file path in Node.js.

```javascript
try {
    const romFile = new BinFile('/nonexistent/path.bin');
} catch (err) {
    console.log(err.message);  // '/nonexistent/path.bin does not exist'
}
```

--------------------------------

### createPatch Example

Source: https://github.com/marcrobledo/rompatcher.js/blob/master/_autodocs/api-reference/RomPatcher.md

Example demonstrating how to use RomPatcher.createPatch to create and export a BPS patch.

```javascript
const patch = RomPatcher.createPatch(originalRom, modifiedRom, 'bps', {
    Description: 'Version 1.0 patch'
});
const patchFile = patch.export('my_patch');
patchFile.save();
```

--------------------------------

### applyPatch Example

Source: https://github.com/marcrobledo/rompatcher.js/blob/master/_autodocs/api-reference/RomPatcher.md

Example demonstrating how to apply a patch to a ROM file with various options using RomPatcher.applyPatch.

```javascript
const patchedRom = RomPatcher.applyPatch(romFile, patch, {
    requireValidation: true,
    fixChecksum: true,
    addHeader: true
});
patchedRom.save();
```

--------------------------------

### BinFile seek() Method Example

Source: https://github.com/marcrobledo/rompatcher.js/blob/master/_autodocs/api-reference/BinFile.md

Illustrates how to navigate the file pointer to specific absolute positions.

```javascript
binFile.seek(0);           // go to beginning
binFile.seek(0x1000);      // jump to offset 0x1000
```

--------------------------------

### Example 4: Game Boy ROM patching

Source: https://github.com/marcrobledo/rompatcher.js/blob/master/_autodocs/CLI-USAGE.md

Applies a patch to a Game Boy ROM and fixes the header checksum.

```bash
# Apply patch and fix Game Boy header checksum
node index.js patch pokemon.gb patch.ips -f

# Validates and fixes header
# Output: pokemon (patched).gb
```

--------------------------------

### BinFile.swapBytes Error Example

Source: https://github.com/marcrobledo/rompatcher.js/blob/master/_autodocs/errors.md

Example demonstrating the 'file size is not divisible by X' error in BinFile.swapBytes.

```javascript
try {
    binFile.swapBytes(3);  // ❌ File size not divisible by 3
} catch (err) {
    console.log(err.message);  // 'file size is not divisible by 3'
    binFile.swapBytes(4);  // ✓ Works if size divisible by 4
}
```

--------------------------------

### CLI Error Handling Example

Source: https://github.com/marcrobledo/rompatcher.js/blob/master/_autodocs/configuration.md

Illustrates how the CLI catches and displays errors using try-catch blocks and chalk for formatting.

```javascript
try {
    // Operation
    console.log(chalk.green('successfully saved to ' + patchedRom.fileName));
} catch (err) {
    console.log(chalk.bgRed('error: ' + err.message));
}
```

--------------------------------

### BinFile.copyTo Example

Source: https://github.com/marcrobledo/rompatcher.js/blob/master/_autodocs/errors.md

Demonstrates correct usage of copyTo with a BinFile object as the target, contrasting it with an incorrect string target.

```javascript
try {
    sourceFile.copyTo('output.bin', 0);  // ",
} catch (err) {
    const targetFile = new BinFile(sourceFile.fileSize);
    sourceFile.copyTo(targetFile, 0);  // ". Correct
}
```

--------------------------------

### BinFile.slice Error Example

Source: https://github.com/marcrobledo/rompatcher.js/blob/master/_autodocs/errors.md

Example demonstrating the 'zero length provided for slicing' error in BinFile.slice.

```javascript
try {
    const part = romFile.slice(1000000, 0);  // ❌ Zero length
} catch (err) {
    console.log(err.message);  // 'zero length provided for slicing'
}
```

--------------------------------

### parsePatchFile Example

Source: https://github.com/marcrobledo/rompatcher.js/blob/master/_autodocs/api-reference/RomPatcher.md

Example demonstrating how to parse a binary patch file using RomPatcher.parsePatchFile.

```javascript
const BinFile = require('./rom-patcher-js/modules/BinFile');
const RomPatcher = require('./rom-patcher-js/RomPatcher');

const patchFile = new BinFile('path/to/patch.ips');
const patch = RomPatcher.parsePatchFile(patchFile);
if (patch) {
    console.log('Patch format identified');
}
```

--------------------------------

### Adapter Pattern Example

Source: https://github.com/marcrobledo/rompatcher.js/blob/master/_autodocs/ARCHITECTURE.md

Demonstrates the Adapter Pattern where BinFile adapts different underlying file APIs (File API, fs module, ArrayBuffer) to a common interface.

```javascript
// Browser: File API
const binFile = new BinFile(fileInput);

// Node.js: fs module
const binFile = new BinFile('path/to/file.bin');

// Raw: ArrayBuffer
const binFile = new BinFile(arrayBuffer);

// All use same interface
binFile.readU32();
binFile.writeBytes([...]);
```

--------------------------------

### BinFile isEOF() Method Example

Source: https://github.com/marcrobledo/rompatcher.js/blob/master/_autodocs/api-reference/BinFile.md

Provides an example of using isEOF() to control a loop that reads until the end of the file.

```javascript
while (!binFile.isEOF()) {
    binFile.readU8();
}
```

--------------------------------

### HeaderInfo Example

Source: https://github.com/marcrobledo/rompatcher.js/blob/master/_autodocs/types.md

Example of HeaderInfo.

```javascript
{
    name: 'iNES',
    size: 16
}
```

--------------------------------

### addFakeHeader Example

Source: https://github.com/marcrobledo/rompatcher.js/blob/master/_autodocs/api-reference/RomPatcher.md

Example demonstrating how to use addFakeHeader to inject a header into a headerless ROM.

```javascript
const romWithHeader = RomPatcher.addFakeHeader(romFile);
if (romWithHeader) {
    console.log(`Header added. New size: ${romWithHeader.fileSize}`);
}
```

--------------------------------

### Strategy Pattern Example

Source: https://github.com/marcrobledo/rompatcher.js/blob/master/_autodocs/ARCHITECTURE.md

A conceptual example of the Strategy Pattern where different patch format implementations act as interchangeable strategies.

```javascript
// Client code
const patch = RomPatcher.parsePatchFile(file);  // Any format
const patched = patch.apply(romFile);           // Common interface
```

--------------------------------

### Patch Command Example: Suppress Output Suffix

Source: https://github.com/marcrobledo/rompatcher.js/blob/master/_autodocs/configuration.md

Example of ROM patching suppressing the output suffix.

```bash
# Suppress output suffix (keep original filename)
node index.js patch game.bin game.ips -s false
```

--------------------------------

### canRomGetHeader Example

Source: https://github.com/marcrobledo/rompatcher.js/blob/master/_autodocs/api-reference/RomPatcher.md

Example showing how to use canRomGetHeader to check for header compatibility and add a fake header if possible.

```javascript
const headerInfo = RomPatcher.canRomGetHeader(romFile);
if (headerInfo) {
    console.log(`Can add ${headerInfo.name} header (${headerInfo.size} bytes)`);
    romFile = RomPatcher.addFakeHeader(romFile);
}
```

--------------------------------

### Permission denied troubleshooting

Source: https://github.com/marcrobledo/rompatcher.js/blob/master/_autodocs/CLI-USAGE.md

Commands to make the index.js script executable or to explicitly use Node.js to run it.

```bash
# Make index.js executable (Linux/Mac)
chmod +x index.js

# Or use node explicitly
node index.js patch game.bin game.ips
```

--------------------------------

### BinFile skip() Method Example

Source: https://github.com/marcrobledo/rompatcher.js/blob/master/_autodocs/api-reference/BinFile.md

Demonstrates moving the file pointer forward or backward by a specified number of bytes.

```javascript
binFile.skip(4);   // move ahead 4 bytes
binFile.skip(-2);  // move back 2 bytes
```

--------------------------------

### validateRom Example

Source: https://github.com/marcrobledo/rompatcher.js/blob/master/_autodocs/api-reference/RomPatcher.md

Example showing how to validate a ROM file against a patch using RomPatcher.validateRom.

```javascript
const isValid = RomPatcher.validateRom(romFile, patch);
if (!isValid) {
    console.log('ROM validation failed');
}
```

--------------------------------

### Installation and CLI Usage

Source: https://github.com/marcrobledo/rompatcher.js/blob/master/_autodocs/README.md

Instructions for installing RomPatcher.js via npm and using its command-line interface.

```bash
# Clone repository
git clone https://github.com/marcrobledo/RomPatcher.js.git
cd RomPatcher.js

# Install dependencies
npm install

# Run tests
npm test

# Use CLI
node index.js patch game.bin patch.ips

# Or install globally
npm install -g .
RomPatcher patch game.bin patch.ips
```

--------------------------------

### BinFile Instance Properties Example

Source: https://github.com/marcrobledo/rompatcher.js/blob/master/_autodocs/api-reference/BinFile.md

Shows how to modify and access instance properties like littleEndian, offset, and fileName.

```javascript
binFile.littleEndian = true; // switch to little-endian
console.log(binFile.offset); // current position
binFile.fileName = 'patched.bin';
```

--------------------------------

### CLI Usage Examples

Source: https://github.com/marcrobledo/rompatcher.js/blob/master/_autodocs/README.md

Examples of applying and creating patches using the Rom Patcher JS command-line interface.

```bash
node index.js patch game.bin patch.ips

# Create a patch
node index.js create original.bin modified.bin -f bps
```

--------------------------------

### RomPatcher.parsePatchFile Error Example

Source: https://github.com/marcrobledo/rompatcher.js/blob/master/_autodocs/errors.md

Example demonstrating the 'Patch file is not an instance of BinFile' error and its resolution.

```javascript
try {
    const patch = RomPatcher.parsePatchFile('patch.ips');  // ❌ String, not BinFile
} catch (err) {
    console.log(err.message);  // 'Patch file is not an instance of BinFile'
    const patchFile = new BinFile('patch.ips');  // ✓ Correct way
    const patch = RomPatcher.parsePatchFile(patchFile);
}
```

--------------------------------

### isRomHeadered Example

Source: https://github.com/marcrobledo/rompatcher.js/blob/master/_autodocs/api-reference/RomPatcher.md

Example demonstrating the use of isRomHeadered to detect if a ROM has a header.

```javascript
const headerInfo = RomPatcher.isRomHeadered(romFile);
if (headerInfo) {
    console.log(`ROM has ${headerInfo.name} header`);
}
```

--------------------------------

### RomPatcher.createPatch Error Example

Source: https://github.com/marcrobledo/rompatcher.js/blob/master/_autodocs/errors.md

Example demonstrating the 'Invalid patch format' error and how to provide a valid format.

```javascript
try {
    const patch = RomPatcher.createPatch(original, modified, 'zips');  // ❌ Invalid
} catch (err) {
    console.log(err.message);  // 'Invalid patch format'
    const patch = RomPatcher.createPatch(original, modified, 'bps');  // ✓ Valid
}
```

--------------------------------

### removeHeader Example

Source: https://github.com/marcrobledo/rompatcher.js/blob/master/_autodocs/api-reference/RomPatcher.md

Example showing how to use removeHeader to split a headered ROM into its header and ROM components.

```javascript
const result = RomPatcher.removeHeader(romFile);
if (result) {
    const { header, rom } = result;
    console.log(`Extracted ${header.fileSize} byte header`);
}
```

--------------------------------

### Creating a patch

Source: https://github.com/marcrobledo/rompatcher.js/blob/master/_autodocs/api-reference/PatchFormats.md

Example of creating an IPS or BPS patch.

```javascript
const originalRom = new BinFile('original.bin');
const modifiedRom = new BinFile('modified.bin');

// Create IPS patch
const ipsPatch = RomPatcher.createPatch(originalRom, modifiedRom, 'ips');

// Create BPS patch (more efficient)
const bpsPatch = RomPatcher.createPatch(originalRom, modifiedRom, 'bps');

// Export and save
const patchFile = ipsPatch.export('my_patch');
patchFile.save();
```

--------------------------------

### Checking file sizes

Source: https://github.com/marcrobledo/rompatcher.js/blob/master/_autodocs/CLI-USAGE.md

Commands to compare ROM file sizes before and after patching.

```bash
# Compare ROM sizes before/after
ls -lh game.bin game\ \(patched\).bin
```

--------------------------------

### View create command help

Source: https://github.com/marcrobledo/rompatcher.js/blob/master/_autodocs/configuration.md

Displays help information for the 'create' command, detailing its usage, arguments, and available options for creating patch files between two ROMs.

```bash
node index.js create --help
```

--------------------------------

### RomPatcher.applyPatch Error Example

Source: https://github.com/marcrobledo/rompatcher.js/blob/master/_autodocs/errors.md

Example demonstrating handling the 'Invalid input ROM checksum' error during RomPatcher.applyPatch.

```javascript
try {
    const result = RomPatcher.applyPatch(romFile, patch, {
        requireValidation: true
    });
} catch (err) {
    if (err.message === 'Invalid input ROM checksum') {
        console.log('ROM does not match patch');
        // Try with removeHeader or addHeader option
        const result = RomPatcher.applyPatch(romFile, patch, {
            addHeader: true
        });
    }
}
```

--------------------------------

### Programmatic Configuration Options

Source: https://github.com/marcrobledo/rompatcher.js/blob/master/_autodocs/configuration.md

Example of setting patch options when using RomPatcher.js as a library in Node.js.

```javascript
const RomPatcher = require('./rom-patcher-js/RomPatcher');
const BinFile = require('./rom-patcher-js/modules/BinFile');

// Patch options object
const options = {
    requireValidation: false,
    removeHeader: false,
    addHeader: false,
    fixChecksum: false,
    outputSuffix: true
};

// Create patch options
const createdPatch = RomPatcher.createPatch(original, modified, 'bps', {
    Description: 'My patch v1.0'  // For RUP format
});
```

--------------------------------

### Loading from Browser File Input

Source: https://github.com/marcrobledo/rompatcher.js/blob/master/_autodocs/errors.md

Example of how to load a file from a browser's file input element using BinFile and handle potential loading errors.

```javascript
const fileInput = document.querySelector('input[type="file"]');

try {
    const binFile = new BinFile(fileInput, function(loaded) {
        console.log('File loaded:', loaded.fileName);
        const patch = RomPatcher.parsePatchFile(loaded);
        // ...
    });
} catch (err) {
    console.error('File load error:', err.message);
}
```

--------------------------------

### HashCalculator Module - Factory Pattern Example

Source: https://github.com/marcrobledo/rompatcher.js/blob/master/_autodocs/ARCHITECTURE.md

Example of the Factory pattern used in HashCalculator.js, with private helper functions and public methods for hash computations.

```javascript
const HashCalculator = (function() {
    // Private: lookup tables, helper functions
    const CRC32_TABLE = [256 values];
    const _add32 = function(a, b) { ... }
    
    // Public
    return {
        crc32: function(arrayBuffer, offset, len) { ... },
        md5: function(arrayBuffer, offset, len) { ... },
        sha1: async function(arrayBuffer, offset, len) { ... },
        // ...
    }
}());
```

--------------------------------

### Command history navigation

Source: https://github.com/marcrobledo/rompatcher.js/blob/master/_autodocs/CLI-USAGE.md

Bash/zsh commands for navigating command history.

```bash
# Previous command
Up arrow

# Search history
Ctrl+R

# Recent patch commands
history | grep "patch"
```

--------------------------------

### Example: Choose correct patch automatically

Source: https://github.com/marcrobledo/rompatcher.js/wiki/Embedding-Rom-Patcher-JS

This example shows how to automatically select the correct patch from a zip file based on the ROM's CRC32 checksum, and how to display a custom error message for incompatible ROM revisions.

```javascript
	const SML2_CHECKSUM_WORLD = 0xd5ec24e4;
	const SML2_CHECKSUM_JAPAN = 0xa715daf5;
	const SML2_CHECKSUMS_INVALID = [0xe6f886e5, 0x635a9112, 0xbf733e10, 0x29e0911a]; /* incompatible SML2 revisions */

	RomPatcher.initialize(
		{
			onloadrom: function (romFile) {
				const crc32 = romFile.hashCRC32();
				/* if ROM region is USA/Europe */
				if (crc32 === SML2_CHECKSUM_WORLD)
					RomPatcherWeb.pickEmbededFile('SML2DXv181.ips');
				/* if ROM region is Japan */
				else if (crc32 === SML2_CHECKSUM_JAPAN)
					RomPatcherWeb.pickEmbededFile('SML2DXv181_jap.ips');
			},
			onvalidaterom: function (romFile, isRomValid) {
				const crc32 = romFile.hashCRC32();
				/* if ROM is a known SML2 revision that is not compatible with the patch */
				if (!isRomValid && SML2_CHECKSUMS_INVALID.indexOf(crc32) !== -1)
					RomPatcherWeb.setErrorMessage('Please provide a v1.0 SML2 ROM');
			}
		},
		{
			file: 'SML2DXv181.zip',
			patches: [
				{
					file: 'SML2DXv181.ips',
					name: 'Super Mario Land 2 DX - 6 Golden Coins (v1.8.1)',
					inputCrc32: SML2_CHECKSUM_WORLD,
					description: 'SML2 colorization hack (USA/Europe) by toruzz',
					outputName: 'Super Mario Land 2 DX - 6 Golden Coins (Hack)',
					outputExtension: 'gbc'
				},
				{
					file: 'SML2DXv181_jap.ips',
					name: 'Super Mario Land 2 DX - 6-tsu no Kinka (v1.8.1)',
					inputCrc32: SML2_CHECKSUM_JAPAN,
					description: 'SML2 colorization hack (Japan) by toruzz',
					outputName: 'Super Mario Land 2 DX - 6-tsu no Kinka (Hack)',
					outputExtension: 'gbc'
				}
			]
		}
	);

```

--------------------------------

### Node.js Library Usage Example

Source: https://github.com/marcrobledo/rompatcher.js/blob/master/_autodocs/README.md

Example demonstrating how to use the Rom Patcher JS library in a Node.js environment to patch a ROM file.

```javascript
const RomPatcher = require('./rom-patcher-js/RomPatcher');
const BinFile = require('./rom-patcher-js/modules/BinFile');

// Load ROM and patch
const romFile = new BinFile('game.bin');
const patchFile = new BinFile('patch.ips');

// Parse patch
const patch = RomPatcher.parsePatchFile(patchFile);
if (!patch) throw new Error('Unknown patch format');

// Apply patch
const patchedRom = RomPatcher.applyPatch(romFile, patch, {
    requireValidation: true,
    fixChecksum: true
});

// Save result
patchedRom.save();
```

--------------------------------

### File not found troubleshooting

Source: https://github.com/marcrobledo/rompatcher.js/blob/master/_autodocs/CLI-USAGE.md

Commands to check if the ROM and patch files exist before attempting to patch.

```bash
# Check file exists
ls -la game.bin
ls -la patch.ips

# Use correct path
node index.js patch ./roms/game.bin ./patches/patch.ips
```

--------------------------------

### Applying a patch

Source: https://github.com/marcrobledo/rompatcher.js/blob/master/_autodocs/api-reference/PatchFormats.md

Example of applying an IPS patch to a ROM file.

```javascript
const romFile = new BinFile('game.bin');
const patchFile = new BinFile('game.ips');

const patch = RomPatcher.parsePatchFile(patchFile);
if (!patch) throw new Error('Unknown patch format');

const patchedRom = RomPatcher.applyPatch(romFile, patch, {
    requireValidation: true,
    fixChecksum: true
});

patchedRom.save();
```

--------------------------------

### HashCalculator Hash Methods Example

Source: https://github.com/marcrobledo/rompatcher.js/blob/master/_autodocs/errors.md

Illustrates how to handle missing HashCalculator module or sha1 function by loading the module and retrying the hash calculation.

```javascript
try {
    const crc = romFile.hashCRC32();  // ",
} catch (err) {
    console.log(err.message);  // 'no Hash object found...'
    // In Node.js, require the module
    global.HashCalculator = require('./modules/HashCalculator');
    const crc = romFile.hashCRC32();  // ". Now works
}
```

--------------------------------

### Example: Fix ROM endianness

Source: https://github.com/marcrobledo/rompatcher.js/wiki/Embedding-Rom-Patcher-JS

This example demonstrates how to handle N64 ROMs with different endianness (Big Endian .z64 and Little Endian .n64) by swapping bytes and changing the file extension before and after patching.

```javascript
	const SSB_LITTE_ENDIAN_CRC32 = 0xf0b7c200;
	var romIsLittleEndian;

	RomPatcher.initialize(
		{
			onloadrom:function(romFile, patch){
				/* if ROM is little endian */
				if(romFile.getExtension()==='n64' && romFile.hashMD5()===SSB_LITTE_ENDIAN_CRC32){
					/* change endianness to big */
					romFile.swapBytes(4);
					/* change extension */
					romFile.setExtension('z64');

					romIsLittleEndian=true;
				}else{
					romIsLittleEndian=false;
				}
			},
			onpatch:function(patchedRomFile){
				/* if ROM was little endian */
				if(romIsLittleEndian){
					/* revert endianness to little */
					romFile.swapBytes(4);
					/* revert extension */
				romFile.setExtension('n64');
				}
			}
		},
		{
			file: 'smashremix1.5.2.xdelta',
			inputCrc32: 0xeb97929e,
			name: 'Smash Remix v1.5.2',
			outputName: 'Smash Remix v1.5.2 (Hack)'
		}
	);

```

--------------------------------

### IPS.setEBPMetadata Example

Source: https://github.com/marcrobledo/rompatcher.js/blob/master/_autodocs/errors.md

Illustrates an error when metadata values are not strings, showing the expected object structure.

```javascript
try {
    patch.setEBPMetadata({
        author: 'Name',
        version: 123  // ". Should be string
    });
} catch (err) {
    console.log(err.message);  // 'metadataObject values must be strings'
}
```

--------------------------------

### File size not divisible by troubleshooting

Source: https://github.com/marcrobledo/rompatcher.js/blob/master/_autodocs/CLI-USAGE.md

Commands to address ROM size incompatibility with header types, suggesting trying without header options or specifying header handling.

```bash
# This is usually about adding header with wrong ROM size
# Try without header options
node index.js patch game.bin patch.ips

# Or specify exact header handling
node index.js patch game.bin patch.ips -h0  # remove if has header
```

--------------------------------

### slice(offset, len, doNotClone)

Source: https://github.com/marcrobledo/rompatcher.js/blob/master/_autodocs/api-reference/BinFile.md

Creates a new BinFile containing a portion of the current file. The parameters define the starting offset, the number of bytes to slice, and an option to avoid cloning if slicing the entire file from offset 0.

```javascript
binFile.slice(offset, len, doNotClone)
```

```javascript
const header = binFile.slice(0, 512);
const rom = binFile.slice(512);  // from 512 to end
```

--------------------------------

### Workflow 2: Creating a patch

Source: https://github.com/marcrobledo/rompatcher.js/blob/master/_autodocs/configuration.md

Steps to create a patch file by comparing two ROMs using the CLI, and then testing the created patch.

```bash
# 1. Compare two ROMs
node index.js create game_original.smc game_modded.smc -f bps

# Result: game_modded.smc.bps

# 2. Test the patch on fresh copy
cp game_original.smc game_test.smc
node index.js patch game_test.smc game_modded.smc.bps -v

# Verify: game_test (patched).smc matches game_modded.smc
```

--------------------------------

### Command Reference: patch - Output suffix (disabled)

Source: https://github.com/marcrobledo/rompatcher.js/blob/master/_autodocs/CLI-USAGE.md

Example of disabling the output suffix to overwrite the original file.

```bash
node index.js patch game.bin patch.ips -s false
```

--------------------------------

### RUP ValidationInfo Example

Source: https://github.com/marcrobledo/rompatcher.js/blob/master/_autodocs/types.md

Example of ValidationInfo from RUP.

```javascript
{
    type: 'MD5',
    value: ['d41d8cd98f00b204e9800998ecf8427e', 'c4ca4238a0b923820dcc509a6f75849b']
}
```

--------------------------------

### Workflow 4: NES ROM with header issues

Source: https://github.com/marcrobledo/rompatcher.js/blob/master/_autodocs/configuration.md

Demonstrates how to handle NES ROMs with potential header issues by trying to add or remove headers during patching.

```bash
# Original ROM may have header, try adding header
node index.js patch game.nes game.ips -h1

# If that fails, try without header
node index.js patch game.nes game.ips -h0
```

--------------------------------

### UPS ValidationInfo Example

Source: https://github.com/marcrobledo/rompatcher.js/blob/master/_autodocs/types.md

Example of ValidationInfo from UPS.

```javascript
{
    type: 'CRC32',
    value: 0x12345678
}
```

--------------------------------

### View patch command help

Source: https://github.com/marcrobledo/rompatcher.js/blob/master/_autodocs/configuration.md

Displays help information for the 'patch' command, detailing its usage, arguments, and available options for patching ROM files.

```bash
node index.js patch --help
```

--------------------------------

### Workflow 1: Patching a ROM

Source: https://github.com/marcrobledo/rompatcher.js/blob/master/_autodocs/configuration.md

Steps to apply a patch to a ROM file using the CLI, including creating a backup and applying the patch with validation.

```bash
# 1. Create a backup
cp game.smc game_backup.smc

# 2. Apply patch with validation
node index.js patch game.smc game_v1.0.bps -v -f

# Result: game (patched).smc

# 3. Verify result
echo "Patched ROM ready at game (patched).smc"
```

--------------------------------

### Create Command Usage

Source: https://github.com/marcrobledo/rompatcher.js/blob/master/_autodocs/configuration.md

Command-line usage for creating a patch from two ROM files.

```bash
node index.js create <original_rom_file> <modified_rom_file> [options]
```

--------------------------------

### RomPatcher.validateRom Error Example

Source: https://github.com/marcrobledo/rompatcher.js/blob/master/_autodocs/errors.md

Example demonstrating errors related to incorrect parameter types for RomPatcher.validateRom.

```javascript
try {
    RomPatcher.validateRom('rom.bin', patch);  // ❌ Wrong type
} catch (err) {
    const romFile = new BinFile('rom.bin');    // ✓ Correct
    RomPatcher.validateRom(romFile, patch);
}
```

--------------------------------

### Constructor Pattern

Source: https://github.com/marcrobledo/rompatcher.js/blob/master/_autodocs/ARCHITECTURE.md

Illustrates the Constructor Pattern for creating objects with properties and methods, including static methods.

```javascript
function ConstructorName(source, options) {
    this.property = value;
    this.method = function() { ... }
}

ConstructorName.staticMethod = function() { ... }

const instance = new ConstructorName(...);
```

--------------------------------

### View available commands

Source: https://github.com/marcrobledo/rompatcher.js/blob/master/_autodocs/configuration.md

Command to display help information and available commands for the RomPatcher.js CLI.

```bash
node index.js --help
```

--------------------------------

### npm Dependencies

Source: https://github.com/marcrobledo/rompatcher.js/blob/master/_autodocs/configuration.md

List of npm packages used as dependencies.

```json
{
  "dependencies": {
    "chalk": "^4.1.2",
    "commander": "^11.0.0"
  }
}
```

--------------------------------

### RomPatcher Module - Core API Example

Source: https://github.com/marcrobledo/rompatcher.js/blob/master/_autodocs/ARCHITECTURE.md

Example of the Module pattern (IIFE) used in the RomPatcher.js file, exporting a singleton object with public methods.

```javascript
const RomPatcher = (function () {
    // Private: constants, helper functions
    const TOO_BIG_ROM_SIZE = 67108863;
    const HEADERS_INFO = [...];
    const _getRomSystem = function() { ... }
    
    // Public: return object with methods
    return {
        parsePatchFile: function() { ... },
        validateRom: function() { ... },
        applyPatch: function() { ... },
        // ...
    }
}());
```

--------------------------------

### Patch Creation Workflow Diagram

Source: https://github.com/marcrobledo/rompatcher.js/blob/master/_autodocs/ARCHITECTURE.md

Illustrates the step-by-step process of creating a patch file from two ROM files.

```plaintext
User Input (original ROM, modified ROM)
    ↓
BinFile (load files)
    ↓
RomPatcher.createPatch(original, modified, format)
    ↓
FormatModule.buildFromRoms(original, modified)
    ↓
Compare files byte-by-byte
    ↓
Generate records/actions
    ↓
Patch object
    ↓
Patch.export(fileName) — encode to binary
    ↓
BinFile (patch file)
    ↓
Output (save to disk)
```

--------------------------------

### Example: Remove header

Source: https://github.com/marcrobledo/rompatcher.js/wiki/Embedding-Rom-Patcher-JS

This example shows how to detect and remove the 512-byte header from SNES ROM files (typically with a .smc extension) before patching, and then set the extension to .sfc.

```javascript
	RomPatcher.initialize(
		{
			onloadrom: function (romFile) {
				const SMC_HEADER_SIZE=512;
				if(romFile.getExtension()==='smc' && ((romFile.fileSize - SMC_HEADER_SIZE) % 0x20000) === 0){
					romFile.removeLeadingBytes(SMC_HEADER_SIZE);
					romFile.setExtension('sfc');
					console.log('removed SMC header');
				}
			}
		},
		{
			file: 'Tekkaman Blade v1.0.rup',
			name: 'English translation by D and Near',
			outputName: 'Uchuu no Kishi Tekkaman Blade (English v1.0)',
		}
	);

```

--------------------------------

### Patch with metadata

Source: https://github.com/marcrobledo/rompatcher.js/blob/master/_autodocs/api-reference/PatchFormats.md

Example of creating a RUP patch with metadata.

```javascript
const patch = RomPatcher.createPatch(original, modified, 'rup', {
    Description: 'My awesome mod v1.0'
});
```

--------------------------------

### Runtime Detection

Source: https://github.com/marcrobledo/rompatcher.js/blob/master/_autodocs/api-reference/BinFile.md

Shows how to check the runtime environment before using environment-specific features.

```javascript
switch (BinFile.RUNTIME_ENVIROMENT) {
    case 'browser':
        console.log('Running in browser');
        break;
    case 'node':
        console.log('Running in Node.js');
        break;
    case 'webworker':
        console.log('Running in Web Worker');
        break;
    default:
        console.log('Unknown environment');
}
```

--------------------------------

### Integration with BinFile

Source: https://github.com/marcrobledo/rompatcher.js/blob/master/_autodocs/api-reference/HashCalculator.md

Demonstrates how HashCalculator methods are typically accessed through the BinFile class, which handles buffer extraction automatically.

```javascript
const BinFile = require('./rom-patcher-js/modules/BinFile');

const romFile = new BinFile('rom.bin');

// These methods delegate to HashCalculator
const crc = romFile.hashCRC32();        // entire file
const md5 = romFile.hashMD5(0, 512);    // first 512 bytes
const sha1 = await romFile.hashSHA1();  // entire file (async)
const adler = romFile.hashAdler32(0, 1024);  // first 1KB
const crc16 = romFile.hashCRC16();      // entire file
```

--------------------------------

### IPS toString Method

Source: https://github.com/marcrobledo/rompatcher.js/blob/master/_autodocs/api-reference/PatchFormats.md

Get human-readable patch info.

```javascript
const info = patch.toString()
```

--------------------------------

### Invalid patch file troubleshooting

Source: https://github.com/marcrobledo/rompatcher.js/blob/master/_autodocs/CLI-USAGE.md

Commands to verify patch file integrity and format.

```bash
# Verify file integrity
file patch.ips

# Try with different format flag (note: -f is for create, not patch)
# For patching, format is auto-detected
```

--------------------------------

### Byte Ordering

Source: https://github.com/marcrobledo/rompatcher.js/blob/master/_autodocs/api-reference/BinFile.md

Demonstrates how to set and use little-endian byte order for multi-byte reads and writes.

```javascript
binFile.littleEndian = false;  // big-endian (default)
binFile.writeU32(0x12345678);  // writes 0x12, 0x34, 0x56, 0x78

binFile.littleEndian = true;   // little-endian
binFile.seek(0);
binFile.writeU32(0x12345678);  // writes 0x78, 0x56, 0x34, 0x12
```

--------------------------------

### Validating a ROM

Source: https://github.com/marcrobledo/rompatcher.js/blob/master/_autodocs/api-reference/HashCalculator.md

Example of validating a ROM file by comparing its calculated CRC32 checksum against an expected value.

```javascript
const expectedCrc = 0x12345678;
const actualCrc = romFile.hashCRC32();
if (actualCrc === expectedCrc) {
    console.log('ROM is valid');
} else {
    console.log('ROM checksum mismatch');
}
```

--------------------------------

### Create Patch Command

Source: https://github.com/marcrobledo/rompatcher.js/blob/master/_autodocs/CLI-USAGE.md

Command to create a patch file from two ROM files, with options for format selection.

```bash
Usage: node index.js create [options] <original_rom_file> <modified_rom_file>

creates a patch based on two ROMs

Arguments:
  original_rom_file     Path to original unmodified ROM
  modified_rom_file     Path to modified ROM

Options:
  -f, --format <format>
                        Patch format: ips, bps, ppf, ups, aps, rup, ebp
                        (default: "ips")
  -h, --help            Show help
```