Swift MultiLineDiff Package Usage Guide

website: https://d1f.ai
mirror: https://diff.xcf.ai

📦 Package Information

Repository: CodeFreezeAI/swift-multi-line-diff
License: MIT
Language: Swift 100%
Latest Release: v2.0.12(May 27, 2025)
Creator: Todd Bruss © xcf.ai

🚀 Installation Methods

Method 1: Swift Package Manager (Recommended)

Via Xcode

Open your Xcode project
Go to File → Add Package Dependencies

Enter the repository URL:

https://github.com/CodeFreezeAI/swift-multi-line-diff.git

Select version 2.0.1 or Up to Next Major Version
Click Add Package
Select MultiLineDiff target and click Add Package

Via Package.swift

Add the dependency to your Package.swift file:

// swift-tools-version: 6.1
import PackageDescription

let package = Package(
    name: "YourProject",
    platforms: [
        .macOS(.v10_15),
        .iOS(.v13_0),
        .watchOS(.v6_0),
        .tvOS(.v13_0)
    ],
    dependencies: [
        .package(
            url: "https://github.com/CodeFreezeAI/swift-multi-line-diff.git",
            from: "2.0.1"
        )
    ],
    targets: [
        .target(
            name: "YourTarget",
            dependencies: [
                .product(name: "MultiLineDiff", package: "swift-multi-line-diff")
            ]
        )
    ]
)

Then run:

swift package resolve
swift build

Method 2: Local Compilation

Clone and Build Locally

# Clone the repository
git clone https://github.com/CodeFreezeAI/swift-multi-line-diff.git
cd swift-multi-line-diff

# Build the package
swift build

# Run tests to verify installation
swift test

# Build in release mode for production
swift build -c release

Integration into Local Project

# Add as a local dependency in your Package.swift
.package(path: "../path/to/swift-multi-line-diff")

📱 Platform Support

Platform	Minimum Version
macOS	10.15+
iOS	13.0+
watchOS	6.0+
tvOS	13.0+

🔧 Basic Usage

Import the Package

import MultiLineDiff

Quick Start Examples

1. Basic Diff Creation

import MultiLineDiff

let source = """
func greet() {
    print("Hello")
}
"""

let destination = """
func greet() {
    print("Hello, World!")
}
"""

// Create diff using default Megatron algorithm
let diff = MultiLineDiff.createDiff(
    source: source,
    destination: destination
)

// Apply the diff
let result = try MultiLineDiff.applyDiff(to: source, diff: diff)
print(result) // Outputs the destination text

2. Algorithm Selection

// Ultra-fast Flash algorithm (recommended for speed)
let flashDiff = MultiLineDiff.createDiff(
    source: source,
    destination: destination,
    algorithm: .flash
)

// Detailed Optimus algorithm (recommended for precision)
let optimusDiff = MultiLineDiff.createDiff(
    source: source,
    destination: destination,
    algorithm: .optimus
)

// Semantic Megatron algorithm (recommended for complex changes)
let megatronDiff = MultiLineDiff.createDiff(
    source: source,
    destination: destination,
    algorithm: .megatron
)

3. ASCII Diff Display

// Generate AI-friendly ASCII diff
let asciiDiff = MultiLineDiff.createAndDisplayDiff(
    source: source,
    destination: destination,
    format: .ai,
    algorithm: .flash
)

print("ASCII Diff for AI:")
print(asciiDiff)
// Output:
// 📎 func greet() {
// ❌     print("Hello")
// ✅     print("Hello, World!")
// 📎 }

4. JSON and Base64 Encoding

// Create diff with metadata
let diff = MultiLineDiff.createDiff(
    source: source,
    destination: destination,
    includeMetadata: true
)

// Convert to Base64 for storage/transmission
let base64Diff = try MultiLineDiff.diffToBase64(diff)
print("Base64 Diff: \(base64Diff)")

// Convert to JSON for APIs
let jsonString = try MultiLineDiff.encodeDiffToJSONString(diff, prettyPrinted: true)
print("JSON Diff: \(jsonString)")

// Restore from Base64
let restoredDiff = try MultiLineDiff.diffFromBase64(base64Diff)
let finalResult = try MultiLineDiff.applyDiff(to: source, diff: restoredDiff)

🎯 Advanced Features

Truncated Diff Application

// Create a section diff
let sectionSource = """
func calculateTotal() -> Int {
    return 42
}
"""

let sectionDestination = """
func calculateTotal() -> Int {
    return 100
}
"""

let sectionDiff = MultiLineDiff.createDiff(
    source: sectionSource,
    destination: sectionDestination,
    algorithm: .megatron,
    includeMetadata: true,
    sourceStartLine: 10  // Line number in larger document
)

// Apply to full document (automatic detection)
let fullDocument = """
class Calculator {
    var value: Int = 0
    
    func calculateTotal() -> Int {
        return 42
    }
    
    func reset() {
        value = 0
    }
}
"""

