Why F# for a CLI Tool#

F# is a functional-first language on .NET. Three features make it a strong fit for file-processing CLIs.

Discriminated unions model success and failure at the type level:

1
type FileResult =
2
    | Success of string * int64
3
    | Failure of string * string

The compiler forces you to handle both cases. No nullable returns, no forgotten error checks.

Pattern matching makes argument parsing readable and exhaustive:

1
match args.[i] with
2
| "--output" when i + 1 < args.Length ->
3
    loop (i + 2) { opts with OutputPath = args.[i + 1] }
4
| "--recursive" ->
5
    loop (i + 1) { opts with Recursive = true }
6
| "--help" | "-h" | "-?" ->
7
    None
8
| arg when arg.StartsWith("--") ->
9
    printfn "Error: Unknown option '%s'" arg
10
    None

First-class .NET interop means System.IO, System.Diagnostics.Stopwatch, and high-performance streams are available directly. No FFI overhead. You write F#, you get native .NET performance.

Streaming I/O: Merging PGN Files Without Loading Them into Memory#

The naive merge approach loads entire files into memory before writing. For a folder with 10 GB of PGN files, that’s 10 GB in RAM before a single byte hits disk.

PGN Merger never loads an entire file into memory. It streams through each file with 64 KB buffers:

1
use inputStream = new FileStream(pgnFile, FileMode.Open, FileAccess.Read, FileShare.Read, 65536)
2
use reader = new StreamReader(inputStream, Encoding.UTF8, true, 65536)

The copy loop operates on a pre-allocated char array, allocated once per file:

1
let streamFileToWriter (reader: StreamReader) (writer: StreamWriter) bufferSize =
2
    let buffer = Array.zeroCreate<char> bufferSize
3
    let mutable charsRead = 0
4
    while (charsRead <- reader.Read(buffer, 0, buffer.Length); charsRead > 0) do
5
        writer.Write(buffer, 0, charsRead)

No strings created during streaming. Memory footprint is ~64 KB per file regardless of input size. You could merge a 50 GB PGN archive on a machine with 512 MB of RAM.

Both input and output streams use 64 KB buffers, which means writes are batched, the OS receives larger sequential requests, and the read-ahead cache can prefetch the next block. The access pattern is purely sequential: front-to-back reads, append-only writes. On a modern NVMe SSD, throughput is hundreds of MB/s, bottlenecked by the storage device, not the code.

Safety comes from F#‘s use bindings (deterministic Dispose() even on exceptions) and exhaustive exception handling per file. The tool returns non-zero exit codes on failure, making it script-friendly.

Discriminated Unions vs Exceptions for Error Handling#

Most CLI tools use try-catch blocks and return -1 on any error. PGN Merger models every outcome explicitly:

1
type FileResult =
2
    | Success of string * int64       // filename, bytes written
3
    | Failure of string * string       // filename, error message

Each file processed produces a FileResult. The merge loop collects these and reports partial success (exit code 2) when some files fail but others succeed. This is critical when you’re merging 10,000 files — one corrupted file shouldn’t kill the entire batch.

The compiler enforces exhaustiveness. If you add a new case to FileResult, every match expression breaks at compile time until you handle it. No silent failures.

Install and Try PGN Merger#

1
# Install from NuGet (requires .NET 10.0 SDK or later)
2
dotnet tool install --global PgnMerger
3

4
# Merge all PGN files in a folder
5
pgn-merger ./your_pgn_folder
6

7
# With verbose output and custom filename
8
pgn-merger ./your_pgn_folder --verbose --output database.pgn

Browse the NuGet package page for version history, or check the project page for a feature overview, comparison table, and FAQ.

More chess tooling: I also built corentings/chess, a Go library for chess move generation, PGN encoding, and UCI interop. For tournament stories, read about my experience at the Karen Asrian Memorial in Armenia.

Related posts on performance and concurrency: If you enjoyed the streaming I/O patterns here, you might like my posts on worker pools in Go and parallel merge sort with goroutines.