io_module_demo.ruff

# IO Module Demo
# Demonstrates advanced binary I/O operations for real-world use cases

print("=== IO Module - Advanced Binary I/O Operations ===")
print()

# Example 1: Reading specific chunks from log files
print("Example 1: Log File Analysis - Read Last N Bytes")
print("---------------------------------------------------")

# Create a sample log file
let log_file := "/tmp/app.log"
let log_entries := "INFO: App started\nWARN: Low memory\nERROR: Connection failed\nINFO: Retrying\nINFO: Success\n"
io_write_bytes(log_file, decode_base64(encode_base64(log_entries)))

# Read only the last 50 bytes (recent log entries)
let file_meta := io_file_metadata(log_file)
let file_size := file_meta["size"]
let last_50_start := file_size - 50

if last_50_start > 0 {
    let recent_logs := io_seek_read(log_file, last_50_start)
    print("Last 50 bytes of log file:")
    print(encode_base64(recent_logs))  # In real use, decode to string
} else {
    # File is smaller than 50 bytes, read it all
    let all_logs := read_binary_file(log_file)
    print("Entire log file (< 50 bytes):")
    print(encode_base64(all_logs))
}
print()

# Example 2: Binary file header inspection
print("Example 2: Binary File Format Detection")
print("-------------------------------------------")

# Create a fake image file with header
let image_file := "/tmp/test.png"
# PNG files start with: 0x89 0x50 0x4E 0x47 (magic number)
let png_header := decode_base64("iVBORw==")  # Base64 for PNG header bytes
let image_data := decode_base64(encode_base64("placeholder image bytes"))
io_write_bytes(image_file, png_header)

# Read just the first 8 bytes to detect file type
let header := io_read_bytes(image_file, 8)
let header_b64 := encode_base64(header)

print("File: " + image_file)
print("Header (first 8 bytes): " + header_b64)

if header_b64 == "iVBORw==" {
    print("✓ Detected PNG image file")
} else {
    print("Unknown file format")
}
print()

# Example 3: Patch binary file at specific offset
print("Example 3: Binary Patching - Update Configuration")
print("---------------------------------------------------")

# Create a binary config file
let config_file := "/tmp/app.config"
let config_data := "VERSION=1.0.0\0FLAGS=0x0000\0PORT=8080"
io_write_bytes(config_file, decode_base64(encode_base64(config_data)))

print("Original config size: " + to_string(io_file_metadata(config_file)["size"]))

# Update the FLAGS field at offset 22 (after "FLAGS=")
let new_flags := "0xFFFF"
io_write_at(config_file, decode_base64(encode_base64(new_flags)), 22)

print("✓ Patched FLAGS at offset 22")
print("Config file updated without rewriting entire file")
print()

# Example 4: Extract specific section from large file
print("Example 4: Data Extraction - Copy File Section")
print("---------------------------------------------------")

# Create a large data file
let data_file := "/tmp/dataset.bin"
let section_a := "AAAAA"  # 5 bytes
let section_b := "BBBBB"  # 5 bytes  
let section_c := "CCCCC"  # 5 bytes
let full_data := section_a + section_b + section_c
io_write_bytes(data_file, decode_base64(encode_base64(full_data)))

# Extract only section B (bytes 5-10)
let extracted_file := "/tmp/section_b.bin"
io_copy_range(data_file, extracted_file, 5, 5)

let extracted := read_binary_file(extracted_file)
let extracted_str := encode_base64(extracted)

print("Extracted 5 bytes from offset 5:")
if extracted_str == encode_base64(decode_base64(encode_base64("BBBBB"))) {
    print("✓ Successfully extracted section B")
}
print("Use case: Extract specific data ranges from large files efficiently")
print()

# Example 5: Incremental file building
print("Example 5: Incremental File Assembly")
print("-------------------------------------------")

let assembled_file := "/tmp/assembled.dat"
# Create empty file
io_write_bytes(assembled_file, decode_base64(encode_base64("")))

# Append data chunks as they become available
print("Building file incrementally...")
io_append_bytes(assembled_file, decode_base64(encode_base64("Chunk1")))
print("  Added chunk 1")

io_append_bytes(assembled_file, decode_base64(encode_base64("-Chunk2")))
print("  Added chunk 2")

io_append_bytes(assembled_file, decode_base64(encode_base64("-Chunk3")))
print("  Added chunk 3")

let final_size := io_file_metadata(assembled_file)["size"]
print("✓ Final file size: " + to_string(final_size) + " bytes")
print("Use case: Stream processing, downloading in chunks")
print()

# Example 6: File metadata inspection
print("Example 6: Comprehensive File Inspection")
print("-------------------------------------------")

let inspect_file := "/tmp/inspect_me.bin"
let test_data := "Sample file for metadata inspection"
io_write_bytes(inspect_file, decode_base64(encode_base64(test_data)))

let meta := io_file_metadata(inspect_file)

print("File: " + inspect_file)
    let type_label := "Directory"
    if meta["is_file"] {
        type_label := "File"
    }
    print("  Type: " + type_label)