let updatedDocument = try MultiLineDiff.applyDiff(to: fullDocument, diff: sectionDiff)

Verification and Undo

// Create diff with full metadata
let diff = MultiLineDiff.createDiff(
    source: source,
    destination: destination,
    includeMetadata: true
)

// Verify diff integrity
let isValid = MultiLineDiff.verifyDiff(diff)
print("Diff is valid: \(isValid)")

// Create automatic undo diff
if let undoDiff = MultiLineDiff.createUndoDiff(from: diff) {
    let originalText = try MultiLineDiff.applyDiff(to: destination, diff: undoDiff)
    print("Undo successful: \(originalText == source)")
}

AI Integration

// Parse AI-submitted ASCII diff
let aiSubmittedDiff = """
📎 func calculate() -> Int {
❌     return 42
✅     return 100
📎 }
"""

// Apply AI diff directly
let result = try MultiLineDiff.applyASCIIDiff(
    to: source,
    asciiDiff: aiSubmittedDiff
)

🔧 Build Configuration

Development Build

# Debug build with full symbols
swift build --configuration debug

# Run with verbose output
swift build --verbose

Production Build

# Optimized release build
swift build --configuration release

# Build with specific target
swift build --product MultiLineDiff

Testing

# Run all tests
swift test

# Run specific test
swift test --filter MultiLineDiffTests

# Generate test coverage
swift test --enable-code-coverage

📊 Performance Optimization

Algorithm Selection Guide

// For maximum speed (2x faster)
let fastDiff = MultiLineDiff.createDiff(
    source: source,
    destination: destination,
    algorithm: .flash,
    includeMetadata: false
)

// For maximum detail and accuracy
let detailedDiff = MultiLineDiff.createDiff(
    source: source,
    destination: destination,
    algorithm: .optimus,
    includeMetadata: true
)

// For balanced performance
let balancedDiff = MultiLineDiff.createDiff(
    source: source,
    destination: destination,
    algorithm: .megatron,
    includeMetadata: true
)

Memory Management

// For large files, use streaming approach
func processLargeFile(sourceURL: URL, destURL: URL) throws {
    let source = try String(contentsOf: sourceURL)
    let destination = try String(contentsOf: destURL)
    
    // Use Flash algorithm for large files
    let diff = MultiLineDiff.createDiff(
        source: source,
        destination: destination,
        algorithm: .flash,
        includeMetadata: false
    )
    
    // Save to disk immediately
    let diffURL = sourceURL.appendingPathExtension("diff")
    try MultiLineDiff.saveDiffToFile(diff, fileURL: diffURL)
}

🛠️ Troubleshooting

Common Issues

1. Import Error

// ❌ Error: No such module 'MultiLineDiff'
import MultiLineDiff

// ✅ Solution: Ensure package is properly added to dependencies
// Check Package.swift or Xcode package dependencies

2. Platform Compatibility

// ❌ Error: Platform version too low
// ✅ Solution: Update minimum deployment target
// iOS 13.0+, macOS 10.15+, watchOS 6.0+, tvOS 13.0+

3. Memory Issues with Large Files

// ❌ Memory pressure with large files
// ✅ Solution: Use Flash algorithm and disable metadata
let diff = MultiLineDiff.createDiff(
    source: largeSource,
    destination: largeDestination,
    algorithm: .flash,
    includeMetadata: false
)

Debug Information

// Enable debug output
#if DEBUG
print("Diff operations count: \(diff.operations.count)")
if let metadata = diff.metadata {
    print("Algorithm used: \(metadata.algorithmUsed?.displayName ?? "Unknown")")
    print("Source lines: \(metadata.sourceTotalLines ?? 0)")
}
#endif

📚 Documentation References

Key Files in Repository

README.md: Main documentation
ASCIIDIFF.md: ASCII diff format specification
FLASH_OPTIMUS_ALGORITHMS.md: Algorithm performance details
NEW_SUMMARY_2025.md: Complete feature overview
Sources/: Core implementation
Tests/: Comprehensive test suite

API Documentation

// Core methods
MultiLineDiff.createDiff(source:destination:algorithm:includeMetadata:)
MultiLineDiff.applyDiff(to:diff:)
MultiLineDiff.displayDiff(diff:source:format:)

// Encoding methods
MultiLineDiff.diffToBase64(_:)
MultiLineDiff.encodeDiffToJSON(_:prettyPrinted:)

// Verification methods
MultiLineDiff.verifyDiff(_:)
MultiLineDiff.createUndoDiff(from:)

// AI integration
MultiLineDiff.parseDiffFromASCII(_:)
MultiLineDiff.a...

Releases: CodeFreezeAI/D1F-swift-multi-line-diff

Swift Multi Line Diff Release 2.0.2