print("  Size: " + to_string(meta["size"]) + " bytes")
print("  Read-only: " + to_string(meta["readonly"]))
print("  Modified: " + to_string(meta["modified"]) + " (Unix timestamp)")

if meta["created"] > 0 {
    print("  Created: " + to_string(meta["created"]) + " (Unix timestamp)")
}

if meta["accessed"] > 0 {
    print("  Accessed: " + to_string(meta["accessed"]) + " (Unix timestamp)")
}

print()

# Example 7: File truncation for cleanup
print("Example 7: File Size Management")
print("-------------------------------------------")

let large_file := "/tmp/large_data.bin"
# Create a 100-byte file
let large_content := "0123456789" + "ABCDEFGHIJ" + "abcdefghij" + "0123456789" + "ABCDEFGHIJ"
large_content := large_content + large_content  # 100 bytes
io_write_bytes(large_file, decode_base64(encode_base64(large_content)))

let before_size := io_file_metadata(large_file)["size"]
print("Before: " + to_string(before_size) + " bytes")

# Truncate to first 20 bytes
io_truncate(large_file, 20)

let after_size := io_file_metadata(large_file)["size"]
print("After truncate: " + to_string(after_size) + " bytes")
print("✓ Reduced file size by " + to_string(before_size - after_size) + " bytes")
print("Use case: Log rotation, cleanup, size limits")
print()

# Example 8: Offset-based reading for structured data
print("Example 8: Structured Binary Data Access")
print("-------------------------------------------")

# Create a binary record file with fixed-size records
let records_file := "/tmp/records.bin"

# Each record: ID (4 bytes) + Name (10 bytes) + Score (2 bytes) = 16 bytes
let record1 := "0001" + "Alice     " + "95"  # 16 bytes
let record2 := "0002" + "Bob       " + "87"  # 16 bytes
let record3 := "0003" + "Charlie   " + "92"  # 16 bytes

let all_records := record1 + record2 + record3
io_write_bytes(records_file, decode_base64(encode_base64(all_records)))

print("Record file created with 3 records (16 bytes each)")

# Read record 2 directly (offset 16, length 16)
let record_2 := io_read_at(records_file, 16, 16)
print("Read record 2 at offset 16:")
print("  Raw: " + encode_base64(record_2))
print("  Use case: Random access to database records")

# Read just the score from record 3 (offset 32 + 14 = 46, length 2)
let score_3 := io_read_at(records_file, 46, 2)
print("Score from record 3: " + encode_base64(score_3))
print()

# Example 9: Zero-copy file operations
print("Example 9: Efficient File Manipulation")
print("-------------------------------------------")

let source := "/tmp/source_data.bin"
let partial_copy := "/tmp/partial.bin"

# Create source with 50 bytes
let source_content := "0123456789ABCDEFGHIJ" + "klmnopqrstuvwxyz0123" + "ENDMARKER"
io_write_bytes(source, decode_base64(encode_base64(source_content)))

# Copy middle section (bytes 10-30) without loading entire file
io_copy_range(source, partial_copy, 10, 20)

let partial_size := io_file_metadata(partial_copy)["size"]
print("✓ Copied 20 bytes from middle of source file")
print("  Source size: 59 bytes")
print("  Partial copy size: " + to_string(partial_size) + " bytes")
print("  Memory efficient: only copied target range")
print()

print("=== Real-World Use Cases ===")
print()
print("1. Log Analysis:")
print("   - Read last N bytes for recent entries")
print("   - Scan log headers without loading entire file")
print()
print("2. Binary File Format Detection:")
print("   - Read file signatures/magic numbers")
print("   - Identify file types before processing")
print()
print("3. In-Place File Updates:")
print("   - Patch configuration without rewriting")
print("   - Update binary structures efficiently")
print()
print("4. Data Extraction:")
print("   - Extract specific sections from archives")
print("   - Copy byte ranges from large files")
print()
print("5. Streaming & Assembly:")
print("   - Build files incrementally")
print("   - Append chunks as they arrive")
print()
print("6. Database-like Access:")
print("   - Random access to fixed-size records")
print("   - Read/write at specific offsets")
print()
print("7. File Cleanup:")
print("   - Truncate logs to size limits")
print("   - Manage file sizes efficiently")
print()

print("=== IO Module Functions ===")
print()
print("Core Operations:")
print("  io_read_bytes(path, count)           - Read N bytes from start")
print("  io_write_bytes(path, bytes)          - Write binary data")
print("  io_append_bytes(path, bytes)         - Append binary data")
print()
print("Offset-Based Operations:")
print("  io_read_at(path, offset, count)      - Read from specific offset")
print("  io_write_at(path, bytes, offset)     - Write at specific offset")
print("  io_seek_read(path, offset)           - Read from offset to end")
print()
print("Advanced Operations:")
print("  io_file_metadata(path)               - Get comprehensive metadata")
print("  io_truncate(path, size)              - Shrink or extend file")
print("  io_copy_range(src, dest, off, count) - Copy byte range")
print()